# DermaIntegrate

**Repository Path**: peakb_admin/DermaIntegrate

## Basic Information

- **Project Name**: DermaIntegrate
- **Description**: https://github.com/kiko401/DermaIntegrate
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DermaIntegrate: 皮肤病多源数据集成与智能辅助诊断系统

**许可协议**：MIT License
**运行环境**：Python 3.11 / Node 18+ / Vue 3
**系统架构**：基于 API 契约的模块解耦，推理服务与应用服务进程级隔离与独立部署

---

## 摘要

本项目面向皮肤病专科门诊场景，构建了一套数据集成与多模态辅助诊断系统，旨在解决临床业务中多源异构数据孤岛、初诊数据缺失与医疗 AI 缺乏可解释性的问题。

系统采用“推理计算与业务流转解耦”的架构设计，划分为**智能推理域**与**应用平台域**。在**数据集成层面**，针对 HIS、PACS、LIS 等系统数据异构与标识不一的问题，系统采用主索引映射与 FHIR R4 标准协议，实现跨系统异构数据的归一化接入与逻辑聚合，构建患者全生命周期临床视图。

在**AI 辅助层面**，系统提出基于多 Agent 协作与检索增强（RAG）的多模态可解释机制。接收皮肤镜图像、病历文本与病理分子数据等多模态输入，由独立的图像 Agent、病历 Agent、病理与分子 Agent 按需处理，最终由整合 Agent 融合多源特征与 RAG 检索结果，生成结构化风险提示与检查建议。全管线实施全中文强制防线与强引用约束，有效防范术语漂移与知识幻觉。

在**工程实现层面**，系统针对医学影像解析瓶颈、DICOM 标签不规范风险与长时 AI 推理引发的资源占用问题，分别实现了基于成像特性的防御性后端转码机制，以及基于 SSE 的异步响应代理与断连感知计算资源回收机制。同时，通过容器化编排与 ONNX 推理优化，实现了在低资源云服务器环境下的稳定部署。

---

## 1. 核心问题与方法映射

| 临床/工程问题                      | 系统应对策略与工程机制                                       |
| :--------------------------------- | :----------------------------------------------------------- |
| **多源异构数据孤岛**               | **主索引映射与 FHIR 标准归一化**：基于主索引映射跨系统患者标识，结合 FHIR R4 标准协议解析资源，实现异构数据的逻辑聚合与患者全生命周期视图构建。 |
| **初诊数据缺失与单模态局限**       | **多模态缺失兼容与定向建议**：系统以任务驱动多模态管线，各 Agent 按需触发，跳过缺失模态。整合 Agent 针对缺失项动态生成定向补充检查建议，报告状态降级，不因数据不全而阻断流程。 |
| **医疗 AI 缺乏可解释性与幻觉风险** | **多 Agent 证据链与全中文防幻觉防线**：图像 Agent 仅输出客观形态学特征，病理 Agent 基于注册表分诊与指南输出规则分层，整合 Agent 结合 RAG 强引用生成报告。全管线实施全中文强制映射、后置语义清洗与自重试机制。 |
| **跨模态术语漂移与误诊风险**       | **跨模态术语对齐与疾病注册表分诊**：病历 Agent 实施后置语义清洗将口语词汇归一为规范触发词；病理 Agent 基于全局疾病注册表进行配置驱动分诊，非黑瘤疾病走独立临床路径。 |
| **DICOM 影像前端解析与标签风险**   | **防御性影像转码与轻量渲染**：后端离线解析 DICOM 并执行防御性色彩空间还原转码为 PNG，结合前端轻量滑动对比组件，实现影像数据的透明集成调阅。 |
| **长时 AI 推理引发的资源占用**     | **异步响应代理与低资源部署**：基于 SSE 异步契约解耦业务与推理，建立断连感知逻辑，前端断连即终止推理计算；智能推理域云端采用低资源部署，通过 ONNX 推理替换与容器内存限制保障稳定性。 |

---

## 2. 系统架构设计

系统遵循“推理计算与业务流转解耦”原则，划分两大进程级隔离服务域。**智能推理域**负责多模态 AI 推理、特征提取与影像预处理；**应用平台域**负责数据集成归一、标准协议接入与前端交互。

```text
[架构图占位符]
预计内容（待应用域完成开发后确定）：
1. 表现层（Vue 前端）：医生工作站、影像对比组件、流式对话框。
2. 服务层：
   - 应用平台域（Node/Express）：数据聚合、SSE代理、FHIR适配、EMPI映射。
   - 智能推理域（FastAPI）：Multi-Agent管线、RAG检索、DICOM转码。
3. 数据层：
   - 应用数据库（MySQL）：业务数据、患者主索引。
   - 推理数据库（MySQL）：Task任务映射、多模态上下文。
   - 向量数据库（Qdrant）：专科知识库。
4. 基础设施：Docker Compose、Nginx网关。
```

---

## 3. 核心功能模块

### 3.1 智能推理域

智能推理域提供多模态数据接收、分析与结构化报告输出的核心能力。

#### 3.1.1 DICOM 离线摄取与防御性转码
针对皮肤镜数据集标签不规范（如 `YBR_FULL_422` 实为 RGB）导致的偏色问题，管线采用防御性映射策略。对 3 通道图像直接按位深缩放输出，无视可能误导的标签；对单通道灰度图严格按标签处理（`MONOCHROME1` 执行反转，`MONOCHROME2` 执行归一化）。转码结果存储为 Web 友好的 PNG 格式，释放前端解析压力。

#### 3.1.2 多模态 Multi-Agent 协作框架
系统采用任务驱动架构，支持图像、病历文本、病理 JSON 等多模态输入。
*   **图像 Agent**：基于 FastViT-UNet（ONNX Runtime）实现病灶精准分割，计算病灶占比（coverage）与位置（location），并输出热力图。若无权重文件自动降级至高斯占位符。
*   **病历 Agent**：支持自由文本与结构化 JSON 双通道输入，实施防漂移自重试机制，确保术语输出全中文且符合 Schema 定义。
*   **病理 Agent**：基于全局 `DISEASE_REGISTRY` 实现疾病分诊（支持 MEL/BCC/SCC/NEV/ACK/SEK），非黑瘤疾病走独立临床路径，避免误入高危评估流程。
*   **化验 Agent**：基于纯规则引擎实现分期逻辑，支持跨模态依赖（如引用病历部位信息触发肢端建议）。

#### 3.1.3 RAG 两阶段检索与知识增强
*   **受控词表**：基于 `VALID_TAGS` v1.2 强校验入库语料标签，确保数据质量。
*   **两阶段检索**：第一阶段基于特征映射（如 T分期、部位）进行硬匹配筛选；第二阶段在筛选子集内进行向量精排，返回 Top-3 结果。
*   **强引用阻断**：整合 Agent Prompt 强制 LLM 照抄 RAG 返回的原始 ID（如 `[AJCC-05]`），禁止凭空捏造引用来源。

#### 3.1.4 异步流式推理与资源回收
基于 SSE（Server-Sent Events）实现流式输出。主协程通过 `asyncio.Queue` 与独立推理线程通信，实时监测前端连接状态。一旦检测到断连，立即发送终止信号，释放计算资源，防止无效占用。

### 3.2 应用平台域

<!-- TODO: Application Domain: 请根据实际实现情况补充以下内容 -->
应用平台域负责连接外部医疗系统、聚合患者数据以及提供医生交互界面。

#### 3.2.1 数据集成与标准协议接入
*   **FHIR R4 适配**：解析符合 FHIR 标准的临床数据资源，实现异构数据归一化。
*   **主索引映射 (EMPI)**：构建元数据表，关联跨系统患者标识（如身份证号、病历号），实现患者全生命周期视图聚合。
*   **只读路由**：通过 API 或视图路由获取异构源系统数据，避免侵入性写入。

#### 3.2.2 业务服务与 AI 代理
*   **SSE 流式代理**：封装对智能推理域的 SSE 调用，实现请求转发与流式响应代理给前端。
*   **临床视图聚合**：整合 HIS、LIS、PACS 数据与 AI 分析结果，提供统一展示接口。
*   **多模态数据预处理**：处理前端提交的图像、文本、结构化数据，转换为推理域契约格式。

#### 3.2.3 前端交互与可视化
*   **医生工作站**：患者信息展示、任务列表管理。
*   **影像对比组件**：原图与 AI 热力图滑动对比渲染。
*   **流式报告渲染**：实时接收并渲染 AI 推理的步级事件（`image_done`, `clinical_done` 等）与最终结构化报告。

---

## 4. 关键工程实现细节

### 4.1 疾病注册表驱动的临床路径分诊
在病理 Agent 中引入全局疾病注册表（`DISEASE_REGISTRY`），配置各病种的匹配词、良恶性标识及 RAG 查询模板。病理 Agent 首先遍历注册表匹配诊断，若匹配到非 MEL 病种（如 BCC），直接输出专科建议，**无需按黑色素瘤分期**，彻底解决非黑瘤疾病误入高危路径的问题。

### 4.2 跨模态术语对齐机制
针对 LLM 输出部位词（如“脚底”）与规则触发词（如“足”）不对齐的问题，病历 Agent 实施后置语义清洗。通过 `REGION_NORMALIZATION_MAP` 强制替换，确保病理 Agent 的跨模态关键词（“手”、“足”、“甲”）100% 存在，保障规则稳定触发。

### 4.3 低资源云端部署优化
针对 4C4G 云服务器环境，实施了多项优化：
*   **ONNX 推理替换**：使用 ONNX Runtime 替代 PyTorch，大幅降低内存占用。
*   **依赖版本锁定**：强制锁定 `numpy==1.26.4`，解决 OpenCV 与 ONNX Runtime 的依赖冲突。
*   **国内镜像源注入**：配置 `HF_ENDPOINT` 环境变量，解决模型下载受阻问题。
*   **Swap 虚拟内存**：宿主机配置 4GB Swap，防止容器 OOM 崩溃。

### 4.4 综合研判与数据锚定
整合 Agent 的 Prompt 约束明确：若病理已给出明确的 T 分期结论，必须以此作为风险分层核心依据，不因视觉或临床特征的缺失而过度保守降级。

---

## 5. 部署与运行

### 5.1 环境依赖

*   **智能推理域**：Python 3.11, Docker, Docker Compose
*   **应用平台域**：Node 18+, MySQL 8.0, Redis

### 5.2 智能推理域部署

智能推理域已实现容器化部署，推荐使用 Docker Compose。

1.  **配置环境变量**
    复制并修改配置文件：
    ```bash
    cp backend-ai/.env.example backend-ai/.env
    ```
    需配置的关键项（在 `backend-ai/.env` 中）：
    ```env
    DATABASE_URL=mysql+aiomysql://root:password@mysql:3307/derma_ai
    INTEGRATION_API_KEY=your_api_key
    HF_ENDPOINT=https://hf-mirror.com
    DOCKER_ENV=true
    ```

2.  **启动服务**
    在项目根目录执行：
    ```bash
    docker-compose up -d mysql qdrant
    docker-compose up -d --build fastapi
    ```

3.  **初始化 RAG 知识库**
    进入容器执行初始化脚本：
    ```bash
    docker exec -it derma-fastapi python init_rag.py
    ```

### 5.3 应用平台域部署

<!-- TODO: Application Domain: 请根据实际技术栈修改以下部署说明 -->
1.  **数据库初始化**
    ```bash
    # 示例命令，请根据实际脚本修改
    mysql -u root -p < backend-app/sql/init.sql
    ```

2.  **后端服务启动**
    ```bash
    cd backend-app
    npm install
    npm run dev
    ```

3.  **前端服务启动**
    ```bash
    cd frontend
    npm install
    npm run dev
    ```

### 5.4 全链路访问

启动完成后，访问应用平台前端地址（通常为 `http://localhost:3000` 或根据 Nginx 配置）进入系统。

---

## 6. 目录结构

```text
DermaIntegrate/
├── backend-ai/                  # [智能推理域] Python 后端
│   ├── agents/                  # Multi-Agent 逻辑
│   ├── api/                     # FastAPI 路由与 SSE 接口
│   ├── cnn/                     # 视觉模型推理 (ONNX)
│   ├── rag/                     # 知识库与检索引擎
│   ├── preprocessing/           # DICOM 处理
│   ├── sql/                     # 数据库初始化脚本
│   └── init_rag.py              # 知识库初始化脚本
│
├── backend-app/                 # [应用平台域] 后端服务
│   ├── src/
│   │   ├── routes/              # API 路由
│   │   ├── services/            # 业务逻辑
│   │   └── empi/                # 主索引映射
│   └── sql/                     # 数据库脚本
│
├── frontend/                    # [应用平台域] 前端界面
│   ├── src/
│   │   ├── components/          # UI 组件
│   │   └── views/               # 页面视图
│   └── package.json
│
├── infra/                       # 基础设施配置
│   ├── docker-compose.yml       # 容器编排
│   └── nginx/                   # 网关配置
│
└── docs/                        # 项目文档
    └── api-contract.yaml        # API 契约定义
```

---

## 7. 协作与开发规范

### 7.1 分支策略
*   `main`：稳定基线分支。
*   `feat/ai/*`：智能推理域功能开发分支。
*   `feat/app/*`：应用平台域功能开发分支。
*   **合并规范**：功能开发完成并通过自测后，提交 Pull Request 合入 `main`。

### 7.2 API 契约
双方开发严格遵循 `docs/api-contract.yaml` 定义的接口规范。
*   **上传接口**：`POST /upload`，接收多模态数据，返回 `task_id`。
*   **流式接口**：`GET /stream/{task_id}`，返回 SSE 事件流。

---

## 8. 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

---

*注：本系统提供的辅助诊断建议仅供临床参考，最终诊断结论应由执业医师结合患者实际情况做出。*