ForcePilot/docs/intro/knowledge-base.md

# 知识库与知识图谱

Yuxi 提供了强大的知识管理能力，将知识以向量和图谱两种形式存储，既支持传统的语义检索，又能构建结构化的知识关系网络。

## 为什么需要知识库

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

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

## 知识库类型

系统支持两种知识库存储形式，各有不同的适用场景：

| 存储类型 | 特点 | 适用场景 |
|----------|------|----------|
| **Milvus** | 高性能向量数据库 | 大规模生产环境，需要快速检索 |
| **LightRAG** | 图增强检索 | 复杂知识关系，需要图结构理解 |

选择建议：如果是简单的文档问答，Milvus 就足够了；如果需要理解实体之间的关系，构建知识图谱，LightRAG 是更好的选择。

## 创建知识库

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

1. 填写知识库名称和描述
2. 选择存储类型（Milvus 或 LightRAG）
3. 配置访问权限
4. 保存

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

## 文件处理流程

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

### 1. 上传阶段

将本地文件上传到服务器。文件保持原始格式存储（PDF 还是 PDF，Word 还是 Word）。

### 2. 解析阶段

系统将文件转换为 Markdown 格式：
- 提取文本内容
- 图片上传到 MinIO，并在 Markdown 中用 URL 引用
- 表格、公式等保持结构化

### 3. 入库阶段

- **Milvus 知识库**：对 Markdown 内容进行分块，向量存储到 Milvus
- **LightRAG 知识库**：提取实体和关系，构建知识图谱到 Neo4j

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

## 知识库权限控制

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

- **全局共享**：所有用户可访问
- **部门授权**：仅指定部门可访问
- **私有**：仅创建者和管理员可访问

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

## 知识图谱

系统支持两种图谱相关能力，理解它们的区别很重要：

### LightRAG 图谱

针对单个知识库由 LightRAG 自动抽取实体和关系。特点：
- 自动从文档中提取
- 附属于特定知识库
- 用于该知识库内的图增强检索
- 通过知识库 ID 作为 Label 区分，与全局图谱隔离

### 全局知识图谱

通过三元组文件上传的图谱数据。特点：
- 手动导入
- 系统级知识库
- 提供图查询和可视化能力
- 作为工具供智能体调用

两者共享同一个 Neo4j 实例，但数据完全隔离，互不影响。

### 导入三元组数据

系统支持通过网页导入 `jsonl` 格式的图谱数据：

**简单格式**：
```json
{"h": "北京", "t": "中国", "r": "首都"}
{"h": "上海", "t": "中国", "r": "直辖市"}
```

**扩展格式（支持属性）**：
```json
{"h": {"name": "孙悟空", "title": "齐天大圣"}, "t": {"name": "唐僧"}, "r": {"type": "徒弟"}}
```

导入后，可以在图谱可视化页面查看和查询。

### Neo4j 配置

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

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

::: warning 注意事项
确保每个节点都有 `Entity` 标签和 `name` 属性，每个关系都有 `RELATION` 类型和 `type` 属性，否则会影响图的检索与构建功能。
:::

## 常见问题

**Q：只有节点没有边怎么办？**

A：这通常是因为模型调用量受限。请尝试：
- 更换 TPM（每分钟令牌数）更大的模型
- 更换模型服务商

**Q：构建图谱时出现超时错误？**

A：可以配置增加超时时间：
```env
EMBEDDING_TIMEOUT=60
LLM_TIMEOUT=180
```

**Q：LightRAG 和全局图谱有什么区别？**

A：简单理解：
- LightRAG 图谱 = 自动从知识库文档中提取，附属于知识库
- 全局图谱 = 手动导入，系统级图谱查询

## API 使用

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

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

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

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

---

知识库是 Yuxi 的核心能力之一，通过本文档的介绍，你应该能够掌握创建和使用知识库的基本方法。对于更高级的用法，如评估基准构建、图增强检索优化等，可以进一步探索系统的其他功能。