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 整理完成后，应基于本文件再补充对应的架构方案文档，或直接拆解为实施计划。