Liu_JB/fastapi

Fork 0

Files

T

刘金宝 b92cefbd0b docs: add handover and deployment guides

2026-06-10 11:02:12 +08:00

6.1 KiB

Raw Blame History

医疗问诊 Agent FastAPI 后端

本项目是医疗教学平台中的 FastAPI 后端服务，负责医疗问诊训练、教学互动、AI 评价、PDF 报告、AI 学习助手，以及后台预留的机构知识库能力。

本服务不负责登录注册、用户管理、病例 PDF 解析入库、病例增删改、多租户后台、HIS/LIS/PACS 对接。用户身份由 Django 用户中心验证，病例、检查项、教学题和评分规则由平台数据库维护。

1. 当前功能

训练页面：

推荐配置信息
训练配置信息
新建会话
AI 病人流式问诊
王主任练习提示
体格检查列表和结果
辅助检查列表和结果
完成问诊
提交诊断
提交治疗
生成 AI 评价
获取评价详情
下载 PDF

教学互动：

获取教学列表，包含题目、选项、答案、解析文本和视频
生成教学互动评价
获取评价详情
下载 PDF

个人中心：

训练记录列表
训练记录详情

AI 学习助手：

普通用户通过 SSE 流式接口提问
后端优先检索本机构知识库
知识库未初始化或检索失败时，自动降级为大模型通用学习回答

后台预留能力：

内容管理员上传 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. 目录结构

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. 本地启动

cd D:\Code\newfounder\medical-consultation-agent

python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
uvicorn app.main:app --host 127.0.0.1 --port 9000

本地 Swagger：

http://127.0.0.1:9000/docs

真实密码、LLM Key、Embedding Key 和 access token 只写入本地 .env 或服务器环境变量，不提交 Git。

5. 关键环境变量

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. 云服务器部署

服务器目录：

/home/code/medical-ai/
├── django/
├── fastapi/
├── vueapp/
├── vuecms/
├── data/
├── logs/
└── docker-compose.yml

更新 FastAPI：

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. 验证命令

健康检查：

curl http://127.0.0.1:9000/health/ready

用户鉴权：

curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Entry-Scene: production_vue"

AI 学习助手流式问答：

curl -N -X POST "http://8.160.178.88/fastapi/api/v1/learning-assistant/chat/stream" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Entry-Scene: production_vue" \
  -H "Content-Type: application/json" \
  -d '{"question":"支气管肺炎有哪些典型临床表现？","top_k":5}'

正常应看到：

event: retrieval_done
event: answer_delta
event: answer_done

8. 测试

.\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。

6.1 KiB Raw Blame History Unescape Escape