基因组智能 — DNA序列模型 是做什么的？
Genomic Intelligence (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托管了一个MCP服务器，地址为 https://mcp.genomicintelligence.ai/mcp（Streamable HTTP）。当您的代理主机支持MCP时，优先使用它：它对具有速率和并发限制的公共演示层无密钥工作，可选的 gi_ 承载密钥可提高这些限制。它公开了返回序列句柄 (sequence_ref) 的获取工具和接受该句柄的 predict_* 工具，因此大序列不会占用上下文。请参阅下面的 MCP工作流（基于句柄） 和 references/mcp.md。
REST API（通用）
使用 requests 通过普通HTTP与 https://api.genomicintelligence.ai/v1 通信。REST路径需要 GI_API_KEY（一个 gi_ 承载密钥）。在任何主机、脚本中或需要原始信封时使用它。请参阅 核心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 | n/a (trained_window_bp 9,198) | log(TPM+1)；需要 tss_index，除非恰好9,198 bp，外加细胞类型 description |
annotation | 异步 | 1,000–500,000 bp | n/a | 从头转录本；提交+轮询；超过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上限都是 422 validation_failed，位于 loc ["body","sequence"]；过长不是 413。所有长度都是在去除空白字符后测量的，因此可以逐字粘贴换行的FASTA主体（> 标头行仍会导致字母表检查失败）。
options 是类型化的并且是封闭的（additionalProperties: false）每个任务 — 未知键是硬性 422 validation_failed，类型为 "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 # expression only
# Each task is its own published operation, but the URL string is unchanged.
r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body)
# 422 validation_failed — sequence under the task floor OR over 500,000 bp,
# bad tss_index, missing options.description,
# or ANY unknown body/options key (options is closed)
# 401 no/bad key · 404 unknown task · 413 body over 16 MiB · 429 rate limit
r.raise_for_status()
return r.json() # {"data": {...}, "meta": {...}}
# Promoter:
out = predict("promoter", seq, "TP53_region")
print(out["data"]["summary"])
# Expression — a pre-cut 9,198 bp TSS-centred window (tss_index defaults to 4,599):
out = predict("expression", tss_window_9198bp, "HBB",
options={"description": "K562 cells"})
print(out["data"]["prediction"]["expression_log_tpm"])
# Expression — a whole locus; the server slices ±4,599 bp around the TSS you name.
# tss_index is 0-based into the whitespace-stripped sequence.
out = predict("expression", locus_seq, "HBB",
options={"description": "K562 cells"}, tss_index=tss_offset_in_locus)
print(out["meta"]["task_specific_counts"]["scored_window"]) # confirm the window scored
异步（任何任务；注释推荐）
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: # terminal: body is the final {data, meta}
break
j.raise_for_status() # 202 = still running (2xx, won't raise)
time.sleep(5) # ~20 s typical for ~20 kb
transcripts = j.json()["data"]["transcripts"]
MCP工作流（基于句柄）
在MCP主机上，先获取句柄，然后根据句柄进行预测 — 序列不进入上下文：
# 1. Acquire a sequence handle (each returns a sequence_ref):
load_demo_sequence(name="promoter_tp53") # keyless smo
…
[为翻译而截断]