fastapi/README.md

# 医疗问诊 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. 目录结构

```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 .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：

```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 -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}'
```

正常应看到：

```text
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。