AIRegulation-DocAnalysis/docs/rfc/backend-api-parsing-embedding-migration-requirements.md

BGE-M3 下线与阿里云/API 解析迁移需求说明

1. 当前状态

当前后端文档上传与处理主链路已经存在，且真实入口与核心依赖如下：

• 现有真实上传入口是 backend/app/api/routes/documents.py 的 /api/v1/documents/upload
• 当前主链路依赖 backend/app/services/document_processor.py
• 当前解析链路是本地 PDF/DOCX/MinerU
• 当前嵌入链路依赖 backend/app/services/embedding/bge_m3_embedder.py
• 当前检索链路依赖 backend/app/services/storage/milvus_client.py 和 backend/app/services/rag/retriever.py

本文件用于冻结本轮迁移需求、影响面和约束条件，作为后续 backend architecture 梳理、实施拆解和验收对齐的输入基线。

2. 背景与动机

当前系统的文档处理能力建立在本地解析与本地向量模型基础之上，但该路径已经不再满足后续演进要求。为支持统一的解析质量、降低本地模型依赖、并为后续后端架构调整预留空间，本期需要先冻结迁移需求。

本期背景和动机明确如下：

• 不再使用本地 models--BAAI--bge-m3
• 解析和 embedding 主链路准备切换到 API 方式
• 后续还会整体调整 backend 架构，因此本文件只冻结需求，不提前固化最终模块设计

3. 目标需求

本期目标是完成文档解析、分块、向量化和检索底座的迁移需求定义，明确后续架构和实施阶段必须满足的结果边界。

已确认的目标需求如下：

• 文档解析统一改为阿里云文档智能能力
• 当前阿里云接入基础已经迁移到 backend/app/infrastructure/parser/aliyun_layout_normalizer.py
• 解析结果以 structure_nodes、semantic_blocks、vector_chunks 三层结构为基础
• 分块以阿里云 vector_chunks 为准，不再走当前本地 RegulationChunker
• embedding 改为 OpenAI 兼容 API 调用，模型使用 text-embedding-v3
• 检索能力本期降级为 dense-only
• Milvus 继续保留，但 schema 需要围绕 1536 维 dense 向量重建

以上内容属于本期已经确认的迁移方向，不再作为待讨论事项。

4. 范围

本期需求范围覆盖以下内容：

• 上传处理链路
• 阿里云解析适配
• embedding API 适配
• Milvus 入库与检索
• RAG/Agent 检索依赖的元数据适配
• 配置、依赖、README 和部署说明同步清理

本期范围的核心目标是让现有上传后处理主链路可以在新的 API 化解析和 embedding 方式下继续工作，并保持主要外部接口不变。

5. 非目标

以下事项不属于本期需求目标，不应在本文件内被提前设计或默认纳入实施：

• 本文件不定义最终 backend 分层、目录结构和 service boundary
• 本文件不引入异步任务系统
• 本文件不把 PostgreSQL 三层结构表接入主链路
• 本文件不处理前端大规模交互改版

如果后续实施阶段需要触及上述内容，应另行在架构方案或单独 RFC 中说明，而不是在本需求说明中默认展开。

6. 影响面清单

本期迁移将影响现有后端多个子系统。以下清单用于冻结影响面，方便后续做架构设计、任务拆分和回归验证。

6.1 入口与流程

受影响的入口与主流程文件包括：

• backend/app/api/routes/documents.py
• backend/app/services/document_processor.py

该部分需要承接上传接口保持不变的前提下，对解析、分块、向量化和入库主流程进行迁移。

6.2 解析能力

受影响的解析能力范围包括：

• 当前本地 parser 目录
• backend/app/infrastructure/parser

迁移后阿里云文档智能能力将成为主解析来源，本地 PDF/DOCX/MinerU 解析链路需要重新界定保留、下线或回退策略，但具体模块组织方式不在本文件内定义。

6.3 向量能力

受影响的向量能力范围包括：

• backend/app/services/embedding/bge_m3_embedder.py
• embedding 配置
• embedding 相关依赖包

该部分需要移除对本地 BGE-M3 模型的运行时依赖，并改为 OpenAI 兼容 API 方式调用 text-embedding-v3。

6.4 存储检索

受影响的存储与检索能力包括：

• backend/app/services/storage/milvus_client.py
• backend/app/services/rag/retriever.py
• backend/app/api/routes/knowledge.py
• backend/app/services/agent/qa_agent.py

该部分需要围绕 1536 维 dense 向量重建 Milvus schema，并确保知识检索与 Agent 检索链路继续可用。

6.5 配置与状态

受影响的配置与状态相关文件包括：

• backend/app/config/settings.py
• backend/app/core/config.py
• backend/app/api/routes/status.py
• backend/app/services/mock_data.py

该部分需要清理与旧本地模型和旧处理链路耦合的配置项、状态展示和 mock 数据假设。

6.6 文档与部署

受影响的文档与部署项包括：

• README.md
• QUICK_DEPLOY.md
• .env.example
• requirements 相关文件
• pyproject.toml

该部分需要同步反映新的 API 化解析与 embedding 依赖，去除或更新本地模型准备、运行说明和环境配置描述。

7. 风险与约束

以下风险和约束在本期已经明确，需要在后续架构和实施阶段优先处理：

• 旧 Milvus collection 与新 1536 维 schema 不兼容，需要新 collection 和重建索引
• 阿里云凭据必须继续只通过环境变量或凭据链注入，不能回到脚本内硬编码
• RAG 下游当前对 clause_number 有依赖，迁移后需要优先适配 section_title 和 Aliyun chunk metadata
• 如果阿里云返回字段与当前样例不同，需要在架构阶段补充 adapter 层

上述条目属于实施约束和迁移风险，不代表当前已经确定最终解决方案，只代表这些问题必须被显式处理。

8. 待架构阶段决策

以下事项属于后续 backend architecture 阶段需要单独拍板的决策项，不属于本文件已确认的需求结论：

• 阿里云能力封装为内部模块还是独立 adapter package
• 同步阻塞上传还是改为异步 job
• DocumentProcessor 是否拆为 ingest orchestrator
• 检索元数据模型是否统一重命名
• status/config 是否改为真实运行态而不是 mock

后续如输出架构方案，应围绕这些待决策项给出明确取舍和原因，但不应回退本文件已经确认的迁移目标。

9. 验收基线

本期需求的验收基线固定如下：

• 上传接口外部契约保持不变
• PDF/DOC/DOCX 上传后能完成解析、向量化、入库
• 新索引可支持 /knowledge/retrieval 和 /agent/ask
• 系统中不再依赖本地 bge-m3 模型文件
• 所有敏感凭据从代码移出

以上验收基线用于后续架构方案评审和实施完成后的回归核对。

10. 说明

本文件是需求说明，不是最终技术设计文档。文中只冻结目标、范围、影响面、风险和约束，不定义最终 backend 分层、类图、目录结构、模块边界或详细实现步骤。

后续待新的 backend architecture 整理完成后，应基于本文件再补充对应的架构方案文档，或直接拆解为实施计划。