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

项目开发日志 | 阶段一中医智能诊疗系统后端基础架构搭建与环境配置文章目录项目开发日志 | 阶段一中医智能诊疗系统后端基础架构搭建与环境配置前言一、项目背景与本阶段目标1.1 项目简介1.2 本阶段核心目标二、项目基础架构设计与搭建2.1 后端目录结构规划2.2 关键文件实现与说明2.2.1 服务入口文件 main.py2.2.2 启动脚本 run.py三、开发环境配置与验证3.1 虚拟环境搭建3.2 依赖清单配置3.3 环境验证与服务启动四、Git工作流配置与团队协作规范实践4.1 仓库初始化与分支策略4.2 .gitignore文件配置4.3 提交与推送流程实践五、本阶段遇到的问题与解决方法问题1Git Bash中激活虚拟环境失败问题2分支状态混乱误在master分支操作问题3提交时文件未被正确识别六、阶段总结与后续计划6.1 阶段成果总结6.2 后续工作计划结语前言作为一名计算机专业大三学生我正在参与开发“基于大模型的中医智能诊疗多智能体系统”项目。本阶段的核心任务是搭建项目后端基础架构、配置开发环境并建立符合团队规范的Git工作流。在这篇博客中,我将分享从零开始搭建项目的完整过程、遇到的问题与解决方法以及对团队协作规范的理解与实践。一、项目背景与本阶段目标1.1 项目简介本项目旨在构建一个基于大模型的中医智能诊疗系统通过多智能体协作的方式实现从用户对话、舌象分析、辨证论治到处方生成与报告输出的全流程辅助诊疗功能。后端采用FastAPI作为服务框架结合大模型、向量数据库、RAG检索等技术为前端提供稳定、高效的API支持。1.2 本阶段核心目标根据项目计划阶段一的核心任务包括搭建后端项目基础架构建立清晰的目录结构配置Python虚拟环境与项目依赖清单初始化Git仓库配置.gitignore文件建立团队协作规范完成服务入口文件编写验证服务可正常启动熟悉并遵守团队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.pyfromfastapiimportFastAPI# 初始化FastAPI应用实例appFastAPI(title中医智能诊疗多智能体系统后端,description基于大模型的中医智能诊疗辅助系统后端服务,version1.0.0)# 基础健康检查路由app.get(/)asyncdefroot():return{message:后端服务启动成功}2.2.2 启动脚本run.pyimportuvicornfrommainimportappif__name____main__:uvicorn.run(app,host0.0.0.0,port8000,reloadTrue# 开发模式下开启热重载修改代码后自动重启服务)三、开发环境配置与验证3.1 虚拟环境搭建为了保证项目依赖的独立性避免与系统Python环境冲突我使用venv创建了项目专属的虚拟环境# 在backend目录下创建虚拟环境python-mvenv mynew_env# 在Git Bash中激活虚拟环境Windows系统sourcemynew_env/Scripts/activate激活成功后终端前缀会出现(mynew_env)标识表示当前处于项目虚拟环境中。3.2 依赖清单配置根据项目当前阶段的需求创建了requirements.txt文件声明了基础依赖fastapi0.100.0 uvicorn0.23.2 python-dotenv1.0.0 pydantic2.1.1 requests2.31.03.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 CTRLC 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 *.sqlite4.3 提交与推送流程实践根据团队规范代码提交和推送必须遵循以下流程提交前Pull在提交代码前必须先拉取远程dev分支的最新代码确保本地代码与远程仓库同步避免代码冲突本地提交使用Git Commit - dev提交代码提交信息必须清晰规范说明本次提交的内容推送到远程通过TortoiseGit → Push将本地提交推送到远程dev分支本次提交的信息为后端基础架构搭建完成虚拟环境配置依赖声明服务入口文件清晰说明了提交的核心内容方便团队成员和队长后续查看与审核。五、本阶段遇到的问题与解决方法问题1Git 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 阶段成果总结通过本阶段的工作我完成了以下核心任务搭建了项目后端基础架构建立了清晰的目录结构配置了Python虚拟环境与项目依赖验证了服务可正常启动熟悉并实践了团队Git工作流掌握了分支管理与提交规范编写了服务入口文件实现了基础健康检查接口解决了开发过程中遇到的环境配置与Git操作问题积累了项目开发经验6.2 后续工作计划下一阶段我将重点开发以下功能模块实现api/health.py健康检查接口完善服务监控能力搭建core/llm.py大模型调用封装实现与大模型的基础交互开发rag/retriever.py向量检索逻辑实现知识库检索功能继续完善项目目录结构逐步实现各模块的基础代码定期提交博客记录开发过程中的技术学习与项目进展结语本阶段的工作让我对项目整体架构有了清晰的认识也熟悉了团队协作的Git工作流规范。在后续的开发过程中我将继续严格遵守团队规范稳步推进项目开发同时通过博客记录学习过程加深对技术的理解。