主题
01 - 文档接入与解析
一句话：一份文档从上传到可检索要过四道——解析、切片、向量化、就绪，麻烦全在第一道：PDF 的表格和扫描件一旦在解析阶段丢了结构，后面调什么参数都补不回来，所以“解析任务成功”从来不是验收，抽得出原文的章节关系才算。
一、入库链路
四段各有独立责任：解析归引擎的文档处理链路，切片由解析器配置决定，向量化取决于 embedding 服务，就绪状态是前三段都成功。任何一段失败都不该让文档“看起来在库里”。
上传入口两条：管理台手工上传，和 Connector 定时同步企业网盘与文档系统。两条走同一条解析链路，区别只在触发者。
二、解析是质量的地基
企业文档的坑集中在三类：
| 文档类型 | 会在哪里丢信息 | 生产做法 |
|---|---|---|
| 纯文本 / Markdown | 基本不丢，可能切碎代码块 | 按标题层级切，代码块整体保留 |
| 含表格 PDF | 表头与单元格关系被压成一行文本 | 走表格结构还原，转成带表头的结构化文本再入块 |
| 扫描件 / 图片型 PDF | 识别错字、漏行、表格线断裂 | OCR 后进人工抽检，未过抽检不进默认检索 |
| 图表与架构图 | 图里的结论完全丢失 | 能转表的走图表转表；补不了的单独成块、带上下文并标注“来自图”，且只参与定位不参与重排（见 02、06） |
解析这一层由三个能力拼成，选型时容易被当成一个：版面与文字检测识别（含中文扫描件基线）、表格结构还原（转成带表头的结构化文本）、图表转表与公式识别。第三项对图表类文档必须单独确认覆盖范围，缺位时按“需改写”或“拒收”处置（见 08），不要在检索层补救。工作流形态的解析节点用来把解析挂到上游系统的变更事件上，批量重解析与增量重解析走同一条路径，不另起一次性脚本。
判断解析有没有做够，不看任务状态，看内容能否还原：随机抽 20 份解析结果，逐份对照原文回答“这一段的上级标题是什么、表格第 3 行第 2 列是什么”。抽不出来就是解析丢信息，下游检索调参救不回来。
三、切片的默认取值
原则一句话：结构优先，长度兜底。先按标题、段落、列表、表格这些自然边界切，边界内超过长度上限再按 token 二次切。
| 项 | 取值 | 说明 |
|---|---|---|
| 目标块长 | 300–800 token | 经验值；技术文档偏短利于定位，制度条款偏长保证一句规定不被切断 |
| 相邻重叠 | 10–15% | 经验值；用于兜住跨块指代，不是越多越好 |
| 硬上限 | 不超过 embedding 输入窗口 | 超了就是静默截断，比召回差更难查 |
| 表格 | 整表一块，带表头 | 拆行会丢行列关系 |
| 代码 | 按函数或代码块成块 | 不按行切 |
把上面原则落成一张可执行表（取值是经验起点，首轮上线后按各桶评测结果校准，不当作实测值）：
| 文档类型 | 切片策略 | 块长 / 重叠 | 检索取值 | 就绪抽检判据 |
|---|---|---|---|---|
| 制度、法规条款 | 按标题与条款边界，整条不拆 | 600–800 / 10% | 关键词权重不低于语义，重排开 | 条款号整条命中，不出现半条 |
| 技术手册、接口文档 | 按标题层级，代码块整体保留 | 300–500 / 10% | 双路召回，重排开 | 错误码与接口名精确串可查 |
| FAQ、问答对 | 一问一答配成块 | ≤300 / 0 | 语义权重可上调 | 同义问法命中同一块 |
| 报表、含表 PDF | 整表一块并带表头；超限按行组切且重复表头 | 表不按长度二次切 | 重排必开，送入 ≤4 条 | 指定行列定位题答对 |
| 论文、长报告 | 按章节，父子块开 | 500–800 / 15% | 多跳桶达标才开父子块 | 跨节指代题可答 |
| 扫描件、图文混排 | OCR 后按版面块，图单独成块 | 300–500 / 10% | 强制人工抽检后才进默认检索 | OCR 错字率与页码回链同时合格 |
| 会议纪要、个人笔记 | 默认拒收，最多降级为参考源 | — | 不进权威源清单 | 拒收留回执 |
父子块与上下文增强块默认关。开的条件只有一条：黄金集里出现“文档找到了、但块内信息不完整”的题型，也就是模型拿到了正确块却缺前后文。代价同步到位——存储与 embedding 成本随块数线性上涨，索引重建时间也涨。
四、就绪状态怎么判
解析任务返回成功只说明流程跑完，不代表内容可用。生产上“就绪”要同时满足三条：
- 解析终态为成功，且分块数与按文档长度估算的期望值偏差在约定范围内、空块与乱码块为零——引擎当前只给整篇终态与进度，拿不到分片级失败计数，所以用这三项替代“失败分片数为 0”这种落不了地的判据；
- 抽检通过：新入库文档按比例抽检，能还原章节关系与表格行列；抽检记录（样本、判定人、结论）必须留档，不留档等于没做；
- 元数据归位：负责人、复审周期、所属项目、共享范围、密级五项齐备。任一项缺失即不进默认检索，落“待归位”状态并在管理台可见——与 08 的体检口径一致，不给“缺项但先入库试试看”留口子。
三条不过，文档停在“已入库、不可检索”，在管理台可见但不会出现在答案里。这样比悄悄入库后给出半截答案要好——前者是看得见的延迟，后者是看不见的错误。
五、更新与替换
文档改版是高频动作，规则是先挂新、再停旧、最后清旧：
这里的真风险不是时间窗，而是同一文档两个版本同时可召回导致混版答案——新旧条款出现在同一个回答里，引用还都成立。所以规则是两条：同一文档同一时间只允许一个版本进默认检索；另一版本只能作为兜底来源存在，且引用必须带版本，事后能判定答案出自哪一版。窗口长度按解析耗时定即可，不必压到极短；新版有缺陷时靠版本标签退回，不靠抢时间。
引用要带版本。答案里指向“第 3 页第 2 条”的引用，文档一改版就可能对不上，所以引用快照固定记录当次的文档版本与内容哈希，供事后核对“当时答的是哪一版”。
六、失败怎么分
解析失败不是一类，是四类，处置完全不同：
| 类别 | 现象 | 处置 |
|---|---|---|
| 格式不支持 | 引擎无对应解析器 | 明确拒绝并回传原因，转人工或第三方转换后重投 |
| 超大 / 超长 | 内存或时间超限 | 分片处理；反复失败进人工队列，不无限重试 |
| 内容可疑 | 命中注入模式、异常脚本 | 进隔离区，不参与默认检索，等人工判定（见 03） |
| 依赖抖动 | embedding 服务不可达、向量库超时 | 可重投，带退避与最大次数，超限进死信队列并告警 |
分类的价值在于：前三类是文档问题，重投一百次也不会变好；只有第四类值得自动重试。不做分类的队列会退化成一个不断吞资源、始终不动的状态。
七、边界
- 多模态一期不做：音视频转写、图文混排理解与图表内容抽取均不在本链路承诺，遇到时转人工或单独能力接入。要说清因此无解的题型——会议决议、客服话术、培训录屏往往是口径的唯一记载处，缺了它们表现为“库里有制度却答不上”；将来再入时还要另计转写成本并指定转写块的复审责任人。
- 上游系统的删除与变更事件（连接器）未就绪时，本链路只能靠每日全量清单比对兜底：比对成本随文档总数线性上涨，删除的可见延迟从秒级退化为一天（后果与兜底见 03、06）。
- 扫描件 OCR 的正确率依赖具体文档质量，上线前按库抽检口径判，不用“支持 OCR”这句话代替验收。
- 解析吞吐与并发是容量问题，取值见 05 部署运维与容量，本栏只定判定口径。