刘金宝
251 lines
7.1 KiB
Markdown
251 lines
7.1 KiB
Markdown
# 医疗问诊 Agent FastAPI 后端
|
||
|
||
本项目是医疗教学平台中的 FastAPI 后端服务，负责医疗问诊训练、教学互动、AI 评价、PDF 报告、AI 学习助手，以及后台预留的机构知识库能力。
|
||
|
||
本服务不负责登录注册、用户管理、病例 PDF 解析入库、病例增删改、多租户后台、HIS/LIS/PACS 连接。用户身份由 Django 用户中心验证，病例、检查项、教学题和评分规则由平台数据库维护。
|
||
|
||
## 1. 当前功能
|
||
|
||
训练页面：
|
||
|
||
- 推荐配置信息
|
||
- 训练配置信息
|
||
- 新建会话
|
||
- AI 病人流式问诊
|
||
- 王主任练习提示
|
||
- 体格检查列表和结果（无单独数据库，解析case_base对应字段获取）
|
||
- 辅助检查列表和结果（无单独数据库，解析case_base对应字段获取）
|
||
- 完成问诊
|
||
- 提交诊断
|
||
- 提交治疗
|
||
- 生成 AI 评价
|
||
- 获取评价详情
|
||
- 下载 PDF
|
||
|
||
教学互动：
|
||
|
||
- 获取教学列表，包含题目、选项、答案、解析文本和视频（数据库无具体数据，AI生成对应题库，自测通过，视频未测试）
|
||
- 生成教学互动评价
|
||
- 获取评价详情
|
||
- 下载 PDF
|
||
|
||
个人中心：
|
||
|
||
- 训练记录列表
|
||
- 训练记录详情
|
||
|
||
AI 学习助手：
|
||
|
||
- 普通用户先新建 AI 学习助手短期会话，再通过 SSE 流式接口提问
|
||
- 后端优先检索本机构知识库
|
||
- 知识库未初始化或检索失败时，自动降级为大模型通用学习回答
|
||
- 学习助手会话使用 Redis 短期缓存保存最近问答上下文，不写入训练记录
|
||
|
||
后台预留能力：
|
||
|
||
- 内容管理员上传 PDF 构建机构知识库
|
||
- PDF 解析、分片、Embedding、Milvus 写入、Celery 异步任务预留
|
||
|
||
## 2. 技术栈
|
||
|
||
- Python 3.11
|
||
- FastAPI
|
||
- Uvicorn
|
||
- SQLAlchemy
|
||
- Pydantic
|
||
- MySQL
|
||
- Redis
|
||
- OpenAI-compatible LLM
|
||
- OpenAI-compatible Embedding
|
||
- Milvus
|
||
- Celery
|
||
- Docker / Docker Compose
|
||
|
||
## 3. 目录结构
|
||
|
||
```text
|
||
fastapi/
|
||
├── app/
|
||
│ ├── api/ # API router
|
||
│ ├── agents/ # LLM Agent
|
||
│ ├── core/ # 配置、响应、异常、上下文
|
||
│ ├── db/ # 数据库连接
|
||
│ ├── integrations/ # PDF、Embedding、Milvus 适配
|
||
│ ├── models/ # SQLAlchemy ORM
|
||
│ ├── prompts/ # Markdown 提示词模板
|
||
│ ├── repositories/ # 数据访问层
|
||
│ ├── schemas/ # Pydantic 入参/出参
|
||
│ ├── services/ # 业务服务
|
||
│ └── tasks/ # Celery 异步任务预留
|
||
├── docs/ # API、架构、数据库、部署和项目文档
|
||
├── scripts/ # 初始化和维护脚本
|
||
├── tests/ # 自动化测试
|
||
├── Dockerfile
|
||
├── requirements.txt
|
||
├── .env.example
|
||
└── .env.production.example
|
||
```
|
||
|
||
## 4. 本地启动
|
||
|
||
```powershell
|
||
cd D:\Code\newfounder\medical-consultation-agent
|
||
|
||
python -m venv backend\.venv
|
||
.\backend\.venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
copy .env.example .env
|
||
uvicorn app.main:app --host 127.0.0.1 --port 9000
|
||
```
|
||
|
||
本地 Swagger：
|
||
|
||
```text
|
||
http://127.0.0.1:9000/docs
|
||
```
|
||
|
||
真实密码、LLM Key、Embedding Key 和 access token 只写入本地 `.env` 或服务器环境变量，不提交 Git。
|
||
|
||
## 5. 关键环境变量
|
||
|
||
```env
|
||
APP_ENV=local
|
||
APP_ROOT_PATH=
|
||
DATABASE_URL=mysql+pymysql://root:<password>@127.0.0.1:3306/medical?charset=utf8mb4
|
||
RUNTIME_MEMORY_BACKEND=redis
|
||
REDIS_URL=redis://127.0.0.1:6379/0
|
||
|
||
AUTH_VALIDATE_ENABLED=true
|
||
AUTH_USER_ME_URL=http://127.0.0.1:8000/api/user/users/me/
|
||
|
||
LLM_BASE_URL=https://api.deepseek.com/chat/completions
|
||
LLM_API_KEY=<llm_api_key>
|
||
LLM_MODEL=deepseek-chat
|
||
LLM_FAST_MODEL=deepseek-chat
|
||
LLM_REASON_MODEL=deepseek-reasoner
|
||
|
||
MILVUS_URI=http://127.0.0.1:19530
|
||
MILVUS_COLLECTION_PREFIX=kb_inst
|
||
MILVUS_DEFAULT_DB=default
|
||
|
||
EMBEDDING_PROVIDER=openai_compatible
|
||
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
EMBEDDING_API_KEY=<embedding_api_key>
|
||
EMBEDDING_MODEL=text-embedding-v4
|
||
EMBEDDING_DIM=1024
|
||
|
||
KNOWLEDGE_INGESTION_SYNC=true
|
||
KNOWLEDGE_STORAGE_DIR=./storage/knowledge
|
||
```
|
||
|
||
## 6. 云服务器部署
|
||
|
||
服务器目录：
|
||
|
||
```text
|
||
/home/code/medical-ai/
|
||
├── django/
|
||
├── fastapi/
|
||
├── vueapp/
|
||
├── vuecms/
|
||
├── data/
|
||
├── logs/
|
||
└── docker-compose.yml
|
||
```
|
||
|
||
更新 FastAPI：
|
||
|
||
```bash
|
||
cd /home/code/medical-ai/fastapi
|
||
git pull origin main
|
||
|
||
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. 验证命令
|
||
|
||
健康检查：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:9000/health/ready
|
||
```
|
||
|
||
用户鉴权：
|
||
|
||
```bash
|
||
curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
|
||
-H "Authorization: Bearer <access_token>" \
|
||
-H "X-Entry-Scene: production_vue"
|
||
```
|
||
|
||
AI 学习助手新建会话：
|
||
|
||
```bash
|
||
curl -X POST "http://8.160.178.88/fastapi/api/v1/learning-assistant/sessions" \
|
||
-H "Authorization: Bearer <access_token>" \
|
||
-H "X-Entry-Scene: production_vue" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"title":"儿科肺炎知识复习"}'
|
||
```
|
||
|
||
AI 学习助手会话式流式问答：
|
||
|
||
```bash
|
||
curl -N -X POST "http://8.160.178.88/fastapi/api/v1/learning-assistant/sessions/<assistant_session_id>/chat/stream" \
|
||
-H "Authorization: Bearer <access_token>" \
|
||
-H "X-Entry-Scene: production_vue" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"question":"支气管肺炎有哪些典型临床表现？","top_k":5}'
|
||
```
|
||
|
||
正常应看到：
|
||
|
||
```text
|
||
event: session_ready
|
||
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/00_project_overview.md` | 项目总览和功能讲解顺序 |
|
||
| `docs/01_architecture.md` | 系统架构、调用链路和模块边界 |
|
||
| `docs/02_database.md` | 核心数据库表和读写边界 |
|
||
| `docs/03_api_design.md` | 前端 API 文档 |
|
||
| `docs/04_deployment.md` | 云服务器部署、更新和回滚 |
|
||
| `docs/05_modules.md` | 功能模块说明 |
|
||
| `docs/06_maintenance_guide.md` | 开发维护说明和风险清单 |
|
||
| `docs/07_troubleshooting.md` | 常见故障排查 |
|
||
| `docs/08_feature_code_map.md` | 功能到接口、代码和数据表的映射表 |
|
||
| `docs/09_prompt_template_catalog.md` | 提示词模板目录和调用说明 |
|
||
| `docs/10_function_workflow.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。
|