知识库选型与接入方案

本文按 2026-09-30 核对的项目实现和官方文档整理。针对聊天助手、Python 模块化接入和个人笔记管理的需求，建议先用 Markdown 原文跑通问答，再通过现有 KnowledgeBase 接口接入混合检索。需要现成的资料管理界面时，可优先评估 Dify 检索 API。

当前已实现的是知识库使用指南中的用户独立资料库与角色关联、本地导入、关键词检索、原文增量更新与删除。本文中的 Qdrant、pgvector、Dify 和平台自动同步属于接入设计，尚未安装、配置或接入运行时。当前的增量更新是资料级维护，尚未涉及向量索引的增量重建。

2026-10-10 资源约束更新：当前保留本地原文检索与显式生成、保存的 LLM Wiki 预览，不新增常驻 embedding 模型、向量服务或容器。保存的 Wiki 目录尚未接入默认对话检索；实验导航仍需通过知识质量门槛。下列向量/混合检索路线作为可选扩展设计保留，不作为当前默认部署建议。

资料管理与检索各自解决什么问题

Obsidian、Notion、Workflowy、腾讯文档用于编辑、协作和组织原文。向量索引用于按含义找相关片段。两者可以同时使用：保留文档标题、层级、链接和版本作为可靠原文，再为其中的段落建立搜索索引。

建议的数据流程为：

笔记或业务文档
  → 授权读取 / 导出
  → 统一正文与来源信息
  → 按章节切分、建立关键词和向量索引
  → 按用户与角色过滤、检索相关片段
  → 将片段及出处交给当前对话模型

文件夹与标题结构适合限定主题、定位原文；向量适合问题改写和同义表达；关键词适合产品型号、人名、订单号等精确词。推荐将结构信息作为过滤条件或片段上下文，并结合关键词与向量搜索，而不是要求一种检索方式承担所有任务。

文档来源怎么选

Obsidian 的笔记以本地 Markdown 文件保存，适合直接用 Python 管理原文与增量索引。官方存储说明

Notion 的子块读取接口返回分页内容；完整页面可能需要递归读取嵌套子块。应按获授权的页面同步，并处理后续访问权限变化。官方子块接口

Workflowy 官方已提供面向应用与 AI 助手的 API，可作为后续连接器的入口。官方 API 说明

聊天中提到 Workflowy 外接腾讯文档；这里应区分「节点含有文档链接」与「能授权获取文档正文」。同步节点中的链接并不会自动同步目标文档，需要单独处理目标平台的权限与内容读取。当前网页导入也不能替代这类授权连接器。

检索方式怎么选

混合检索可用 Reciprocal Rank Fusion（RRF）合并各路排名，必要时再用 reranker 给候选重新排序。Qdrant 提供混合检索与融合能力；pgvector 官方也给出了与 PostgreSQL 全文检索结合的方式。Qdrant 混合检索教程、pgvector 官方说明

三条实际接入路径

路径一：Python + Qdrant，适合自主维护检索

这是需要独立向量服务时的可选路线：用现有导入与绑定作为入口，通过 Qdrant 官方 Python 客户端构建独立检索适配器。当前资源约束下不部署此服务。

1. 选择能覆盖中文业务语料的 embedding 模型，用真实问题评估；不能直接把英文教程里的模型效果当作中文效果。
2. 按 Markdown 标题、段落或文档章节切分，给每个片段保留标题路径、来源 ID、用户、版本和内容哈希。
3. 建立稠密向量和关键词或稀疏检索路径；分别检索、融合，再返回少量片段。稀疏模型也需验证中文支持。
4. 所有检索路径都在查询时应用服务端确认的用户和已绑定文档过滤条件，给常用过滤字段建 payload 索引。
5. 通过 KnowledgeBaseToolSource 将结果交给现有对话模型；无需接管语音会话编排。

Qdrant 支持 payload 条件过滤，并建议对过滤字段建索引。它提供的是检索底座，原文管理、增量更新与角色授权仍需要本项目实现。官方过滤文档

路径二：PostgreSQL + pgvector，适合统一持久化

若部署中已确定用 PostgreSQL 保存资料与角色绑定，可以将原文、片段、权限关系和向量放到同一数据库。pgvector 提供向量相似度搜索，并可结合 PostgreSQL 全文检索构建混合检索。pgvector 官方仓库

接入时建立文档、片段、绑定三类记录；查询先限定用户与角色允许的文档，再检索与融合结果。中文全文搜索需要单独选择和验证分词方案，不能默认 PostgreSQL 的默认文本搜索配置就满足中文 BM25 要求。当前知识目录仍是 JSON 文件，这条路线还需要目录迁移与数据访问层改造。

路径三：Dify 检索 API，适合优先获得管理界面

若最快获得上传、切分、索引状态等可视化管理能力是首要目标，可先在 Dify 管理资料，再由 Python 适配器调用知识库检索接口。让 Dify 返回片段，当前项目继续负责语音与答案生成。

官方 API 定义包含 POST /datasets/{dataset_id}/retrieve。应以所部署版本的官方 API 文档核对请求、检索配置与返回字段，使用知识库 API 凭据。Dify 官方 API 定义

接入顺序：创建知识库并完成索引 → 用独立请求验证片段结果 → 服务端建立用户/角色到远程知识库和文档的映射 → 实现适配器 → 接通测试检索与会话检索。共享远程知识库时必须能在请求中限定允许的文档；如果 API 无法满足所需过滤，就按权限隔离知识库。

Dify 的远程知识库不会因配置地址而自动出现在当前资源页。仍需补充远程资料列表、绑定映射与索引状态展示；密钥保存在服务端。外部服务不可用时应明确报错，不能当作「没有相关资料」。

当前项目具体从哪里接

现有检索协议是一个小型 Python 接口：

from typing import Protocol

class KnowledgeBase(Protocol):
    async def search(self, query: str, *, top_k: int = 3) -> list[str]: ...

适配器只需返回片段字符串，建议沿用当前的资料标题、文档 ID、来源 URL 和 <untrusted_knowledge> 数据边界。用户与角色范围由服务端身份和绑定解析，不能让模型在工具参数中自由选择其他用户的资料。以下是改造位置，属于实施清单：

目前 Python 会话与 TypeScript 测试检索分别实现了关键词评分，接外部后端时需要一起切换。仅替换 Python 类会造成「测试与会话使用不同引擎」。

建议把后续 Python 模块分成来源读取、文本切分、embedding、索引写入、范围解析、检索适配器几部分，直接使用 SDK 或 HTTP 客户端即可。现有 Protocol 和 ToolSource 已具备扩展点，无需为了这次接入引入 LangChain。是否使用框架应取决于需要的组件与维护成本，不能仅凭发布时间判断是否过时。

如何快速推进并验收

1. 先完成现有闭环：整理一组高质量 Markdown 或问答资料，按使用指南导入、绑定，并记录命中与失败问题。
2. 选择一个检索后端：偏自主、Python 模块化选 Qdrant；已有 PostgreSQL 统一持久化计划选 pgvector；管理界面优先选 Dify。这些是本项目的选型判断。
3. 用同一组问题比较：覆盖精确名称、同义表达、条件例外、无答案问题和中文问题，记录原文能否进入前 3 个结果及检索耗时。
4. 接通两条调用路径：让资源页测试与语音会话使用相同后端；验证用户隔离、角色绑定、取消绑定，以及超时和服务错误。
5. 再加自动同步：先做 Markdown 文件哈希与版本替换，再按实际资料来源加入 Notion 或 Workflowy 连接器；同步删除和撤销权限也要更新索引。

语音场景还需测量从提问到首段可播放回复的耗时，embedding、外部请求与 reranker 都会增加等待。建议先限制候选数和返回片段数，再根据实际测量决定是否加入额外重排序。

验收至少应包含：原文问法与改写问法均命中、资料不足时明确说明、用户之间不能互搜、角色取消绑定后无法检索、来源可追溯，以及更新资料后旧版本不再参与检索。通过这些检查再逐步扩大资料规模。