# 文档知识库准备

将产品手册、报告等资料解析、分段并写入知识库，同时保存解析结果和来源关系。处理完成后，可以在知识库中检索文档内容，并查看保存的解析文件。

本模板建立文本索引。需要检索页面图片或文档中的图片对象时，选择[文档知识库准备（含图片索引）](document-image-index.md)；需要分析工程图纸时，选择[图纸解析](drawing-parsing.md)。

## 开始前准备

| 准备项 | 如何选择 |
| --- | --- |
| 源文件 | 将待处理资料上传到 Catalog 卷。首次使用可先选一份熟悉的 PDF 或 Word 手册，方便核对结果 |
| 知识库 | 选择已有知识库，或在配置时创建；所选知识库提供文本索引表和嵌入模型 |
| 输出位置 | 准备用于保存解析结果的 Catalog 卷或目录 |

源文件和输出位置分别用于读取和保存。配置时逐项确认，避免把结果保存到不易查找的位置。音频或视频资料请使用对应的[语音](audio-knowledge-base.md)或[视频](video-knowledge-base.md)模板。

## 载入模板

1. 在工作流创建页面选择 **从模板开始**。
2. 搜索 **文档知识库准备**，选择模板并载入画布。
3. 检查画布中的处理步骤，再填写运行参数。

下图展示模板选择入口。

![工作流模板选择界面](../images/template-picker.png)

## 理解处理步骤

下面按模板的执行顺序展示完整流程。框内说明各步骤处理的数据，连线表示先后顺序。

![文档知识库准备的七个处理步骤](../images/document-knowledge-base-flow.svg)

1. **读取 MOI 卷**：确定本次处理的文件，取得文件来源和原始文件 ID。
2. **文档解析**：读取源文件，生成包含正文及来源信息的文档数组。
3. **分段**：对解析文档按长度切分，生成用于索引的文本块。
4. **嵌入并添加到知识库**：为分段结果生成向量，写入所选知识库的索引表。
5. **写出文档文件**：将解析文档写成文件，供后续登记来源关系使用。
6. **存至 MOI 卷**：将解析文档保存到指定输出位置。
7. **血缘登记**：记录原文件、解析产物、结果文件与文本索引之间的关系。

**知识库使用分段结果，文件保存步骤使用分段前的解析文档。** 因此，下载结果文件时看到的记录数量，不一定等于分段数量或索引写入行数。

模板已经配置了这些数据绑定。调整节点时，保留解析结果与分段结果各自的引用，避免让保存步骤误用某个中间节点的输出。绑定方式见[变量与数据传递](../variables-and-data.md)。

## 配置本次处理

### 选择资料和目标

| 配置 | 填写方式 |
| --- | --- |
| 源文件 | 选择要处理的文件或卷；选整个卷时，检查文件范围和类型 |
| 解析档位 | 必填，默认 **标准**；根据资料结构调整 |
| 知识库 | 选择或创建接收文本索引的知识库，确认其嵌入模型 |
| 输出位置 | 选择接收解析结果的卷或目录 |

从卷读取时，可按文件类型筛选。只想验证部分内容时，也可以在解析配置中设置页码范围，例如 `1-3`。页码从 1 开始；未设置页码范围时处理全部页面。

### 选择解析方式

| 资料特点 | 配置建议 |
| --- | --- |
| 常规手册、报告 | 先使用 **标准**，运行后检查正文和表格 |
| 已有文字和结构的 Office 文档 | 可选择 **原生**，检查源文件结构是否被保留 |
| 扫描件、复杂表格、公式或多栏版面 | 使用 **增强**，按需调整表格、图片和阅读顺序选项 |

增强档位的详细参数见[文档解析](../nodes/ai-processing/document-parse.md)。调整解析选项后，先核对正文是否正确，再判断是否需要修改分段设置。

### 调整分段和索引

以下是**本模板**的默认值。

| 配置 | 默认值 | 作用与调整方法 |
| --- | --- | --- |
| 文本块大小 | 512 | 可切分文本的目标字符长度。块内缺少上下文时，可增大后对比；一个块混入多个主题时，可减小后检查 |
| 重叠字符数 | 50 | 相邻块重复保留的字符数。检查跨块内容是否需要更多上下文；必须大于等于 0 且小于文本块大小 |
| 三级索引（doc/section/chunk） | 开启 | 同时建立文档、段落和文本块层级的索引 |
| Section 大小 | 5 | 开启三级索引时，每个段落组合的连续文本块数 |

文本块大小按字符计算，不是模型 Token 数。表格和代码块保留结构，实际长度可能超过目标值。详见[分段](../nodes/ai-processing/chunk.md)和[嵌入并添加到知识库](../nodes/ai-processing/knowledge-index.md)。

## 运行并检查结果

1. 保存参数后发起手动运行。系统先保存当前工作流，再提交执行；如果提示参数缺失，补全并保存表单后再次运行。
2. 打开运行记录，检查读取节点的文件数量，确认本次处理范围。
3. 查看解析节点的正文和来源信息，对照原文件检查标题、表格及关键内容。
4. 查看分段输出，检查段落边界、相邻块上下文和来源信息。
5. 查看知识库写入节点的目标表和 `written`，确认索引写入结果。
6. 打开输出位置，查看保存的解析文件；需要追溯来源时，检查最后的血缘登记结果。
7. 在知识库中检索一段已知内容，核对返回内容是否来自预期文件。

### 各处结果分别表示什么

| 检查位置 | 关注内容 |
| --- | --- |
| 文档解析节点 | `documents` 是解析文档；`plain_text` 便于检查正文 |
| 分段节点 | `documents` 是切分后的记录，保留来源信息 |
| 知识库写入节点 | `written` 是实际写入行数；开启三级索引后包含多个层级，不能直接当作文件数或文本块数 |
| 文件写出与保存节点 | `file_id` 表示主要文件，`file_ids` 覆盖全部结果；多来源输入可能产生多个文件 |
| 血缘登记节点 | 检查来源资产、解析资产和索引资产是否与本次处理对象一致 |

输出保存步骤按 ZIP 配置处理。文件写出步骤的结果也会随解析产物变化：普通记录可写为 JSONL，带有关联解析产物时可形成 ZIP。检查实际返回的文件列表和格式，说明见[写出文档文件](../nodes/other/write-document-files.md)。

## 示例：准备产品手册知识库

以一份包含章节标题和参数表格的产品手册为例：

1. 选择该手册作为源文件，选择用于产品资料的知识库和输出卷。
2. 使用标准解析，保留 512 / 50 的分段设置、三级索引和 Section 大小 5。
3. 发起运行，对照手册检查一个完整章节和一张参数表格。
4. 用手册中有明确答案的问题验证检索，例如某个参数的取值范围，并核对返回内容。
5. 如果参数表格解析不完整，调整增强解析中的表格选项，再用同一份资料对比结果。

重新运行前确认目标知识库和输出位置，检查已有结果是否需要保留；涉及覆盖或重复写入时，先核对相关节点配置。

## 常见问题

| 现象 | 检查方法 |
| --- | --- |
| 处理了不需要的文件 | 检查源文件选择和文件类型筛选，再查看读取节点的数量 |
| 表格缺字或阅读顺序不正确 | 先对照解析输出与原文件；按需切换增强档位，调整表格或阅读顺序设置 |
| 检索片段缺少上下文 | 先确认解析正文完整，再检查分块边界、重叠字符数和多级索引设置 |
| 写入行数比文件数多 | 开启三级索引后会生成多个层级的记录，结合分段结果核对，不能直接按文件数量判断异常 |
| 没有找到保存文件 | 检查保存节点是否完成、目标位置是否正确，并查看全部 `file_ids` |
| 索引已写入，但整个流程失败 | 查看后续写出、保存或血缘登记节点的错误；重新运行前检查已经写入的结果 |
| 希望检索图片本身 | 改用[含图片索引的模板](document-image-index.md)，并配置图片模型与索引 |

更多运行排查方法见[运行与调试](../run-debug.md)。