genomic-intelligence

Genomic Intelligence — 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 在 https://mcp.genomicintelligence.ai/mcp 托管 MCP 服务（Streamable HTTP）。如果你的 Agent 主机支持 MCP，请优先使用此方式：它无需密钥即可调用受速率和并发限制的公共演示层；可选的 gi_ Bearer 密钥可以提高这些限制。它提供获取工具，返回序列句柄 （sequence_ref），以及接收该句柄的 predict_* 工具，因此大序列 不会占用上下文。请参阅下文的 MCP 工作流 和 references/mcp.md。

REST API（通用）

通过 requests 对 https://api.genomicintelligence.ai/v1 发起普通 HTTP 请求。REST 路径需要 GI_API_KEY（gi_ Bearer 密钥）。可在任何主机、脚本中使用，或在需要原始响应封装时使用。请参阅 REST 核心工作流。

访问与身份验证

1. 托管 MCP 演示无需密钥——无需任何设置即可试用。
2. REST /v1 API 需要密钥，通过 Authorization: Bearer <key> 发送。 请通过 [email protected] 申请。
3. 切勿将密钥硬编码。 从 GI_API_KEY 环境变量读取 （或通过 python-dotenv 从 .env 读取）。切勿提交密钥。

export GI_API_KEY="gi_yourkeyhere"     # optional for MCP; required for REST
export GI_BASE_URL="https://api.genomicintelligence.ai"   # override for staging

密钥按合作伙伴层级分配，并设有并发和每分钟调用次数上限。遇到 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	sync	300–500,000 bp	2,000 bp	滑动窗口启动子区域
splice	sync	100–500,000 bp	15,000 bp	供体／受体位点（长上下文 BigBird）；具有链特异性——请使用转录本方向
enhancer	sync	50–500,000 bp	249 bp	发育 + 管家基因评分（DeepSTARR，Drosophila）
chromatin	sync	200–500,000 bp	1,000 bp	数百个轨道（DeepSEA）
expression	sync	9,198–500,000 bp	n/a（trained_window_bp 为 9,198）	log(TPM+1)；除非长度恰好为 9,198 bp，否则需要 tss_index，还需要细胞类型 description
annotation	async	1,000–500,000 bp	n/a	从头转录本；提交 + 轮询；超过 200,000 bp 时，同步请求返回 413 sync_too_large

Recommended mode 是指导建议，不是限制——每个任务都接受这两种模式。省略 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 会导致请求失败，因此绝不要将其硬编码。若要固定模型，或选择非人类模型（多个任务都有 Drosophila、酵母和 Arabidopsis 模型），请在调用时通过 GET /v1/tasks/{task}/models（REST）或 list_models（MCP）查询 ID——切勿臆造 ID。各任务完整的输出格式见 references/tasks.md。

在六个任务中，expression 的限制最严格：只有它的 schema 要求除了 sequence 外还必须提供 options。它会强制执行三条硬性规则——任何违反都会导致 422；不会进行填充或截断；也没有退出选项、请求头或查询参数：

• 始终对一个以 TSS 为中心、长度恰好为 9,198 bp 的窗口进行评分 — sequence[tss_index-4599 : tss_index+4599]。端点接受的长度为 9,198–500,000 bp；任何短于 9,198 bp 的序列都会被直接拒绝。
• 除非序列长度恰好为 9,198 bp，否则必须提供 tss_index。 它是 TSS 在 去除空白字符后的序列中的 0 起始偏移，范围为 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 为必填项。

精确的 Ensembl 调用和表达窗口计算方法，请参阅 references/sequence-acquisition.md。

核心 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 是所有六个 predict 操作和复合操作中声明的标头参数。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 smoke test; name is required
fetch_ensembl_sequence(gene="TP53")       # gene symbol or Ensembl ID -> handle
fetch_region(region="chr11:5,225,000-5,235,000")   # coordinates -> handle
fetch_gene_for_expression(gene="HBB")     # TSS-centred 9,198 bp handle for expression

# 2. Predict against the handle:
predict_promoter(sequence_ref=<ref>)
predict_expression(sequence_ref=<ref>, description="K562 cells")
predict_splice(sequence_ref=<ref>)        # + predict_enhancer / predict_chromatin

# 3. Annotation on MCP is `find_genes` (there is no predict_annotation).
#    It takes a handle, not a region, and runs async internally:
find_genes(sequence_ref=<ref>)            # wait=True (default) returns the result
find_genes(sequence_ref=<ref>, wait=False)  # -> job_id; poll get_job(job_id)

# Discover models with list_models(task); reference context lives in the
# gi://models, gi://docs/tasks, and gi://account MCP resources.

组合工作流：查找基因并预测表达

要回答“这个区域有哪些基因？它们的表达情况如何？”，请使用以下组合工作流：

• MCP： find_genes_and_predict_expression(sequence_ref=..., description=...) — 接受的是句柄，而非区域（请先使用 fetch_region 获取句柄）； description 为必填项。该工具会在序列中查找基因，并为每个基因返回表达预测。
• REST： 一次调用即可 — POST /v1/workflows/find-genes-and-predict-expression， 请求体为 {sequence, options}，其中 sequence 长度为 1,000–500,000 bp， 且 options.description（细胞类型 / 检测）为必填项；缺少或为空的 描述会导致 422 validation_failed。该接口会对序列进行注释，以每个发现的基因的 TSS 为中心截取 9,198 bp 窗口（对于边缘基因，会用 N 填充至窗口长度的一半， 而不是将其丢弃），并为每个基因返回预测结果。 meta.task_specific_counts = {genes_found, genes_predicted, genes_skipped}， 其中 genes_predicted + genes_skipped == genes_found；每个基因的跳过原因位于 data.expression_predictions[].skip_reason。超过 50,000 bp（其 x-sync-limit-bp）时会强制 使用异步模式：超过此长度的同步请求会返回 413 sync_too_large，且 error.details = {sequence_length, threshold} — 请使用相同请求体并添加 Prefer: respond-async 重试。

错误

代码	error.code	含义	操作
400	bad_request	请求格式错误	检查请求正文结构
401 / 403	unauthorized / forbidden	缺少或无效的密钥（REST）	设置 GI_API_KEY；或使用无需密钥的 MCP 演示
404	not_found	未知任务（/v1/tasks/bogus/predict）或未知作业	检查任务名称——无法识别的任务会返回 404，而不是 422
413	payload_too_large	原始请求正文超过 16 MiB	拆分输入——这是正文大小上限，不是序列长度上限
413	sync_too_large	同步请求超过操作的 x-sync-limit-bp（annotation 为 200,000 bp，组合操作为 50,000 bp）	使用 Prefer: respond-async 重试
415	unsupported_format	不支持的 format 查询值	使用任务支持的格式；不会静默回退到 JSON
422	validation_failed	最常见的失败：序列低于任务下限或超过 500,000 bp、表达数据低于 9,198 bp、缺少或超出范围的 tss_index、缺少 options.description，或存在任何未知的正文或 options 键	阅读消息并修正正文
429	rate_limited / too_many_requests	速率或并发上限	降低请求频率（遵循 Retry-After）；联系 GI 提升套餐等级
5xx	internal_error / service_unavailable / model_loading / timeout	服务端错误	重试；如果问题持续，请联系支持人员

error.code 是一个包含 21 个值的封闭枚举（bad_request、unauthorized、 forbidden、not_found、conflict、job_expired、payload_too_large、 sync_too_large、unsupported_format、validation_failed、 too_many_requests、rate_limited、internal_error、timeout、 insufficient_memory、model_not_found、task_not_supported_by_model、 model_loading、service_unavailable、http_error、unknown）；对于未列出的值， 应将其视为通用失败，而不是解析错误。

应根据 code 分支处理，绝不要根据 details 或 loc。 details 根据同级的 code 确定；对于 validation_failed，它是架构中声明的 {errors: [{loc, msg, type}, …]} 对象。应仅将其用于展示——code 才是稳定的判别字段。

对于请求关联，每个响应都会设置 error.request_id 和 X-Request-Id 标头， 成功响应信封中则包含 meta.request_id。优先读取标头仍是安全的默认做法。 每个响应都包含 RateLimit-Limit、RateLimit-Remaining、 RateLimit-Reset、RateLimit-Policy；429 响应还会添加 Retry-After。

已根据 OpenAPI info.version 2026.08.20.7 验证。接口契约会变更， /v1/openapi.json 中的 info.version 会报告特定部署实际提供的版本：如果它 高于上述版本，请依据该文档重新核对本文中的数值；若两者不一致，以该文档为准。

参考文件

• references/tasks.md — 各任务的输出结构、模型注册表、异步注释契约。
• references/api-and-auth.md — REST 端点、{data, meta} 信封、身份验证、基础 URL 覆盖、套餐等级。
• references/mcp.md — 托管 MCP 工具列表、基于句柄的流程，以及 gi:// 资源。
• references/sequence-acquisition.md — Ensembl 获取请求和表达窗口（9,198 bp，以 TSS 为中心）的计算，包括 tss_index。

相关技能

• arboreto：使用可扩展算法（GRNBoost2、GENIE3）从基因表达数据推断基因调控网络（GRN）。
• tamarind：通过 Tamarind Bio 平台的 REST API 或 MCP 服务，访问一系列开源分子设计和结构生物学工具……