基因體智能 — DNA 序列模型 是做什麼的？
基因體智能（GI）在託管 GPU 上運行 transformer DNA 語言模型，處理六種序列分析任務。提供基因符號、基因體區域或 DNA/FASTA 序列，它將回傳結構化預測結果 — 啟動子區域、剪接位點、增強子活性、染色質狀態、表現量（log TPM）以及從頭基因註解。無需在本機執行任何操作：不需要模型權重、GPU 或繁重的 Python 套件。它是針對託管、有版本管理的推理 API 的精簡客戶端。
官方文件： docs.genomicintelligence.ai ·
REST 合約位於 api.genomicintelligence.ai/v1/openapi.json ·
託管 MCP 伺服器位於 https://mcp.genomicintelligence.ai/mcp
何時使用此技能
當使用者擁有 DNA 且需要模型預測時，請使用 GI：
- 尋找啟動子 在基因體區域中 (
promoter) - 預測剪接 供體/受體位點 (
splice) - 評分增強子活性 — 發育型與看家型 (
enhancer) - 註解染色質狀態 跨越數百條追蹤 (
chromatin) - 預測表現量 以 log(TPM+1) 形式，從序列與細胞類型上下文得出 (
expression) - 從頭註解基因/轉錄本，無需參考基因組 (
annotation) - 找出區域中的基因並預測每個基因的表現量（複合）
不適用於本地比對、變異體識別或檔案 I/O — 請使用本地工具（BioPython，bcftools）處理這些作業。GI 是用於從序列進行模型推論。
研究與開發用途。不適用於臨床或診斷決策。
兩種呼叫 GI 的方式
託管 MCP 伺服器（無金鑰；在 MCP 主機上較佳）
GI 在 https://mcp.genomicintelligence.ai/mcp（Streamable HTTP）託管了一個 MCP 伺服器。當您的 Agent 主機支援 MCP 時，建議使用此方式：它在無金鑰的情況下，針對有速率和並發限制的公開試用層級運作，而選用的 gi_ bearer 金鑰可提高這些限制。它公開了獲取工具，可回傳序列控制代碼（sequence_ref）以及接收該控制代碼的 predict_* 工具，因此大型序列不會佔用上下文。請參閱下方的 MCP 工作流程 和 references/mcp.md。
REST API（通用）
使用 requests 透過 HTTP 與 https://api.genomicintelligence.ai/v1 通訊。REST 路徑需要 GI_API_KEY（一個 gi_ bearer 金鑰）。在任何主機上、腳本中，或當您需要原始封包時使用它。請參閱核心 REST 工作流程。
存取與驗證
- 託管 MCP 試用版本無需金鑰 — 不設定任何東西即可試用。
- REST
/v1API 需要金鑰，以Authorization: Bearer <key>的形式發送。 請透過 [email protected] 申請。 - 切勿將金鑰寫死在程式碼中。 從
GI_API_KEY環境變數讀取（或透過python-dotenv從.env讀取）。切勿提交金鑰。
export GI_API_KEY="gi_yourkeyhere" # MCP 選用；REST 必要
export GI_BASE_URL="https://api.genomicintelligence.ai" # 用於覆蓋測試環境
金鑰範圍限定於合作夥伴層級，具有並發和每分鐘限制。429 表示已達到限制 — 請退避並重試，或要求 GI 提高您的層級。
六項任務
每項任務都是其自身已發布的操作，具有自己的請求結構、自己的最小長度以及自己的封閉 options 物件 — POST /v1/tasks/promoter/predict、/v1/tasks/splice/predict、/v1/tasks/enhancer/predict、/v1/tasks/chromatin/predict、/v1/tasks/annotation/predict、/v1/tasks/expression/predict。每個路徑都是一個字面字串，因此無需建構任何東西，也沒有共享的 PredictRequest 結構。請求本體為 {sequence, sequence_name?, model?, options?}，回傳 {data, meta} 封包。各任務的差異如下：
| 任務 | 建議模式 | 接受長度 | context_window_bp | 備註 |
|---|---|---|---|---|
promoter | 同步 | 300–500,000 bp | 2,000 bp | 滑動視窗啟動子區域 |
splice | 同步 | 100–500,000 bp | 15,000 bp | 供體/受體位點（長上下文 BigBird）；限制鏈 — 提交轉錄本方向 |
enhancer | 同步 | 50–500,000 bp | 249 bp | 發育 + 看家評分（DeepSTARR，果蠅） |
chromatin | 同步 | 200–500,000 bp | 1,000 bp | 數百條追蹤（DeepSEA） |
expression | 同步 | 9,198–500,000 bp | 無 (trained_window_bp 9,198) | log(TPM+1)；需要 tss_index 除非剛好 9,198 bp，加上細胞類型 description |
annotation | 非同步 | 1,000–500,000 bp | 無 | 從頭轉錄本；提交 + 輪詢；高於 200,000 bp 的同步請求回傳 413 sync_too_large |
建議模式 是指導而非限制 — 每項任務皆接受兩種模式。省略 Prefer 以獲得同步 200；發送 Prefer: respond-async 以獲得 202 加上 GET /v1/tasks/jobs/{job_id}。唯一強制限制是按操作劃分：在 /v1/openapi.json 中，若 POST 上發布了 x-sync-limit-bp，則超過該長度的同步請求會回傳 413 sync_too_large — 截至 info.version 2026.09.10.1，annotation 為 200,000 bp，複合工作流程為 50,000 bp。請讀取該欄位，而非記住數字；其他預測任務目前沒有此限制。
最小值是准入控制，而非運作模式。 高於下限但短於所選模型 bio_spec.context_window_bp 的請求會被接受並評分 — 針對補齊至上下文視窗的視窗進行評分。Enhancer 是明顯案例：下限為 50 bp，但上下文視窗為 249 bp，因此 50–248 bp 主要根據補齊進行評分。請將您的長度與來自 GET /v1/tasks/{task}/models 的 context_window_bp 進行比較，以了解模型是否看到了真實序列。長於上下文的輸入沒問題 — 掃描器一次移動一個預測視窗，僅補齊最後一個部分視窗。
低於下限和高於 500,000 bp 上限的請求都會在 loc ["body","sequence"] 處回傳 422 validation_failed；過長不是 413。所有長度都是在移除空白字元後測量，因此可以逐字貼上換行的 FASTA 主體（> 標題行仍會導致字母檢查失敗）。
options 是類型化且封閉的（additionalProperties: false），按任務區分 — 未知金鑰會是硬性的 422 validation_failed，並帶有 type: "extra_forbidden"，絕不會被忽略：
| 任務 | options 金鑰 |
|---|---|
| promoter | threshold (0–1，預設 0.5) |
| splice | threshold (0–1，預設 0.5)，site_types (["donor","acceptor"] 的子集，預設兩者) |
| enhancer | (無) |
| chromatin | threshold (0–1，預設 0.5) |
| annotation | batch_size (1–128，預設 8)，shift_coordinates，reverse_complement (預設 true) |
| expression | description — 必要，且為唯一金鑰 |
Prefer: respond-async 是在所有六個預測操作以及複合操作上宣告的標頭，不僅限於 annotation — 請參閱非同步。
省略 model，API 會使用該任務的預設值 — 這是建議的呼叫方式。預設模型 ID 故意不在此處文件化：預設值會變更，且已退役的 ID 會硬性失敗，因此切勿硬編碼一個。若要固定一個模型，或選擇非人類的模型（果蠅、酵母和阿拉伯芥模型存在於多項任務中），請在呼叫時使用 GET /v1/tasks/{task}/models（REST）或 list_models（MCP）發現 ID — 並且切勿自行發明一個。每個任務的完整輸出格式請參閱 references/tasks.md。
expression 是六項任務中最嚴格的：單獨其中，其結構要求 options 以及 sequence。它強制執行三項硬性規則 — 每次違規都會回傳 422，不會補齊或限制，且沒有選擇退出標誌、標頭或查詢參數：
- 它總是對恰好一個 9,198 bp 的 TSS 中心視窗進行評分 —
sequence[tss_index-4599 : tss_index+4599]。端點本身接受 9,198–500,000 bp；低於 9,198 bp 的會被直接拒絕。 tss_index是必要的，除非序列剛好是 9,198 bp。 它是 移除空白字元後 序列中 0 為基礎的 TSS 偏移量，範圍限制為4599 ≤ tss_index ≤ len(sequence) − 4599。在剛好 9,198 bp 時，它預設為 4,599，這是唯一合法的值。因此您可以提交整個基因座（最多 500 kb）並讓伺服器切割視窗 — 但伺服器不會為您發現 TSS（這是複合工作流程的工作），也不會反向互補：請提交基因有意義鏈的序列。options.description— 一個細胞類型/檢測字串（例如"K562 cells"）— 是必要的，且是expression在options內接受的唯一金鑰。未知的頂層本體欄位也會被拒絕。
注意：合法的
tss_index範圍很廣，因此一個僅是錯誤的偏移量（在包括換行符的原始 FASTA 字元上計算，或相對於基因座起點而非提交的切片計算）不會引發錯誤 — 它會針對錯誤的視窗回傳一個確定的200。請斷言回應中的meta.task_specific_counts.scored_window/.tss_index。您提交的長度是meta.sequence_length（也在data.input.submitted_sequence_length中回顯）；評分的寬度始終是 9,198，即scored_window[1] - scored_window[0]。（data.input.sequence_length已在合約修訂版 13 中移除。）兩個
tss_index違規 — "除非剛好是 9,198 bp，否則為必要"和範圍檢查 — 都來自整個模型的驗證器，因此它們出現在本體層級而非tss_index之下。請比對error.code == "validation_failed"並僅將訊息用於顯示。此技能中引用的任何loc元組僅為該形狀的說明範例，並非合約的一部分：它未在結構中發布，且不應根據它進行分支。
序列獲取
您很少從原始的 9,198 bp 字串開始。請先獲取序列：
- 從基因符號 → MCP
fetch_ensembl_sequence(gene=...)；從座標 →fetch_region(region=...)。兩者都擷取公開的 Ensembl 參考序列（無需金鑰）。REST 使用者可以直接查詢 Ensembl REST。（find_genes是註解任務，而非獲取工具。） - 用於
expression→ 使用 TSS 中心擷取，使視窗恰好為 9,198 bp。MCP：fetch_gene_for_expression（處理居中）。否則擷取一個更寬的基因座並將 TSS 作為tss_index傳遞，以便伺服器切割視窗 — 但請在移除空白字元的核苷酸字串上計算該偏移量，而非在檔案字元上。 - 從本地 FASTA → MCP
store_inline_sequence，或自行讀取檔案以用於 REST。（load_local_fasta僅存在於本地部署中，不存在於託管伺服器上。） - 示範序列 → MCP
load_demo_sequence(name=...)回傳一個立即可用的控制代碼，用於無金鑰的整合測試；name是必要的。
請參閱 references/sequence-acquisition.md 以了解確切的 Ensembl 呼叫和表現量視窗數學。
核心 REST 工作流程
同步呼叫 — 所有任務的預設方式 — 一次預測即為一次呼叫：
import os, requests
BASE = os.environ.get("GI_BASE_URL", "https://api.genomicintelligence.ai")
HEADERS = {"Authorization": f"Bearer {os.environ['GI_API_KEY']}"}
def predict(task, sequence, sequence_name, model=None, options=None, tss_index=None):
body = {"sequence": sequence, "sequence_name": sequence_name}
if model: body["model"] = model
if options: body["options"] = options
if tss_index is not None: body["tss_index"] = tss_index # 僅表現量
# 每個任務都是其自身已發布的操作，但 URL 字串保持不變。
r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body)
# 422 validation_failed — 序列低於任務下限 OR 超過 500,000 bp，
# 錯誤的 tss_index，遺失 options.description，
# 或 ANY 未知的 body/options 金鑰 (options 是封閉的)
# 401 無金鑰/金鑰錯誤 · 404 未知任務 · 413 主體超過 16 MiB · 429 速率限制
r.raise_for_status()
return r.json() # {"data": {...}, "meta": {...}}
# Promoter:
out = predict("promoter", seq, "TP53_region")
print(out["data"]["summary"])
# Expression — 一個預先切割的 9,198 bp TSS 中心視窗 (tss_index 預設為 4,599):
out = predict("expression", tss_window_9198bp, "HBB",
options={"description": "K562 cells"})
print(out["data"]["prediction"]["expression_log_tpm"])
# Expression — 一個完整的基因座；伺服器圍繞您命名的 TSS 切片 ±4,599 bp。
# tss_index 是 0 為基礎的，進入移除空白字元的序列。
out = predict("expression", locus_seq, "HBB",
options={"description": "K562 cells"}, tss_index=tss_offset_in_locus)
print(out["meta"]["task_specific_counts"]["scored_window"]) # 確認評分的視窗
非同步（任何任務；建議用於註解）
Prefer: respond-async 是在所有六個預測操作和複合操作上宣告的標頭參數。202 攜帶與同步 200 相同的 {data, meta} 封包，並帶有 data = {job_id, status: "accepted", links}；任務 ID 也位於 Content-Location 和 X-Job-Id 回應標頭中。非同步僅限 JSON — 與文字 format 結合使用會被拒絕。annotation 是需要它的任務：
import time
r = requests.post(f"{BASE}/v1/tasks/annotation/predict",
headers={**HEADERS, "Prefer": "respond-async"},
json={"sequence": seq, "sequence_name": "TP53"})
r.raise_for_status() # 202 Accepted
job_id = r.json()["data"]["job_id"]
while True:
j = requests.get(f"{BASE}/v1/tasks/jobs/{job_id}", headers=HEADERS)
if j.status_code == 200: # 終端：主體為最終的 {data, meta}
break
j.raise_for_status() # 202 = 仍在執行中 (2xx，不會引發異常)
time.sleep(5) # 約 20 kb 約需 20 秒
轉錄本 = j.json()["data"]["transcripts"]
MCP 工作流程（基於控制代碼）
在 MCP 主機上，獲取一個控制代碼，然後對其進行預測 — 序列保持在上下文之外：
# 1. 獲取一個序列控制代碼 (每個都回傳一個 sequence_ref):
load_demo_sequence(name="promoter_tp53") # 無金鑰整合測試
…
[已為翻譯截斷]