> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enconvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 知识库工作原理

> 了解 Enconvo 如何存储、切分、索引和搜索你的知识库，以及如何保持良好的搜索效果。

本页适合想了解文档进入知识库之后会发生什么的用户：Enconvo 把它存放在哪里、如何切分和建立索引，以及搜索如何挑选结果。你可以据此优化文档集合、改善不理想的搜索结果，或在自己的代码中调用知识库。如果你刚开始使用知识库，请先阅读[知识库](https://docs.enconvo.ai/zh/ai/knowledge-base.md)。

简而言之：Enconvo 会读取每个条目的文本，将其切分为文本块，把每个文本块转换为向量，并将这些文本块存储在本地的 LanceDB 数据库中。搜索时，它会同时按语义和精确字词查找文本块，然后将两者结果融合。

## 数据存放在哪里

| 内容 | 位置 |
| - | - |
| 文本块、向量和全文索引 | 位于 `~/.config/enconvo/.support/knowledge_base/vector/knowledge_base/` 的 LanceDB 数据库 |
| 知识库、条目及其详细信息 | 位于 `~/.config/enconvo/.support/knowledge_base/db` 的 SQLite 数据库（Drizzle ORM） |

所有知识库共用同一个 LanceDB 数据库，每个知识库对应其中的一张表。当 Enconvo 重建某个知识库的索引时，会在旧表旁写入一张新表，待新表准备就绪后再切换过去，因此重建期间搜索仍可正常使用。

每个知识库都有一个 ID。API 中对应的参数为 `knowledge_base_id`，Enconvo 会以 `knowledge_base|<id>` 命令形式运行该知识库。要复制知识库的 ID，请从知识库顶部打开 **知识库设置**，然后进入 **高级**。

存储占用取决于原始文件、提取出的文本、文本块数量和向量维度。请监控集合的实际磁盘使用量，而不要仅凭文档数量估算。请独立于搜索索引保存源文件和备份。

## 内容如何进入知识库

### 读取

Enconvo 会使用最适合的工具读取每种类型的条目：

| 内容 | 读取方式 |
| - | - |
| **PDF** | Document Parser 插件。它会直接读取 PDF 中的文本，仅对扫描页运行你的 OCR 服务提供商 |
| **Word、PowerPoint、Excel、EPUB、CSV** | Document Parser 插件 |
| **纯文本与 Markdown** | 直接按原文读取 |
| **图片** | 你的 OCR 服务提供商 |
| **音频和视频** | 你的语音转写服务提供商 |
| **网页** | 你的获取网页服务提供商 |
| **整个网站** | 网站爬虫，逐页抓取 |
| **YouTube** | 视频的字幕文稿 |

### 切分为文本块

Enconvo 会根据内容的书写语言，将文本切分为相应大小的文本块：

| 文本语言 | 文本块大小 | 重叠大小 |
| - | - | - |
| 以拉丁字母为主（如英文） | 1,500 个字符 | 200 个字符 |
| 以中文、日文或韩文为主 | 560 个字符 | 80 个字符 |
| 混合文本 | 介于两者之间，按各自占比计算 | 介于两者之间 |

它会在保证文本块不超过大小限制的前提下，尽量在最自然的边界处切分，尝试顺序如下：

1. 段落
2. 行
3. 句子
4. 分句
5. 单词
6. 硬切分（最后手段）

电子表格大约按每行一个文本块进行切分，因此搜索某一行数据时就能定位到该行。这些切分大小是内置的，没有单独的设置项。

### 向量化（Embedding）

所有知识库使用同一个嵌入模型：EmbeddingGemma 300M。你可以在 **设置 → 记忆 → 嵌入模型** 中选择它的运行位置：

* **这台 Mac**：免费，且数据不会离开你的 Mac，但在为新内容建立索引时会占用 GPU。需要配备 Apple 芯片的 Mac。
* **Enconvo Cloud**：使用你的 Enconvo 账户免费提供。正在建立索引或搜索的文本会发送到 Enconvo Cloud。

两者运行的是同一个模型，因此切换运行位置后你的搜索索引仍可保留。Enconvo 会分批对文本块进行向量化。

### 存储

每个文本块在知识库的表中占一行：

| 字段 | 存储内容 |
| - | - |
| `text` | 文本块的文字内容 |
| `vector` | 对应的向量 |
| `id` | 文本块的 ID |
| `attachment_id` | 该文本块所属的条目 |
| `type`、`url`、`title`、`ext`、`loc` | 条目的类型、地址、标题、文件扩展名，以及该文本块在条目中的位置 |
| `metadata` | 条目的其他详细信息 |

Enconvo 还会为 `text` 维护一个由短字符片段构成的全文索引，从而能够精确匹配人名、数字、代码以及中日韩词汇。

## 搜索如何工作

每次搜索会同时对知识库的文本块执行最多三种查找：

1. **按语义**：使用同一个模型对查询词生成向量，并查找最接近的向量。
2. **按字词**：对查询中的每个词执行全文（BM25）搜索，过滤掉常见的英文停用词。
3. **按标题**：查找标题匹配查询词的条目，并取其中与查询最接近的文本块。

随后 Enconvo 会对这些结果进行融合。每个列表的分数都会被缩放到 0 到 1 之间，文本块的综合得分为语义得分的 0.6 倍加上字词得分的 0.4 倍。标题匹配的条目，或包含完整查询词的文本块，排名会更靠前。同一条目只会保留少量文本块，避免单个长文档挤占全部结果；同时每个文本块都会附带其前后上下文一起返回。

知识库搜索中没有单独的重排序（reranking）步骤。

## 保持索引健康

Enconvo 会自动创建全文索引并整理数据表。如果某个知识库是使用旧版切分器或不同的嵌入模型建立的，Enconvo 也会根据已保存的文本自动重建其索引，无需重新读取原文件。

如需手动重建：

* **整个知识库**：从知识库顶部打开 **知识库设置**，进入 **索引与搜索**，点击 **重建整个索引** 旁的 **重新索引…**。重建期间搜索仍可正常工作。
* **单个条目**：右键点击该条目并选择 **重新索引**。

**知识库设置** 包含五个部分：**通用**（名称和描述）、**索引与搜索**（索引健康状态、需要处理的条目、搜索模型以及重新索引）、**来源与捕捉**（关联文件夹和捕捉工具）、**AI 客户端（MCP）**，以及 **高级**（ID 和删除知识库）。

删除不再需要的知识库可以释放磁盘空间。

### 关联文件夹

如果发现缺少条目，请先检查源文件夹的导入和同步状态。在 **来源与捕捉** 中，每个关联文件夹都会显示它是否正在同步、上次同步的时间，或提示找不到源文件夹，并提供 **立即同步**、**重新关联…** 和 **自动同步**。

接着分别检查条目的内容提取状态和向量索引状态：条目的 **流水线** 会将 **内容解析** 和 **搜索索引** 显示为两个独立阶段，能够读取到提取出的文本并不代表向量索引已经完成。修复服务提供商或文件访问错误后，请重新索引该条目。

源文件夹始终是关联文件的权威来源。请将离线驱动器恢复与文件删除区分开：当找不到源文件夹时，知识库会保留已有条目。在将一次导入视为完成之前，请先查看被跳过的文件数量。

## 整理多个知识库

每个知识库都有各自独立的文档、索引和数据表。请按你的检索方式来划分内容：

| 策略 | 说明 | 示例 |
| - | - | - |
| **按项目** | 每个项目一个知识库 | `project-alpha`、`project-beta` |
| **按类型** | 按内容类型区分知识库 | `code-docs`、`meeting-notes`、`research` |
| **按团队** | 团队专属知识 | `engineering`、`marketing`、`support` |
| **按范围** | 个人与共享分开 | `personal-notes`、`company-wiki` |

要同时搜索多个知识库，可以通过上下文选择器将它们附加到对话中，或在智能体设置中指定关联的知识库。如果搜索时未指定知识库，则会搜索除“记忆”之外的所有知识库。

## 在代码中使用知识库

Knowledge Base 插件在 [Local API](https://docs.enconvo.ai/zh/advanced/cli-local-api.md) 上提供了相应路由，方便其他插件、工作流和脚本调用。主要路由包括：

| 路由 | 用途 |
| - | - |
| `knowledge_base/create` | 创建知识库 |
| `knowledge_base/delete` | 删除知识库及其所有数据 |
| `knowledge_base/add`、`knowledge_base/add_attachments` | 添加文件、文本、链接或媒体 |
| `knowledge_base/search` | 搜索一个或多个知识库 |
| `knowledge_base/list` | 列出所有知识库 |
| `knowledge_base/get_attachments` | 列出知识库中的条目 |
| `knowledge_base/delete_attachments` | 从知识库中移除条目 |
| `knowledge_base/reindex` | 重建知识库或单个条目的索引 |
| `knowledge_base/summarize` | 总结单个条目 |

打开 **设置 → API** 即可查看当前安装版本中各路由的参数说明。

知识库步骤可以无缝融入工作流和自动化中，例如：

```
Trigger: New file in ~/Documents/research/
  → Add to Knowledge Base "research"
  → Search for related content
  → Generate summary
  → Save summary to notes
```

对于其他 AI 客户端，请使用[知识库 MCP](https://docs.enconvo.ai/zh/advanced/knowledge-base-mcp.md)。它通过本地只读服务暴露选定的知识库，不会导出智能体记忆或录音。

## 故障排除

| 问题 | 解决方法 |
| - | - |
| 搜索返回不相关的结果 | 检查该条目的 **搜索索引** 阶段是否已完成，然后重新索引知识库。尽量使用文档中出现的原词进行搜索：精确的人名和数字会通过全文索引进行匹配。 |
| 建立索引速度慢 | 大文档需要更长时间。使用 **这台 Mac** 时索引会占用 GPU；将 **嵌入模型** 切换为 **Enconvo Cloud** 可以释放 Mac 的资源。 |
| 在 Enconvo Cloud 模式下新增条目无法搜到 | 请登录你的 Enconvo 账户。在登录之前，新内容不会被建立索引，搜索只能找到字面匹配的词。 |
| 某种文件类型不受支持 | 将其转换为 PDF、TXT 或 MD 后重新添加。 |
| 无法通过 ID 找到知识库 | 从 **知识库设置 → 高级** 复制 ID，并将其作为 `knowledge_base_id` 传入。 |

## 相关内容

> [card] [知识库基础](https://docs.enconvo.ai/zh/ai/knowledge-base.md)
>
> 开始使用知识库

> [card] [知识库 MCP](https://docs.enconvo.ai/zh/advanced/knowledge-base-mcp.md)
>
> 从其他 AI 客户端搜索你的知识库

> [card] [记忆](https://docs.enconvo.ai/zh/ai/memory.md)
>
> 搜索模型以及智能体记住的内容

> [card] [工作流](https://docs.enconvo.ai/zh/workflows/introduction.md)
>
> 自动化处理知识库任务


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.