Genomic Intelligence — DNA 서열 모델
Genomic Intelligence(GI)는 관리형 GPU에서 6가지 서열 분석 작업을 수행하는 트랜스포머 DNA 언어 모델을 제공합니다. 유전자 심볼, 유전체 영역, 또는 DNA/FASTA 시퀀스를 입력하면 프로모터 영역, 스플라이스 부위, 인핸서 활동, 염색질 상태, 발현량(log TPM), de-novo 유전자 주석과 같은 구조화된 예측 결과를 반환합니다. 모든 작업은 로컬에서 실행되지 않습니다. 모델 가중치, 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) - 유전자/전사체 주석 de novo, 참조 게놈 불필요 (
annotation) - 영역 내 유전자를 찾고 각 유전자의 발현 예측 (복합 작업)
로컬 정렬, 변이 호출 또는 파일 I/O에는 적합하지 않습니다. 이러한 작업은 로컬 도구(BioPython, bcftools)를 사용하세요. GI는 서열로부터의 모델 추론을 위한 것입니다.
연구 및 개발 용도입니다. 임상 또는 진단 결정에는 사용하지 마십시오.
GI를 호출하는 두 가지 방법
호스티드 MCP 서버 (키 불필요; MCP 호스트에서 선호)
GI는 https://mcp.genomicintelligence.ai/mcp 에 MCP 서버(Streamable HTTP)를 호스팅합니다. 에이전트 호스트가 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); 정확히 9,198 bp가 아닌 경우 tss_index 필요 + 세포 유형 description |
annotation | 비동기 | 1,000–500,000 bp | 해당 없음 | de-novo 전사체; 제출 + 폴링; 200,000 bp 이상 동기는 413 sync_too_large |
권장 모드는 제약이 아닌 지침입니다. 모든 작업이 두 모드를 모두 허용합니다. 동기 200을 위해 Prefer를 생략하고, 202 + GET /v1/tasks/jobs/{job_id}를 위해 Prefer: respond-async를 보내세요. 유일하게 적용되는 제한은 작업별로 다릅니다. /v1/openapi.json이 POST에 x-sync-limit-bp를 게시하는 경우, 해당 길이 이상의 동기 요청은 413 sync_too_large입니다. — annotation은 200,000 bp, 복합 워크플로는 info.version 2026.09.10.1 기준 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)되어 있습니다. 알 수 없는 키는 무시되지 않고 type: "extra_forbidden"과 함께 하드 422 validation_failed입니다:
| 작업 | 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뿐만 아니라 6개 예측 작업 모두와 복합 작업에 선언된 헤더입니다. — 비동기 참조.
model을 생략하면 API가 작업의 기본 모델을 사용합니다. 이것이 권장되는 호출 방식입니다. 기본 모델 ID는 의도적으로 여기에 문서화되지 않았습니다. 기본값은 변경되고 중단된 ID는 하드 오류를 발생시키므로 절대 하드코딩하지 마세요. 모델을 고정하거나 비인간(초파리, 효모, 애기장대 모델이 여러 작업에 존재) 모델을 선택하려면 호출 시점에 GET /v1/tasks/{task}/models (REST) 또는 list_models (MCP)로 ID를 찾으세요 — 직접 생성하지 마세요. 전체 작업별 출력 형태는 references/tasks.md에 있습니다.
expression은 6개 중 가장 엄격합니다. 유일하게 스키마가 sequence 외에 options를 필수로 요구합니다. 세 가지 엄격한 규칙을 적용합니다. 모든 위반은 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이며, 유일한 유효한 값입니다. 따라서 전체 유전자좌(최대 500kb)를 제출하고 서버가 윈도우를 자르게 할 수 있습니다. 그러나 서버는 사용자를 위해 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
# 각 작업은 자체 게시된 작업이지만 URL 문자열은 변경되지 않습니다.
r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body)
# 422 validation_failed — 작업 최소 길이 미만 또는 500,000 bp 초과 시퀀스,
# 잘못된 tss_index, 누락된 options.description,
# 또는 알 수 없는 본문/options 키 (options는 폐쇄됨)
# 401 키 없음/잘못됨 · 404 알 수 없는 작업 · 413 본문 16 MiB 초과 · 429 속도 제한
r.raise_for_status()
return r.json() # {"data": {...}, "meta": {...}}
# 프로모터:
out = predict("promoter", seq, "TP53_region")
print(out["data"]["summary"])
# 표현식 — 미리 잘라낸 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"])
# 표현식 — 전체 유전자좌; 서버가 지정한 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"]) # 점수가 매겨진 윈도우 확인
비동기 (모든 작업; annotation에 권장)
Prefer: respond-async는 6개 예측 작업과 복합 작업 모두에 선언된 헤더 매개변수입니다. 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") # 키 없는 스모크 테스트
…
[번역을 위해 잘렸습니다]