Delete log file for May 14, 2026, to clean up unnecessary data and maintain log management.
This commit is contained in:
ash66
717
docs/architecture/backend-project-architecture.md
Normal file
717
docs/architecture/backend-project-architecture.md
Normal file
@@ -0,0 +1,717 @@
|
||||
# Backend Project Architecture
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
本文档定义当前 backend 的目标态架构，用于在保持单服务部署的前提下，将系统整理为职责清晰、边界稳定、可替换实现的模块化结构。本文档的重点不是描述理想化分层，而是基于当前真实代码形态，明确后续重构时必须遵守的模块职责、依赖方向、内部稳定接口和替换边界。
|
||||
|
||||
本文档与 `docs/rfc/backend-api-parsing-embedding-migration-requirements.md` 的关系如下：
|
||||
|
||||
- RFC 负责冻结本轮迁移需求、范围、风险和约束。
|
||||
- 本文档负责冻结目标模块边界、依赖规则和实现组织方式。
|
||||
- 后续任何代码重构、能力替换或底座升级，都应同时满足 RFC 与本文档。
|
||||
|
||||
## 2. Current-State Problems
|
||||
|
||||
基于当前代码，后端已经具备以下能力：
|
||||
|
||||
- 文档上传、下载、列表
|
||||
- 文档解析与切片
|
||||
- 向量化与 Milvus 入库
|
||||
- 检索
|
||||
- 基于 RAG 的 Agent 问答 workflow
|
||||
|
||||
但这些能力当前主要是“可运行”，还不是“结构清晰、便于替换、便于演进”的状态。核心问题如下。
|
||||
|
||||
### 2.1 `DocumentProcessor` 责任过载
|
||||
|
||||
`backend/app/services/document_processor.py` 当前同时承担：
|
||||
|
||||
- 文档解析
|
||||
- 摘要生成
|
||||
- 分块
|
||||
- 向量化
|
||||
- Milvus 入库
|
||||
- 检索入口
|
||||
|
||||
这使上传处理链路、检索链路与基础设施初始化逻辑耦合在一个大类中。流程编排与具体实现没有边界，后续无论替换 parser、embedding、vector store 还是增加文档状态管理，都会直接影响同一个类。
|
||||
|
||||
### 2.2 检索逻辑缺少稳定边界
|
||||
|
||||
`backend/app/services/rag/retriever.py` 当前同时管理：
|
||||
|
||||
- embedder 初始化
|
||||
- Milvus 连接与 collection lifecycle
|
||||
- 检索执行
|
||||
- 结果映射
|
||||
|
||||
这意味着“检索能力”不是一个稳定的业务能力接口，而是一个直接依赖具体 embedding 和 Milvus 实现的复合服务。后续如果从 `BGE-M3 + hybrid search` 切到 `1536 dense-only` 或替换向量索引实现，会直接影响检索服务本身。
|
||||
|
||||
### 2.3 `QAAgent` 责任过载
|
||||
|
||||
`backend/app/services/agent/qa_agent.py` 当前同时承担：
|
||||
|
||||
- 检索调用
|
||||
- 上下文构建
|
||||
- Prompt 选择
|
||||
- LLM 调用
|
||||
- SSE 流式问答流程
|
||||
- 会话 workflow 编排
|
||||
|
||||
这导致 Agent workflow 与检索底座、LLM provider、上下文构造逻辑紧耦合。后续切换 LLM provider、替换 session store、复用 retrieval 能力时，影响面会扩散到整个 Agent 实现。
|
||||
|
||||
### 2.4 API 层直接编排具体服务
|
||||
|
||||
当前 API 路由主要在：
|
||||
|
||||
- `backend/app/api/routes/documents.py`
|
||||
- `backend/app/api/routes/knowledge.py`
|
||||
- `backend/app/api/routes/agent.py`
|
||||
|
||||
这些路由直接实例化具体服务类，例如 `DocumentProcessor`、`QAAgent`、`MinIOClient`。这意味着：
|
||||
|
||||
- API 层不仅处理 transport concerns，也在做业务编排
|
||||
- 路由层知道过多内部实现细节
|
||||
- 后续如果内部模块调整，路由层也要跟着改
|
||||
|
||||
### 2.5 文档元数据与对象存储组织方式耦合
|
||||
|
||||
当前文档列表与下载逻辑高度依赖 MinIO 对象命名方式和对象遍历结果。对象存储目前承担了部分“业务真相”的角色，但对象存储只适合作为文件二进制载体，不适合作为完整文档元数据和状态管理的唯一来源。
|
||||
|
||||
### 2.6 `knowledge` 与 `agent` 共享检索底座的边界不清晰
|
||||
|
||||
当前 `/knowledge/*` 与 `/agent/*` 都依赖检索能力，但共享方式不够清晰：
|
||||
|
||||
- `knowledge` 通过 `DocumentProcessor.search()` 访问检索
|
||||
- `agent` 通过 `Retriever` 访问检索
|
||||
|
||||
这会导致同一检索能力未来演进成两条链路，难以统一检索策略、元数据模型和可替换边界。
|
||||
|
||||
## 3. Architecture Goals
|
||||
|
||||
本项目后端的目标态架构必须满足以下目标。
|
||||
|
||||
### 3.1 单服务部署
|
||||
|
||||
系统继续保持单服务部署，不拆分为多个微服务。架构治理发生在单服务内部，通过清晰模块边界实现高内聚低耦合，而不是通过进程级拆分回避设计问题。
|
||||
|
||||
### 3.2 高内聚、低耦合优先级最高
|
||||
|
||||
后续模块设计以“一个模块只承载一类稳定职责”为原则。跨能力流程统一在编排层组织，不允许继续把 parser、embedding、storage、retrieval、LLM workflow 堆进同一个服务类。
|
||||
|
||||
### 3.3 外部 API 尽量保持兼容
|
||||
|
||||
现有前端与外部调用方依赖的主接口保持不变优先，包括但不限于：
|
||||
|
||||
- `/api/v1/documents/*`
|
||||
- `/api/v1/knowledge/*`
|
||||
- `/api/v1/agent/*`
|
||||
|
||||
内部可以重组，但外部接口不应因为内部重构而被迫大改。
|
||||
|
||||
### 3.4 关键能力必须可替换
|
||||
|
||||
以下能力必须通过稳定端口隔离实现细节：
|
||||
|
||||
- 文档解析
|
||||
- 分块构建
|
||||
- 向量化
|
||||
- 向量索引
|
||||
- 检索
|
||||
- LLM 回答生成
|
||||
- 会话存储
|
||||
- 原始文件存储
|
||||
|
||||
后续替换方案时，只允许替换实现，不允许穿透影响其他模块。
|
||||
|
||||
### 3.5 `knowledge` 与 `agent` 共用同一检索底座
|
||||
|
||||
检索必须被视为独立的业务能力，由统一的 retrieval application service 对外暴露。`knowledge` 与 `agent` 必须复用同一个 retrieval 底座，避免两套召回策略、两套元数据模型、两套 adapter。
|
||||
|
||||
### 3.6 依赖必须单向流动
|
||||
|
||||
系统必须形成稳定的单向依赖关系：
|
||||
|
||||
- `api -> application -> domain`
|
||||
- `application -> infrastructure` 通过端口/实现绑定
|
||||
- `infrastructure -> external systems`
|
||||
|
||||
不允许出现基础设施实现反向驱动业务编排，也不允许 domain 依赖 Web 或第三方 SDK。
|
||||
|
||||
## 4. Target Module Layout
|
||||
|
||||
目标目录结构如下：
|
||||
|
||||
```text
|
||||
backend/app/
|
||||
api/
|
||||
application/
|
||||
documents/
|
||||
knowledge/
|
||||
agent/
|
||||
domain/
|
||||
documents/
|
||||
retrieval/
|
||||
conversation/
|
||||
infrastructure/
|
||||
storage/
|
||||
vectorstore/
|
||||
parser/
|
||||
embedding/
|
||||
llm/
|
||||
session/
|
||||
shared/
|
||||
```
|
||||
|
||||
该结构是本项目 backend 的目标态模块布局。后续实现可以渐进迁移，但职责边界不能偏离。
|
||||
|
||||
### 4.1 `api`
|
||||
|
||||
职责：
|
||||
|
||||
- HTTP 路由注册
|
||||
- 请求参数校验
|
||||
- 响应模型映射
|
||||
- 异常转换
|
||||
- SSE 事件格式输出
|
||||
|
||||
非职责：
|
||||
|
||||
- 不直接组织完整业务流程
|
||||
- 不直接访问 MinIO、Milvus、Parser SDK、LLM SDK
|
||||
- 不直接 new 具体基础设施客户端
|
||||
|
||||
### 4.2 `application`
|
||||
|
||||
职责：
|
||||
|
||||
- 用例编排
|
||||
- 跨领域能力协作
|
||||
- 业务流程统一入口
|
||||
- workflow 级别的状态推进
|
||||
|
||||
非职责：
|
||||
|
||||
- 不直接依赖第三方 SDK
|
||||
- 不承担具体存储、向量库、解析器实现细节
|
||||
|
||||
### 4.3 `domain`
|
||||
|
||||
职责：
|
||||
|
||||
- 核心业务对象
|
||||
- 领域术语
|
||||
- 稳定端口接口
|
||||
- 统一元数据模型
|
||||
- 检索结果模型
|
||||
- 会话消息模型
|
||||
|
||||
非职责：
|
||||
|
||||
- 不依赖 FastAPI
|
||||
- 不依赖 MinIO、Milvus、LLM SDK
|
||||
- 不依赖路由请求响应模型
|
||||
|
||||
### 4.4 `infrastructure`
|
||||
|
||||
职责：
|
||||
|
||||
- 外部系统适配器实现
|
||||
- 第三方 SDK 封装
|
||||
- provider-specific 配置适配
|
||||
- 数据格式转换
|
||||
|
||||
包含但不限于：
|
||||
|
||||
- MinIO binary store
|
||||
- Milvus vector index
|
||||
- Aliyun / local parser adapter
|
||||
- OpenAI-compatible embedding adapter
|
||||
- DeepSeek / Qwen LLM adapter
|
||||
- in-memory / Redis session store
|
||||
|
||||
### 4.5 `shared`
|
||||
|
||||
职责：
|
||||
|
||||
- 配置
|
||||
- 日志
|
||||
- 通用异常
|
||||
- 通用工具
|
||||
- 公共基础设施无关组件
|
||||
|
||||
非职责：
|
||||
|
||||
- 不承载业务编排
|
||||
- 不变成新的 `services` 大杂烩目录
|
||||
|
||||
## 5. Module Responsibilities
|
||||
|
||||
### 5.1 `api`
|
||||
|
||||
`api` 是 transport 层，只关心请求进来和响应出去的表达方式。它应该把请求转换为 application service 的输入，把 application service 的结果转换为 HTTP 响应。
|
||||
|
||||
`api` 不应该知道：
|
||||
|
||||
- MinIO bucket 怎么组织
|
||||
- Milvus collection 怎么建
|
||||
- parser 是本地还是阿里云
|
||||
- embedding 是本地模型还是 API
|
||||
- session 是内存还是 Redis
|
||||
|
||||
### 5.2 `application`
|
||||
|
||||
`application` 是业务编排层，是系统内唯一允许跨模块组织完整流程的层。它应该定义稳定的用例服务，而不是把流程散落在路由或基础设施实现中。
|
||||
|
||||
本项目至少固定以下 4 类 application service：
|
||||
|
||||
- `DocumentCommandService`
|
||||
- `DocumentQueryService`
|
||||
- `KnowledgeRetrievalService`
|
||||
- `AgentConversationService`
|
||||
|
||||
### 5.3 `domain`
|
||||
|
||||
`domain` 层定义系统内部真正稳定的概念，例如：
|
||||
|
||||
- `Document`
|
||||
- `DocumentStatus`
|
||||
- `ParsedDocument`
|
||||
- `Chunk`
|
||||
- `RetrievalQuery`
|
||||
- `RetrievedChunk`
|
||||
- `ConversationSession`
|
||||
- `ConversationMessage`
|
||||
- `AnswerSource`
|
||||
|
||||
这些对象必须脱离具体技术实现，成为 parser、embedding、vector index、agent workflow 之间的公共契约。
|
||||
|
||||
### 5.4 `infrastructure`
|
||||
|
||||
`infrastructure` 只负责“怎么接某个外部系统”，不负责“业务上应该先做什么后做什么”。例如：
|
||||
|
||||
- MinIO adapter 负责上传和下载文件
|
||||
- Milvus adapter 负责 upsert/search/delete
|
||||
- Qwen / DeepSeek adapter 负责生成回答
|
||||
- Aliyun parser adapter 负责把解析结果映射成统一 `ParsedDocument`
|
||||
|
||||
### 5.5 `shared`
|
||||
|
||||
`shared` 只放横切能力。任何和文档 ingest、检索、问答编排直接相关的业务逻辑，都不应该放进 `shared`。
|
||||
|
||||
## 6. Stable Internal Ports
|
||||
|
||||
以下端口是系统内部稳定契约。后续方案替换时，只能替换实现，不允许改动上层 application service 的调用方式，也不允许影响 sibling 模块。
|
||||
|
||||
### 6.1 `DocumentRepository`
|
||||
|
||||
职责：
|
||||
|
||||
- 管理文档元数据
|
||||
- 管理文档状态
|
||||
- 管理统计字段，例如 chunk 数、索引状态、摘要状态
|
||||
|
||||
说明：
|
||||
|
||||
- 列表和状态查询应以 `DocumentRepository` 为主，而不是直接遍历对象存储。
|
||||
|
||||
### 6.2 `DocumentBinaryStore`
|
||||
|
||||
职责：
|
||||
|
||||
- 保存原始文件
|
||||
- 下载原始文件
|
||||
- 删除原始文件
|
||||
- 处理对象存储相关细节
|
||||
|
||||
说明：
|
||||
|
||||
- 替换 MinIO 或对象存储方案时，只替换该实现。
|
||||
|
||||
### 6.3 `DocumentParser`
|
||||
|
||||
职责：
|
||||
|
||||
- 输入原始文件
|
||||
- 输出统一结构化解析结果
|
||||
|
||||
说明：
|
||||
|
||||
- 本地 PDF/MinerU 或阿里云解析只能作为实现差异，不能外溢到业务流程层。
|
||||
|
||||
### 6.4 `ChunkBuilder`
|
||||
|
||||
职责：
|
||||
|
||||
- 输入统一解析结果
|
||||
- 输出统一 chunk 模型
|
||||
|
||||
说明：
|
||||
|
||||
- chunk 规则变化只能影响该端口实现，不应影响 retrieval、agent 或 API。
|
||||
|
||||
### 6.5 `EmbeddingProvider`
|
||||
|
||||
职责：
|
||||
|
||||
- 输入文本列表
|
||||
- 输出 embedding 向量结果
|
||||
|
||||
说明：
|
||||
|
||||
- 从本地模型切到 OpenAI-compatible embedding，只替换该实现。
|
||||
|
||||
### 6.6 `VectorIndex`
|
||||
|
||||
职责：
|
||||
|
||||
- upsert chunks
|
||||
- delete by document
|
||||
- search by query vector
|
||||
- 管理索引内部 schema
|
||||
|
||||
说明：
|
||||
|
||||
- Milvus schema 或向量库替换，只能影响该层。
|
||||
|
||||
### 6.7 `Retriever`
|
||||
|
||||
职责：
|
||||
|
||||
- 基于 query、filter、top_k 返回统一检索结果
|
||||
|
||||
说明：
|
||||
|
||||
- `Retriever` 是业务侧的检索端口，不应再直接持有 embedder、Milvus lifecycle 和 provider-specific 逻辑。
|
||||
|
||||
### 6.8 `AnswerGenerator`
|
||||
|
||||
职责：
|
||||
|
||||
- 基于 query 与 context 生成最终回答
|
||||
- 屏蔽具体 LLM provider 差异
|
||||
|
||||
说明：
|
||||
|
||||
- DeepSeek、Qwen 或其他模型切换时，只替换该实现。
|
||||
|
||||
### 6.9 `ConversationStore`
|
||||
|
||||
职责：
|
||||
|
||||
- 创建和读取 session
|
||||
- 持久化消息历史
|
||||
- 管理会话生命周期
|
||||
|
||||
说明：
|
||||
|
||||
- 从内存实现切到 Redis 或数据库实现时，只替换该实现。
|
||||
|
||||
## 7. Application Services
|
||||
|
||||
### 7.1 `DocumentCommandService`
|
||||
|
||||
职责：
|
||||
|
||||
- 接收文档上传命令
|
||||
- 生成 `doc_id`
|
||||
- 保存原始文件
|
||||
- 触发解析、分块、向量化、入库
|
||||
- 更新文档状态和统计信息
|
||||
- 返回最终处理结果
|
||||
|
||||
说明：
|
||||
|
||||
- 当前 `DocumentProcessor` 的“流程编排”职责在目标态应迁移到这里。
|
||||
- parser、chunker、embedder、vector index 的具体实现不应继续塞进一个大类里统一管理。
|
||||
|
||||
### 7.2 `DocumentQueryService`
|
||||
|
||||
职责：
|
||||
|
||||
- 文档列表
|
||||
- 文档下载
|
||||
- 文档状态查询
|
||||
- 文档管理视图查询
|
||||
|
||||
说明：
|
||||
|
||||
- 列表和状态查询应基于 `DocumentRepository`
|
||||
- 下载应通过 `DocumentBinaryStore`
|
||||
- 不再依赖 MinIO 对象结构作为业务视图主来源
|
||||
|
||||
### 7.3 `KnowledgeRetrievalService`
|
||||
|
||||
职责：
|
||||
|
||||
- 对外提供统一检索能力
|
||||
- 管理 retrieval query 到 retrieval result 的业务转换
|
||||
- 被 `/knowledge/*` 和 Agent workflow 共用
|
||||
|
||||
说明：
|
||||
|
||||
- 当前 `knowledge` 与 `agent` 必须统一依赖这一层，不允许各自再维护一套检索流程。
|
||||
|
||||
### 7.4 `AgentConversationService`
|
||||
|
||||
职责：
|
||||
|
||||
- 统一管理问答 workflow
|
||||
- 读取或创建会话
|
||||
- 调用 `KnowledgeRetrievalService`
|
||||
- 构建问答上下文
|
||||
- 调用 `AnswerGenerator`
|
||||
- 保存回答和引用来源
|
||||
|
||||
说明：
|
||||
|
||||
- 当前 `QAAgent` 的 workflow 编排职责在目标态应迁移到这里，或被其吸收后只保留 façade 角色。
|
||||
- SSE 与普通问答必须共用这一层，不允许复制业务编排逻辑。
|
||||
|
||||
## 8. Core Workflows
|
||||
|
||||
### 8.1 文档上传入库链路
|
||||
|
||||
目标流程如下：
|
||||
|
||||
1. `api/documents` 接收上传请求并完成输入校验。
|
||||
2. `DocumentCommandService` 生成 `doc_id`，初始化文档记录和状态。
|
||||
3. `DocumentBinaryStore` 保存原始文件。
|
||||
4. `DocumentParser` 对原始文件执行解析，输出统一结构化结果。
|
||||
5. `ChunkBuilder` 将解析结果转换为统一 chunk 集合。
|
||||
6. `EmbeddingProvider` 为 chunks 生成向量。
|
||||
7. `VectorIndex` 将 chunks 与 vectors 写入索引。
|
||||
8. `DocumentRepository` 更新文档状态、chunk 数量、索引状态、元数据。
|
||||
9. API 返回处理结果。
|
||||
|
||||
约束：
|
||||
|
||||
- 上传处理链路的主编排必须只存在于 `DocumentCommandService`
|
||||
- 不允许再由 route 或基础设施类直接组织全流程
|
||||
|
||||
### 8.2 文档查询链路
|
||||
|
||||
目标流程如下：
|
||||
|
||||
1. `api/documents` 调用 `DocumentQueryService`
|
||||
2. 文档列表与状态查询通过 `DocumentRepository`
|
||||
3. 文档下载通过 `DocumentBinaryStore`
|
||||
4. 对象存储命名规则只作为实现细节，不作为最终业务真相
|
||||
|
||||
约束：
|
||||
|
||||
- 文档“存在、状态、统计信息”必须有稳定元数据模型
|
||||
- 不允许继续通过对象存储遍历结果拼出全部业务语义
|
||||
|
||||
### 8.3 Agent 问答链路
|
||||
|
||||
目标流程如下：
|
||||
|
||||
1. `api/agent` 接收问答请求
|
||||
2. `AgentConversationService` 读取或创建 session
|
||||
3. `KnowledgeRetrievalService` 统一执行检索
|
||||
4. `AnswerGenerator` 基于 query 和 retrieval context 生成回答
|
||||
5. `ConversationStore` 保存消息历史和引用来源
|
||||
6. API 将结果以普通 JSON 或 SSE 格式输出
|
||||
|
||||
约束：
|
||||
|
||||
- 普通问答和 SSE 问答只允许输出形式不同
|
||||
- 业务编排链必须完全复用
|
||||
- 检索能力必须来自同一 `KnowledgeRetrievalService`
|
||||
|
||||
## 9. Dependency Rules
|
||||
|
||||
系统内部依赖方向固定如下：
|
||||
|
||||
```text
|
||||
api -> application -> domain
|
||||
application -> infrastructure (through ports)
|
||||
infrastructure -> external systems
|
||||
```
|
||||
|
||||
具体规则如下：
|
||||
|
||||
- `api` 可以依赖 `application` 和 API 自己的 request/response models
|
||||
- `application` 可以依赖 `domain` 和端口绑定后的 infrastructure 实现
|
||||
- `domain` 不能依赖 `api` 或 `infrastructure`
|
||||
- `infrastructure` 可以依赖 `domain` 定义的端口和数据模型，但不能反向驱动 application 逻辑
|
||||
|
||||
## 10. Migration Mapping From Current Code
|
||||
|
||||
当前关键代码到目标模块的映射如下。
|
||||
|
||||
### 10.1 文档处理
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/services/document_processor.py`
|
||||
|
||||
目标：
|
||||
|
||||
- 其流程编排职责迁移到 `application/documents/DocumentCommandService`
|
||||
- 解析、分块、向量、入库分别通过端口接入
|
||||
- 检索入口从该类中剥离，不再由 ingest orchestration 承担 search 职责
|
||||
|
||||
### 10.2 检索
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/services/rag/retriever.py`
|
||||
|
||||
目标：
|
||||
|
||||
- `domain/retrieval` 中定义 `Retriever` 端口和统一检索结果模型
|
||||
- `infrastructure/vectorstore` 中承载具体检索实现
|
||||
- `application/knowledge/KnowledgeRetrievalService` 作为统一检索用例入口
|
||||
|
||||
### 10.3 Agent Workflow
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/services/agent/qa_agent.py`
|
||||
|
||||
目标：
|
||||
|
||||
- workflow 编排职责迁移到 `application/agent/AgentConversationService`
|
||||
- 具体 LLM 调用走 `AnswerGenerator`
|
||||
- 具体 session 读写走 `ConversationStore`
|
||||
- 检索统一走 `KnowledgeRetrievalService`
|
||||
|
||||
### 10.4 存储
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/services/storage/minio_client.py`
|
||||
- `backend/app/services/storage/milvus_client.py`
|
||||
|
||||
目标：
|
||||
|
||||
- MinIO 迁移到 `infrastructure/storage`
|
||||
- Milvus 迁移到 `infrastructure/vectorstore`
|
||||
|
||||
### 10.5 解析
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/services/parser/*`
|
||||
- `backend/app/services/parser/mineru_parser.py`
|
||||
|
||||
目标：
|
||||
|
||||
- 全部迁移到 `infrastructure/parser`
|
||||
- 对外只暴露统一 `DocumentParser` 端口实现
|
||||
|
||||
### 10.6 向量化
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/services/embedding/*`
|
||||
|
||||
目标：
|
||||
|
||||
- 迁移到 `infrastructure/embedding`
|
||||
- 对外只暴露统一 `EmbeddingProvider`
|
||||
|
||||
### 10.7 LLM
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/services/llm/*`
|
||||
|
||||
目标：
|
||||
|
||||
- 迁移到 `infrastructure/llm`
|
||||
- 由 `AnswerGenerator` 屏蔽 provider 差异
|
||||
|
||||
### 10.8 会话
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/services/agent/session_manager.py`
|
||||
|
||||
目标：
|
||||
|
||||
- 迁移到 `infrastructure/session`
|
||||
- 对外通过 `ConversationStore` 暴露
|
||||
|
||||
### 10.9 API 模型与内部模型
|
||||
|
||||
当前：
|
||||
|
||||
- `backend/app/api/models/*`
|
||||
- `backend/app/schemas/*`
|
||||
|
||||
目标：
|
||||
|
||||
- 对外 request/response model 保留在 `api`
|
||||
- 内部 DTO / VO / domain object 收敛到 `application` 或 `domain`
|
||||
- 不允许 API model 直接渗透到 domain
|
||||
|
||||
## 11. Technology Replacement Boundaries
|
||||
|
||||
### 11.1 本地解析 / MinerU -> 阿里云文档解析
|
||||
|
||||
替换原则：
|
||||
|
||||
- 只替换 `DocumentParser` adapter
|
||||
- `DocumentCommandService` 不应感知解析提供商差异
|
||||
- `ChunkBuilder` 只接收统一解析结果模型
|
||||
|
||||
### 11.2 BGE-M3 -> OpenAI-compatible embedding
|
||||
|
||||
替换原则：
|
||||
|
||||
- 只替换 `EmbeddingProvider`
|
||||
- `KnowledgeRetrievalService` 与 `DocumentCommandService` 不应感知 embedding 来源变化
|
||||
|
||||
### 11.3 Milvus `1024 + sparse` -> `1536 dense-only`
|
||||
|
||||
替换原则：
|
||||
|
||||
- 只替换 `VectorIndex` 实现
|
||||
- collection schema、index 参数、dense-only search 属于 index 内部实现细节
|
||||
- 上层 retrieval 和 agent workflow 不应因为 schema 变化而改业务接口
|
||||
|
||||
### 11.4 DeepSeek / Qwen 切换
|
||||
|
||||
替换原则：
|
||||
|
||||
- 只替换 `AnswerGenerator` 背后的 provider adapter
|
||||
- 上层 conversation workflow 不应直接依赖具体模型 SDK
|
||||
|
||||
### 11.5 内存 session -> Redis / DB session
|
||||
|
||||
替换原则：
|
||||
|
||||
- 只替换 `ConversationStore`
|
||||
- API 和 application service 不应感知 session 持久化细节
|
||||
|
||||
## 12. Guardrails
|
||||
|
||||
后续所有 backend 重构和新增功能必须遵守以下规则：
|
||||
|
||||
- 禁止 `api/routes` 直接实例化 parser、embedder、Milvus、MinIO、LLM client
|
||||
- 禁止 `application` 层直接 import 第三方 SDK
|
||||
- 禁止 `domain` 层依赖 FastAPI、Pydantic route model、MinIO SDK、Milvus SDK、LLM SDK
|
||||
- 禁止 SSE 和普通问答各自维护独立 workflow
|
||||
- 禁止把对象存储命名规则作为唯一业务元数据来源
|
||||
- 禁止新建第二个“大一统流程类”替代 `DocumentProcessor`
|
||||
- 禁止 `knowledge` 和 `agent` 各自维护独立检索实现
|
||||
- 禁止 parser、embedding、vector index、llm provider 的替换穿透到 API 层
|
||||
|
||||
## 13. Architecture Review Checklist
|
||||
|
||||
后续评审和重构验收时，至少核对以下问题：
|
||||
|
||||
1. 上传、下载、列表、解析、切片、向量、入库、检索、Agent Workflow 是否都映射到了明确模块。
|
||||
2. 系统是否仍保持单服务，而不是被动演化成伪微服务结构。
|
||||
3. 是否存在唯一、清晰的目标目录结构。
|
||||
4. 是否定义了稳定端口列表。
|
||||
5. 是否定义了文档上传入库、文档查询、Agent 问答三条核心 workflow。
|
||||
6. 是否定义了单向依赖方向。
|
||||
7. 是否明确列出了架构禁令。
|
||||
8. 是否定义了当前关键代码到目标模块的映射。
|
||||
9. 是否明确定义了 parser、embedding、vector index、LLM、session store 的替换边界。
|
||||
10. 是否明确 `knowledge` 与 `agent` 共用同一 retrieval 底座。
|
||||
11. 是否明确 API 层只负责 transport concerns，不再直接承担业务编排。
|
||||
12. 是否保证后续替换方案时，上层 application service 与外部 API 契约不被迫变化。
|
||||
170
docs/rfc/backend-api-parsing-embedding-migration-requirements.md
Normal file
170
docs/rfc/backend-api-parsing-embedding-migration-requirements.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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/aliyun_parser/parse_pdf.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/aliyun_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 和重建索引
|
||||
- `backend/app/aliyun_parser` 现有脚本含硬编码密钥，后续必须全部移到环境变量
|
||||
- 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 整理完成后，应基于本文件再补充对应的架构方案文档，或直接拆解为实施计划。
|
||||
Reference in New Issue
Block a user