2026-09-02 11:28:13 +08:00

2.7 KiB
Raw Permalink Blame History

ARCH-005 Shadow Index 重建与切换

ARCH-005 将正式运行默认值切换为 BOS、OceanBase Vector 和千帆 BCE Reranker。PostgreSQL 继续保存 canonical Document、Chunk、ChunkIndexState 和 Index Profile 生命周期;OceanBase 只保存可以重建的检索行。旧 Mochow 运行配置、依赖和代码已移除,但本流程不会自动删除 旧外部索引,物理退役必须由受控运维流程另行确认。

Profile 与迁移前提

默认新 Profile 为:

demo-bge-large-zh-structure-v1-oceanbase-v1

它与旧 Demo Profile 使用不同 ID,避免已有 Mochow ChunkIndexState 被误认为 OceanBase 写入证据。自定义 ID 仍由 INDEX_PROFILE_ID 注入,并且必须是全新的、稳定的版本标识。

执行前必须:

  1. 运行 uv run alembic upgrade head,创建 canonical index_profiles 表;
  2. 使用 deploy/oceanbase/001_knowledge_chunks_v1.sql 预创建目标表和 HNSW 索引;
  3. 注入 OceanBase 与千帆 Embedding 的轮换凭据,不使用配置清单中的历史 Secret;
  4. 确认目标 OceanBase 为 4.6.0+,且应用账号只有目标数据库/表所需权限;
  5. 在重建期间避免修改 Chunk 策略;激活事务会阻止 PostgreSQL Chunk 并发写入穿过最终核对。

顺序执行

每一步只输出 Profile ID 和计数,不输出 Endpoint、SQL、Chunk 内容或凭据。

uv run ekp-index-rebuild build
uv run ekp-index-rebuild verify
uv run ekp-index-rebuild activate
  • build 注册 Shadow Profile,从 PostgreSQL canonical Chunk 分文档生成 Embedding 并写入 OceanBase。命令中断后可以原样重试;已完整文档会跳过,部分目标 Profile 数据会先定向 清理再重建,不触碰 Active Profile;
  • verify 要求目标策略下至少存在一个 canonical Chunk,并核对全部 Chunk 与匹配模型、 维度的 ChunkIndexState。输出中的 complete 必须为 true;
  • activate 在 PostgreSQL 事务内再次验证,锁定 Chunk 写入,将原 Active Profile 标为 retired,再将目标 Shadow Profile 标为 active。重复执行已成功的激活是幂等的。

激活后 API 从 PostgreSQL 解析 Active Profile,不再仅依赖进程环境中的 ID。新上传与查询 统一使用 OceanBase Active Profile。部署仍应保留前一版本制品和旧索引回滚窗口;本 Task 不自动销毁任何旧外部数据。

验证与已知边界

离线测试覆盖多文档构建、重试跳过、完整性失败关闭、单 Active 约束、原子激活、迁移和 CLI 输出脱敏。真实 BOS/OceanBase/Qianfan 连通性、DDL 权限、30~50 条脱敏 Golden Query、 召回质量和延迟属于 ARCH-006,且只能使用轮换后的凭据与受控测试资源。