# 文档知识库准备（含图片索引）

在文本知识库准备流程中增加页面和文档图片对象的图片索引，适合需要结合图片检索的资料。

## 开始前准备

准备包含正文和图片的文档、文本知识库、图片索引配置及输出卷。先用一份带有代表性图片的资料验证，确认图片可以被解析和索引。

文本嵌入模型处理正文，图片嵌入模型处理图片本身。选择知识库后，检查图片索引是否启用，以及目标表、模型、维度、预处理版本和距离度量是否匹配。仅有图片描述文本不代表已经建立图片索引。

## 使用模板

在创建工作流页面选择“从模板开始”，搜索“文档知识库准备（含图片索引）”并载入画布。

在参数表单中填写以下必填项。

| 配置 | 用途 |
| --- | --- |
| 源文件 | 选择要处理的文档文件或文件夹 |
| 解析档位 | 决定文档解析的速度、质量和费用 |
| 知识库 | 选择已有知识库或创建新的知识库 |
| 输出位置 | 解析结果文件保存到 Catalog 的位置 |

运行前检查[图片嵌入](../nodes/ai-processing/image-embedding.md)配置，确认图片模型和索引维度匹配。

保存参数后发起手动运行，系统先保存当前流程，再提交执行。

## 完整处理流程

连线表示执行顺序；各步骤通过模板配置的数据绑定取得输入。

![文档知识库准备（含图片索引）](../images/document-image-index-flow.svg)

## 调整文本与图片索引

| 配置 | 如何使用 |
| --- | --- |
| 解析档位 | 默认标准；扫描件和复杂版面可选择增强，具体设置见[文档解析](../nodes/ai-processing/document-parse.md) |
| 文本分块 | 模板默认大小 512、重叠 50，按字符计算；先检查正文，再调整分块 |
| 三级文本索引 | 默认开启，Section 大小为 5 |
| 图片索引 | 确认启用，并保留页面和视觉对象的图片引用 |
| 模型与维度 | 图片模型输出维度必须与索引一致，不能直接套用文本模型维度 |

图片索引按原始图片生成向量。本模板允许文件没有可索引图片：`no_indexable_images` 表示该文件未写入图片向量；`disabled` 表示图片索引被禁用。两者都不能当作图片索引成功。

## 运行后逐项核对

1. 检查读取文件的数量和解析文档中的图片来源。
2. 在文本索引步骤查看 `written`，在图片索引步骤查看 `page_rows`、`visual_object_rows` 和 `file_statuses`。
3. 核对 `indexed_source_file_ids`，确认目标文件实际进入图片索引。`all_source_file_ids` 仅表示本次考虑的来源。
4. 查看输出卷中的解析文件，再检查文本和图片两次血缘登记的来源关系。
5. 分别用已知文字内容和图片内容验证检索。

模板先完成文本索引，再构建视觉清单和图片索引，最后保存解析文档并登记关系。清单和保存步骤使用分段前的解析文档，文本索引使用分段结果。

## 示例：准备含插图的设备手册

选择一份同时包含参数表和设备示意图的手册。保留默认分块配置，检查文本知识库与图片模型配置后运行。先对照参数表检查文本结果，再对照示意图检查图片记录和来源文件。

图片内容缺失时，先检查解析输出是否有可读取的图片，再检查清单与索引状态；不要只通过文本检索成功判断整个任务完成。

## 常见问题

| 现象 | 检查与处理 |
| --- | --- |
| 文字可检索，图片不可检索 | 检查图片索引启用状态、图片来源和逐文件状态 |
| 图片维度不匹配 | 核对图片模型输出和目标索引配置 |
| 有些文件没有图片行 | 查看 `file_statuses`，区分没有可索引图片与处理失败 |
| 重跑后索引发生变化 | 模板图片写入使用 `OVERWRITE`；运行前确认目标索引与已有结果 |
| 最后登记失败 | 保留运行结果，核对派生图片与原文件映射，再决定是否重新执行已有写入步骤 |

## 继续阅读

- [工作流模板](index.md)
- [运行与调试](../run-debug.md)