Liu_JB/fastapi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add handover and deployment guides

Browse Source
This commit is contained in:
刘金宝
2026-06-10 11:02:12 +08:00
parent 89258ab448
commit b92cefbd0b
8 changed files with 1236 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+86 -97
View File
@@ -1,33 +1,31 @@
# 医疗问诊 Agent FastAPI 后端
医疗问诊 Agent 是医疗教学平台中的 FastAPI 后端服务，负责 Django 用户鉴权、病例读取、问诊训练、教学互动、AI 评价、PDF 下载、AI 学习助手问答，以及后台预留的机构知识库构建能力。
本项目是医疗教学平台中的 FastAPI 后端服务，负责医疗问诊训练、教学互动、AI 评价、PDF 报告、AI 学习助手，以及后台预留的机构知识库能力。
本服务不负责登录注册、病例 PDF 解析入库、病例增删改、多租户后台、HIS/LIS/PACS 对接。病例、检查项、教学题和评分规则由平台数据库维护，本服务只读取并使用。
本服务不负责登录注册、用户管理、病例 PDF 解析入库、病例增删改、多租户后台、HIS/LIS/PACS 对接。用户身份由 Django 用户中心验证，病例、检查项、教学题和评分规则由平台数据库维护。
## 当前功能
## 1. 当前功能
训练页面：
- 推荐配置信息
- 训练配置信息
- 新建会话
- 流式会话
- AI 病人流式问诊
- 王主任练习提示
- 体格检查列表获取
- 辅助检查列表获取
- 体格检查某项结果
- 辅助检查某项结果
- 体格检查列表和结果
- 辅助检查列表和结果
- 完成问诊
- 提交诊断
- 提交治疗
- 生成评价
- 生成 AI 评价
- 获取评价详情
- 下载 PDF
教学互动：
- 获取教学列表，包含题目、选项、答案、解析文本和视频
- 生成评价
- 生成教学互动评价
- 获取评价详情
- 下载 PDF
@@ -38,53 +36,60 @@
AI 学习助手：
- 普通用户通过流式接口提问
- 普通用户通过 SSE 流式接口提问
- 后端优先检索本机构知识库
- 未命中知识库或知识库暂不可用时，自动转为大模型通用学习回答
- 命中知识库时返回 PDF 标题、页码、chunk_uid 和引用片段
- 知识库未初始化或检索失败时，自动降级为大模型通用学习回答
后台预留能力：
- 内容管理员上传 PDF 构建机构知识库
- PDF 解析、分片、Embedding、Milvus 写入和 Celery 异步任务已留出接口
- 当前阶段不要求真实 PDF 入库测试，优先保证 AI 学习助手问答可用
- PDF 解析、分片、Embedding、Milvus 写入、Celery 异步任务预留
基础能力：
## 2. 技术栈
- Django access token 鉴权
- MySQL 业务数据读取和训练记录写入
- Redis 短期会话 memory
- OpenAI-compatible LLM 调用
- OpenAI-compatible Embedding 调用预留
- Milvus 向量检索预留
- Swagger / OpenAPI
- 健康检查
- Python 3.11
- FastAPI
- Uvicorn
- SQLAlchemy
- Pydantic
- MySQL
- Redis
- OpenAI-compatible LLM
- OpenAI-compatible Embedding
- Milvus
- Celery
- Docker / Docker Compose
## 项目结构
## 3. 目录结构
```text
fastapi/
├── app/ # FastAPI 应用、Agent、服务、模型和提示词
├── app/
│ ├── api/ # API router
│ ├── agents/ # LLM Agent
│ ├── integrations/ # PDF、Embedding、Milvus 外部适配
│ ├── core/ # 配置、响应、异常、上下文
│ ├── db/ # 数据库连接
│ ├── integrations/ # PDF、Embedding、Milvus 适配
│ ├── models/ # SQLAlchemy ORM
│ ├── prompts/ # Markdown 提示词模板
│ ├── repositories/ # 数据访问层
│ ├── schemas/ # Pydantic schema
│ ├── schemas/ # Pydantic 入参/出参
│ ├── services/ # 业务服务
│ └── tasks/ # Celery 异步任务预留
├── docs/ # API、架构、数据库、部署和交接文档
├── scripts/ # 初始化和维护脚本
├── tests/ # 自动化测试
├── docs/03_api_design.md # 前端联调 API 文档
├── Dockerfile
├── requirements.txt
├── .env.example
└── .env.production.example
```
## 本地启动
## 4. 本地启动
```powershell
cd D:\Code\newfounder\medical-consultation-agent
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
@@ -98,9 +103,9 @@ uvicorn app.main:app --host 127.0.0.1 --port 9000
http://127.0.0.1:9000/docs
```
真实密码、LLM Key、Embedding Key 和 access token 只写入本地 `.env` 或服务器环境变量，不提交到 Git。
真实密码、LLM Key、Embedding Key 和 access token 只写入本地 `.env` 或服务器环境变量，不提交 Git。
## 关键环境变量
## 5. 关键环境变量
```env
APP_ENV=local
@@ -132,9 +137,9 @@ KNOWLEDGE_INGESTION_SYNC=true
KNOWLEDGE_STORAGE_DIR=./storage/knowledge
```
## 服务器部署
## 6. 云服务器部署
服务器目录示例：
服务器目录：
```text
/home/code/medical-ai/
@@ -147,46 +152,29 @@ KNOWLEDGE_STORAGE_DIR=./storage/knowledge
└── docker-compose.yml
```
首次拉取：
```bash
cd /home/code/medical-ai
git clone http://82.157.235.104:3000/Liu_JB/LiuJinbao.git fastapi
cp fastapi/.env.production.example fastapi/.env
vi fastapi/.env
```
FastAPI 构建和启动：
```bash
cd /home/code/medical-ai
docker compose build fastapi
docker compose up -d fastapi
docker compose logs --tail=200 fastapi
```
后续更新：
更新 FastAPI：
```bash
cd /home/code/medical-ai/fastapi
git pull origin main
cd ..
cd /home/code/medical-ai
docker compose build fastapi
docker compose up -d fastapi
docker compose logs --tail=200 fastapi
```
## 验证
如果 `requirements.txt` 有变动，必须重新 `docker compose build fastapi`。
公网验证：
## 7. 验证命令
```text
http://8.160.178.88/fastapi/docs
http://8.160.178.88/fastapi/openapi.json
http://8.160.178.88/fastapi/health/ready
健康检查：
```bash
curl http://127.0.0.1:9000/health/ready
```
Django 用户鉴权：
用户鉴权：
```bash
curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
@@ -204,42 +192,43 @@ curl -N -X POST "http://8.160.178.88/fastapi/api/v1/learning-assistant/chat/stre
-d '{"question":"支气管肺炎有哪些典型临床表现？","top_k":5}'
```
PDF 评价报告下载：
```bash
curl -L "http://8.160.178.88/fastapi/api/v1/evaluations/<evaluation_id>/download-pdf" \
-H "Authorization: Bearer <access_token>" \
-H "X-Entry-Scene: production_vue" \
-o evaluation_report.pdf
```
## 测试
```powershell
python -m compileall app scripts tests
python tests\test_core_logic.py
python tests\test_api_contract.py
python tests\test_demo_flow.py
```
测试覆盖：
- Django token 鉴权和 user_id 隔离
- 推荐配置和训练配置
- 新建会话、流式问诊、王主任练习提示
- 体格检查和辅助检查列表
- 单项检查结果和重复申请幂等
- 完成问诊、提交诊断、提交治疗、生成评价
- 教学互动列表和教学互动评价
- 训练记录列表、评价详情、PDF 下载
- AI 学习助手无知识库降级流式回答
- AI 学习助手命中知识库后的来源返回
- 跨用户访问拒绝
## API 文档
前端联调文档：
正常应看到：
```text
docs/03_api_design.md
event: retrieval_done
event: answer_delta
event: answer_done
```
## 8. 测试
```powershell
.\backend\.venv\Scripts\python.exe -m compileall app scripts tests
.\backend\.venv\Scripts\python.exe tests\test_core_logic.py
.\backend\.venv\Scripts\python.exe tests\test_demo_flow.py
.\backend\.venv\Scripts\python.exe tests\test_api_contract.py
```
## 9. 交接文档
| 文档 | 用途 |
|---|---|
| `docs/01_architecture.md` | 系统架构、调用链路和模块边界 |
| `docs/02_database.md` | 核心数据库表和读写边界 |
| `docs/03_api_design.md` | 前端联调 API 文档 |
| `docs/04_deployment.md` | 云服务器部署、更新和回滚 |
| `docs/05_modules.md` | 功能模块说明 |
| `docs/06_handover.md` | 离职交接说明和风险清单 |
| `docs/07_troubleshooting.md` | 常见故障排查 |
## 10. 重要约定
- FastAPI 不负责登录注册。
- 用户身份来自 Django `/api/user/users/me/`。
- FastAPI 使用 Django 返回的 `id` 作为 `user_id`。
- 普通 JSON 接口统一返回 `code`、`message`、`data`。
- SSE 接口返回 `event + data`。
- 检查结果只来自数据库，不由 LLM 编造。
- 完整训练结束后才写入长期训练记录。
- Redis 只保存短期会话 memory。
- `.env`、日志、PDF、storage 生成物不提交 Git。