项目实训（一）｜中医智能诊疗系统后端基础架构搭建与环境配置

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

前言

作为一名计算机专业大三学生，我正在参与开发“基于大模型的中医智能诊疗多智能体系统”项目。本阶段的核心任务是搭建项目后端基础架构、配置开发环境，并建立符合团队规范的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

fromfastapiimportFastAPI# 初始化FastAPI应用实例app=FastAPI(title="中医智能诊疗多智能体系统后端",description="基于大模型的中医智能诊疗辅助系统后端服务",version="1.0.0")# 基础健康检查路由@app.get("/")asyncdefroot():return{"message":"后端服务启动成功！"}

2.2.2 启动脚本run.py

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

三、开发环境配置与验证

3.1 虚拟环境搭建

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

# 在backend目录下创建虚拟环境python-mvenv mynew_env# 在Git Bash中激活虚拟环境（Windows系统）sourcemynew_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 环境验证与服务启动

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

# 安装项目依赖pipinstall-rrequirements.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分支：

# 拉取远程仓库代码gitclone[团队仓库地址]# 切换到项目目录cdagent# 拉取所有远程分支信息gitfetch--all--prune# 从远程dev分支创建并切换到本地dev分支gitcheckout-bdev 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命令激活：

  sourcemynew_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工作流规范。在后续的开发过程中，我将继续严格遵守团队规范，稳步推进项目开发，同时通过博客记录学习过程，加深对技术的理解。