FastAPI 后端工程治理
目前需要改进一下基于fastapi后端的一些架构设计
后端项目结构概述
整体结构如下：
bash
RagBackend/
├── .dockerignore
├── .env.example
├── .gitignore
├── .python-version
├── ASF_SRE/ # 软件研发效能相关模块
│ └── SRE_mian.py
├── Dockerfile
├── RAGF_User_Management/ # 用户管理模块
│ ├── LogonAndLogin.py # 注册和登录功能
│ ├── QQ_Login.py # QQ登录功能
│ ├── Reset_Password.py # 密码重置功能
│ ├── User_Management.py # 用户管理功能
│ ├── User_settings.py # 用户设置功能
│ └── db_config.py # 数据库配置
├── RAG_M/ # 核心RAG应用模块
│ ├── Pipfile
│ ├── Pipfile.lock
│ ├── RAG_app.py # RAG核心应用程序
│ ├── README.md
│ ├── requirements.txt
│ └── src/ # RAG源代码
│ ├── __init__.py
│ ├── agent/ # 智能代理模块
│ ├── api/ # API接口
│ ├── ingestion/ # 数据摄取模块
│ ├── models/ # 模型相关
│ ├── rag/ # RAG核心逻辑
│ ├── scripts/ # 脚本文件
│ └── vectorstore/ # 向量存储
├── agent_tools/ # 智能体工具
│ ├── __init__.py
│ ├── agent_advanced.py
│ ├── enterprise_tools.py
│ └── web_search_tool.py
├── assets/ # 资源文件
├── audit/ # 审计日志
│ ├── __init__.py
│ └── audit_log.py
├── billing/ # 计费管理
│ ├── __init__.py
│ └── billing_manager.py
├── chat_units/ # 聊天功能单元
│ └── chat_management/ # 聊天管理
│ ├── chat_delete.py
│ ├── chat_download.py
│ ├── chat_history_attacher.py
│ ├── chat_main.py
│ └── chat_send.py
├── creation/ # 内容创建
│ ├── __init__.py
│ └── doc_creation.py
├── data_sources/ # 数据源管理
│ ├── __init__.py
│ └── datasource_manager.py
├── docs/ # 文档
├── document_processing/ # 文档处理模块
│ ├── API.md
│ ├── doc_list.py
│ ├── doc_manage.py
│ ├── doc_upload.py
│ ├── incremental_vectorizer.py
│ ├── pipeline.py
│ ├── retrieval_strategy.py
│ ├── semantic_splitter.py
│ ├── task_queue.py
│ └── vectorize_task.py
├── enterprise/ # 企业功能
├── evaluation/ # 评估模块
├── feedback/ # 反馈系统
├── integrations/ # 第三方集成
├── knowledge/ # 知识管理
├── knowledge_base/ # 知识库管理
├── knowledge_graph/ # 知识图谱
├── main.py # 主入口文件
├── models/ # 模型配置
├── monitoring/ # 监控模块
├── multi_model/ # 多模型支持
├── multimodal/ # 多模态处理
├── ollama_management/ # Ollama管理
├── open_api/ # 开放API
├── rag_enhancement/ # RAG增强功能
├── search/ # 搜索功能
├── square/ # 广场功能
├── tests/ # 测试文件
├── trace_logging.py # 追踪日志
└── requirements.txt # Python依赖包列表主要功能模块有：
项目目前是一个典型的“按技术功能分散式”结构，在项目初期开发速度快(当时大二两周梭完了)，但随着业务复杂度增加（比如 RAG 这种涉及数据流、模型调度、向量检索的复杂系统），主要存在一些问题：
模块边界不清：RAG_M 嵌套过深，与外层的 agent_tools、document_processing 职责重叠。 命名不规范：RAGF_User_Management 目录名过长且包含大写，ASF_SRE 含义不明，chat_units/chat_management 层级冗余。 配置分散：db_config.py 藏在用户模块中，RAG_M 里还有独立的 Pipfile，导致依赖管理混乱。 根目录拥堵：过多的顶层文件夹导致项目难以导航。
面对这种情况计划采用 “领域驱动 + 分层架构” 的模式进行重构:
一、 顶层架构设计原则
- 单体优先，模块化设计：虽然目前是一个服务，但内部应按业务领域（User、RAG、Agent、Doc）划分清晰的边界。
- 核心下沉：RAG 核心逻辑不应只是
RAG_M下的一个子目录，而应提升为核心域。 - 统一依赖与配置：废除子目录的独立环境配置，统一由根目录管理。
二、 改进后的项目结构树
bash
RagBackend/
├── .env # 环境变量
├── .gitignore
├── .python-version
├── Dockerfile
├── requirements.txt # 统一的依赖管理
├── main.py # 应用入口 (FastAPI app 初始化)
├── alembic.ini # 数据库迁移配置
├── alembic/ # 数据库迁移脚本
│
├── app/ # 核心应用目录
│ ├── __init__.py
│ ├── core/ # 核心配置与安全
│ │ ├── __init__.py
│ │ ├── config.py # 全局配置 (合并原 db_config, .env 读取)
│ │ ├── security.py # JWT, 密码哈希
│ │ └── logging.py # 日志配置 (合并 trace_logging)
│ │
│ ├── api/ # API 路由层
│ │ ├── __init__.py
│ │ ├── dependencies.py # 公共依赖 (如 get_db, get_current_user)
│ │ └── v1/ # API 版本控制
│ │ ├── __init__.py
│ │ ├── auth.py # 登录注册 (原 LogonAndLogin)
│ │ ├── chat.py # 聊天接口
│ │ ├── knowledge.py # 知识库接口
│ │ ├── rag.py # RAG 执行接口
│ │ └── ollama.py # 模型管理接口
│ │
│ ├── models/ # 数据库 ORM 模型
│ │ ├── __init__.py
│ │ ├── user.py
│ │ ├── chat.py
│ │ └── knowledge.py
│ │
│ ├── schemas/ # Pydantic 数据模型
│ │ ├── __init__.py
│ │ ├── user.py
│ │ └── chat.py
│ │
│ ├── domain/ # [核心] 业务领域逻辑层
│ │ ├── __init__.py
│ │ │
│ │ ├── rag/ # RAG 核心引擎 (整合原 RAG_M)
│ │ │ ├── __init__.py
│ │ │ ├── engine.py # RAG 执行引擎
│ │ │ ├── retrieval.py # 检索策略
│ │ │ └── reranker.py # 重排序模块
│ │ │
│ │ ├── agent/ # 智能体模块 (整合原 agent_tools, RAG_M/agent)
│ │ │ ├── __init__.py
│ │ │ ├── executor.py # Agent 执行器
│ │ │ └── tools/ # 工具箱
│ │ │ ├── web_search.py
│ │ │ └── enterprise_tool.py
│ │ │
│ │ ├── document/ # 文档处理 (整合原 document_processing)
│ │ │ ├── __init__.py
│ │ │ ├── processor.py # 文档处理流水线
│ │ │ ├── splitter.py # 语义分割
│ │ │ └── loaders/ # 不同格式加载器
│ │ │
│ │ ├── knowledge/ # 知识库管理 (整合原 knowledge/knowledge_base)
│ │ │ ├── __init__.py
│ │ │ ├── manager.py
│ │ │ └── graph.py # 知识图谱逻辑
│ │ │
│ │ └── chat/ # 聊天业务逻辑
│ │ ├── __init__.py
│ │ ├── service.py # 聊天服务 (整合原 chat_management)
│ │ └── history.py # 历史记录管理
│ │
│ ├── infrastructure/ # 基础设施层
│ │ ├── __init__.py
│ │ ├── database.py # 数据库连接
│ │ ├── vectorstore/ # 向量库连接
│ │ │ ├── __init__.py
│ │ │ └── chroma_client.py
│ │ ├── llm/ # 模型提供商适配
│ │ │ ├── __init__.py
│ │ │ ├── ollama_adapter.py
│ │ │ └── openai_adapter.py
│ │ └── storage/ # 文件存储
│ │
│ └── utils/ # 通用工具函数
│ ├── __init__.py
│ └── helpers.py
│
├── tests/ # 测试目录
│ ├── __init__.py
│ ├── conftest.py
│ └── test_api/
│
└── docs/ # 接口文档等三、 工程治理
1. 整合 RAG_M 子项目
现状：RAG_M 作为一个子目录存在，甚至包含独立的 requirements.txt 和 src。 改进：
- 消除嵌套：将
RAG_M/src下的代码提升到app/domain/rag和app/infrastructure/vectorstore中。 - 统一依赖：删除
RAG_M/Pipfile，将其依赖合并到根目录的requirements.txt。 - 理由：RAG 是你的核心业务，不应被“藏”在子目录里，它应该与其他业务模块平级。
2. 规范用户管理模块 (RAGF_User_Management)
现状：目录名过长，文件以功能命名（如 QQ_Login.py），不符合 Python 模块化习惯。 改进：
- 重命名为
domain/user或直接拆解。 LogonAndLogin.py-> 拆分为api/v1/auth.py(接口层) 和services/user_service.py(逻辑层)。QQ_Login.py-> 集成到core/security.py或infrastructure/oauth.py中，作为 OAuth 登录策略的一种。db_config.py-> 移动到core/config.py，全局只保留一份配置。
3. 清理顶层散乱的功能目录
现状：根目录下有 agent_tools, billing, audit, creation 等近 20 个文件夹。 改进：
按领域归集
agent_tools->app/domain/agent/toolsdocument_processing->app/domain/documentchat_units->app/domain/chatknowledge,knowledge_base,knowledge_graph-> 合并为app/domain/knowledgemulti_model,ollama_management-> 归类到app/infrastructure/llm(底层适配) 或app/domain/model_manager(业务管理)。
辅助功能下沉
audit,billing,monitoring-> 如果代码量不大，可以放在app/services下；如果复杂度高，保留在app/domain下作为独立子域。ASF_SRE-> 如果是运维脚本，移出app到单独的scripts目录；如果是业务功能，重命名并归入相关领域。
4. 分层职责定义
- API 层 (
app/api)：只负责接收请求、参数校验、调用 Domain 层、返回响应。禁止在 API 层写 SQL 查询或直接操作向量库。 - Domain 层 (
app/domain)：这是系统的核心。例如domain/chat/service.py负责“聊天”这个动作的业务编排，它调用domain/rag获取背景知识，调用infrastructure/llm生成回答。 - Infrastructure 层 (
app/infrastructure)：封装外部依赖。数据库、向量库、Redis、Ollama 接口都在这里。这样如果未来要换向量库（比如从 Chroma 换到 Milvus），只需修改此层代码，Domain 层代码无需改动。
四、 迁移实施
使用 uv 管理项目依赖
根据文档，使用 uv 管理项目依赖的典型流程如下：
bash
# 1. 安装 uv
pip install uv
# 2. 创建虚拟环境
uv venv
# 3. 激活虚拟环境
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
# 4. 安装依赖
uv pip install -r requirements.txt
# 或者对于使用 pyproject.toml 的项目
uv pip install -e .4. uv 与传统方式对比
| 传统方式 | uv 方式 |
|---|---|
python -m venv .venv | uv venv |
pip install -r requirements.txt | uv pip install -r requirements.txt |
pip install package_name | uv pip install package_name |
| 较慢的依赖解析 | 更快的依赖解析 |
5. 为什么项目推荐使用 uv
- 性能：uv 用 Rust 编写，执行速度显著快于传统的 pip
- 现代性：uv 是为现代 Python 生态系统设计的，支持最新的依赖解析算法
- 易用性：命令简洁，功能强大
进行渐进式重构，不要试图一次性全部改完：
- 第一步（基础设施统一）：先将
db_config.py、RAG_M中的配置文件统一迁移到app/core/config.py，确保全局使用同一个配置对象。 - 第二步（入口整理）：修改
main.py，将散落在各个目录下的路由文件统一注册到app/api/v1下，确保 API 路径规范（如/api/v1/chat/...）。 - 第三步（领域聚合）：挑选一个相对独立的模块（例如
document_processing），将其移动到app/domain/document，并修复导入路径。逐步将其他模块迁移进来。
这种架构设计将使你的 RAG 后端具备良好的扩展性，特别是方便后续引入更复杂的 Agent 编排和多模型切换逻辑