docs: add handover and deployment guides
This commit is contained in:
刘金宝
+1
-1
@@ -38,7 +38,7 @@ uploads/
|
||||
|
||||
# Demo-only or temporary files
|
||||
docs/*
|
||||
!docs/03_api_design.md
|
||||
!docs/*.md
|
||||
demo_frontend/
|
||||
scripts/check_mysql_demo.ps1
|
||||
scripts/init_mysql_demo.ps1
|
||||
|
||||
@@ -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。
|
||||
|
||||
@@ -0,0 +1,154 @@
|
||||
# 系统架构说明
|
||||
|
||||
本文档用于交接医疗问诊 Agent FastAPI 后端的系统边界、核心链路和外部依赖。
|
||||
|
||||
## 1. 项目定位
|
||||
|
||||
本项目是医疗教学平台中的 FastAPI 后端子服务，不负责登录注册和用户管理。用户从前端进入医疗问诊 Agent 时携带 Django 用户中心签发的 `access_token`，FastAPI 调用 Django `/api/user/users/me/` 验证用户身份，并使用 Django 返回的 `id` 作为本服务统一 `user_id`。
|
||||
|
||||
当前已完成并保留的业务模块：
|
||||
|
||||
- 训练页面：训练配置、新建会话、流式问诊、练习提示、检查申请、诊断治疗提交、AI 评价、PDF 下载
|
||||
- 教学互动：题目列表、答题评价、评价详情、PDF 下载
|
||||
- 个人中心：训练记录列表、训练记录详情
|
||||
- AI 学习助手：流式知识问答，优先 RAG，知识库不可用时降级为通用 LLM 回答
|
||||
- 后台预留：内容管理员知识库上传、PDF 解析、分片、Embedding、Milvus、Celery 异步任务
|
||||
|
||||
## 2. 总体架构
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Vue["Vue 前端"] --> FastAPI["FastAPI 医疗问诊 Agent"]
|
||||
FastAPI --> Django["Django 用户中心 /api/user/users/me/"]
|
||||
FastAPI --> MySQL["MySQL medical"]
|
||||
FastAPI --> Redis["Redis 短期会话 memory"]
|
||||
FastAPI --> LLM["OpenAI-compatible LLM"]
|
||||
FastAPI --> Milvus["Milvus 向量库"]
|
||||
FastAPI --> Storage["storage/reports 和 storage/knowledge"]
|
||||
```
|
||||
|
||||
## 3. 代码分层
|
||||
|
||||
| 目录 | 职责 |
|
||||
|---|---|
|
||||
| `app/api` | FastAPI 路由层，只做参数接收、依赖注入和响应返回 |
|
||||
| `app/schemas` | Pydantic 入参和出参模型 |
|
||||
| `app/services` | 业务流程编排，例如会话、评价、PDF、学习助手 |
|
||||
| `app/repositories` | 数据库读写封装 |
|
||||
| `app/models` | SQLAlchemy ORM 模型 |
|
||||
| `app/agents` | LLM Agent、评分、报告、病人、学习助手 |
|
||||
| `app/integrations` | 外部适配器：PDF、Embedding、Milvus |
|
||||
| `app/core` | 配置、响应、异常、上下文、用户鉴权依赖 |
|
||||
| `app/db` | 数据库连接 |
|
||||
| `app/tasks` | Celery 异步任务预留 |
|
||||
| `app/prompts` | Markdown 提示词模板 |
|
||||
| `tests` | 核心逻辑、Demo 流程、API 合约测试 |
|
||||
|
||||
## 4. 用户鉴权链路
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as Vue 前端
|
||||
participant API as FastAPI
|
||||
participant DJ as Django 用户中心
|
||||
FE->>API: Authorization: Bearer access_token
|
||||
API->>DJ: GET /api/user/users/me/
|
||||
DJ-->>API: 用户信息 / 401
|
||||
API-->>FE: data.user_id / role / institution_id
|
||||
```
|
||||
|
||||
关键点：
|
||||
|
||||
- FastAPI 不解析和签发 token。
|
||||
- 用户身份以 Django 返回为准。
|
||||
- `user_id` 使用 Django `user.id`。
|
||||
- 业务接口通过 `Authorization` 和 `X-Entry-Scene` 进入上下文。
|
||||
|
||||
## 5. 训练链路
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["获取病例和训练配置"] --> B["创建 training_session"]
|
||||
B --> C["Redis 初始化短期 memory"]
|
||||
C --> D["流式问诊 Patient Agent"]
|
||||
D --> E["申请体格/辅助检查"]
|
||||
E --> F["完成问诊"]
|
||||
F --> G["提交诊断"]
|
||||
G --> H["提交治疗"]
|
||||
H --> I["Scoring Agent 生成评价"]
|
||||
I --> J["写入 training_record 和 score_detail"]
|
||||
J --> K["生成 / 下载 PDF"]
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- 问诊过程只作为短期 memory，不作为长期聊天历史保存。
|
||||
- 检查结果只来自数据库，不由 LLM 编造。
|
||||
- 只有完整训练结束后写入训练记录。
|
||||
|
||||
## 6. 教学互动链路
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["读取 case_base + teaching_case"] --> B["返回题目、选项、答案、解析、视频"]
|
||||
B --> C["前端提交答题结果"]
|
||||
C --> D["教学互动评价"]
|
||||
D --> E["写入训练记录和评分明细"]
|
||||
E --> F["评价详情 / PDF 下载"]
|
||||
```
|
||||
|
||||
当前教学题数据由数据库维护；如数据库暂无完整题目，可由种子数据或后台维护补齐。
|
||||
|
||||
## 7. AI 学习助手链路
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["用户提问"] --> B["按 institution_id 定位知识空间"]
|
||||
B --> C{"知识库可用?"}
|
||||
C -- 是 --> D["Embedding 用户问题"]
|
||||
D --> E["Milvus 检索 chunks"]
|
||||
E --> F["拼接来源和问题"]
|
||||
C -- 否 --> G["空来源降级"]
|
||||
F --> H["LLM 流式回答"]
|
||||
G --> H
|
||||
H --> I["SSE: retrieval_done / answer_delta / answer_done"]
|
||||
```
|
||||
|
||||
当前正式前端接口只使用：
|
||||
|
||||
```text
|
||||
POST /api/v1/learning-assistant/chat/stream
|
||||
```
|
||||
|
||||
知识库不可用时不会阻断回答，接口会返回 `retrieval_hit=false` 和 `retrieval_error`，随后继续输出通用 LLM 回答。
|
||||
|
||||
## 8. 后台知识库预留链路
|
||||
|
||||
后台内容管理员能力，学生端不展示入口：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["内容管理员上传 PDF"] --> B["保存文档元数据"]
|
||||
B --> C["解析 PDF"]
|
||||
C --> D["语义分片"]
|
||||
D --> E["Embedding"]
|
||||
E --> F["写入 Milvus"]
|
||||
F --> G["写入 MySQL chunk 元数据"]
|
||||
```
|
||||
|
||||
生产级后续重点：
|
||||
|
||||
- 大文件上传限制和进度
|
||||
- PDF 解析质量校验
|
||||
- 分片策略调优
|
||||
- Embedding 批量重试
|
||||
- Milvus collection 生命周期管理
|
||||
- Celery 任务监控和失败重试
|
||||
|
||||
## 9. 当前生产化风险
|
||||
|
||||
- 部分知识库能力是生产预留接口，真实大规模 PDF 入库仍需压测。
|
||||
- Milvus、Embedding、Celery 需要运维侧监控。
|
||||
- LLM 调用需要进一步完善限流、重试、熔断和成本统计。
|
||||
- PDF 报告样式可继续优化。
|
||||
- 前端最终 UI 不在本仓库维护。
|
||||
@@ -0,0 +1,214 @@
|
||||
# 数据库说明
|
||||
|
||||
本文档说明医疗问诊 Agent FastAPI 后端依赖的核心数据表、读写边界和交接注意事项。
|
||||
|
||||
## 1. 数据库边界
|
||||
|
||||
当前服务连接平台 MySQL 数据库 `medical`。用户、机构、科室由 Django 平台维护；FastAPI 只读取用户上下文，不负责注册登录。
|
||||
|
||||
FastAPI 主要负责：
|
||||
|
||||
- 读取病例、教学题、检查项、评分规则
|
||||
- 写入训练会话过程中的提交结果
|
||||
- 完整训练结束后写入训练记录和评分明细
|
||||
- 生成 PDF 文件路径和导出状态
|
||||
- 后台预留知识库相关表
|
||||
|
||||
## 2. 用户与组织表
|
||||
|
||||
### `user`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 来源 | Django 用户中心 |
|
||||
| FastAPI 用途 | 通过 `/api/user/users/me/` 获取用户身份 |
|
||||
| 关键字段 | `id`、`username`、`real_name`、`phone`、`role_type`、`institution_id`、`department_id`、`status` |
|
||||
| 写入方 | Django |
|
||||
| FastAPI 是否写入 | 否 |
|
||||
|
||||
FastAPI 使用 Django 返回的 `id` 作为业务 `user_id`。
|
||||
|
||||
### `institution`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 来源 | Django / 平台数据库 |
|
||||
| FastAPI 用途 | 学习助手知识库按机构隔离 |
|
||||
| 关键字段 | `id`、`name` |
|
||||
| 写入方 | Django 或平台后台 |
|
||||
| FastAPI 是否写入 | 否 |
|
||||
|
||||
### `department`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 来源 | 平台数据库 |
|
||||
| FastAPI 用途 | 病例科室、评分规则、知识库筛选 |
|
||||
| 关键字段 | `id`、`name`、`category`、`institution_id` |
|
||||
| 写入方 | 平台后台 |
|
||||
| FastAPI 是否写入 | 否 |
|
||||
|
||||
## 3. 病例与训练基础表
|
||||
|
||||
### `case_base`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 病例主表，训练和教学互动共用 |
|
||||
| 读取模块 | 病例列表、病例详情、训练会话、教学互动 |
|
||||
| 关键字段 | `id`、`department_id`、`title`、`difficulty`、`case_type`、`status` |
|
||||
| 写入方 | 平台病例解析 / 后台维护 |
|
||||
| FastAPI 是否写入 | 否 |
|
||||
|
||||
### `traditional_case`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 练习模式传统病例详情 |
|
||||
| 读取模块 | 训练会话、Patient Agent、Scoring Agent |
|
||||
| 关键字段 | `case_id`、主诉、现病史、既往史、查体、辅助检查、诊断、治疗 |
|
||||
| 写入方 | 平台病例解析 / 后台维护 |
|
||||
| FastAPI 是否写入 | 否 |
|
||||
|
||||
### `teaching_case`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 教学互动病例和题目数据 |
|
||||
| 读取模块 | 教学互动列表、教学互动评价 |
|
||||
| 关键字段 | `case_id`、题目、选项、答案、解析、视频 |
|
||||
| 写入方 | 平台病例解析 / 后台维护 |
|
||||
| FastAPI 是否写入 | 否 |
|
||||
|
||||
### `case_exam_item`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 当前病例可申请的体格检查和辅助检查项 |
|
||||
| 读取模块 | 检查列表、检查结果、评价 |
|
||||
| 关键字段 | `case_id`、`item_code`、`item_name`、`item_type`、`result_text` |
|
||||
| 写入方 | 平台病例解析 / 后台维护 |
|
||||
| FastAPI 是否写入 | 否 |
|
||||
|
||||
检查结果必须来自该表，不允许 LLM 编造。
|
||||
|
||||
### `scoring_rule`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | AI 评价基础评分规则 |
|
||||
| 读取模块 | Scoring Agent、教学互动评价 |
|
||||
| 关键字段 | `case_id`、`department_id`、评分维度、分值、规则内容 |
|
||||
| 写入方 | 平台后台 |
|
||||
| FastAPI 是否写入 | 否 |
|
||||
|
||||
## 4. 训练记录表
|
||||
|
||||
### `training_sessions`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 训练过程会话状态 |
|
||||
| 写入模块 | 新建会话、阶段流转 |
|
||||
| 关键字段 | `id`、`session_uid`、`user_id`、`case_id`、`mode`、`status`、`patient_config` |
|
||||
| 访问隔离 | 必须按 `user_id` 查询 |
|
||||
|
||||
### `session_orders`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 记录当前会话已申请检查 |
|
||||
| 写入模块 | 体格检查 / 辅助检查结果接口 |
|
||||
| 关键字段 | `session_id`、`item_code`、`result_text`、`already_ordered` |
|
||||
| 重要规则 | 同一会话同一 `item_code` 幂等，不重复写入 |
|
||||
|
||||
### `session_submissions`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 保存诊断和治疗提交内容 |
|
||||
| 写入模块 | 提交诊断、提交治疗 |
|
||||
| 关键字段 | `session_id`、`submission_type`、`content` |
|
||||
|
||||
### `session_runtime_messages`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 调试或短期会话消息辅助表 |
|
||||
| 规则 | 长期历史不以完整聊天记录为主，正式上下文优先走 Redis 短期 memory |
|
||||
|
||||
### `training_record`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 完整训练结束后的长期记录 |
|
||||
| 写入模块 | 生成评价、教学互动评价 |
|
||||
| 关键字段 | `id`、`user_id`、`case_id`、`score_type`、`total_score`、`report_summary`、`pdf_path` |
|
||||
| 重要规则 | 中断、退出、未完成流程不写入 |
|
||||
|
||||
### `training_score_detail`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 评分明细表 |
|
||||
| 写入模块 | 训练评价、教学互动评价 |
|
||||
| 关键字段 | `record_id`、`rule_id`、`dimension`、`score`、`deducted_reason`、`evidence_message_ids`、`ai_confidence`、`comment` |
|
||||
|
||||
## 5. 知识库预留表
|
||||
|
||||
### `kb_knowledge_space`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 机构知识空间和 Milvus collection 映射 |
|
||||
| 关键字段 | `institution_id`、`collection_name`、`embedding_model`、`embedding_dim`、`status` |
|
||||
|
||||
### `kb_knowledge_document`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | 内容管理员上传 PDF 的元数据 |
|
||||
| 关键字段 | `institution_id`、`uploaded_by`、`file_name`、`file_sha256`、`status`、`parse_status`、`embedding_status`、`chunk_count` |
|
||||
|
||||
### `kb_knowledge_chunk`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | PDF 分片文本和页码来源 |
|
||||
| 关键字段 | `document_id`、`institution_id`、`chunk_uid`、`page_start`、`page_end`、`chunk_text` |
|
||||
|
||||
### `kb_knowledge_ingestion_task`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | PDF 入库任务进度 |
|
||||
| 关键字段 | `document_id`、`institution_id`、`status`、`progress`、`current_step`、`error_message` |
|
||||
|
||||
### `kb_knowledge_query_log`
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 用途 | AI 学习助手 RAG 查询日志 |
|
||||
| 关键字段 | `user_id`、`institution_id`、`question`、`retrieval_hit`、`retrieved_chunk_ids`、`answer_summary`、耗时字段 |
|
||||
|
||||
当前阶段 AI 学习助手不强依赖知识库存在；没有知识库时仍会调用 LLM 流式回答。
|
||||
|
||||
## 6. Redis 数据
|
||||
|
||||
Redis 用于短期会话 memory：
|
||||
|
||||
- 会话创建时初始化
|
||||
- 问诊、检查结果、诊断治疗提交时写入
|
||||
- 评价生成后释放
|
||||
- TTL 到期后自动过期
|
||||
|
||||
Redis 不作为长期训练历史存储。
|
||||
|
||||
## 7. 数据库交接注意事项
|
||||
|
||||
- FastAPI 不维护用户注册登录。
|
||||
- FastAPI 不直接修改病例基础数据。
|
||||
- 训练记录按 `user_id` 隔离。
|
||||
- 检查结果只从 `case_exam_item` 返回。
|
||||
- 评价生成后才写长期训练记录。
|
||||
- 知识库表是生产扩展点，真实大规模入库前需要压测。
|
||||
@@ -0,0 +1,210 @@
|
||||
# 部署说明
|
||||
|
||||
本文档用于交接云服务器部署、更新、回滚和验证流程。
|
||||
|
||||
## 1. 服务器目录
|
||||
|
||||
当前云服务器目录约定：
|
||||
|
||||
```text
|
||||
/home/code/medical-ai/
|
||||
├── django/
|
||||
├── fastapi/
|
||||
├── vueapp/
|
||||
├── vuecms/
|
||||
├── data/
|
||||
├── logs/
|
||||
└── docker-compose.yml
|
||||
```
|
||||
|
||||
FastAPI 项目目录：
|
||||
|
||||
```text
|
||||
/home/code/medical-ai/fastapi
|
||||
```
|
||||
|
||||
FastAPI 容器端口：
|
||||
|
||||
```text
|
||||
9000
|
||||
```
|
||||
|
||||
公网 Nginx 路径：
|
||||
|
||||
```text
|
||||
http://8.160.178.88/fastapi/
|
||||
```
|
||||
|
||||
## 2. 环境变量
|
||||
|
||||
服务器环境变量文件：
|
||||
|
||||
```text
|
||||
/home/code/medical-ai/fastapi/.env
|
||||
```
|
||||
|
||||
`.env` 不提交 Git。首次部署时从模板复制：
|
||||
|
||||
```bash
|
||||
cd /home/code/medical-ai
|
||||
cp fastapi/.env.production.example fastapi/.env
|
||||
vi fastapi/.env
|
||||
```
|
||||
|
||||
必须确认：
|
||||
|
||||
- `APP_ROOT_PATH=/fastapi`
|
||||
- `DATABASE_URL` 指向 Docker 网络中的 MySQL
|
||||
- `REDIS_URL` 指向 Docker 网络中的 Redis
|
||||
- `AUTH_USER_ME_URL` 指向 Django 容器或可访问地址
|
||||
- `LLM_API_KEY` 已配置
|
||||
- `MILVUS_URI`、`MILVUS_HOST`、`MILVUS_PORT` 与 docker-compose 一致
|
||||
- `EMBEDDING_API_KEY` 如启用真实 embedding，需要配置
|
||||
|
||||
## 3. 首次部署
|
||||
|
||||
```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
|
||||
|
||||
docker compose build fastapi
|
||||
docker compose up -d fastapi
|
||||
docker compose logs --tail=200 fastapi
|
||||
```
|
||||
|
||||
## 4. 日常更新
|
||||
|
||||
只更新 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` 有变动，必须执行：
|
||||
|
||||
```bash
|
||||
docker compose build fastapi
|
||||
```
|
||||
|
||||
不能只执行 `docker compose up -d fastapi`。
|
||||
|
||||
## 5. 服务验证
|
||||
|
||||
容器内端口验证：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:9000/health/ready
|
||||
```
|
||||
|
||||
公网 Docs：
|
||||
|
||||
```text
|
||||
http://8.160.178.88/fastapi/docs
|
||||
```
|
||||
|
||||
用户鉴权：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 6. 查看日志
|
||||
|
||||
```bash
|
||||
cd /home/code/medical-ai
|
||||
docker compose logs -f fastapi
|
||||
docker compose logs --tail=200 fastapi
|
||||
```
|
||||
|
||||
查看容器状态：
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker ps
|
||||
```
|
||||
|
||||
## 7. 回滚
|
||||
|
||||
查看历史提交：
|
||||
|
||||
```bash
|
||||
cd /home/code/medical-ai/fastapi
|
||||
git log --oneline
|
||||
```
|
||||
|
||||
回滚到指定提交：
|
||||
|
||||
```bash
|
||||
git checkout <commit_id>
|
||||
|
||||
cd /home/code/medical-ai
|
||||
docker compose build fastapi
|
||||
docker compose up -d fastapi
|
||||
docker compose logs --tail=200 fastapi
|
||||
```
|
||||
|
||||
回到 main 最新版本：
|
||||
|
||||
```bash
|
||||
cd /home/code/medical-ai/fastapi
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
cd /home/code/medical-ai
|
||||
docker compose build fastapi
|
||||
docker compose up -d fastapi
|
||||
```
|
||||
|
||||
## 8. 发布前检查
|
||||
|
||||
发布前至少确认：
|
||||
|
||||
- Git 工作区已提交
|
||||
- `requirements.txt` 无冲突标记
|
||||
- `.env` 配置完整
|
||||
- `docker compose build fastapi` 成功
|
||||
- `docker compose up -d fastapi` 成功
|
||||
- `/health/ready` 可访问
|
||||
- `/fastapi/docs` 可访问
|
||||
- `/api/v1/auth/me` 可用
|
||||
- 学习助手流式接口可用
|
||||
|
||||
## 9. 常见部署问题
|
||||
|
||||
| 现象 | 排查方向 |
|
||||
|---|---|
|
||||
| `/fastapi/docs` 打不开 | 检查 Nginx `/fastapi/` 代理和 `APP_ROOT_PATH=/fastapi` |
|
||||
| 容器启动失败 | `docker compose logs --tail=200 fastapi` |
|
||||
| 依赖缺失 | 重新 `docker compose build fastapi` |
|
||||
| MySQL 连接失败 | 检查 `DATABASE_URL`、MySQL 容器状态、网络名 |
|
||||
| Redis 连接失败 | 检查 `REDIS_URL` 和 Redis 容器 |
|
||||
| 鉴权失败 | 检查 `AUTH_USER_ME_URL` 和 Django 服务 |
|
||||
| LLM 无响应 | 检查 `LLM_API_KEY`、模型名、网络和超时配置 |
|
||||
@@ -0,0 +1,142 @@
|
||||
# 功能模块说明
|
||||
|
||||
本文档用于说明当前后端功能模块的职责、接口、数据表和后续优化方向。
|
||||
|
||||
## 1. 用户鉴权模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 调用 Django 用户中心验证 access token，并生成 FastAPI 用户上下文 |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | `GET /api/v1/auth/me` |
|
||||
| 相关代码 | `app/api/auth.py`、`app/services/external_auth_service.py`、`app/core/user_context.py` |
|
||||
| 相关表 | Django `user`、`institution`、`department` |
|
||||
| 外部依赖 | Django `/api/user/users/me/` |
|
||||
| 后续优化 | 增加用户中心失败重试和更细的审计日志 |
|
||||
|
||||
## 2. 训练配置模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 返回推荐病人配置和可选配置项 |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | `GET /api/v1/training-config/recommended`、`GET /api/v1/training-config/options` |
|
||||
| 相关代码 | `app/api/training_config.py`、`app/services/training_config_service.py` |
|
||||
| 相关表 | `case_base`、`traditional_case` |
|
||||
| 后续优化 | 配置项可迁移到独立后台配置表 |
|
||||
|
||||
## 3. 训练会话模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 创建训练会话、维护状态流转和短期 memory |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | `POST /api/v1/sessions`、`POST /api/v1/sessions/{session_id}/chat/stream` |
|
||||
| 相关代码 | `app/api/sessions.py`、`app/services/session_service.py`、`app/agents/patient_agent.py` |
|
||||
| 相关表 | `training_sessions` |
|
||||
| Redis | 保存当前会话短期问诊上下文 |
|
||||
| 后续优化 | 增加会话超时策略和更完整的状态机校验 |
|
||||
|
||||
## 4. 王主任练习提示模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 根据当前病例和会话上下文生成练习提示 |
|
||||
| 当前状态 | 已实现，正式接口为 SSE |
|
||||
| 相关接口 | `POST /api/v1/sessions/{session_id}/hints/stream` |
|
||||
| 相关代码 | `app/agents/hint_agent.py`、`app/services/session_service.py` |
|
||||
| 相关提示词 | `app/prompts/hint/novice_case_hint.md` |
|
||||
| 后续优化 | 增加科室主任风格模板、提示质量评估和可配置提示强度 |
|
||||
|
||||
## 5. 检查/检验模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 获取体格检查和辅助检查列表，返回单项检查结果 |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | 体格检查列表、辅助检查列表、体格检查结果、辅助检查结果 |
|
||||
| 相关代码 | `app/services/order_service.py`、`app/repositories/case_repository.py` |
|
||||
| 相关表 | `case_exam_item`、`session_orders` |
|
||||
| 重要规则 | 结果只来自数据库；同一会话同一检查项幂等 |
|
||||
| 后续优化 | 检查项可按阶段、难度、病例类型做更细配置 |
|
||||
|
||||
## 6. 诊断治疗提交模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 完成问诊后提交诊断和治疗方案 |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | `complete-inquiry`、`diagnosis`、`treatment` |
|
||||
| 相关代码 | `app/services/session_service.py` |
|
||||
| 相关表 | `session_submissions`、`training_sessions` |
|
||||
| 后续优化 | 增加更细的字段级校验和草稿保存 |
|
||||
|
||||
## 7. AI 评价模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 读取病例、评分规则、会话过程、诊断治疗提交内容，调用 LLM 生成评价 |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | `POST /api/v1/sessions/{session_id}/evaluation` |
|
||||
| 相关代码 | `app/services/evaluation_service.py`、`app/agents/scoring_agent.py`、`app/agents/report_agent.py` |
|
||||
| 相关表 | `scoring_rule`、`training_record`、`training_score_detail` |
|
||||
| 后续优化 | 增加评分一致性校验、评分重试和人工复核入口 |
|
||||
|
||||
## 8. PDF 报告模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 生成和下载 AI 评价 PDF |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | `POST /api/v1/evaluations/{evaluation_id}/export-pdf`、`GET /api/v1/evaluations/{evaluation_id}/download-pdf` |
|
||||
| 相关代码 | `app/services/pdf_export_service.py` |
|
||||
| 相关表 | `training_record` |
|
||||
| 文件目录 | `storage/reports` |
|
||||
| 后续优化 | 优化 PDF 样式、分页、字体和医院模板 |
|
||||
|
||||
## 9. 教学互动模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 返回教学题目并根据答题结果生成评价 |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | `GET /api/v1/teaching/cases/{case_id}/items`、`POST /api/v1/teaching/evaluation` |
|
||||
| 相关代码 | `app/api/teaching.py`、`app/services/teaching_service.py` |
|
||||
| 相关表 | `case_base`、`teaching_case`、`training_record`、`training_score_detail` |
|
||||
| 后续优化 | 增加题目后台维护、错题统计和视频播放记录 |
|
||||
|
||||
## 10. 个人中心模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 查询当前用户训练记录和评价详情 |
|
||||
| 当前状态 | 已实现 |
|
||||
| 相关接口 | `GET /api/v1/evaluations`、`GET /api/v1/evaluations/{evaluation_id}` |
|
||||
| 相关代码 | `app/api/evaluations.py`、`app/services/evaluation_service.py` |
|
||||
| 相关表 | `training_record`、`training_score_detail` |
|
||||
| 重要规则 | 必须按 `user_id` 隔离 |
|
||||
| 后续优化 | 增加分页筛选、统计图表和能力画像 |
|
||||
|
||||
## 11. AI 学习助手模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 普通用户提出医学学习问题，后端优先检索机构知识库并流式回答 |
|
||||
| 当前状态 | 已实现正式流式接口；无知识库时自动降级为通用 LLM 回答 |
|
||||
| 相关接口 | `POST /api/v1/learning-assistant/chat/stream` |
|
||||
| 相关代码 | `app/api/learning_assistant.py`、`app/services/learning_assistant_service.py`、`app/agents/learning_assistant_agent.py` |
|
||||
| 相关表 | `kb_knowledge_space`、`kb_knowledge_chunk`、`kb_knowledge_query_log` |
|
||||
| 外部依赖 | LLM、Embedding、Milvus |
|
||||
| 后续优化 | 查询改写、rerank、多轮记忆、来源引用格式优化、成本统计 |
|
||||
|
||||
## 12. 后台知识库预留模块
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 主要作用 | 内容管理员上传 PDF，构建机构知识库 |
|
||||
| 当前状态 | 接口和数据结构已预留，生产级大规模入库仍需压测 |
|
||||
| 相关接口 | `POST /api/v1/knowledge-admin/documents/upload`、文档列表、文档详情 |
|
||||
| 相关代码 | `app/api/knowledge_admin.py`、`app/services/document_ingestion_service.py`、`app/integrations/*` |
|
||||
| 相关表 | `kb_knowledge_space`、`kb_knowledge_document`、`kb_knowledge_chunk`、`kb_knowledge_ingestion_task` |
|
||||
| 外部依赖 | Milvus、Embedding 服务、Celery |
|
||||
| 后续优化 | 任务队列监控、失败重试、分片策略、文件去重、权限后台 |
|
||||
@@ -0,0 +1,182 @@
|
||||
# 离职交接文档
|
||||
|
||||
本文档用于说明医疗问诊 Agent FastAPI 后端当前状态、接手重点、风险和后续工作。
|
||||
|
||||
## 1. 当前项目状态
|
||||
|
||||
当前 FastAPI 后端已经完成第一阶段核心功能，并已接入 Django 用户中心、MySQL、Redis、LLM、PDF 下载和 AI 学习助手。
|
||||
|
||||
已完成能力：
|
||||
|
||||
- Django access token 鉴权
|
||||
- 训练配置和推荐配置
|
||||
- 新建训练会话
|
||||
- AI 病人流式问诊
|
||||
- 王主任练习提示
|
||||
- 体格检查和辅助检查
|
||||
- 完成问诊、提交诊断、提交治疗
|
||||
- AI 评价和评分明细
|
||||
- PDF 报告导出和下载
|
||||
- 教学互动题目和评价
|
||||
- 个人中心训练记录和详情
|
||||
- AI 学习助手流式问答
|
||||
- 后台知识库上传和 RAG 架构预留
|
||||
|
||||
当前不是最终生产级完整系统，后续上线后仍需要逐模块做稳定性、监控、权限、性能和运维增强。
|
||||
|
||||
## 2. 接手人优先关注
|
||||
|
||||
接手后建议按顺序确认：
|
||||
|
||||
1. 能否本地启动 FastAPI。
|
||||
2. 能否连接云端 MySQL 和 Redis。
|
||||
3. `GET /api/v1/auth/me` 是否能通过 Django token 返回用户信息。
|
||||
4. 训练全流程是否能跑通。
|
||||
5. 教学互动是否能跑通。
|
||||
6. PDF 下载是否正常。
|
||||
7. AI 学习助手流式接口是否正常。
|
||||
8. 云服务器 `docker compose build fastapi` 是否成功。
|
||||
9. `.env` 是否与云服务器 docker-compose 服务名一致。
|
||||
|
||||
## 3. 当前重要约定
|
||||
|
||||
- FastAPI 不负责登录注册。
|
||||
- 用户身份来自 Django `/api/user/users/me/`。
|
||||
- FastAPI 使用 Django 返回的 `id` 作为 `user_id`。
|
||||
- 普通业务接口需要 `Authorization: Bearer <access_token>`。
|
||||
- 训练记录只有完整流程完成后写入。
|
||||
- 问诊过程主要存在 Redis 短期 memory。
|
||||
- 检查结果只来自数据库。
|
||||
- AI 学习助手正式接口只保留流式接口。
|
||||
- 知识库未初始化时，学习助手仍应正常回答。
|
||||
|
||||
## 4. 发布前必须检查
|
||||
|
||||
本地检查：
|
||||
|
||||
```powershell
|
||||
cd D:\Code\newfounder\medical-consultation-agent
|
||||
|
||||
.\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
|
||||
```
|
||||
|
||||
Git 检查：
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git grep -n "<<<<<<<\|=======\|>>>>>>>"
|
||||
git diff --check
|
||||
```
|
||||
|
||||
敏感信息检查：
|
||||
|
||||
```bash
|
||||
git grep -n "sk-"
|
||||
git grep -n "api_key"
|
||||
git grep -n "password"
|
||||
git grep -n "access_token"
|
||||
git grep -n "secret"
|
||||
```
|
||||
|
||||
服务器检查：
|
||||
|
||||
```bash
|
||||
cd /home/code/medical-ai
|
||||
docker compose build fastapi
|
||||
docker compose up -d fastapi
|
||||
docker compose logs --tail=200 fastapi
|
||||
curl http://127.0.0.1:9000/health/ready
|
||||
```
|
||||
|
||||
## 5. 已知风险
|
||||
|
||||
| 风险 | 当前处理 | 后续建议 |
|
||||
|---|---|---|
|
||||
| LLM 调用超时或失败 | 已有异常返回和 mock/fallback 配置 | 增加限流、重试、熔断、成本统计 |
|
||||
| 知识库真实大规模入库 | 当前为生产预留能力 | 压测 PDF 解析、embedding、Milvus 写入 |
|
||||
| Celery 任务监控 | 已预留任务模块 | 增加 worker 部署、重试、任务状态看板 |
|
||||
| 部分宽异常处理 | 保证 Demo 稳定 | 逐步收窄异常类型并补充结构化日志 |
|
||||
| PDF 报告样式 | 当前可下载 | 后续按医院模板优化 |
|
||||
| 前端最终样式 | 不在本仓库维护 | 以后按 API 文档继续联调 |
|
||||
|
||||
## 6. 后续生产级优化建议
|
||||
|
||||
### 6.1 工程与质量
|
||||
|
||||
- 增加 CI/CD。
|
||||
- 增加 lint 和格式化。
|
||||
- 增加数据库 migration 管理。
|
||||
- 增加更多 service 单元测试。
|
||||
- 增加接口压测。
|
||||
|
||||
### 6.2 安全与权限
|
||||
|
||||
- 完善内容管理员角色来源。
|
||||
- 对后台知识库接口增加更细权限。
|
||||
- 增加审计日志检索。
|
||||
- 增加敏感信息脱敏。
|
||||
|
||||
### 6.3 AI 与 Agent
|
||||
|
||||
- 优化 Patient Agent 回答稳定性。
|
||||
- 优化 Scoring Agent JSON 结构校验。
|
||||
- 增加评分重试和人工复核。
|
||||
- 增加 LLM 调用耗时、token、费用统计。
|
||||
- 增加提示词版本管理。
|
||||
|
||||
### 6.4 知识库
|
||||
|
||||
- 完善 PDF 解析质量检测。
|
||||
- 优化分片策略。
|
||||
- 接入真实 embedding 批量任务。
|
||||
- 增加 Milvus collection 生命周期管理。
|
||||
- 增加 RAG 命中率和用户反馈统计。
|
||||
|
||||
## 7. 常用命令
|
||||
|
||||
本地测试：
|
||||
|
||||
```powershell
|
||||
.\backend\.venv\Scripts\python.exe tests\test_api_contract.py
|
||||
```
|
||||
|
||||
服务器日志：
|
||||
|
||||
```bash
|
||||
docker compose logs -f fastapi
|
||||
```
|
||||
|
||||
服务器重启：
|
||||
|
||||
```bash
|
||||
docker compose up -d fastapi
|
||||
```
|
||||
|
||||
拉取最新代码：
|
||||
|
||||
```bash
|
||||
cd /home/code/medical-ai/fastapi
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
## 8. 交接清单
|
||||
|
||||
- [ ] `main` 分支是最新代码
|
||||
- [ ] `git status` 干净
|
||||
- [ ] 无 Git 冲突标记
|
||||
- [ ] 无真实密钥提交
|
||||
- [ ] `.env.example` 和 `.env.production.example` 已更新
|
||||
- [ ] README 已更新
|
||||
- [ ] API 文档已更新
|
||||
- [ ] 架构、数据库、部署、模块、排障文档已补齐
|
||||
- [ ] 本地测试全部通过
|
||||
- [ ] Docker build 通过
|
||||
- [ ] 云端 `/fastapi/docs` 可访问
|
||||
- [ ] `auth/me` 可用
|
||||
- [ ] 训练链路可用
|
||||
- [ ] 教学互动可用
|
||||
- [ ] PDF 下载可用
|
||||
- [ ] AI 学习助手流式可用
|
||||
@@ -0,0 +1,247 @@
|
||||
# 常见故障排查
|
||||
|
||||
本文档用于接手人快速定位本地和云服务器常见问题。
|
||||
|
||||
## 1. `/fastapi/docs` 打不开
|
||||
|
||||
现象：
|
||||
|
||||
- 浏览器访问 `http://8.160.178.88/fastapi/docs` 失败
|
||||
|
||||
排查：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:9000/docs
|
||||
docker compose ps
|
||||
docker compose logs --tail=200 fastapi
|
||||
```
|
||||
|
||||
可能原因：
|
||||
|
||||
- FastAPI 容器未启动
|
||||
- Nginx `/fastapi/` 代理配置错误
|
||||
- `.env` 中 `APP_ROOT_PATH` 未设置为 `/fastapi`
|
||||
|
||||
处理：
|
||||
|
||||
```bash
|
||||
cd /home/code/medical-ai
|
||||
docker compose up -d fastapi
|
||||
docker compose logs --tail=200 fastapi
|
||||
```
|
||||
|
||||
## 2. `/api/v1/auth/me` 返回 401
|
||||
|
||||
现象：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "AUTH_CREDENTIAL_REQUIRED"
|
||||
}
|
||||
```
|
||||
|
||||
排查：
|
||||
|
||||
- 是否携带 `Authorization: Bearer <access_token>`
|
||||
- token 是否过期
|
||||
- `AUTH_USER_ME_URL` 是否可访问
|
||||
- Django 容器是否正常
|
||||
|
||||
验证：
|
||||
|
||||
```bash
|
||||
curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
|
||||
-H "Authorization: Bearer <access_token>" \
|
||||
-H "X-Entry-Scene: production_vue"
|
||||
```
|
||||
|
||||
## 3. Django 用户中心不可达
|
||||
|
||||
现象：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "AUTH_USER_CENTER_UNAVAILABLE"
|
||||
}
|
||||
```
|
||||
|
||||
排查：
|
||||
|
||||
```bash
|
||||
docker compose ps django
|
||||
docker compose logs --tail=200 django
|
||||
```
|
||||
|
||||
处理：
|
||||
|
||||
- 检查 `AUTH_USER_ME_URL`
|
||||
- 检查 Docker 网络
|
||||
- 检查 Django 服务是否能访问 MySQL
|
||||
|
||||
## 4. MySQL 连接失败
|
||||
|
||||
现象：
|
||||
|
||||
- 服务启动时报数据库连接错误
|
||||
- `/health/ready` 不通过
|
||||
|
||||
排查：
|
||||
|
||||
```bash
|
||||
docker compose ps mysql
|
||||
docker compose logs --tail=100 mysql
|
||||
```
|
||||
|
||||
检查 `.env`：
|
||||
|
||||
```env
|
||||
DATABASE_URL=mysql+pymysql://root:<password>@mysql:3306/medical?charset=utf8mb4
|
||||
```
|
||||
|
||||
Docker 内部访问应使用服务名 `mysql`，不是 `127.0.0.1`。
|
||||
|
||||
## 5. Redis 连接失败
|
||||
|
||||
排查：
|
||||
|
||||
```bash
|
||||
docker compose ps redis
|
||||
docker compose logs --tail=100 redis
|
||||
```
|
||||
|
||||
检查 `.env`：
|
||||
|
||||
```env
|
||||
RUNTIME_MEMORY_BACKEND=redis
|
||||
REDIS_URL=redis://redis:6379/0
|
||||
```
|
||||
|
||||
如果 Redis 不可用，短期会话 memory 会受影响。
|
||||
|
||||
## 6. LLM 调用失败或很慢
|
||||
|
||||
现象：
|
||||
|
||||
- 流式问诊长时间无返回
|
||||
- 返回 `LLM_STREAM_FAILED`
|
||||
|
||||
排查：
|
||||
|
||||
- `LLM_BASE_URL`
|
||||
- `LLM_API_KEY`
|
||||
- `LLM_FAST_MODEL`
|
||||
- 网络是否能访问模型服务
|
||||
- 超时时间配置是否过短
|
||||
|
||||
建议：
|
||||
|
||||
- 先用 `/api/v1/learning-assistant/chat/stream` 测试最简单问题
|
||||
- 查看 FastAPI 日志
|
||||
- 确认模型服务账号额度
|
||||
|
||||
## 7. AI 学习助手没有知识库来源
|
||||
|
||||
现象：
|
||||
|
||||
```text
|
||||
retrieval_hit=false
|
||||
retrieval_error=当前机构知识库暂未初始化或检索不可用...
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
这是允许的降级行为。学习助手会继续用 LLM 通用回答。
|
||||
|
||||
排查知识库：
|
||||
|
||||
- 用户是否有 `institution_id`
|
||||
- 是否已有 `kb_knowledge_space`
|
||||
- Milvus 是否运行
|
||||
- Embedding 是否配置
|
||||
|
||||
## 8. Milvus 连接失败
|
||||
|
||||
排查：
|
||||
|
||||
```bash
|
||||
docker compose ps milvus-standalone
|
||||
docker compose logs --tail=200 milvus-standalone
|
||||
```
|
||||
|
||||
检查 `.env`：
|
||||
|
||||
```env
|
||||
MILVUS_URI=http://milvus-standalone:19530
|
||||
MILVUS_HOST=milvus-standalone
|
||||
MILVUS_PORT=19530
|
||||
```
|
||||
|
||||
## 9. PDF 下载失败
|
||||
|
||||
现象：
|
||||
|
||||
- 评价详情有，但 PDF 下载 404 或 500
|
||||
|
||||
排查：
|
||||
|
||||
- 评价是否属于当前 `user_id`
|
||||
- 是否已经调用过导出 PDF
|
||||
- `storage/reports` 是否挂载
|
||||
- 容器是否有写权限
|
||||
|
||||
命令：
|
||||
|
||||
```bash
|
||||
docker compose exec fastapi ls -lah /app/storage/reports
|
||||
```
|
||||
|
||||
## 10. Docker build 失败
|
||||
|
||||
排查：
|
||||
|
||||
```bash
|
||||
docker compose build fastapi
|
||||
```
|
||||
|
||||
常见原因：
|
||||
|
||||
- `requirements.txt` 依赖下载失败
|
||||
- 网络无法访问 pip 源
|
||||
- Python 版本不兼容
|
||||
- 文件编码或语法错误
|
||||
|
||||
本地先跑：
|
||||
|
||||
```powershell
|
||||
.\backend\.venv\Scripts\python.exe -m compileall app scripts tests
|
||||
```
|
||||
|
||||
## 11. API 文档和实际接口不一致
|
||||
|
||||
排查：
|
||||
|
||||
```bash
|
||||
curl http://8.160.178.88/fastapi/openapi.json
|
||||
```
|
||||
|
||||
如果接口已改动：
|
||||
|
||||
- 更新 `docs/03_api_design.md`
|
||||
- 运行 `tests/test_api_contract.py`
|
||||
- 再提交 Git
|
||||
|
||||
## 12. Git 拉取后服务没变化
|
||||
|
||||
处理：
|
||||
|
||||
```bash
|
||||
cd /home/code/medical-ai/fastapi
|
||||
git log -1 --oneline
|
||||
|
||||
cd /home/code/medical-ai
|
||||
docker compose build fastapi
|
||||
docker compose up -d fastapi
|
||||
docker compose logs --tail=200 fastapi
|
||||
```
|
||||
|
||||
如果 `requirements.txt` 或 Dockerfile 有变动，必须重新 build。
|
||||
Reference in New Issue
Block a user