xerrors--yuxi/docs/intro/knowledge-base.md

知识库与知识图谱

Yuxi 提供文档知识库、向量检索、知识导图和知识图谱构建能力。当前支持 Milvus 知识库、Milvus 知识库内的图谱构建/展示/检索，以及 Dify Dataset、Notion Data Source 只读检索。

为什么需要知识库

在大模型应用场景中，仅依靠模型的内部知识往往不够准确和全面。通过构建知识库，我们可以：

• 注入私有知识：让模型能够回答基于私有文档的问题
• 降低幻觉：回答内容可追溯到原始文档
• 知识复用：一次上传，多轮对话中重复使用

知识库类型

类型	特点	适用场景
Milvus	高性能向量检索，支持文档入库、检索测试、知识导图、评估和知识图谱构建	自建文档知识库与生产检索
Dify	连接 Dify Dataset 检索 API，只读连接器	复用已有 Dify 数据集
Notion	连接 Notion Data Source 检索 API，只读连接器	复用已有 Notion 页面内容

只读连接器（Dify、Notion）仅用于检索，不支持上传与入库；历史 LightRAG 类型不再作为受支持类型展示或创建。

创建知识库

访问 Web 界面的「知识库」页面，点击「新建知识库」：

1. 填写知识库名称和描述
2. 选择知识库类型（Milvus、Dify 或 Notion）
3. Milvus 配置嵌入模型和分块策略；只读连接器（Dify、Notion）按类型动态渲染连接参数（如 API URL、Token、Dataset ID 等）
4. 配置访问权限
5. 保存

::: tip 提示 知识库的名称和描述会被智能体用来判断何时应该使用这个知识库进行检索，所以请尽量详细地描述。 :::

文件处理流程

Milvus 文件从上传到可检索，经历三个阶段：

1. 上传阶段

将本地文件上传到服务器。文件保持原始格式存储。

2. 解析阶段

系统将文件转换为 Markdown 格式：

• 提取文本内容
• 图片上传到 MinIO，并在 Markdown 中用 URL 引用
• 表格、公式等尽量保持结构化

3. 入库阶段

系统对 Markdown 内容进行分块，将 chunk 内容与元数据双写到 PostgreSQL 的 knowledge_chunks 表，并将向量写入 Milvus。

在前端界面中，默认会自动完成前两个阶段。如果需要自动入库，勾选「上传后自动入库」选项；否则需要手动点击入库按钮。

知识导图与示例问题

Milvus 知识库详情页提供「知识导图」Tab，用来把知识库文件列表整理成层次化结构。生成时，后端会读取当前知识库的文件元数据，把文件名和类型交给默认模型生成 JSON 树，并保存到知识库的 mindmap 字段。文件数量较多时，当前实现最多取前 20 个文件参与生成，避免一次提示词过长。Agent 运行时也可以通过 get_mindmap 工具读取这份结构，用来快速判断知识库大致包含哪些资料。

导图支持增量更新：详情页的「增量更新」按钮会先调用 GET /api/knowledge/databases/{kb_id}/mindmap/diff 检测当前文件列表与已追踪文件之间的变化，再通过 POST /api/knowledge/databases/{kb_id}/mindmap/generate?incremental=true 仅处理新增/删除的文件。纯删除场景不需要 AI 调用，直接对现有树做递归手术；新增文件时由 AI 整合进现有分类结构。单文件删除与批量删除接口成功后也会同步移除导图快照中对应的叶子节点，不需要再手动触发增量更新。

知识库还支持生成示例问题。该能力会基于文件列表生成适合检索测试的问题，并保存到 sample_questions 字段；前端检索测试区域会优先使用这些问题作为查询示例。示例问题只依赖文件元数据，不等同于对每个文档全文做总结；如果要在对话中围绕具体内容回答，仍应通过 query_kb、find_kb_document 和 open_kb_document 检索原始 chunk 或文档片段。

知识库权限控制

每个知识库可以配置独立的访问权限：

• 全局共享：所有用户可访问
• 部门共享：指定部门可访问，且必须包含当前用户所在部门
• 指定人：仅创建者、管理员及被明确授权的人员可访问

权限规则：

• 超级管理员可访问所有知识库
• 管理员可访问共享知识库和本部门的知识库
• 普通用户只能访问已授权的知识库

知识图谱

Milvus 知识库详情页提供「知识图谱」Tab。图谱构建流程会从已入库 chunks 中抽取实体和关系，将 entity/triple 本体与 chunk 引用写入 Neo4j 和 PostgreSQL，并为唯一实体/三元组建立 Milvus 语义索引；检索时可召回图谱实体与三元组，并与 chunk 命中结果融合（RRF）。

主要能力：

• 配置 LLM 抽取器，更多抽取方式拓展中
• 构建待索引 chunks 的图谱实体与关系
• 查看构建状态、标签和统计信息
• 在知识库详情页搜索和展示子图
• 重置图谱配置与已构建数据

Neo4j 仍作为 Milvus 图谱存储服务保留，但不再提供独立 /graph 前端页面，也不再支持上传 JSONL 三元组到默认全局图谱。

Neo4j 配置

Neo4j 连接信息可以在 .env 中配置：

• 默认账户：neo4j
• 默认密码：0123456789
• 管理界面：http://localhost:7474
• 连接地址：bolt://localhost:7687

API 使用

如果需要通过程序批量处理文件，可以使用以下接口：

# 1. 上传文件
POST /api/knowledge/files/upload?kb_id=<知识库ID>
# 返回 file_path 和 content_hash

# 2. 解析并入库
POST /api/knowledge/databases/{kb_id}/documents
# 返回 status=queued 和 task_id

系统会自动去重：基于内容哈希判断是否已存在相同文件。