夜雨聆风RAG入库不是“上传后自动切片”。FDE要把采集、解析、切片、元数据和索引做成可追溯、可重跑、可删除的生产流水线。
INSIGHT
本篇核心学习成果
画出从权威源到生产索引的五步入库链路。
定义支持版本、权限、生效时间和溯源的数据契约。
根据文档结构选择切片粒度，而不是盲目调整字符数。
用幂等、隔离队列和删除闭环防止脏数据进入生产。
图 1：入库链路的终点不是向量，而是每个切片都能返回权威原文、版本和权限。
INSIGHT
01 生产问题：文档进了库，答案却更不可信
一家企业把文档网站、共享盘和邮件附件全部接入RAG。演示时能问到答案，上线后却出现三类故障：同一制度的新旧版同时被召回；图片扫描件解析为空文本却被标记成功；原文已删除，向量库里的切片仍在提供答案。
问题不在模型，而在入库系统没有说清“这是什么、从哪里来、什么时候有效、谁能看、怎么撤回”。
INSIGHT
02 先立数据契约，再谈切片
最小文档契约建议包含：
doc_id：跨系统稳定的业务标识，不要用临时文件名代替。
version与effective_at：区分“最后修改”和“业务生效”，答案应按后者判断。
acl与tenant_id：在入库阶段保留权限属性，查询时必须先过滤再排名。
source_uri与page_anchor：让引用可以回到原页、标题或表格单元。
checksum：判断内容是否真的变化，避免重复解析和建索引。
owner与classification：明确数据责任人及敏感级别，便于删除、质量与审计闭环。
必填字段缺失时，记录应进入QUARANTINE，不得用默认值“补齐”后混入生产。特别是acl缺失不能解释为所有人可见。
图 2：切片不是一段孤立文字；标识、版本、权限、时间和来源共同构成它的生产身份。
INSIGHT
03 五步流水线：每步都要能单独重跑
Collect：只从登记的权威源拉取，保留源系统标识、修改时间和权限快照。拉取成功不等于解析成功。
Parse：对PDF、Office、HTML和扫描件分别选择解析器，输出标题层级、段落、表格、页码与置信度。空文本、页数不符或低置信度页面不应继续。
Chunk：先按章节、条款、表格和步骤的语义边界切，再用长度上限保底。每块保留父标题和相邻重叠，但不要让重叠制造多份相同证据。
Enrich：添加标题、关键词、业务实体和可检索问题等元数据。机器生成字段要与原文字段分开，并保留生成版本。
Index：同时写入原文、可检索文本、向量和过滤字段。建索引成功后还要抽样回读，确认块数、权限和源链接没有在写入时丢失。
INSIGHT
04 切片决策：看问题，不看一个固定数字
制度问答常以条款为单位，操作手册常需保留完整步骤，会议纪要需联系议题与决议，表格则要带上表头和行标题。如果只按每五百字硬切，很容易把适用条件与结论拆开。
切片试验要回答三个问题：目标问题所需信息是否在同一块？被召回时能否上下文独立阅读？引用能否精确回到原文？用真实查询的Golden Set比较方案，不用“觉得这个大小合适”做决策。
INSIGHT
05 幂等、版本和删除：完成入库的后半程
用doc_id + version + checksum生成稳定处理键。相同输入重跑时直接命中缓存；内容变化时生成新版块，完成验证后再切换活跃版本。不要先删旧版再写新版，否则中途失败会留下知识空窗。
删除也是流水线：接收源系统删除事件，标记文档不可检索，清理全部切片和缓存，最后回读确认零召回。删原文不删索引，等于在生产中保留幽灵知识。
图 3：断点续跑、隔离队列、版本切换和删除回读，让流水线失败时仍然可控。
INSIGHT
06 常见失败分支
源文档重复：先用业务标识聚合，再用哈希判断内容；不要只靠文件名去重。
解析局部失败：保留失败页和错误码，文档进入待复核状态，不用残缺文本冒充全文。
权限拉取失败：默认关闭该文档的可见性，而不是沿用上次或公开权限。
向量服务超时：保留已完成块状态，按块重试并限速，不重跑整份文档。
新版校验失败：继续服务已验证的旧版，新版保留在候选索引中排查。
INSIGHT
07 离线实作：先守住契约底线
example/fixture.json是一条完整的模拟制度记录。ingestion_contract.py检查七个必填字段，并用文档、版本和正文生成稳定切片标识。执行：
cd example
python3 -m unittest -v test_ingestion_contract.py
python3 ingestion_contract.py
它不代替真实解析器，但能证明一条重要规则：必填元数据不完整时，记录只能进隔离队列，不能带病入索引。
INSIGHT
08 让入库可观测：不只记一个成功率
每次处理应生成run_id，每份文档记录stage/status/attempt/input_hash/output_count/error_code/duration_ms。当业务反馈“刚发的制度查不到”时，运营人员才能判断是采集没拉到、解析被隔离、向量超时，还是索引已写入但发布别名未切换。
至少跟踪五类运营指标：源变更到可检索的延迟；按解析器和文档类型分组的隔离率；每份文档生成的切片数异常；权限与源系统对账的差异数；删除事件到零召回的时长。“处理了一万份”是吞吐量，不是知识质量。
告警要能转化为行动。例如隔离率突然上升时，先按源系统、文件类型和错误码切片；权限对账失败时，暂停对应数据域的新版切换；删除SLO超时时，优先关闭检索可见性，再处理物理清理。
INSIGHT
09 入库发布不要直接覆盖生产索引
对重要知识域，先写入候选索引，运行三类检查：契约完整性，从文档到切片的数量对账，以及十到二十条关键查询的检索烟雾测试。通过后再原子切换索引别名，并保留上一版到回滚窗口结束。
如果候选索引的块数比上一版骤降，或关键查询的期望证据消失，这次发布应失败，而不是相信“新解析器更先进”。回滚时切回旧别名，同时保留候选索引与run_id供排查，不要立即销毁故障证据。
INSIGHT
10 30分钟练习
用一份公开制度制作两个版本，为每版填写六个核心元数据。
删除新版的acl，确认校验器返回QUARANTINE。
恢复权限后修改正文，检查切片标识是否随内容变化。
写一条删除验收：原文删除后，按doc_id检索必须返回零结果。
图 4：一次合格的入库练习，应同时覆盖正常路径、字段缺失、内容变更和删除回读。
INSIGHT
11 上线前的六问
每个切片能否找回权威原文？新旧版本能否明确切换？权限缺失是否默认拒绝？单步失败能否从断点恢复？删除后能否证明零召回？数据Owner能否看懂隔离队列并重处理？
交接时还要留下三份文档：数据源与Owner清单，包含认证方式、变更频率和新鲜度SLO；字段与状态字典，说清契约、空值和隔离原因；运行手册，覆盖重跑、版本切换、删除、回滚和证据保留。接手人应能不询问原作者，独立重处理一条隔离记录并证明它最终进入正确版本。
同时为每个数据源指定停止条件：权限无法对账、解析缺页、隔离率超阈、删除无法闭环或关键查询回归失败时，系统应暂停该源的新版发布，不影响已验证版本继续服务。
只有这六个问题有可检查的答案，文档才算真正进入RAG生产系统。把文档变成向量很容易；把知识变成可治理、可撤回的企业资产，才是FDE的工程价值。
人人会AI-智能体进阶
把工具变成方法，把方法变成流程，把流程变成自己的 AI 工作系统。
