From b92cefbd0b92e260ce43dd8e53d2e5239805950a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E9=87=91=E5=AE=9D?= Date: Wed, 10 Jun 2026 11:02:12 +0800 Subject: [PATCH] docs: add handover and deployment guides --- .gitignore | 2 +- README.md | 183 +++++++++++++-------------- docs/01_architecture.md | 154 +++++++++++++++++++++++ docs/02_database.md | 214 ++++++++++++++++++++++++++++++++ docs/04_deployment.md | 210 +++++++++++++++++++++++++++++++ docs/05_modules.md | 142 +++++++++++++++++++++ docs/06_handover.md | 182 +++++++++++++++++++++++++++ docs/07_troubleshooting.md | 247 +++++++++++++++++++++++++++++++++++++ 8 files changed, 1236 insertions(+), 98 deletions(-) create mode 100644 docs/01_architecture.md create mode 100644 docs/02_database.md create mode 100644 docs/04_deployment.md create mode 100644 docs/05_modules.md create mode 100644 docs/06_handover.md create mode 100644 docs/07_troubleshooting.md diff --git a/.gitignore b/.gitignore index 2f47aee..c74535e 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/README.md b/README.md index 44cae92..d9bd07b 100644 --- a/README.md +++ b/README.md @@ -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//download-pdf" \ - -H "Authorization: Bearer " \ - -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。 diff --git a/docs/01_architecture.md b/docs/01_architecture.md new file mode 100644 index 0000000..46b0a75 --- /dev/null +++ b/docs/01_architecture.md @@ -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 不在本仓库维护。 diff --git a/docs/02_database.md b/docs/02_database.md new file mode 100644 index 0000000..8404135 --- /dev/null +++ b/docs/02_database.md @@ -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` 返回。 +- 评价生成后才写长期训练记录。 +- 知识库表是生产扩展点，真实大规模入库前需要压测。 diff --git a/docs/04_deployment.md b/docs/04_deployment.md new file mode 100644 index 0000000..54c1c2d --- /dev/null +++ b/docs/04_deployment.md @@ -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 " \ + -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 " \ + -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 + +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`、模型名、网络和超时配置 | diff --git a/docs/05_modules.md b/docs/05_modules.md new file mode 100644 index 0000000..4628be4 --- /dev/null +++ b/docs/05_modules.md @@ -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 | +| 后续优化 | 任务队列监控、失败重试、分片策略、文件去重、权限后台 | diff --git a/docs/06_handover.md b/docs/06_handover.md new file mode 100644 index 0000000..583f272 --- /dev/null +++ b/docs/06_handover.md @@ -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 `。 +- 训练记录只有完整流程完成后写入。 +- 问诊过程主要存在 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 学习助手流式可用 diff --git a/docs/07_troubleshooting.md b/docs/07_troubleshooting.md new file mode 100644 index 0000000..af76037 --- /dev/null +++ b/docs/07_troubleshooting.md @@ -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 ` +- token 是否过期 +- `AUTH_USER_ME_URL` 是否可访问 +- Django 容器是否正常 + +验证： + +```bash +curl "http://8.160.178.88/fastapi/api/v1/auth/me" \ + -H "Authorization: Bearer " \ + -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:@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。