deepspot-m 是做什麼的？
概述
DeepSpot-M 是一個多模態基礎模型，能將 224x224 的 H&E 組織學圖塊對應到 log1p-CPM 格式的空間基因表現。輸出為虛擬空間轉錄組學：每個查詢基因在每個圖塊上有一個值，並依圖塊來源的網格排列。
一個 LoRA 適配的病理學基礎骨幹（Midnight）將圖塊標記化。一個交叉注意力基因解碼器讓每個基因查詢關注圖塊標記，而一個基因路由器超網路則從冷凍生物嵌入（Evo 2、Orthrus、ProtT5、scGPT、Apertus）建立基因特定投影。基因以可查詢的嵌入形式而非固定輸出槽進入模型，因此釋出的模型涵蓋約 19,000 個蛋白質編碼基因面板，包括訓練中未見過的基因。該面板以 tokens.csv 形式隨權重提供，並透過 model.gene_names 公開；此版本無法查詢面板以外的基因。
應用於 TCGA 後，該模型產生了涵蓋 32 種癌症類型、共 28,664 張切片的虛擬空間轉錄組學圖譜。
授權
程式碼採用 PolyForm Noncommercial 1.0.0 授權，權重採用 CC-BY-NC-SA-4.0 授權。僅限非商業研究使用，並在重新發布輸出前檢查這兩個授權條款。
安裝
uv pip install deepspotm==1.0.0
1.0.0 版本支援 Python 3.10 至 3.13，並會拉取 PyTorch。如果需要 GPU 推理，請先安裝與您 CUDA 版本匹配的 PyTorch 建置版本。
模型存取
權重為門控存取：
- 開啟 https://huggingface.co/ratschlab/DeepSpotM 並請求存取權限。
- 獲得存取權後，驗證將下載權重的機器：
huggingface-cli login
from_pretrained 會讀取該快取令牌，因此每台機器只需登入一次。
快速開始
from deepspotm import DeepSpotM
model, image_processor = DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source="scgpt")
vals = model.predict_genes(image_processor(pil_tile).unsqueeze(0), ["EPCAM", "CD3D"])
pil_tile 是一個精確 224x224 像素的 PIL 圖片。image_processor 將其轉換為張量，unsqueeze(0) 增加批次維度，predict_genes 接受批次和一個 HGNC 基因符號列表。回傳值為 log1p-CPM 格式，與您傳入的基因列表對齊，因此請將該列表與輸出一起保存，以保持欄位標記。基因符號必須在釋出的約 19,000 個基因面板（model.gene_names）中；未知的符號會引發 KeyError，並指出有問題的基因。
圖塊要求
圖塊必須是 224x224 RGB，放大倍率約為 20 倍（約每像素 0.5 微米）。在管線邊界處檢查尺寸，而不是傳遞未經檢查的裁切：
TILE_PX = 224
def require_tile(tile):
"""回傳一個 RGB 224x224 圖塊，如果裁切尺寸錯誤則引發錯誤。"""
if tile.size != (TILE_PX, TILE_PX):
raise ValueError(
f"DeepSpot-M 需要一個約 20 倍放大倍率（~0.5 微米/像素）的 {TILE_PX}x{TILE_PX} 圖塊；"
f"收到 {tile.size[0]}x{tile.size[1]}。"
"請在匹配的層級重新切割圖塊，或重新取樣裁切。"
)
return tile.convert("RGB")
在切片層級提取解析度最接近每像素 0.5 微米的圖塊，然後在該處裁切為 224x224。從較粗糙的層級重新取樣會改變骨幹讀取的紋理。
保持依賴為可選
deepspotm 及其權重是一個龐大且門控的依賴項。在需要它的函式內部進行匯入，以便周圍專案在沒有它的情況下仍能安裝、匯入和測試，並將 ImportError 轉換為一個說明每個步驟的訊息：
DEEPSPOTM_HELP = (
"DeepSpot-M 不可用。請使用 `uv pip install deepspotm==1.0.0` 安裝，"
"在 https://huggingface.co/ratschlab/DeepSpotM 請求門控權重的存取權限，"
"然後使用 `huggingface-cli login` 進行驗證。"
)
def load_deepspotm(source="scgpt"):
try:
from deepspotm import DeepSpotM
except ImportError as exc:
raise RuntimeError(DEEPSPOTM_HELP) from exc
return DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source=source)
嵌入來源
source 選項選擇路由器從哪個冷凍基因嵌入建立投影。共有五個選項：
source | 基因嵌入 |
|---|---|
evo2 | 基因組序列 |
orthrus | RNA |
prott5 | 蛋白質序列 |
scgpt | 單細胞表現 |
apertus | 語言模型 |
每個嵌入提供不同的基因身份視角。每次執行選擇一個，並在選擇對分析重要時，使用多個來源對相同圖塊執行。請參閱 references/api.md 了解完整的呼叫介面、批次處理、設備放置、基因符號處理和輸出單位。
全切片工作流程
預測是按圖塊進行的，因此切片規模的執行是先切割圖塊，再進行批次推理：
- 使用
histolab技能在網格上提取 224x224 圖塊，並記錄每個圖塊的座標。 - 使用
torch.stack處理並將圖塊堆疊成批次。 - 對每個批次使用相同的基因列表呼叫
predict_genes。 - 將批次串聯成一個圖塊×基因的矩陣，並附加座標。
該矩陣即為該切片的虛擬空間轉錄組學地圖，可直接匯入 AnnData 進行後續空間分析。references/whole_slide.md 中提供了完整的迴圈、批次大小設定和 AnnData 組裝步驟。
常見使用案例
- 腫瘤切片標記基因的空間表現地圖。
- 對無匹配檢測的切片隊列進行全轉錄組預測。
- 按符號查詢約 19,000 個基因面板中的任何基因，包括訓練中未見過的基因——遠超過典型空間檢測面板的數百個基因。
- 為僅基於型態學的組織學管線添加表現通道。
- 建立切片層級的隊列圖譜，如 TCGA 所做。
詳細參考資料
references/api.md：from_pretrained和predict_genes的完整說明、五種嵌入來源及其選擇方式、批次處理、設備放置、基因符號處理，以及轉換 log1p-CPM 輸出。references/whole_slide.md：使用 histolab 進行圖塊切割、切片規模的預測迴圈、組裝和儲存圖塊×基因矩陣，以及隊列規模的執行。
主要來源
- 論文：https://doi.org/10.64898/2026.06.19.26356060（medRxiv，發布於 2026 年 6 月 22 日）
- 程式碼：https://github.com/ratschlab/DeepSpotM
- 權重：https://huggingface.co/ratschlab/DeepSpotM
- PyPI：https://pypi.org/project/deepspotm/