knowledge-platform/docs/plans/ARCHITECTURE_MIGRATION_PLAN.md

3.3 KiB
Raw Blame History

Provider 架构迁移计划

目标基线

本计划依据 2026-09-02 对最新内部配置与 test 环境的只读核验调整 EKP Provider 和数据库 选型,同时保留 canonical-data 和 API-first 原则。

OceanBase MySQL       canonical Metadata / Chunk / Index State
Baidu BOS             immutable source and derived artifacts
OceanBase Vector      co-located rebuildable Dense retrieval index
Qianfan bge-large-zh  1024-dimensional Embedding
Qianfan BCE Reranker  bce-reranker-base

Provider、内部地址、数据库账户和凭据不得出现在 API/MCP Contract、日志、镜像或提交中。 本地测试继续使用 LocalObjectStorage、FakeVectorStore、FakeEmbeddingProvider 和 FakeRerankerProvider。

明确保留的行为

  • OceanBase 关系表保持 canonical database,专用向量表只保存可重建索引;
  • 原始文件不可变;
  • Dense Top20 → Reranker Top5;
  • 当前 PDF/DOCX/TXT/Markdown Parser 和 structure_v1 Chunk;
  • /api/v1 和 MCP 继续只暴露业务语义;
  • index_profile_id 过滤在召回阶段下推;
  • 新索引通过 shadow 表/Profile 构建和验证,不原地覆盖旧索引。

明确不随迁移引入

  • 将 OceanBase 向量表当作 canonical source;
  • Top50、距离阈值、标准答案捷径、双查询和 RRF;
  • Marker/Pandoc、LLM 摘要/问题/关键词索引;
  • RBAC/ACL、异步队列、MCP、Hybrid/BM25 或 Admin Console 扩展;
  • 旧系统 .env/镜像配置加载方式或任何现有敏感凭据。

Task 与验收

ARCH-001 架构和执行基线

更新 ADR、PRD、Architecture、Demo Scope、Tasks 和 Progress,消除目标 Provider 歧义。

ARCH-002 BOS ObjectStorage

新增 provider-neutral BOS Adapter、配置、脱敏错误和离线单元测试。Local Adapter 保留为 测试/开发实现。

依赖:ARCH-001。

ARCH-003 OceanBase VectorStore

新增 OceanBase Vector Adapter 和专用索引 DDL,覆盖 Upsert、文档/Profile 删除、Dense TopN、Cosine Distance 到统一高分优先 score 的转换,以及 profile 过滤。

依赖:ARCH-002。

ARCH-004 BCE Reranker

将运行基线改为 bce-reranker-base,按真实接口约束更新配置、Adapter、单元测试和 RAG Evaluation;保持 Top5 API 行为。

依赖:ARCH-003。

ARCH-005 Runtime Cutover

将 API 运行时切换到 BOS、OceanBase Vector 和 BCE Reranker;提供从 canonical Chunk 构建新 shadow index 的可重试命令,验证后激活新 Profile,再清理 Mochow 运行配置。

依赖:ARCH-004。

ARCH-006 真实验收

修正先前错误的 PostgreSQL 前提:将 canonical SQLAlchemy/Alembic 迁移到 OceanBase MySQL, 同库保留逻辑隔离的可重建向量表;在受控 test 资源中执行 OceanBase canonical → BOS → Qianfan Embedding → OceanBase Vector → BCE Reranker → canonical Source Result 全链路,并完成 30~50 条脱敏 Golden Query 验收。

依赖:ARCH-005、已授权的 test 运行凭据、数据库/表和 BOS 专用前缀。

安全边界

内部配置清单中的现有凭据按已暴露处理。经所有者明确要求,本次只允许把 test 凭据临时 注入 ARCH-006 进程;不得生成 .env、测试快照或调试日志,不得连接 fat/prod,验收后仍应 轮换。真实集成测试必须使用专用表/BOS 前缀并清理本次临时对象。