SHEPHERD 完整教學：用少樣本圖神經網路做罕見疾病表型驅動診斷

Repository: mims-harvard/SHEPHERD Stars: 83 · Language: HTML（文件/專案頁）；核心程式碼為 Python + PyTorch + PyTorch Geometric 論文：npj Digital Medicine 8, 1–22 (2025) ——「Few shot learning for phenotype-driven diagnosis of patients with rare genetic diseases」 線上 Demo：Hugging Face Space · 專案頁：zitniklab.hms.harvard.edu/projects/SHEPHERD 出處實驗室：Harvard MIMS Lab（Marinka Zitnik 實驗室）+ 波士頓兒童醫院/UDN 臨床團隊 License：MIT

1. 專案概述 (Project Overview)

1.1 這個專案在解決什麼問題？

想像一位罹患罕見遺傳疾病 (rare genetic disease; 罕見遺傳疾病) 的孩子，經歷了好幾年、看過十幾位專科醫師，做過基因測序 (genetic sequencing; 基因測序)，卻始終沒有確診。這不是虛構的情境——這正是美國國家衛生研究院 (NIH) 主導的「未確診疾病網路」(Undiagnosed Diseases Network, UDN; 未確診疾病網路) 每天在處理的真實案例。全世界已知的罕見疾病超過 7,000 種，其中不少疾病在美國的患者數不到 3,500 人。臨床醫師一輩子可能只會遇到某種罕見疾病的病例一到兩次，累積的臨床經驗 (clinical experience; 臨床經驗) 極度稀薄，而每種罕見疾病的臨床表現 (clinical presentation; 臨床表現) 又高度異質 (heterogeneous; 異質)——同一種病在不同患者身上,可能呈現完全不同的症狀組合。

一個生活化的比喻：想像你是一位偵探，手上有一份「症狀清單」（患者出現的表型 (phenotype; 表型），例如「肌張力低下、發育遲緩、特殊面部特徵」），任務是從數千個「嫌疑人」（候選基因、候選疾病、或其他病患）裡找出真正的答案。傳統的機器學習偵探需要看過大量「已破案的案例」才能學會辦案技巧——但罕見疾病的問題在於，每種病的「已破案案例」可能只有個位數,甚至一個都沒有。SHEPHERD 這位偵探的訓練方式很不一樣：它不看真實破案記錄，而是靠一本詳盡的「醫學百科全書」（外部知識圖譜 (knowledge graph, KG; 知識圖譜)，收錄基因、表型、疾病之間已知的關聯）加上大量「模擬案例」（電腦生成的虛擬病患）苦練辦案邏輯,培養出「舉一反三」的推理能力，然後才被派去處理真實、罕見、資料稀少的案件。

SHEPHERD 全名可理解為「牧羊人」的意象——在患者於 UDN 診斷流程中「迷路」時，提供多個階段的引導。具體而言，它同時支援三種診斷任務：

1. 候選致病基因排序 (causal gene discovery; 候選致病基因排序)：給定患者的表型與一批候選基因（通常來自基因測序後的變異過濾清單），排序出最可能致病的基因。
2. 相似病患檢索 (patients-like-me identification; 相似病患辨識)：在龐大病患資料庫中,找出表型與基因型都與目前病患相似的其他病患，用「別人的診斷歷程」佐證或啟發目前病患的診斷。
3. 新型疾病表徵化 (novel disease characterization; 新型疾病表徵化)：當患者的症狀組合根本不吻合任何已知疾病時，把患者的表型嵌入 (embedding; 嵌入) 到「疾病語意空間」中，藉此描述這是一種介於哪些已知疾病之間的「新亞型」，協助研究者判斷是否值得深入研究、是否可能是尚未命名的新疾病。

1.2 為什麼這是難題,而不是隨便套個模型就能解決？

一般監督式學習 (supervised learning; 監督式學習) 模型的黃金律是「資料越多、模型越準」。但罕見疾病診斷剛好踩到這條律的天花板：

• 標籤極度稀缺：每種罕見疾病可能只有個位數的已確診病例，遠遠不足以訓練一個穩健的分類器。
• 表型描述的不精確性：真實臨床記錄裡的表型是由不同醫師用不同方式描述、可能有雜訊、遺漏、或誤記（例如記錄了與疾病無關的「干擾表型」）。
• 候選集合極大：人類基因組約有 20,000 個蛋白編碼基因，候選疾病可能有數千種——用窮舉或規則式比對的效率與準確率都不夠。
• 模型必須能在「零樣本疾病」上工作：對於一種訓練時完全沒見過的罕見疾病，模型仍必須能給出合理的診斷線索，這已經超出傳統少樣本學習 (few shot learning; 少樣本學習) 的舒適區（少樣本學習通常假設每個類別至少有 1-5 個標記樣本,而許多罕見疾病是 0 個）。

SHEPHERD 的解法是把問題重新定義成知識引導的度量學習 (knowledge-guided metric learning; 知識引導的度量學習)：不直接學「這個表型組合 → 這個疾病標籤」的映射，而是先在一個涵蓋基因、表型、疾病關聯的知識圖譜上,用純粹的圖結構自我監督學習 (self-supervised learning; 自我監督學習) 訓練出一組「語意豐富」的節點嵌入,再用完全合成、可無限量產生的模擬病患資料，教模型學會「把患者的表型集合投影到與其真正病因（基因/疾病/其他病患）距離最近的位置」。因為模擬病患的產生過程刻意注入了與真實臨床記錄相似的雜訊（不精確的表型選取、隨機的干擾症狀），模型學到的是一種可以泛化到真實世界雜訊的度量空間,而不是死記某個特定疾病的症狀清單。

1.3 在生物醫學 AI 領域的重要性與地位

SHEPHERD 於 2025 年正式發表於《npj Digital Medicine》，是圖神經網路 (graph neural network, GNN; 圖神經網路) 應用於臨床診斷決策支援 (clinical decision support; 臨床決策支援) 的代表性作品之一，也是 Harvard MIMS Lab 在「知識圖譜驅動的精準醫療」系列研究中,少數直接與真實臨床網路（UDN）合作、並在真實未確診病患資料上驗證的工作。它的地位可以從幾個角度理解：

1. 從實驗室到臨床的橋接：許多學術 GNN 模型止步於基準資料集 (benchmark dataset; 基準資料集) 上的指標比較，SHEPHERD 團隊實際把系統跑在 UDN 的未確診病患與 MyGene2（病患家庭自行回報的病例平台）資料上，並公開了推論流程 (Inference-README)，讓其他臨床單位可以套用到自己的病患佇列 (patient cohort; 病患佇列)。
2. 標籤效率 (label efficiency; 標籤效率) 的方法論貢獻：完全不使用真實標記資料訓練，是這類「資料極度稀缺的臨床領域」值得參考的訓練策略範本——先驗知識圖譜 + 合成資料的組合，繞開了「隱私法規不允許大量共享病患資料」與「罕見病例天生就少」這兩個結構性障礙。
3. 多工輸出設計：同一套底層節點嵌入,同時服務三種診斷情境（找基因、找病患、找疾病），對應到 UDN 真實診斷流程裡不同階段的實際需求，而不是單一指標的模型。
4. 實驗室生態系中的角色：在 Marinka Zitnik 實驗室的作品版圖裡，SHEPHERD 與 PrimeKG（大型精準醫學知識圖譜）、TxGNN（零樣本藥物再利用）共享「異質知識圖譜 + GNN」的方法論骨幹，但應用場景往下游延伸到「病患層級的個人化診斷」，補齊了實驗室從「知識圖譜建構」到「藥物發現」再到「臨床診斷」的完整價值鏈。

1.4 相關發表論文與引用

 1@article{shepherd,
 2  title={Few shot learning for phenotype-driven diagnosis of patients with rare genetic diseases},
 3  author={Alsentzer, Emily and Li, Michelle M and Kobren, Shilpa N and Noori, Ayush and Kohane, Isaac S and Zitnik, Marinka},
 4  journal={npj Digital Medicine},
 5  volume={8},
 6  number={1},
 7  pages={1--22},
 8  year={2025},
 9  publisher={Nature Publishing Group}
10}

作者團隊包含 Emily Alsentzer 與 Michelle M. Li（共同第一作者）、Shilpa N. Kobren、Ayush Noori、未確診疾病網路 (UDN) 團隊、Isaac S. Kohane，以及通訊作者 Marinka Zitnik。模擬病患的生成方法另外記錄在姊妹 repo EmilyAlsentzer/rare-disease-simulation，值得在深入理解訓練資料時一併參考。

1.5 在 mims-harvard 實驗室生態系中的角色

flowchart TB
    subgraph ECO["Harvard MIMS Lab 生醫 AI 生態系"]
        PKG["PrimeKG
精準醫學知識圖譜基礎設施"]
        TXG["TxGNN
零樣本藥物再利用"]
        SHP["SHEPHERD
少樣本罕見疾病診斷"]
        OTH["其他 mims-harvard repo
(TxAgent / GraphXAI 等)"]
    end

    PKG -->|提供疾病/基因/表型節點與關聯| SHP
    PKG -->|提供疾病/藥物/基因節點與關聯| TXG
    SHP -.->|方法論骨幹共用: 異質 GNN + 度量學習| TXG
    OTH -.->|可解釋性/agent 工具鏈延伸| SHP

    subgraph CLINICAL["真實臨床場域"]
        UDN["UDN 未確診疾病網路
臨床工作流程"]
        MG2["MyGene2
病患家庭回報平台"]
    end

    SHP -->|部署於推論階段| UDN
    MG2 -->|提供真實病患驗證資料| SHP

    style SHP fill:#DBEAFE,color:#0F172A
    style PKG fill:#E0E7FF,color:#0F172A
    style TXG fill:#E0E7FF,color:#0F172A

從這張圖可以看出，SHEPHERD 並不是孤立的作品——它與 PrimeKG 共享「用知識圖譜承載生醫先驗知識」的基礎設施思路，與 TxGNN 共享「異質 GNN + 度量學習應對資料稀缺」的方法論骨幹，但應用場景更貼近臨床第一線：它的輸出不是給藥廠研發部門看的候選藥物清單，而是給臨床醫師與遺傳諮詢師 (genetic counselor; 遺傳諮詢師) 在診斷會議上直接使用的候選基因/病患/疾病排序表。

1.6 小結：SHEPHERD 是什麼、不是什麼

• 它是：一套基於知識圖譜的少樣本圖神經網路系統,用合成資料訓練，在真實罕見疾病病患資料上做因果基因排序、相似病患檢索、新疾病表徵化三種推論任務。
• 它不是：一個通用的疾病診斷聊天機器人、一個可以取代基因測序與變異解讀 (variant interpretation; 變異解讀) 的工具、或一個可以直接輸出「確診結果」的黑盒子系統——它產出的是排序後的候選清單與相似度分數，仍需臨床專業人員做最終判讀。

2. 核心架構 (Core Architecture)

2.1 系統架構總覽

SHEPHERD 的架構可以拆成三個階段：知識圖譜預訓練 (KG pretraining) → 病患表徵編碼 (patient representation encoding) → 任務專屬頭 (task-specific heads)。三個任務（因果基因排序、相似病患辨識、新疾病表徵化）共用同一套預訓練節點嵌入,只在最後一層接上不同的度量學習頭。

flowchart TD
    subgraph SRC["外部知識來源"]
        HPO["HPO 表型本體
Human Phenotype Ontology"]
        ORPHA["Orphanet
罕見疾病-基因-表型關聯"]
        OMIM["OMIM
孟德爾遺傳疾病資料庫"]
        PPI["基因/蛋白質互作網路
PPI network"]
    end

    subgraph KGCONST["知識圖譜建構 (data_prep/construct_kg)"]
        BUILD["prepare_graph.py
整合多源資料"]
        ADDORPHA["add_orphanet_data_to_kg.py
補充孤兒疾病關聯"]
        KG["罕見疾病知識圖譜
節點: 基因/表型/疾病
邊: gene_phenotype / disease_phenotype / gene_disease / PPI"]
    end

    subgraph PRETRAIN["階段一: 節點嵌入預訓練 (pretrain.py)"]
        GATCONV["GATv2Conv 三層編碼器
異質注意力訊息傳遞"]
        DECODER["解碼器: bilinear / trans / dot
連結預測自我監督"]
        EMB["預訓練節點嵌入
checkpoints/pretrain.ckpt"]
    end

    subgraph PATIENTENC["階段二: 病患編碼 (train.py 共用元件)"]
        PHENOSET["病患表型集合
HPO 詞彙清單"]
        ATTN["表型注意力層
Transformer 式聚合"]
        PATEMB["病患嵌入向量"]
    end

    subgraph HEADS["階段三: 任務專屬頭"]
        GP["gene_prioritization_model.py
GP Aligner
→ 候選基因排序"]
        NCA["patient_nca_model.py
Patient-NCA 度量學習
→ 相似病患檢索"]
        DC["疾病表徵化
病患嵌入 vs 疾病節點嵌入
→ 新疾病表徵化"]
    end

    HPO --> BUILD
    ORPHA --> ADDORPHA
    OMIM --> BUILD
    PPI --> BUILD
    BUILD --> KG
    ADDORPHA --> KG
    KG --> GATCONV --> DECODER --> EMB
    EMB --> PATEMB
    PHENOSET --> ATTN --> PATEMB
    PATEMB --> GP
    PATEMB --> NCA
    PATEMB --> DC

    style KG fill:#FEF3C7,color:#0F172A
    style EMB fill:#DBEAFE,color:#0F172A
    style PATEMB fill:#DBEAFE,color:#0F172A
    style GP fill:#DCFCE7,color:#0F172A
    style NCA fill:#DCFCE7,color:#0F172A
    style DC fill:#DCFCE7,color:#0F172A

關於這張圖的閱讀方式：外部知識來源（HPO、Orphanet、OMIM、蛋白質互作網路）先被整合成一張異質知識圖譜；這張圖譜先用純粹的圖結構自我監督（連結預測任務）預訓練出一組節點嵌入,這一步完全不需要任何病患資料，只需要「基因 A 與表型 B 之間存在已知關聯」這類事實；接著病患的表型集合會通過注意力機制聚合成一個病患嵌入向量，注意力權重（phenotype_attn.csv）本身就是一種可解釋性輸出——它告訴使用者「模型主要依賴哪幾個表型做判斷」；最後,病患嵌入向量分別接上三個任務頭,產出三種不同的排序輸出。

2.2 資料流向：一位病患從輸入到輸出的完整旅程

sequenceDiagram
    participant Clinician as 臨床醫師/研究者
    participant Prep as 資料前處理
preprocess.py
    participant SPL as 最短路徑計算
shortest_paths.py
    participant Model as SHEPHERD 模型
(pretrain + task head)
    participant Out as 輸出結果

    Clinician->>Prep: 提交病患 jsonlines
(表型清單 + 候選基因/疾病/病患)
    Prep->>Prep: 將 HPO 表型字串映射到 KG 節點 ID
    Prep->>SPL: 計算表型節點與候選節點間
最短路徑長度 (SPL)
    SPL-->>Prep: SPL 矩陣 (輔助特徵)
    Prep->>Model: 病患表型序列 + SPL 特徵 + 候選清單
    Model->>Model: 查詢預訓練節點嵌入 (checkpoints/pretrain.ckpt)
    Model->>Model: 表型注意力聚合 → 病患嵌入
    Model->>Model: 任務頭打分 (bilinear 相似度)
    Model-->>Out: scores.csv (候選項排序 + 相似度分數)
    Model-->>Out: phenotype_attn.csv (可解釋性: 表型注意力權重)
    Model-->>Out: phenotype_embeddings.pth (病患嵌入向量)
    Out-->>Clinician: 排序後的候選基因/病患/疾病清單

這張序列圖對應的正是 predict.py 實際執行的流程，也解釋了為什麼專案的 Inference-README.md 特別強調「必須先跑最短路徑計算 (add_spl_to_patients.py --only_test_data)」——SPL 不是可省略的裝飾特徵，而是模型判斷「這個候選基因/表型在知識圖譜上離患者的症狀有多『近』」的重要輔助訊號，尤其在候選集合很大、直接連結證據稀缺時，圖上距離提供了額外的先驗。

2.3 關鍵演算法與方法論

2.3.1 知識圖譜預訓練：用連結預測學通用生醫語意

shepherd/node_embedder_model.py 裡的 NodeEmbeder 類別是整個系統的地基。它用三層 GATv2Conv（Graph Attention Network v2 的圖卷積層；相較於原始 GAT，GATv2 修正了注意力分數的表達力限制，能學到更豐富的鄰居權重分配）在異質知識圖譜上做訊息傳遞,鄰居取樣策略採用 neighbor_sampler_sizes = [15, 10, 5]（對應三層卷積,逐層縮小取樣鄰居數,是大型圖神經網路訓練常見的 mini-batch 取樣手法，用來控制記憶體與計算量）。

解碼器 (decoder) 支援三種選擇：

• bilinear：$\text{score}(h_u, h_v) = h_u^T W_r h_v$，每種關係型 (relation type) 有自己的權重矩陣 $W_r$，表達力最強，是預設值。
• trans（TransE 風格）：$\text{score} = -|h_u + r - h_v|$，把關係視為嵌入空間中的平移向量。
• dot：最簡單的內積相似度，適合快速基準測試。

訓練目標是 max-margin 損失（最大邊界損失），也就是讓「真實存在的邊」的分數明顯高於「隨機取樣的負邊」分數，中間留出邊界 (margin)。這一步完全是自我監督——不需要任何病患標籤，本質上與 TxGNN 的 KG 預訓練階段方法論相通，都是「先讓模型讀懂整本醫學百科全書的知識結構,再談具體任務」。

2.3.2 病患表徵編碼：把一串症狀變成一個向量

有了預訓練節點嵌入之後,SHEPHERD 需要把「一位病患的表型集合」（可能是 5 個、也可能是 30 個 HPO 詞彙）壓縮成單一個病患向量,才能拿去跟候選基因/病患/疾病的節點嵌入做比較。從 hparams.py 中的 n_transformer_layers、n_transformer_heads、attention_type 等超參數可以推斷，這一步採用了類似 Transformer 的自注意力機制對病患的表型嵌入集合做聚合——每個表型節點先取出其在 KG 中學到的嵌入，再透過注意力層動態決定「這位病患的哪些症狀對診斷最關鍵」，這也正是 phenotype_attn.csv 輸出檔案的來源。

一個直覺的比喻：假設病患的症狀清單裡有「肌張力低下」「輕度發育遲緩」「反覆感染」三項，其中「反覆感染」對某個罕見免疫缺陷病特別具指標性，而另外兩項是很多疾病的共同表現。注意力機制學到的效果就類似一位資深醫師「一眼掃過症狀清單，直覺抓住最關鍵的那一項」——把更多權重放在鑑別力高的症狀上。

2.3.3 三種任務頭的具體運作方式

(a) 因果基因排序 (gene_prioritization_model.py 的 GP Aligner)：對每個候選基因，計算病患嵌入與該基因節點嵌入的 bilinear 相似度分數，分數越高代表模型認為該基因越可能是致病基因。超參數 alpha（「GP gate 的貢獻度」）用於控制此任務中一個額外的門控機制，讓模型可以動態決定「這次要多依賴圖結構訊號、多依賴直接的表型—基因關聯訊號」。

(b) 相似病患辨識 (patient_nca_model.py)：核心是 NCA（Neighborhood Component Analysis; 鄰域成分分析）——一種經典的度量學習 (metric learning) 方法,目標是學一個嵌入空間，讓「同一疾病的病患彼此靠近、不同疾病的病患彼此遠離」。這與人臉識別系統學習「同一人的照片嵌入要靠近、不同人要遠離」的目標函數在數學形式上是同一類問題，只是這裡的「同一人」換成了「同一種罕見疾病」。

(c) 新疾病表徵化：把病患嵌入直接拿去跟知識圖譜中所有已知疾病節點（MONDO 或 Orphanet 命名）計算相似度。如果病患與某個已知疾病的距離很近，代表這很可能就是那種病；如果病患的嵌入落在「多個已知疾病之間」的模糊地帶,這本身就是有價值的訊號——暗示這位病患可能患有一種目前科學界尚未正式命名、但與這幾種已知疾病機制相關的新亞型或新疾病。

超參數 lambda（λ，控制兩個損失函數的相對貢獻）與 kappa（κ，衍生自 (1 - lambda) * kappa）反映了訓練時通常會同時優化「任務目標損失」與「圖結構正則化損失」，避免模型在少量合成資料上過度擬合而忘記預訓練階段學到的通用圖結構知識——這是遷移學習 (transfer learning; 遷移學習) 與持續學習 (continual learning; 持續學習) 交界處常見的「災難性遺忘 (catastrophic forgetting; 災難性遺忘) 防護」設計。

2.4 內部元件互動：程式碼結構地圖

 1shepherd/
 2├── pretrain.py              # 階段一入口: KG 節點嵌入預訓練
 3├── train.py                 # 階段二入口: 三種任務的訓練
 4├── predict.py                # 階段三入口: 用已訓練模型產生預測
 5├── node_embedder_model.py   # GATv2Conv 異質圖編碼器 (NodeEmbeder)
 6├── decoders.py               # bilinear / trans / dot 解碼器
 7├── gene_prioritization_model.py  # 因果基因排序模型主體
 8├── patient_nca_model.py     # 相似病患辨識的度量學習模型
 9├── task_heads/
10│   ├── gp_aligner.py         # GP (Gene Prioritization) 對齊頭
11│   └── patient_nca.py        # NCA 度量學習頭
12├── dataset.py                 # jsonlines 病患資料的 Dataset 封裝
13├── samplers.py                 # 圖鄰居取樣與負取樣策略
14├── hparams.py                   # 三階段 (pretrain/train/predict) 超參數集中管理
15└── utils/
16    ├── pretrain_utils.py       # 預訓練用的批次組裝/指標計算/繪圖
17    ├── train_utils.py          # 訓練迴圈輔助函式
18    └── loss_utils.py            # max-margin / NCA 損失實作

project_config.py 是全域設定的樞紐——所有路徑（資料目錄、checkpoint 目錄、自訂病患資料路徑）都在此檔案集中管理，這也是為什麼 Inference-README.md 反覆提醒使用者「先改這個檔案的路徑變數」。data_prep/ 目錄則是完全獨立於核心模型程式碼的資料整備管線——知識圖譜建構 (construct_kg/)、MyGene2 病患佇列整理 (create_mygene2_cohort/)、UDN 病患佇列整理（含用 Exomiser 做變異篩選的 create_udn_cohort/create_exomiser_cohort/）、以及最短路徑特徵計算 (shortest_paths/)，彼此透過統一的 jsonlines 病患格式與 KG 節點映射檔銜接。

3. 安裝與設定 (Installation & Setup)

3.1 前置需求

• 作業系統：Linux（官方環境檔以 conda 為基礎，Windows/macOS 未在 README 中明確驗證）
• 硬體：建議有 CUDA 相容 GPU——node_embedder_model.py 明確寫了 device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')，在 CPU 上跑三層 GATv2Conv 對整張知識圖譜做預訓練會非常慢
• 核心依賴：Python、PyTorch、PyTorch Geometric (PyG)、PyTorch Lightning、Weights & Biases (wandb，訓練過程記錄用)、conda（官方指定的環境管理工具）
• 資料下載空間：知識圖譜 + 模擬病患資料集存放於 Harvard Dataverse，加上模型 checkpoint（figshare），建議預留數 GB 硬碟空間

3.2 逐步安裝指南

方法一：官方建議流程（conda + PyG 專用安裝腳本）

 1# 1. 下載專案
 2git clone https://github.com/mims-harvard/SHEPHERD
 3cd SHEPHERD
 4
 5# 2. 建立 conda 環境（環境定義檔已包含 PyTorch/PyTorch Lightning/wandb 等）
 6conda env create -f environment.yml
 7conda activate shepherd
 8
 9# 3. PyTorch Geometric 的 C++ 擴充套件需要對應 CUDA/PyTorch 版本，
10#    官方額外提供腳本處理版本匹配問題
11bash install_pyg.sh

方法二：AIKT 環境治理慣例下的隔離安裝（依全域規範，Python 專案優先 uv 而非裸 conda pip）

若要在 AIKT 的工具鏈規範下管理，建議把 conda 僅用於取得正確的 CUDA/PyTorch 組合，其餘 Python 套件改用 uv pip install 安裝進同一個環境,避免混用系統 pip：

1conda create -n shepherd python=3.9 -y
2conda activate shepherd
3# 用 uv 而非裸 pip 安裝其餘依賴（先確認 environment.yml 中列出的版本）
4uv pip install -r <(python -c "import yaml,sys; d=yaml.safe_load(open('environment.yml')); print('\n'.join(d.get('dependencies', [])))" 2>/dev/null || echo "請手動比對 environment.yml")
5bash install_pyg.sh

註：SHEPHERD 官方未提供 pyproject.toml 或 setup.py（本專案是研究程式碼而非套件化的函式庫），因此沒有 pip install shepherd 這種安裝方式，所有執行都是以「clone 後在 repo 目錄內直接跑腳本」的模式進行。

3.3 資料下載與環境設定

 1# 4. 從 Harvard Dataverse 下載資料集（罕見疾病知識圖譜 + 模擬病患 train/val split + MyGene2 病患）
 2#    網址: https://doi.org/10.7910/DVN/TZTPFL
 3#    下載時務必選「全部檔案」並保持原始資料夾結構，下載後記得解壓縮每個檔案
 4
 5# 5. 編輯 project_config.py，將 PROJECT_DIR 指向剛下載的資料資料夾
 6#    PROJECT_DIR = Path("/your/path/to/SHEPHERD_data")
 7
 8# 6.（可選但強烈建議）下載預訓練與已訓練的 checkpoint，省去重新訓練
 9#    網址: https://figshare.com/articles/software/SHEPHERD/21444873
10#    下載後移動到 project_config.PROJECT_DIR / 'checkpoints'

若要串接自己的病患資料（例如院內的罕見疾病病患佇列），除了改 project_config.py 的資料變數（第 10-16 行），還需要在 data_prep/shortest_paths/ 用其中的腳本，替新病患計算與知識圖譜節點的最短路徑特徵——這一步在正式跑 predict.py 前是硬性要求，跳過會導致模型缺少 SPL 特徵而報錯或效能大幅下降。

3.4 驗證安裝是否成功

1# 確認 PyTorch 與 PyG 正確安裝且能偵測到 GPU
2python -c "import torch; print('CUDA available:', torch.cuda.is_available())"
3python -c "import torch_geometric; print('PyG version:', torch_geometric.__version__)"
4
5# 用小規模的 sanity check：載入 hparams 確認超參數字典可以被正確組裝
6cd shepherd
7python -c "from hparams import get_pretrain_hparams; print('hparams module OK')"

若上述指令皆無錯誤，且 project_config.PROJECT_DIR 底下已能看到 KG_edgelist_mask.txt、KG_node_map.txt 等檔案，即代表環境與資料準備完成，可以進入下一節的實際使用流程。

4. 基本使用 (Basic Usage)

4.1 快速入門：用官方 checkpoint 直接推論（不需重新訓練）

對絕大多數想「拿來用」而非「重現論文訓練過程」的使用者，最快的路徑是直接使用官方提供的已訓練 checkpoint 對自己的病患資料做推論。整體流程對應 Inference-README.md 所描述的十個步驟，核心概念是：環境 + 資料 + checkpoint 三者到位後，唯一需要自己動手的部分是把病患資料轉成指定的 jsonlines 格式,並計算好最短路徑特徵。

4.2 輸入資料格式：一位病患的 jsonlines 範例

SHEPHERD 的病患輸入格式是 JSON Lines——每一行是一個完整病患的 JSON 物件。以下是一個假想的病患範例（模擬一個影響肌肉張力與心臟發育的複合症狀組合）：

1{
2  "id": "patient_0001",
3  "positive_phenotypes": ["HP:0001252", "HP:0001636", "HP:0000252", "HP:0004322"],
4  "all_candidate_genes": ["ENSG00000134242", "ENSG00000141736", "ENSG00000171862"],
5  "true_genes": ["ENSG00000134242"],
6  "true_diseases": ["MONDO:0009830"]
7}

• id：病患的唯一識別碼（自訂字串即可，不需對應真實身分）
• positive_phenotypes：以 HPO (Human Phenotype Ontology; 人類表型本體) 詞彙碼表示的陽性表型清單。例如 HP:0001252（肌張力低下）、HP:0000252（小頭畸形）
• all_candidate_genes：Ensembl 基因 ID 表示的候選基因清單（通常來自基因測序後的變異過濾結果，例如 Exomiser 的輸出）——僅在跑因果基因排序任務時需要
• true_genes：真正的致病基因（若已知，用於計算效能指標；若未知診斷,可省略或留空，此時 predict.py 只會輸出排序結果、不計算正確率）
• true_diseases：以 MONDO 本體碼表示的真實疾病（若已知，僅用於新疾病表徵化任務的效能評估）

4.3 範例一：執行因果基因排序 (Causal Gene Discovery)

假設某醫院的臨床遺傳團隊有一批已完成基因測序、但候選基因清單仍有 20-30 個候選、需要優先順序排序的病患，可以這樣呼叫：

1cd shepherd
2python predict.py \
3        --run_type causal_gene_discovery \
4        --patient_data my_data \
5        --edgelist KG_edgelist_mask.txt \
6        --node_map KG_node_map.txt \
7        --saved_node_embeddings_path checkpoints/pretrain.ckpt \
8        --best_ckpt checkpoints/causal_gene_discovery.ckpt

輸出的 scores.csv 每一行代表「病患 ID + 候選基因 + 相似度分數 + 是否為真實致病基因（二元標籤，若提供了 true_genes）」，直接依相似度分數排序即可得到模型認為最可能的候選基因排名。

4.4 範例二：執行相似病患辨識 (Patients-Like-Me)

當一位病患的症狀組合罕見到連候選基因清單都難以縮小時，找出「表型/基因型相似的其他病患」往往能提供關鍵的診斷線索（例如「原來三年前也有一位病患有幾乎一樣的症狀組合，最後確診是 X 症」）：

1cd shepherd
2python predict.py \
3        --run_type patients_like_me \
4        --patient_data my_data \
5        --edgelist KG_edgelist_mask.txt \
6        --node_map KG_node_map.txt \
7        --saved_node_embeddings_path checkpoints/pretrain.ckpt \
8        --best_ckpt checkpoints/patients_like_me.ckpt

若想跟一個更大的外部病患資料庫比較（例如把自己院內的病患與公開的模擬病患資料集一起比較），官方建議把兩批病患的 jsonlines 檔案合併成同一個檔案再輸入，讓模型在同一個嵌入空間中計算彼此的相似度。

4.5 範例三：執行新疾病表徵化 (Novel Disease Characterization)

1cd shepherd
2python predict.py \
3        --run_type disease_characterization \
4        --patient_data my_data \
5        --edgelist KG_edgelist_mask.txt \
6        --node_map KG_node_map.txt \
7        --saved_node_embeddings_path checkpoints/pretrain.ckpt \
8        --best_ckpt checkpoints/disease_characterization.ckpt

輸出結果除了 scores.csv（病患對每個已知疾病節點的相似度排序），還會產出 disease_embeddings.pth——這是唯一在三個任務中額外輸出疾病嵌入的模式，方便後續做視覺化（例如把病患嵌入與鄰近的疾病嵌入投影到二維空間，觀察病患是否落在多個已知疾病的「中間帶」）。

4.6 範例四：用 Python 讀取並分析輸出結果

predict.py 執行完後，結果會落在 project_config.PROJECT_RESULTS/<TASK>/<RUN_NAME>/<DATASET_NAME>/ 目錄下。以下是一個讀取因果基因排序結果、取出每位病患前 5 名候選基因的範例：

 1import pandas as pd
 2from pathlib import Path
 3
 4results_dir = Path("PROJECT_RESULTS/causal_gene_discovery/my_run/my_data")
 5scores = pd.read_csv(results_dir / "scores.csv")
 6
 7# 假設欄位為: patient_id, gene_id, score, is_true_gene
 8top5_per_patient = (
 9    scores.sort_values("score", ascending=False)
10    .groupby("patient_id")
11    .head(5)
12)
13
14for patient_id, group in top5_per_patient.groupby("patient_id"):
15    print(f"病患 {patient_id} 的前 5 名候選基因：")
16    for _, row in group.iterrows():
17        marker = " ← 真實致病基因" if row.get("is_true_gene") else ""
18        print(f"  {row['gene_id']}  分數={row['score']:.4f}{marker}")

搭配 phenotype_attn.csv 還可以進一步分析「模型主要依賴這位病患的哪些症狀做出這個排序」，這對臨床溝通（向病患家庭或多學科團隊解釋模型判斷依據）相當重要——單純給一個排序清單而不給理由，在臨床場域的可信度與可用性都會大打折扣。

5. 進階功能與應用場景 (Advanced Features & Use Cases)

5.1 從零訓練：重現論文結果或訓練自己的知識圖譜

若研究單位有自己專屬的知識圖譜（例如聚焦在某個疾病亞領域、或整合了院內獨有的基因-表型統計關聯），可以完整走一遍預訓練 + 訓練流程，而不只是用官方 checkpoint：

 1cd shepherd
 2
 3# 階段一: 在自訂 KG 上預訓練節點嵌入
 4python pretrain.py \
 5        --edgelist my_KG_edgelist.txt \
 6        --node_map my_KG_node_map.txt \
 7        --save_dir checkpoints/
 8
 9# 階段二: 用模擬病患資料訓練因果基因排序任務頭
10python train.py \
11        --edgelist my_KG_edgelist.txt \
12        --node_map my_KG_node_map.txt \
13        --patient_data disease_simulated \
14        --run_type causal_gene_discovery \
15        --saved_node_embeddings_path checkpoints/<BEST_PRETRAIN_CHECKPOINT>.ckpt

超參數調整建議聚焦在 hparams.py 裡的 get_pretrain_hparams() 與 get_train_hparams()：預訓練階段最值得留意的是 hidden/output（嵌入維度）與 n_heads（GATv2 注意力頭數），維度越大理論表達力越強但也越容易在小型自訂 KG 上過擬合；訓練階段的 lambda/kappa（損失權重平衡）與 n_transformer_layers/n_transformer_heads（病患表型聚合的 Transformer 深度）則直接影響病患表徵的品質，建議用官方提供的驗證集分割 (disease-split train/val) 先做超參數搜尋再套用到正式資料。

5.2 建構自訂知識圖譜：整合機構內部資料

data_prep/construct_kg/ 目錄提供了知識圖譜建構的完整範例（build_graph.ipynb 展示互動式流程，prepare_graph.py 為可批次執行版本，add_orphanet_data_to_kg.py 示範如何補充 Orphanet 的孤兒疾病關聯）。若要整合機構內部的基因-表型統計資料（例如自己收集的院內病患群體統計出的基因-表型共現頻率），可以參考以下擴充模式：

 1# 示意程式碼: 將自訂的基因-表型關聯加入既有知識圖譜邊清單
 2import pandas as pd
 3
 4kg_edges = pd.read_csv("KG_edgelist_mask.txt", sep="\t", header=None,
 5                        names=["source", "relation", "target"])
 6
 7# 假設有一份院內統計出的基因-表型共現資料
 8custom_associations = pd.read_csv("institutional_gene_phenotype.csv")
 9new_edges = pd.DataFrame({
10    "source": custom_associations["ensembl_gene_id"],
11    "relation": "gene_phenotype_institutional",
12    "target": custom_associations["hpo_id"],
13})
14
15combined_edges = pd.concat([kg_edges, new_edges], ignore_index=True)
16combined_edges.to_csv("KG_edgelist_mask_extended.txt", sep="\t",
17                       header=False, index=False)

注意：加入新關係型 (relation type) 後，node_embedder_model.py 中的 num_relations = len(edge_attr_dict) 會自動因應變化，但既有的 checkpoint 因為輸出維度改變將無法直接沿用，必須重新跑預訓練。

5.3 與變異篩選工具鏈整合：Exomiser 前處理

data_prep/create_udn_cohort/create_exomiser_cohort/ 展示了 SHEPHERD 如何與 Exomiser（廣泛使用的表型驅動變異優先排序工具）銜接——實務上的診斷流程通常是「先用 Exomiser 從全外顯子測序 (whole exome sequencing, WES; 全外顯子測序) 結果中，依據已知的基因-疾病資料庫過濾出數十個候選變異/基因,再把這批候選基因清單餵給 SHEPHERD 做知識圖譜層級的重新排序」。這種兩階段管線 (two-stage pipeline; 兩階段管線) 設計——先用變異層級的生物資訊工具做粗篩，再用圖神經網路做語意層級的精篩——是目前臨床基因體學 (clinical genomics; 臨床基因體學) 管線常見的架構模式，SHEPHERD 定位在第二階段。

5.4 效能優化建議

• 鄰居取樣大小的取捨：neighbor_sampler_sizes 預設 [15, 10, 5]，若知識圖譜規模擴大（例如節點數超過百萬），可考慮降低取樣數以換取訓練速度，但需留意過度縮小會犧牲遠距離節點的訊息傳遞能力。
• 批次大小與 GPU 記憶體：預訓練預設 batch_size: 512、inference_batch_size: 64，若在較小 GPU（例如 8GB 顯存）上跑，需要相應下調並搭配梯度累積 (gradient accumulation; 梯度累積)。
• checkpoint 重用策略：因果基因排序、相似病患辨識、新疾病表徵化三個任務共用同一份預訓練嵌入（saved_node_embeddings_path），只有任務頭不同——若要同時跑三種任務，預訓練只需做一次，可以大幅節省運算資源。
• 推論階段的批次化：面對大量病患（例如整個院區的未確診病患佇列），建議把 jsonlines 檔案切成多個批次平行跑 predict.py，而非單次載入所有病患，避免記憶體壓力。

5.5 實際應用情境：多學科團隊會議前的預先分析

一個具體的應用場景是：某醫學中心的罕見疾病多學科團隊 (multidisciplinary team, MDT; 多學科團隊) 會議前，遺傳諮詢師先把本週要討論的病患資料（表型清單 + 候選基因）批次跑過 SHEPHERD 的因果基因排序與相似病患辨識，產出的排序清單與相似病患案例，作為會議討論的起點素材,讓臨床醫師、遺傳學家、生物資訊分析師能在有量化排序依據的基礎上,更聚焦地討論候選診斷方向，而不是從零開始逐一檢視每個候選基因。這正是 SHEPHERD 論文中反覆強調的定位：加速診斷流程中的假設生成階段，而非取代最終的臨床判斷。

6. AIKT 整合分析與策略 (AIKT Integration & Strategy)

6.1 整合架構圖：SHEPHERD 在 AIKT 27 層中的落點

flowchart LR
    subgraph EXTERNAL["SHEPHERD 專案本體 (GitHub)"]
        REPO["mims-harvard/SHEPHERD
程式碼 + README + 論文連結"]
    end

    subgraph L2["L2 ai-gh-save"]
        GHSAVE["gh-save.sh
抓取 repo metadata + README"]
    end

    subgraph L12["L12 gh-tutorial-qd"]
        TUTGEN["本教學文件生成
27-SHEPHERD.md"]
    end

    subgraph L7["L7 quarkdown"]
        QD["md → HTML/PDF/slides
編譯此教學為可分享文件"]
    end

    subgraph L4["L4 graphify"]
        GRAPH["knowledge graph 索引
SHEPHERD 概念節點化"]
    end

    subgraph L8L9["L8/L9 docling + paper-search"]
        DOC["docling: 解析 npj Digital Medicine PDF"]
        PS["paper-search: 檢索相關罕見疾病 AI 文獻"]
    end

    subgraph L10["L10 paper-qa-lite"]
        PQ["對 SHEPHERD 論文 PDF 做本地 RAG 問答"]
    end

    subgraph L19["L19 tu-plan-generator"]
        TU["若延伸至罕見疾病藥物開發計畫"]
    end

    REPO --> GHSAVE --> TUTGEN
    TUTGEN --> QD
    TUTGEN --> GRAPH
    DOC --> PQ
    PS --> PQ
    PQ -.->|補充論文方法細節| TUTGEN
    GRAPH -.->|建立與 TxGNN/PrimeKG 節點的關聯| TU

    style REPO fill:#FEF3C7,color:#0F172A
    style TUTGEN fill:#DBEAFE,color:#0F172A
    style PQ fill:#DCFCE7,color:#0F172A

這張圖說明了 AIKT 對待 SHEPHERD 這類「有程式碼、有論文、有應用場景」的第三方研究專案的標準處理鏈路：L2 負責把 repo 資訊帶進本地知識庫,L12（本教學）負責把技術內容轉譯成結構化的中文學習資料,L7 負責把教學編譯成可攜式文件，L4 負責把概念節點化進知識圖譜以便跨專案關聯查詢,而 L8-L10 則是「如果需要深入讀論文原文」時的輔助管線。

6.2 紅海分析 (Red Ocean Analysis)：與 AIKT 現有功能重疊的領域

SHEPHERD 本質上是一個科學計算/深度學習研究程式碼庫，而 AIKT 是一個知識工作流編排系統，兩者的核心功能定位差異很大，但仍有幾個表層重疊點值得誠實盤點：

市場定位衝突評估：整體而言，紅海範圍非常小。唯一真正重疊、且 AIKT 沒有優勢的領域是「知識圖譜的生醫本體語意建構」——這是 SHEPHERD（以及 PrimeKG、TxGNN 等姊妹專案）的核心強項，AIKT 的 graphify 是文件索引工具而非生醫知識圖譜引擎，不應該也沒有能力試圖取代它。AIKT 應該誠實地把自己定位為「SHEPHERD 這類模型的知識管理與應用外圍工具」，而非競爭者。

6.3 藍海策略 (Blue Ocean Strategy)：AIKT 可以獨特切入的機會

SHEPHERD 作為純研究程式碼庫，存在幾個明顯的「知識工作流缺口」，恰好是 AIKT 各層可以互補補位之處：

缺口一：論文與程式碼之間沒有橋接文件。SHEPHERD 的 README 是操作導覽,但沒有任何文件把「為什麼要用 GATv2Conv」「為什麼用 max-margin 損失」「NCA 度量學習如何運作」講清楚給非深度學習背景的臨床/生資人員看懂。→ 本教學文件本身就是這個藍海機會的實踐：用 paper-qa-lite (L10) 深入論文的方法細節，配合本教學的中文講解，填補「程式碼可執行但不易理解」的落差。

缺口二：輸出結果缺乏臨床溝通格式。scores.csv、phenotype_attn.csv 都是給程式讀的原始格式，臨床會議上無法直接展示。→ kami (L11) 可以把 SHEPHERD 的推論輸出（排序表 + 表型注意力視覺化）自動排版成符合臨床簡報風格的 PDF/slides，這是 SHEPHERD 完全沒有觸及、但對真實採用至關重要的最後一哩路。

缺口三：與其他罕見疾病研究資源的橫向串接缺失。SHEPHERD 讀者若想知道「還有哪些工具在做類似的表型驅動診斷」「這篇論文之後有哪些後續研究引用/擴展它」，目前必須自己去 Google Scholar 手動查。→ paper-search (L9) + agent-reach (L25) 可以自動化建立「SHEPHERD 及其引用網路」的持續追蹤,搭配 ai-autofetch (L3) 做每日新論文監控，讓研究者不必手動盯 PubMed。

缺口四：多個 mims-harvard 姊妹專案（PrimeKG、TxGNN、SHEPHERD）之間的知識關聯未被系統化。這三個專案共享大量方法論與資料來源（都用到罕見疾病/精準醫學知識圖譜），但目前只以「各自獨立的 GitHub repo」形式存在。→ graphify (L4) 可以在概念層級（而非生醫本體層級）建立這三個專案教學文件之間的交叉索引——例如「SHEPHERD 的 GATv2Conv 編碼器」與「TxGNN 的異質 GNN 編碼器」節點互相連結，讓研究者查詢時能看到方法論家族的全貌。

具體差異化策略：AIKT 不試圖成為「另一個 SHEPHERD」或「更好的 GNN 訓練框架」，而是定位為 「SHEPHERD 這類前沿研究工具與真實工作場景之間的知識轉譯層」——把深度學習研究程式碼轉譯成可讀教學、把原始輸出轉譯成可溝通的簡報、把孤立的論文轉譯成有引用網路脈絡的持續追蹤情報。這正是 AIKT 在「不做直接科學計算」的定位下,唯一合乎邏輯且真正有價值的切入角度。

6.4 推薦整合方案：具體實施路徑

flowchart TD
    A["階段 1: 文件化 (已完成)
本教學 27-SHEPHERD.md
L12 gh-tutorial-qd"] --> B["階段 2: 論文深讀
docling 解析 npj Digital Medicine PDF
→ paper-qa-lite 建立可問答索引"]
    B --> C["階段 3: 知識圖譜化
graphify 索引本教學
與 TxGNN/PrimeKG 教學建立交叉連結"]
    C --> D["階段 4: 持續追蹤
ai-autofetch 監控後續引用文獻
agent-reach 追蹤 SHEPHERD GitHub 更新/issue"]
    D --> E["階段 5: 輸出模板化
kami 設計『SHEPHERD 推論結果簡報』模板
供未來實際跑病患資料時直接套用"]

    style A fill:#DCFCE7,color:#0F172A
    style E fill:#FEF3C7,color:#0F172A

優先順序建議：階段 1（本文件）與階段 3（graphify 索引）成本最低、立即可行,應優先完成；階段 2（論文深讀）建議在真正需要重現訓練細節或撰寫相關研究計畫時才觸發，避免無目的的預先索引造成資訊過載；階段 5（輸出模板化）則應等到真正有一個實際病患資料集要跑 SHEPHERD 推論時才投入設計，避免打造一個沒有真實使用情境驗證的模板。這個優先順序本身也體現了 AIKT 全域規範「先處理真實存在的問題」的實用主義原則——不因為 SHEPHERD 是一個有趣的研究專案就過度工程化整合方案。

7. 效能、限制與替代方案 (Performance, Limitations & Alternatives)

7.1 效能數據與基準測試

論文（npj Digital Medicine 2025）中報告 SHEPHERD 在模擬病患測試集、MyGene2 病患佇列、以及 UDN 真實未確診病患佇列上,對三種任務均展現優於傳統表型比對工具（例如僅依賴 HPO 語意相似度的排序方法）的效能，尤其在候選基因數量龐大、且患者表型描述不完整/有雜訊的情境下優勢更明顯。具體數值指標（如 top-k 命中率）會依資料集分割與候選集大小而變化，建議直接參考論文原文的表格與 GitHub README 中連結的補充材料,本教學不做二次轉載以避免數字過時或引用誤差。

7.2 已知限制

• 無法取得 UDN 真實病患資料：出於病患隱私考量，官方明確聲明「無法提供 UDN 病患資料」，這意味著外部使用者無法完整重現論文中在 UDN 佇列上的驗證結果,只能用公開的模擬病患資料集與 MyGene2 資料驗證。
• 候選集合品質高度依賴上游變異篩選：因果基因排序任務的效能上限,受限於 all_candidate_genes 清單的品質——如果上游的變異篩選工具（如 Exomiser）已經漏掉真正的致病基因，SHEPHERD 也無法「無中生有」找回它，這是典型的「垂圾進、垂圾出 (garbage in, garbage out)」限制。
• 表型編碼必須是 HPO 詞彙：目前的資料格式強制要求表型以 HPO 碼表示，若臨床記錄是自由文字，需要先經過表型正規化 (phenotype normalization; 表型正規化) 步驟（例如用 NLP 工具從病歷文字中抽取並映射到 HPO 碼），SHEPHERD 本身不提供這一步。
• 知識圖譜是靜態快照：訓練用的知識圖譜是特定時間點的 HPO/Orphanet/OMIM 快照,若這些上游本體資料庫更新（新增疾病、修正表型關聯），需要重新建構圖譜並重新預訓練才能反映最新知識,無法即時同步。
• 運算資源門檻：三層 GATv2Conv 在完整知識圖譜規模上訓練需要 GPU，對沒有深度學習基礎設施的小型臨床單位而言,直接使用官方 checkpoint 做推論的門檻遠低於自行訓練。

7.3 與同類工具比較

SHEPHERD 相較於規則式/本體比對工具（Exomiser、Phenomizer）的優勢在於能學到「圖結構層級的隱含關聯」（例如兩個表面上不相似的表型,若在知識圖譜上共享許多中介節點，模型仍能學到它們的隱含關聯）；相較於傳統監督式分類器的優勢則在於完全不需要真實標記資料,適合本質上「每種病例都很少」的罕見疾病場景。

7.4 何時使用 vs 何時不使用

適合使用 SHEPHERD 的情境：

• 已完成基因測序、有一批候選基因需要優先排序，且想要「圖結構層級」的排序依據而非僅是規則比對
• 病患症狀組合罕見到懷疑可能是尚未命名的新疾病亞型，需要系統性地在疾病語意空間中定位
• 研究單位有能力/意願建構或延伸罕見疾病知識圖譜，想探索知識引導深度學習方法論

不適合使用 SHEPHERD 的情境：

• 只需要快速、可解釋的表型比對，且不要求圖結構推理——Phenomizer 這類輕量工具可能更快、更容易向臨床人員解釋
• 目標疾病是常見病、且已有大量真實標記資料——傳統監督式方法或現成的臨床決策支援系統可能更直接有效，不需要 SHEPHERD 這種為資料稀缺場景設計的複雜方法論
• 缺乏 GPU 運算資源且無法使用官方 checkpoint（例如需要處理與官方 KG 節點體系完全不同的自訂本體）——此時自行訓練的門檻可能超出投入產出比

8. 總結與建議 (Summary & Recommendations)

8.1 關鍵要點回顧

SHEPHERD 是 Harvard MIMS Lab 針對罕見遺傳疾病診斷提出的少樣本圖神經網路系統，核心創新在於完全用外部知識圖譜與合成資料訓練,規避真實標記資料稀缺與隱私限制的雙重障礙。它的三段式架構（KG 預訓練 → 病患表徵編碼 → 任務專屬頭）讓同一套底層知識,能同時服務因果基因排序、相似病患檢索、新疾病表徵化三種真實臨床場景的需求,並且在 UDN 未確診疾病網路與 MyGene2 病患佇列上得到實際驗證,是少數真正跨出學術基準測試、觸及臨床應用場域的圖神經網路醫療診斷系統。

8.2 最佳使用場景總結

對於已具備基因測序能力、正在處理未確診罕見疾病病例的臨床遺傳團隊或研究型醫院,SHEPHERD 最適合作為診斷流程中段的假設生成輔助工具——在變異篩選（如 Exomiser）產出候選基因清單之後、正式的多學科團隊會議討論之前，提供一層知識圖譜層級的重新排序與相似病患佐證，幫助團隊把有限的討論時間聚焦在最可能的候選方向上。它不是取代臨床判斷的終局工具，而是加速「從一堆可能性中找出值得優先深入調查的少數幾個方向」這個關鍵瓶頸步驟。

8.3 未來發展方向

從論文與程式碼現況推測，幾個值得關注的後續發展方向包括：

• 表型正規化的前端整合：目前使用者必須自行把臨床文字轉成 HPO 碼，若能整合表型抽取 NLP 工具（例如接上臨床文本挖礦 pipeline），將大幅降低使用門檻。
• 知識圖譜的動態更新機制：隨著 HPO、Orphanet、OMIM 等上游本體資料庫持續更新，若能建立增量式的圖譜更新與嵌入微調流程（而非每次都需要完整重新預訓練），將提升系統的長期可維護性。
• 多模態擴充：目前輸入僅限表型（HPO 詞彙）,未來若能整合影像（如面部特徵辨識）、實驗室數據等多模態資訊,理論上能進一步提升診斷精準度，這也是精準醫療 AI 領域的普遍發展趨勢。
• 與 AIKT 這類知識工作流系統的協作模式深化：如本文第 6 節分析,SHEPHERD 代表的是「深度研究工具」典型的知識轉譯需求,隨著更多類似的專業模型出現，建立標準化的「研究程式碼 → 可理解教學 → 可溝通輸出」轉譯流程,將是讓前沿研究真正落地到臨床實務的關鍵基礎設施。

對於正在評估是否導入 SHEPHERD 的團隊，建議的第一步不是急著重新訓練模型，而是先用官方 checkpoint 在小批次的內部病患資料上做推論驗證，確認排序結果的臨床可信度與可解釋性輸出（表型注意力）是否符合團隊的實際判讀習慣，再決定是否投入資源做知識圖譜客製化或重新訓練。