刘金宝
155 lines
5.1 KiB
Markdown
155 lines
5.1 KiB
Markdown
# 系统架构说明
|
||
|
||
本文档用于交接医疗问诊 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 不在本仓库维护。
|