问题与边界
知识库每天更新,直接覆盖索引可能产生半成品结果。需要在隔离目录构建新版本,验证通过后再切换,失败时回到旧版本。
方案
每个索引目录包含 manifest.json、chunks.jsonl 和健康检查结果;current.json 只保存当前版本指针。切换是一次原子文件替换。
最小实现
import json
from pathlib import Path
def promote(root: Path, version: str) -> None:
manifest = json.loads((root / version / 'manifest.json').read_text())
if manifest.get('status') != 'healthy':
raise ValueError('index is not healthy')
tmp = root / 'current.json.tmp'
tmp.write_text(json.dumps({'version': version}))
tmp.replace(root / 'current.json')
复现步骤
- 将输入文档快照和构建参数写入新版本目录。
- 检查文档数、块数、抽样检索和权限过滤结果。
- 把状态标为 healthy 后原子替换 current.json。
- 观察错误率和零结果搜索,异常时把 current.json 指回旧版本。
验证清单
验证构建中断不改变 current.json、损坏 manifest 不可提升、回滚后旧版本可读、缓存键包含索引版本。
常见问题
为何不用数据库事务切换? 生产实现可以用数据库指针;本案例用文件指针展示原子切换思想。
回滚会删除新索引吗? 不立即删除,保留到回滚窗口结束并完成备份。
官方参考
OpenAI Production best practices;OpenAI Embeddings。
最后核对日期:2026-11-16。版本、接口和安全边界以链接的官方资料为准;本文不虚构性能或费用结论。
