从来源版本到索引发布，设计能够更新、删除和回滚的知识入库流水线。
本文于 2026-09-12 补充整理，按 2026-04 专题归档。示例为方案设计，参数用于说明方法，不代表已上线项目或实测成果。
入库是一条发布流水线
知识库最容易被低估的部分是更新。文档第一次进入向量库后，标题可能更名、权限可能收紧、正文可能删除。如果只支持“新增文本并向量化”，半年后就会出现旧规范持续被引用的问题。
这里设计一个支持重建的入库模型：来源文件保留原始版本；解析结果保留结构；切片属于一个确定的文档版本；索引通过发布指针切换。模型只检索已发布版本，不直接读取正在构建的数据。
标识必须能追溯来源
document:
tenant_id, document_id, source_uri, source_version
content_hash, acl_version, deleted_at
chunk:
document_id, source_version, chunk_id
heading_path, source_locator, text_hash
parser_version, splitter_version, embedding_model
index_release:
release_id, status, manifest_hash, activated_at
这些字段是逻辑设计，实际可拆表。document_id 标识同一来源对象，不能仅依赖文件名；source_locator 可以是页码或段落路径，用于展示引用。内容哈希用于判断变化，但不能代替权限版本。
同一正文换了 ACL，即使无需重新计算向量，也必须更新检索可见性并使相关缓存失效。
切分先保留结构
部署规范通常包含标题、步骤、代码块和表格。固定字符数切分可能把“仅适用于测试环境”留在上一片，把危险命令留在下一片。可以先按标题和段落分块，再对过长块进行 token 预算切分，并附带标题路径。
例如先比较约 300 token 和 600 token 的两组切片，搭配有限重叠；这些只是实验起点。分词器、文档类型和模型不同，不能把一个数字写成通用最佳值。
表格需要重复列名，代码块需要保留语言与上下文。对于扫描 PDF，解析失败应该进入隔离队列，不能以“空字符串成功入库”掩盖异常。
增量更新如何避免半成品
建议让流水线经过 DISCOVERED → PARSED → EMBEDDED → VALIDATED → ACTIVE。同一来源版本的重复任务通过唯一键或任务账本去重。新版本完成抽样检查后，再原子切换发布指针。
如果第 80 个切片向量化失败，旧版本继续服务，新版本保持未发布。不要先删除旧切片再开始远程调用，否则依赖故障会直接造成知识缺口。
大知识库不一定每次复制全部索引。可用发布清单记录各文档的有效版本；实现复杂度增加时，需要验证检索引擎能否高效应用这个版本选择条件。
删除要贯穿所有副本
收到删除通知后，优先撤销在线可见性，再异步清理切片、向量和缓存。旧发布版本回滚时也必须应用当前删除和权限规则，不能恢复已经撤销的数据。
原始文件、解析缓存、对象存储和备份保留策略需要一起考虑。不能因为向量库删除成功，就宣称原文已经从所有系统移除。
一次可验证的更新实验
准备一份包含环境限定和表格的规范，发布 v1；修改一个段落生成 v2；在向量化阶段注入失败。应仍然检索到完整 v1，而不是混合答案。重试成功后，引用必须指向 v2 的正确段落。
随后撤销用户权限，重复之前的查询。验收要求缓存和引用都不再返回该文档。整个实验要记录解析器、切分规则、向量模型和发布清单，确保下一次可以重建相同输入。
关于向量存储的基础能力，可查阅 pgvector 官方仓库。本篇的版本发布和删除流程属于应用层设计，并非向量扩展自动提供的功能。
