問題與邊界
知識庫每天更新,直接覆蓋索引可能產生半成品結果。需要在隔離目錄建立新版本,驗證通過後再切換,失敗時回到舊版本。
方案
每個索引目錄包含 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。介面和安全邊界以連結中的官方資料為準;本文不虛構效能或費用結論。
