Tutorial: medical-multi-agent-system — 企業級多 Agent 醫療臨床輔助決策系統

§1 專案定位與背景

1.1 這是什麼

medical-multi-agent-system 是一個面向面試展示與架構學習的企業級多 Agent 臨床輔助決策系統（Clinical Decision Support System, CDSS）。它以 5 個專業化 Agent 組成 Pipeline，覆蓋「接診 → 診斷 → 治療 → 編碼 → 審計」完整臨床工作流，並以 Python / Java / Go 三種語言同時實作同一套架構。

專案於 2026-04-06 建立，MIT 授權，截至 2026-06-06 累積 74 星、15 fork。README 長達 3,003 行，附帶 7 篇技術文件 + 7 篇面試材料。

1.2 為什麼值得深入研究

在公開的醫療 AI 專案中，多數要麼是「單一 LLM + prompt 問答」的簡單方案（如 MediGenius），要麼是「真實資料驅動但缺乏 Agent 架構」的學術平台（如 Stanford HealthRex/CDSS）。本專案的獨特價值在於：

1. 最完整的 Multi-Agent CDSS 架構：不只有 Agent 編排，還涵蓋 GraphRAG 知識圖譜、FHIR R4 醫療互通標準、HIPAA 合規審計、ICD-10 自動編碼與 MS-DRGs 分組
2. 三語言同架構對比：同一套 Pipeline 設計在 Python (LangGraph)、Java (Spring Boot + LangGraph4j)、Go (Gin + 手寫 Pipeline) 三種生態中的不同實現方式，是學習「跨語言架構映射」的絕佳教材
3. LangGraph 條件路由的教學範例：Diagnosis Agent 可將流程回退至 Intake Agent 補充資訊，這是 LangGraph 區別於簡單鏈式調用的核心能力
4. 合規設計的完整示範：HIPAA Safe Harbor 18 類 PHI 偵測、不可變審計日誌（WORM）、RBAC 存取控制，且 Audit Agent 刻意不使用 LLM（確定性 > 靈活性）

1.3 限制與注意事項

• 非臨床可用：知識圖譜為硬編碼的 10 類症狀 / 15 種疾病子集；ICD-10 僅覆蓋 50+ 病種（完整庫 72,000+）；DDI 僅 10 條規則
• 單一 commit 歷史：整個專案在一次 commit 中完成，無漸進式開發歷程，表明這是精心設計的教學展示而非生產系統
• LLM 依賴：4/5 Agent 需要 OpenAI API（推薦 gpt-4o-mini），Audit Agent 為唯一不用 LLM 的純規則引擎
• Neo4j 為可選：GraphRAG 預設使用內建知識 map（離線模式），Neo4j 連線失敗會自動降級

§2 技術棧總覽

2.1 三語言技術棧對比

Python 版功能最完整（有 Presidio + fhir.resources + Swagger 自動文件），是優先研究的目標。Java / Go 版作為「同架構不同語言」的對照組。

2.2 基礎設施

全部透過 Docker Compose 一鍵啟動，PostgreSQL 與 Redis 配有 healthcheck。

2.3 Python 依賴清單（21 個套件）

核心依賴：langgraph, langchain, langchain-openai, fastapi, uvicorn, pydantic, httpx, neo4j, sqlalchemy, redis, structlog, tenacity, presidio-analyzer, presidio-anonymizer, fhir.resources。測試依賴：pytest, pytest-asyncio。

§3 系統架構

3.1 Pipeline 總體流程

graph LR
    Start([患者描述輸入]) --> Intake

    subgraph Pipeline["Clinical Decision Pipeline"]
        Intake["Intake Agent
患者資訊採集
temp=0.1"]
        Diagnosis["Diagnosis Agent
鑑別診斷
temp=0.2"]
        Treatment["Treatment Agent
治療方案 + DDI
temp=0.2"]
        Coding["Coding Agent
ICD-10 + DRGs
temp=0.1"]
        Audit["Audit Agent
HIPAA 合規
純規則引擎"]

        Intake --> Diagnosis
        Diagnosis -->|"資訊充足"| Treatment
        Diagnosis -->|"needs_more_info=true
最多重試 2 次"| Intake
        Treatment --> Coding
        Coding --> Audit
    end

    Audit --> End([完整臨床報告])

    KG[("Neo4j
醫學知識圖譜")]
    Drug[("DDI 資料庫
藥物交互")]
    ICD[("ICD-10
編碼庫")]
    HIPAA[("HIPAA
合規規則")]

    Diagnosis -.->|"GraphRAG 查詢"| KG
    Treatment -.->|"交互檢查"| Drug
    Coding -.->|"編碼映射"| ICD
    Audit -.->|"合規校驗"| HIPAA

3.2 架構分層

系統分為五層：

1. API 層：REST 端點（FastAPI / Spring Boot / Gin），接收 HTTP 請求，回傳 JSON
2. 編排層：LangGraph StateGraph + 條件路由，管理 Agent 執行順序與狀態流轉
3. Agent 層：5 個獨立 Agent，各有專業 prompt + 工具 + 輸入/輸出規範
4. 服務層：GraphRAG、ICD-10、DDI、FHIR、HIPAA 五個業務服務
5. 基礎設施層：PostgreSQL（審計日誌）、Neo4j（知識圖譜）、Redis（快取）、OpenAI LLM

3.3 ClinicalState — 共享狀態設計

ClinicalState 是 5 個 Agent 之間傳遞資料的核心資料結構。每個 Agent 讀取自己需要的欄位，寫入自己的輸出。

 1ClinicalState
 2├── raw_input: str              ← 原始患者描述
 3├── patient_info: dict | None   ← Intake Agent 輸出
 4├── diagnosis: dict | None      ← Diagnosis Agent 輸出
 5├── needs_more_info: bool       ← 條件路由旗標
 6├── treatment_plan: dict | None ← Treatment Agent 輸出
 7├── coding_result: dict | None  ← Coding Agent 輸出
 8├── audit_result: dict | None   ← Audit Agent 輸出
 9├── messages: list[BaseMessage] ← 對話歷史 (LangGraph add_messages reducer)
10├── errors: list[str]           ← 錯誤追蹤
11└── current_agent: str          ← 當前執行的 Agent 名稱

Python 版使用 Pydantic BaseModel + Annotated[list, add_messages]（LangGraph reducer）；Java 版使用 Lombok @Data @Builder；Go 版使用普通 struct + JSON tag。

3.4 條件路由的三語言實作對比

這是本專案架構上最值得學習的設計：

Python（宣告式 — LangGraph 原生）：

 1# 路由函數
 2def _route_after_diagnosis(state: ClinicalState) -> str:
 3    if state.needs_more_info:
 4        return "intake"      # 回退
 5    return "treatment"       # 前進
 6
 7# 在 StateGraph 中註冊條件邊
 8workflow.add_conditional_edges(
 9    "diagnosis", _route_after_diagnosis,
10    {"intake": "intake", "treatment": "treatment"},
11)

Java（命令式 — do-while 迴圈）：

1int retries = 0;
2do {
3    state = diagnosisAgent.process(state);
4    if (state.isNeedsMoreInfo() && retries < MAX_DIAGNOSIS_RETRIES) {
5        state = intakeAgent.process(state);
6    }
7    retries++;
8} while (state.isNeedsMoreInfo() && retries <= MAX_DIAGNOSIS_RETRIES);

Go（命令式 — for + break）：

 1retries := 0
 2for {
 3    p.runAgent(ctx, p.diagnosis, state)
 4    if state.NeedsMoreInfo && retries < maxDiagnosisRetries {
 5        retries++
 6        p.runAgent(ctx, p.intake, state)
 7        continue
 8    }
 9    break
10}

三種實作風格體現了各語言生態的偏好：Python 傾向宣告式 DSL，Java 傾向企業模式，Go 傾向簡潔直接。

§4 核心模組深度解析

4.1 Intake Agent（接診 Agent）

職責：將非結構化的患者描述文字轉為結構化的 PatientInfo。

• LLM 溫度：0.1（高確定性，資訊提取不需要創造力）
• 輸出格式：Pydantic 嚴格校驗（PatientInfo model 含 76 行欄位定義）
• FHIR 對齊：輸出格式對齊 FHIR R4 Patient 資源
• 提取的欄位：姓名、年齡、性別、主訴、症狀列表（含持續時間 / 嚴重度）、病史、家族史、過敏史（含過敏原 / 反應 / 嚴重度）、當前用藥（含藥名 / 劑量 / 頻率）、生命徵象（體溫 / 心率 / 血壓 / 血氧）、實驗室結果（含是否異常旗標）
• 錯誤處理：try/except 捕獲 JSONDecodeError，清理 markdown 程式碼區塊標記

4.2 Diagnosis Agent（診斷 Agent）

職責：根據結構化患者資訊生成排名的鑑別診斷清單。

• LLM 溫度：0.2
• GraphRAG 整合：可選地查詢 Neo4j 知識圖譜取得症狀-疾病關聯，輔助 LLM 推理
• 條件路由：若判斷資訊不足（needs_more_info = true），Pipeline 回退至 Intake Agent，最多重試 2 次防止無限迴圈
• 輸出結構：主要診斷（disease_name + icd10_hint + confidence + evidence + reasoning）、鑑別診斷清單、建議追加檢查、臨床備註

4.3 Treatment Agent（治療 Agent）

職責：根據診斷生成循證治療方案，並進行藥物安全檢查。

• LLM 溫度：0.2
• DDI 檢查：自動檢查推薦藥物與當前用藥的藥物-藥物交互，支援精確匹配（藥品名）與模糊匹配（藥物類別，如 lisinopril → ace_inhibitor）
• 過敏禁忌：交叉驗證推薦藥物與患者過敏史（含青黴素交叉反應風險）
• DDI 資料庫：10 條規則，覆蓋 warfarin-aspirin (major)、SSRI-MAOI (contraindicated)、metformin-contrast_dye (major)、simvastatin-amiodarone (major)、digoxin-amiodarone (major) 等常見嚴重交互

4.4 Coding Agent（編碼 Agent）

職責：將診斷映射為 ICD-10-CM 編碼並確定 MS-DRGs 分組。

• LLM 溫度：0.1（編碼需要最高確定性）
• ICD-10 覆蓋：50+ 病種，橫跨感染性疾病 (A00-B99)、腫瘤 (C00-D49)、內分泌代謝 (E00-E89)、循環系統 (I00-I99)、呼吸系統 (J00-J99)、消化系統 (K00-K95)、泌尿系統 (N00-N99)、特殊用途 (U00-U85) 等 11 個章節
• DRGs 分組：ICD-10 前綴 → DRG code + 權重 + 平均住院天數（如 J18 → DRG 193, weight=1.4, LOS=4.5 天）
• 輸出：主要 ICD-10 編碼、次要編碼（合併症/併發症）、DRG 分組、編碼信心度

4.5 Audit Agent（審計 Agent）

職責：HIPAA 合規檢查、PHI 偵測與脫敏、生成不可變審計日誌。

• 不使用 LLM：這是刻意的設計決策。理由：(1) 合規檢查需要 100% 確定性；(2) 可審計性 — 規則引擎每一步可追溯；(3) PHI 資料不應發送給第三方 LLM 服務；(4) 速度 < 100ms；(5) 零成本
• PHI 偵測：18 類 HIPAA Safe Harbor 標識符，使用正則表達式（names, geographic_data, dates, phone_numbers, fax_numbers, email_addresses, ssn, mrn, health_plan_id, account_numbers, license_numbers, vehicle_ids, device_ids, urls, ip_addresses, biometric_ids, photographs, unique_identifiers）
• 脫敏：SSN → [SSN_REDACTED]、電話 → [PHONE_REDACTED]、email → [EMAIL_REDACTED]、IP → [IP_REDACTED]
• 審計日誌：不可變 WORM（Write Once Read Many）策略，HIPAA 要求至少保留 6 年
• 合規檢查項目：phi_scan、data_encryption_at_rest、data_encryption_in_transit、access_control_rbac、audit_logging、minimum_necessary_rule、breach_notification_ready、data_retention_policy

§5 GraphRAG 與 FHIR R4 深度解析

5.1 GraphRAG 醫學知識圖譜

GraphRAG 是本專案相對傳統 RAG 的核心差異化點。

傳統 RAG vs GraphRAG：

實作方式：

系統內建了一個離線知識 map，包含 10 類症狀（fever, cough, headache, chest_pain, abdominal_pain, shortness_of_breath, fatigue, nausea, dizziness, joint_pain）到 15 種疾病的映射關係。

查詢演算法使用「投票計數」（vote counting）：每個症狀指向的疾病各得 1 分，最終按分數降序排列。例如輸入 ["fever", "cough"]，Pneumonia 得 2 分（被兩個症狀指向）排第一。

生產環境路徑：

在真實部署中，知識圖譜資料來源包括 UMLS（200+ 醫學術語體系）、SNOMED CT（35 萬+ 概念）、WHO ICD-10，透過 Cypher 查詢在 Neo4j 中執行多跳推理：

1MATCH (s1:Symptom {name: 'fever'})-[:INDICATES]->(d:Disease)
2      <-[:INDICATES]-(s2:Symptom {name: 'cough'})
3RETURN d.name, d.icd10_code
4ORDER BY d.prevalence DESC

5.2 FHIR R4 資源轉換

FHIR（Fast Healthcare Interoperability Resources）R4 是 HL7 制定的醫療系統間資料交換標準。本專案實作了三種 FHIR 資源轉換：

PatientInfo → FHIR Patient：

• 內部 name / age / gender / allergies → FHIR 標準 resourceType: "Patient" + name[].use: "official" + gender + birthDate（年齡反推）+ _allergies[]（AllergyIntolerance 資源）

Diagnosis → FHIR Condition：

• 內部 primary_diagnosis.disease_name + icd10_hint → FHIR resourceType: "Condition" + code.coding[].system: "http://hl7.org/fhir/sid/icd-10-cm" + subject.reference: "Patient/{id}"

Medication → FHIR MedicationRequest：

• 內部 drug_name + dosage + route + frequency → FHIR resourceType: "MedicationRequest" + status: "active" + intent: "order" + dosageInstruction[].timing + route + doseAndRate

Python 版使用 fhir.resources 套件（完整 FHIR 驗證），Java / Go 版為手動 JSON 映射。系統同時支援 FHIR 服務端推送（透過 httpx async POST 到外部 FHIR server）。

§6 資安掃描

6.1 正面安全設計

6.2 風險項目

6.3 硬編碼秘密掃描

1grep -rn "sk-\|password.*=.*['\"]" --include="*.py" --include="*.java" --include="*.go" --include="*.yml"

結果：.env.example 中有 sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 和 your-password-here 佔位符，非真實金鑰。application.yml 中使用 ${OPENAI_API_KEY:} 環境變數注入模式。Docker Compose 使用 ${POSTGRES_PASSWORD:-postgres} 帶預設值語法。未發現洩漏的真實秘密。

§7 資料庫設計與資料流

7.1 資料庫 Schema

兩張核心表，由 docker/init-db.sql 自動建立：

audit_logs — HIPAA 合規審計日誌

索引：timestamp、user_id、(resource_type, resource_id)。HIPAA 要求此表資料至少保留 6 年且不可修改 / 刪除。

clinical_sessions — 臨床會話記錄

此表包含 PHI（受保護健康資訊），需要存取控制。

7.2 完整資料流範例

以「45 歲男性，發燒 3 天 + 咳黃痰 + 胸片浸潤」為例：

§8 測試策略

8.1 現有測試覆蓋

Python 版有 tests/test_services.py（92 行），包含 4 個測試類別 12 個測試案例：

測試聚焦在服務層，不測試 Agent（因為 Agent 依賴 LLM API）。

8.2 測試病例

專案提供 5 個測試病例（python/data/sample_patients.json）：

8.3 執行測試

1# Python
2cd python && pip install pytest pytest-asyncio
3pytest tests/ -v
4
5# Java
6cd java && mvn test
7
8# Go
9cd go && go test ./... -v

§9 部署與運維

9.1 開發環境快速啟動

 1# 1. Clone
 2git clone https://github.com/bcefghj/medical-multi-agent-system.git
 3cd medical-multi-agent-system/python
 4
 5# 2. 虛擬環境 + 依賴
 6python3 -m venv venv && source venv/bin/activate
 7pip install -r requirements.txt
 8
 9# 3. 環境變數
10cp .env.example .env
11# 編輯 .env 填入 OPENAI_API_KEY
12
13# 4. 啟動基礎設施
14docker compose up -d postgres neo4j redis
15# 等待 ~10 秒
16
17# 5. 啟動 API
18uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload
19
20# 6. 驗證
21curl http://localhost:8000/health
22curl -X POST http://localhost:8000/api/v1/clinical/icd10/search \
23  -H "Content-Type: application/json" \
24  -d '{"query": "pneumonia"}'

9.2 Docker 基礎設施管理

1docker compose up -d postgres neo4j redis   # 啟動
2docker compose ps                            # 查看狀態
3docker compose logs -f postgres              # 看日誌
4docker compose exec postgres psql -U postgres -d clinical_decision  # 進 DB
5docker compose down                          # 停止
6docker compose down -v                       # 停止 + 刪除資料（危險!）

9.3 生產部署路線圖（專案 README 規劃）

§10 與其他 CDSS 專案的對比

本專案的最大優勢是「架構完整度」——從 Agent 編排、知識圖譜、醫療標準到合規設計的全鏈路覆蓋；最大劣勢是「資料深度」——知識庫、編碼庫、DDI 庫均為教學用子集。

§11 結語與評價

11.1 學習價值

medical-multi-agent-system 是目前公開的 CDSS 專案中，架構最完整、文件最豐富、跨語言覆蓋最廣的教學範例。它示範了：

1. LangGraph Pipeline 的最佳實踐：StateGraph + 條件路由 + MemorySaver checkpoint，配合 Pydantic 嚴格校驗
2. 醫療 AI 全鏈路設計思維：不只是「給 LLM 一個醫療 prompt」，而是涵蓋資訊採集、知識推理、安全檢查、編碼映射、合規審計
3. 「不是所有場景都適合 LLM」的工程判斷：Audit Agent 刻意不用 LLM，DDI 檢查用規則引擎——確定性需求優先於靈活性
4. 三語言架構映射：同一個 Pipeline 設計在三種語言生態中的實作差異，是跨語言學習的好教材

11.2 主要限制

• 教學專案定位：知識庫（10 症狀 / 15 疾病）、ICD-10（50+ 病種）、DDI（10 條規則）均為極度簡化的子集，距離生產系統（UMLS 200+ 術語體系 / 72,000+ ICD-10 編碼 / DailyMed 完整 DDI 庫）有本質差距
• 無真實臨床驗證：5 個測試病例均為虛構，未經臨床專家審核或大規模測試集驗證
• 單一 commit 歷史：缺乏迭代開發的過程記錄，無法觀察架構演進
• 面試導向設計：大量篇幅用於面試話術與簡歷模板，技術內容有時與「如何在面試中包裝」交織

11.3 對我們管線的潛在價值

• GraphRAG + Neo4j 架構參考：在設計藥物知識圖譜或疾病-標靶關係推理時，可參考其症狀→疾病→治療的三層本體設計
• HIPAA 合規模式：PHI 偵測的 18 類正則、不可變審計日誌、Safe Harbor 脫敏流程——即使不在美國法規範圍內，這套合規設計思維對處理台灣個資法下的健康資料同樣有參考價值
• LangGraph 條件路由：在設計多步驟 Agent Pipeline 時（如 research-pipeline-v2），「資訊不足→回退補充」的模式可直接借鑒
• FHIR R4 資源轉換：若未來需要對接醫院 HIS 系統或建立標準化臨床資料格式，本專案的 Patient / Condition / MedicationRequest 轉換程式碼可作為起點