项目开发日志 | 阶段一：中医智能诊疗系统后端基础架构搭建与环境配置

前言

本阶段的核心任务是搭建项目后端基础架构、配置开发环境，并建立符合团队规范的Git工作流。在这篇博客中,我将分享从零开始搭建项目的完整过程、遇到的问题与解决方法，以及对团队协作规范的理解与实践。

---

一、项目背景与本阶段目标

1.1 项目简介

本项目旨在构建一个基于大模型的中医智能诊疗系统，通过多智能体协作的方式，实现从用户对话、舌象分析、辨证论治到处方生成与报告输出的全流程辅助诊疗功能。后端采用FastAPI作为服务框架，结合大模型、向量数据库、RAG检索等技术，为前端提供稳定、高效的API支持。

1.2 本阶段核心目标

根据项目计划，阶段一的核心任务包括：

1. 搭建后端项目基础架构，建立清晰的目录结构
2. 配置Python虚拟环境与项目依赖清单
3. 初始化Git仓库，配置.gitignore文件，建立团队协作规范
4. 完成服务入口文件编写，验证服务可正常启动
5. 熟悉并遵守团队Git工作流规则，掌握分支管理与提交规范

---

二、项目基础架构设计与搭建

2.1 后端目录结构规划

backend/
├── main.py                 # 项目入口，FastAPI实例初始化
├── config.py               # 全局配置读取
├── requirements.txt        # 项目依赖声明
├── .env                    # 环境变量与密钥
├── run.py                  # 服务启动脚本
│
├── api/                    # 接口层：处理HTTP请求与响应
│   ├── __init__.py
│   ├── diagnosis.py        # 诊疗相关接口
│   ├── conversation.py     # 对话历史管理接口
│   ├── health.py           # 健康检查接口
│   ├── report.py           # 报告生成与导出接口
│   ├── tongue.py           # 舌诊分析接口
│   └── rag.py              # 知识库检索接口
│
├── agent/                  # 智能体层：多智能体调度与流程控制
│   ├── __init__.py
│   ├── base.py             # Agent基类定义
│   ├── orchestrator.py     # 多智能体总调度
│   ├── state_machine.py    # 诊疗流程状态机
│   ├── sse_manager.py      # SSE推送管理
│   └── agents/             # 各领域智能体实现
│       ├── __init__.py
│       ├── diagnosis.py    # 辨证智能体
│       ├── ancient.py      # 古籍医案智能体
│       ├── modern.py       # 现代文献智能体
│       ├── prescription.py # 处方生成智能体
│       ├── pharmacist.py   # 用药审核智能体
│       ├── rehabilitation.py # 康复方案智能体
│       └── report.py       # 报告生成智能体
│
├── core/                   # 核心层：通用工具与基础组件
│   ├── __init__.py
│   ├── llm.py              # 大模型统一调用封装
│   ├── memory.py           # 对话上下文记忆管理
│   └── prompts.py          # 系统提示词模板
│
├── rag/                    # 知识库层：向量检索与文档处理
│   ├── __init__.py
│   ├── loader.py           # 文档加载与分块
│   ├── retriever.py        # 向量检索逻辑
│   ├── vector_store.py     # 向量库操作
│   ├── embedding.py        # 文本向量化
│   └── rerank.py           # 检索结果重排序
│
├── tongue/                 # 舌诊模块：图像识别与特征提取
│   ├── __init__.py
│   ├── recognize.py        # 舌象识别
│   ├── feature_extract.py  # 舌象特征提取
│   └── utils.py            # 舌诊工具函数
│
├── checker/                # 校验模块：逻辑与安全检查
│   ├── __init__.py
│   ├── logic_checker.py    # 诊疗逻辑校验
│   ├── hallucination_checker.py # 幻觉检测
│   └── prescription_safety.py # 处方安全校验
│
├── tools/                  # 工具层：为智能体提供可调用工具
│   ├── __init__.py
│   ├── rag_tool.py         # RAG调用工具
│   ├── tongue_tool.py      # 舌诊调用工具
│   ├── checker_tool.py     # 校验工具
│   ├── intent_tool.py      # 用户意图识别
│   ├── ask_tool.py         # 主动追问工具
│   └── reflect_tool.py     # 自我反思工具
│
├── services/               # 业务层：封装核心业务流程
│   ├── __init__.py
│   └── diagnosis_service.py # 诊疗业务流程服务
│
├── models/                 # 数据模型层：定义数据结构与校验规则
│   ├── __init__.py
│   └── schemas.py          # API数据校验模型
│
├── db/                     # 数据持久层：数据库操作
│   ├── __init__.py
│   ├── base.py             # ORM基类
│   ├── session.py          # 数据库会话管理
│   ├── models/             # 数据库表结构
│   └── crud/               # 数据增删改查操作
│
├── middleware/             # 中间件层：处理请求与响应的通用逻辑
│   ├── __init__.py
│   ├── error_handler.py    # 全局异常处理
│   └── logging.py          # 请求日志中间件
│
├── utils/                  # 工具函数层：通用辅助功能
│   ├── __init__.py
│   ├── logger.py           # 日志工具
│   ├── helpers.py          # 通用辅助函数
│   └── validators.py        # 数据校验工具
│
└── tests/                  # 测试目录：单元测试与集成测试
    ├── __init__.py
    ├── test_agent.py       # Agent单元测试
    ├── test_sse.py         # SSE推送测试
    └── test_tool.py        # 工具函数测试

2.2 关键文件实现与说明

2.2.1 服务入口文件 main.py

from fastapi import FastAPI

# 初始化FastAPI应用实例
app = FastAPI(
    title="中医智能诊疗多智能体系统后端",
    description="基于大模型的中医智能诊疗辅助系统后端服务",
    version="1.0.0"
)

# 基础健康检查路由
@app.get("/")
async def root():
    return {"message": "后端服务启动成功！"}

2.2.2 启动脚本 run.py

import uvicorn
from main import app

if __name__ == "__main__":
    uvicorn.run(
        app,
        host="0.0.0.0",
        port=8000,
        reload=True  # 开发模式下开启热重载，修改代码后自动重启服务
    )

---

三、开发环境配置与验证

3.1 虚拟环境搭建

为了保证项目依赖的独立性，避免与系统Python环境冲突，我使用venv创建了项目专属的虚拟环境：

# 在backend目录下创建虚拟环境
python -m venv mynew_env

# 在Git Bash中激活虚拟环境（Windows系统）
source mynew_env/Scripts/activate

激活成功后，终端前缀会出现(mynew_env)标识，表示当前处于项目虚拟环境中。

3.2 依赖清单配置

根据项目当前阶段的需求，创建了requirements.txt文件，声明了基础依赖：

fastapi==0.100.0
uvicorn==0.23.2
python-dotenv==1.0.0
pydantic==2.1.1
requests==2.31.0

3.3 环境验证与服务启动

在安装完依赖后，运行启动脚本验证环境配置是否正确：

# 安装项目依赖
pip install -r requirements.txt

# 启动服务
python run.py

服务成功启动后，终端会输出以下日志：

INFO: Started server process [31472]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

此时访问http://127.0.0.1:8000，可以看到{"message": "后端服务启动成功！"}的响应，说明服务已正常运行，环境配置全部正确—

四、Git工作流配置与团队协作规范实践

4.1 仓库初始化与分支策略

本项目采用团队统一的Git分支策略，核心规则如下：

• master分支：主分支，仅用于合并稳定版本，禁止直接提交代码，仅由队长进行合并操作
• dev分支：开发分支，所有开发工作都在该分支上进行，团队成员的代码提交和推送都必须在dev分支完成

我通过git clone从团队远程仓库拉取代码，并切换到dev分支：

# 拉取远程仓库代码
git clone [团队仓库地址]

# 切换到项目目录
cd agent

# 拉取所有远程分支信息
git fetch --all --prune

# 从远程dev分支创建并切换到本地dev分支
git checkout -b dev origin/dev

执行完成后，通过git branch可以看到当前处于dev分支，终端前缀也会显示(dev)标识，确保后续所有开发操作都在正确的分支上进行。

4.2 .gitignore文件配置

为了避免将虚拟环境、敏感配置文件、缓存文件等提交到Git仓库，项目根目录下已经配置了完整的.gitignore文件，核心内容包括：

# Python虚拟环境
mynew_env/
env/
venv/

# Python缓存文件
*.pyc
*.pyo
*.pyd
__pycache__/

# 环境变量与密钥文件
.env
.env.local
.env.*.local

# IDE配置文件
.vscode/
.idea/

# 日志与临时文件
logs/
*.log
*.tmp
*.temp

# 数据库文件
*.db
*.sqlite

4.3 提交与推送流程实践

根据团队规范，代码提交和推送必须遵循以下流程：

1. 提交前Pull：在提交代码前，必须先拉取远程dev分支的最新代码，确保本地代码与远程仓库同步，避免代码冲突

2. 本地提交：使用Git Commit -> "dev"提交代码，提交信息必须清晰规范，说明本次提交的内容
   

3. 推送到远程：通过TortoiseGit → Push将本地提交推送到远程dev分支
   

本次提交的信息为：后端基础架构搭建完成：虚拟环境配置+依赖声明+服务入口文件，清晰说明了提交的核心内容，方便团队成员和队长后续查看与审核。

---

五、本阶段遇到的问题与解决方法

问题1：Git Bash中激活虚拟环境失败

• 问题描述：在Git Bash中执行mynew_env\Scripts\activate时，提示command not found
• 原因分析：Git Bash会将Windows的反斜杠\识别为转义字符，导致命令被错误解析
• 解决方法：使用正斜杠/代替反斜杠，或者使用source命令激活：

  source mynew_env/Scripts/activate
  

问题2：分支状态混乱，误在master分支操作

• 问题描述：在开发过程中，终端前缀显示(master)，说明当前处于主分支，存在直接修改主分支的风险
• 解决方法：通过git branch查看当前分支，确认处于dev分支；如果不是，执行git checkout dev切换分支，并在后续所有操作中关注终端的分支标识，确保始终在dev分支开发

问题3：提交时文件未被正确识别

• 问题描述：提交时requirements.txt显示为Unknown状态，无法提交
• 解决方法：确认文件已经创建，并且在.gitignore中没有被忽略；通过git add backend/requirements.txt手动添加文件，或者在提交界面勾选文件，即可正常提交

---

六、阶段总结与后续计划

6.1 阶段成果总结

通过本阶段的工作，我完成了以下核心任务：

1. 搭建了项目后端基础架构，建立了清晰的目录结构
2. 配置了Python虚拟环境与项目依赖，验证了服务可正常启动
3. 熟悉并实践了团队Git工作流，掌握了分支管理与提交规范
4. 编写了服务入口文件，实现了基础健康检查接口
5. 解决了开发过程中遇到的环境配置与Git操作问题，积累了项目开发经验

6.2 后续工作计划

下一阶段，我将重点开发以下功能模块：

1. 实现api/health.py健康检查接口，完善服务监控能力
2. 搭建core/llm.py大模型调用封装，实现与大模型的基础交互
3. 开发rag/retriever.py向量检索逻辑，实现知识库检索功能
4. 继续完善项目目录结构，逐步实现各模块的基础代码
5. 定期提交博客，记录开发过程中的技术学习与项目进展

---

结语

本阶段的工作让我对项目整体架构有了清晰的认识，也熟悉了团队协作的Git工作流规范。在后续的开发过程中，我将继续严格遵守团队规范，稳步推进项目开发，同时通过博客记录学习过程，加深对技术的理解。

---