一份 PDF 从上传到能被智能体检索，中间要经过入库确认、解析、分块、多路建索引几个阶段。每个阶段都有自己的状态和失败处理。理解这条链路，能帮你看懂处理进度，也能在出问题时判断该“重建索引”还是“重新解析”。
从上传到可检索
document_index + indexing_outbox 同一事务写入 → 转发到各索引队列- 上传进暂存区
文件先进入暂存区，只占存储，不消耗解析资源。暂存后超时未确认的文件会过期清理。
- 确认入库
确认时校验配额，文档转为待处理并进入解析队列。开启延迟索引时可以只入库、不处理，之后再批量启动。
- 解析器链
按扩展名和管理员配置，在已启用的解析器里依次尝试，直到有一个成功。解析期间持续发送心跳，卡死的任务会被发现并重新入队。
- 写出中间产物
正文、标题树、分块和图片描述写入对象存储。这组产物是后面所有索引的唯一输入。
- 可靠分发
在同一个数据库事务里为每个启用的索引创建记录和发件箱条目，再由转发器投递到队列。数据库状态和消息投递不会彼此丢失。
- 多路并行建索引
向量、全文、图谱、图片各自独立推进、独立成败。一路失败不影响其他已完成的索引被检索。
- 完成
所有启用的索引都到达终态，文档可以被完整检索。
解析器链：一个失败，下一个接上
ApeMind 支持十多种解析器：进程内的轻量解析器默认可用，OCR、远程文档转换等增强解析器由管理员按需开启。解析时只调用已启用、配置完整、并且声明接受这种扩展名的解析器，按顺序尝试。
关键在于失败分两种。可回退的失败，比如扫描件里提取不到文字、服务暂时不可达，交给下一个解析器；不可回退的失败，比如文件损坏，立即终止，不浪费后面的资源。选一种文件，打开或关闭几个解析器，看链路怎么走。
链路为简化示意，只列出与示例相关的解析器；失败语义与产品一致。
链路全部失败时，错误里带着每个解析器的尝试记录：谁跳过了、谁因为什么回退、最后卡在哪里。状态页上看到的“解析失败”可以一路追到具体原因。解析成功后，产物也会记下最终是哪个解析器成功的。
分块：在自然边界上切
解析出的正文会被切成片段，作为检索和引用的基本单位。切分需要兼顾上下文完整性与长度限制；块大小和重叠量以知识库配置为准。
自然段和句子边界有助于保留完整意思。下面用简化示例展示块大小与重叠对切分的影响；实际结果还取决于文档结构和已设置的边界。
…
标签表示切点：深色为自然边界，红色为硬切；斜纹为与下一块重叠的部分。右上角的解析版本随分块参数实时变化。
片段还可以带有章节、标题、页码（解析器支持时）及相邻片段信息，帮助检索结果回到对应内容。
查看与调整文档切分
在文档的切分视图中，结合原文查看每一块的内容。相关段落被拆开时，可以合并相邻块；内容过长或主题变化时，可以在可编辑的段落、句子边界拆分或移动切点。AI 建议可以逐条接受或拒绝，确认预览后再保存。
保存会重新处理文档并构建索引；新版本就绪前继续使用已有可用结果。长表格、代码等结构仍受长度限制；PDF 通过 Markdown 编辑后不保留原始页码。调整后可用固定问答集核对答案与引用，判断改动是否有帮助。
解析版本：可复现的身份
每次解析都有一个 16 位的解析版本号，由三样东西共同决定：
parse_version = SHA256( 解析器配置指纹 | 文件内容 MD5 | 分块参数 )[:16]换了解析器配置、文件内容变了、分块参数改了，任何一项变化都会得到新的版本号；三者都没变，版本号就不变。配置指纹排除了密钥，轮换凭据不会触发重新解析。
目标版本的解析产物完整可用时，可以复用这些产物，避免重复解析。片段、图片引用与图谱来源记录也关联解析版本，便于追踪结果；复用解析产物并不意味着后续建索引没有计算成本。
重建索引还是重新解析
两者都能“让文档重新处理一遍”，但读的输入完全不同：重建索引只读已经完成的解析产物，不碰源文件；重新解析从源文件开始，生成一个新的解析版本，再按知识库当前启用的索引重建。选一个你遇到的情况：
重新解析失败时，旧的、已经可用的索引不会被提前清除，检索继续使用旧结果。同一篇文档同时只允许一个重新解析或重建任务在跑；较早发起的任务即使后完成，也不能覆盖较新的结果。
知识更新时，减少重复计算
修改文档或切分后，符合复用条件的未变化内容可以沿用已有向量和图谱抽取结果。实际复用范围取决于内容、配置和已有结果，首次处理仍需计算；维护知识库时，应以任务记录核对耗时和用量。
边界
- 扫描件、图片和音视频需要管理员开启 OCR 或语音转写服务；默认部署只包含进程内的文字类解析器。
- 第三方云端解析需要凭据和外网，文件会离开你的网络。有数据驻留要求时选择自托管的解析服务。
- 解析质量取决于源文件。复杂版面、手写体、低清扫描件即使走 OCR 也可能丢失结构。
- 重新解析失败时旧结果继续可读，但这是失败隔离，不是零停机切换：成功后新版本会替换旧版本。
出问题时查哪一环
文件一直停在暂存区
两阶段上传需要确认入库后才会开始处理。开启了延迟索引时，确认后文档会停在“已入库”，需要显式启动处理。
扫描版 PDF 解析失败或内容为空
默认解析器只能提取文字层。请管理员开启支持 OCR 的解析器（如 MinerU，或 ApeMind PDF Parser 搭配 PaddleOCR），然后重新解析这篇文档。
旧版 .doc / .ppt 解析失败
默认路径需要系统安装 LibreOffice 先做格式转换。没有安装时会回退给其他解析器；都不可用时链路失败，错误里会写明缺少的依赖。
部分索引完成，部分失败
每路索引独立成败，已完成的索引可以正常检索。对失败的那一路单独重建即可，不需要重新解析。
给想深入的读者：哪些状态是权威的
文档级索引状态以数据库里的索引记录为准，Redis 只是传输层。数据库状态和队列投递之间由事务发件箱衔接，转发失败可以重放；协调器根据文档状态、心跳新鲜度和索引记录判断任务是否卡住，在有界预算内重新入队，连续恢复失败则标记为失败并保留最近的错误。