c22b03dc07
- Updated LocalDocumentParser to include raw_layouts and artifact_prefix from settings. - Added new documents with failure reasons and metadata to documents.json for better error tracking. - Created a new documentation file detailing the Aliyun ingest implementation process. - Updated RFC to reflect changes in the parsing backend and embedding dimensions. - Modified tests to accommodate the new embedding dimension of 1024 and updated parser and chunk builder assertions. - Verified migration configurations to ensure correct settings for embedding model and backend.
171 lines
7.0 KiB
Markdown
171 lines
7.0 KiB
Markdown
# 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 整理完成后，应基于本文件再补充对应的架构方案文档，或直接拆解为实施计划。
|