2.8 KiB
2.8 KiB
ARCH-005 Shadow Index 重建与切换
ARCH-005 将正式运行默认值切换为 BOS、OceanBase Vector 和千帆 BCE Reranker;ARCH-006 进一步确认 canonical 关系数据与向量索引同处 OceanBase MySQL 数据库。关系表保存 Document、 Chunk、ChunkIndexState 和 Index Profile;向量表只保存可以重建的检索行。旧 Mochow 运行配置、依赖和代码已移除,但本流程不会自动删除 旧外部索引,物理退役必须由受控运维流程另行确认。
Profile 与迁移前提
默认新 Profile 为:
demo-bge-large-zh-structure-v1-oceanbase-v1
它与旧 Demo Profile 使用不同 ID,避免已有 Mochow ChunkIndexState 被误认为 OceanBase
写入证据。自定义 ID 仍由 INDEX_PROFILE_ID 注入,并且必须是全新的、稳定的版本标识。
执行前必须:
- 运行
uv run alembic upgrade head,创建 canonicalindex_profiles表; - 使用
deploy/oceanbase/001_knowledge_chunks_v1.sql预创建目标表和 HNSW 索引; - 仅在运行时注入已授权的 OceanBase 与千帆凭据,不写入仓库或日志;
- 确认目标 OceanBase 为 4.3.5.4+,且应用账号只有目标数据库/表所需权限;
- 在重建期间避免修改 Chunk 策略;激活事务会阻止 canonical 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,从 OceanBase canonical Chunk 分文档生成 Embedding 并写入 OceanBase。命令中断后可以原样重试;已完整文档会跳过,部分目标 Profile 数据会先定向 清理再重建,不触碰 Active Profile;verify要求目标策略下至少存在一个 canonical Chunk,并核对全部 Chunk 与匹配模型、 维度的 ChunkIndexState。输出中的complete必须为true;activate在 OceanBase 事务内再次验证,锁定 Chunk 写入,将原 Active Profile 标为retired,再将目标 Shadow Profile 标为active。重复执行已成功的激活是幂等的。
激活后 API 从 OceanBase canonical 关系表解析 Active Profile,不再仅依赖进程环境中的 ID。新上传与查询 统一使用 OceanBase Active Profile。部署仍应保留前一版本制品和旧索引回滚窗口;本 Task 不自动销毁任何旧外部数据。
验证与已知边界
离线测试覆盖多文档构建、重试跳过、完整性失败关闭、单 Active 约束、原子激活、迁移和 CLI 输出脱敏。真实 BOS/OceanBase/Qianfan 连通性、DDL 权限、30~50 条脱敏 Golden Query、 召回质量和延迟属于 ARCH-006,且只能使用运行时授权凭据与受控测试资源。