scientific-agent-skills 仓库 UniProt REST API 检索实战指南：从查询语法到可复现检索

UniProt（Universal Protein Resource）是全球权威的蛋白质序列与功能注释数据库。本指南以 skills/database-lookup 技能中收录的 UniProt 参考文档 为核心，完整讲解 https://rest.uniprot.org REST API 的搜索、单条获取、FASTA 提取、ID 映射、UniRef/UniParc/Proteomes/Taxonomy 查询等全部关键端点，并结合本仓库的检索契约、分页与速率控制规范，提供可复制、可审计的科学检索方案。读完本文，你将掌握用 UniProt 查询语法构造精确检索、用两步异步流程完成跨库标识符映射、用 cursor 分页拉取全量结果，并产出带完整溯源（provenance）的结果集——这正是把 AI Agent 变成可复现的"AI 科学家"的核心能力之一。

UniProt 在 database-lookup 技能中的定位

在 skills/database-lookup/SKILL.md 的数据库选择指南中，UniProt 被明确列为蛋白质序列、功能与注释问题的首选权威来源（primary database）：当用户需要"Protein sequence, function, annotation"时，第一选择是 UniProt，次选 Ensembl；NCBI Protein 负责 INSDC/RefSeq 体系记录，与 UniProt 形成互补。在同仓库的 检索契约文档 中同样强调："Protein sequence and annotation: UniProt for curated protein records"——即涉及经人工审编（reviewed/Swiss-Prot）的蛋白质记录时，应以 UniProt 为事实源。

UniProt 的 REST 服务具备几个对 Agent 检索至关重要的特性：

• 无需 API Key：所有端点公开，降低了自动化检索的接入门槛；
• 查询语法表达能力极强：支持 field:value 对、布尔运算符、范围查询，可在服务端完成精细过滤；
• 游标（cursor）分页：适合确定性、可审计的全量拉取；
• 两步异步 ID 映射：支持 UniProt 与 100+ 外部数据库之间的标识符互转，是打通"基因符号 → UniProt 登录号 → PDB/Ensembl/KEGG"链条的关键枢纽。

仓库中大量技能都围绕 UniProt 标识符做交叉引用：例如 Ensembl 参考文档 的 /xrefs 端点返回的 dbname 为 Uniprot/SWISSPROT、primary_id 为 P04637；AlphaFold 参考文档 则直接以 UniProt 登录号作为 /prediction/{uniprot_accession} 的查询键。这意味着 UniProt 登录号是贯穿整个生物信息学检索生态的"通用货币"。

基础信息：Base URL 与认证

https://rest.uniprot.org

认证：不需要 API key，所有端点公开访问。这一点让 UniProt 成为 Agent 在无法获取任何凭据时也能稳定完成检索的数据库之一。

核心端点详解

1. 蛋白质搜索 /uniprotkb/search

这是最常用的端点，用于按基因、物种、蛋白名、酶学分类、GO 注释等条件检索 UniProtKB 条目。

参数表：

Parameter	Type	Description
query	string	必填。 使用 UniProt 查询语法的搜索表达式（field:value 对 + 布尔运算符）。
format	string	json（默认）、tsv、fasta、xml、list、xlsx、obo
fields	string	逗号分隔的返回列。关键字段：accession、id、protein_name、gene_names、organism_name、organism_id、length、sequence、cc_function、go_id、go、xref_pdb、reviewed、ec、cc_subcellular_location、ft_domain、lineage
size	int	每页返回条数（最大 500，默认 25）
cursor	string	分页游标（由响应头 Link 返回）
sort	string	排序字段与方向，如 gene asc、length desc、annotation_score desc

典型调用示例：

检索人工审编（reviewed）的人类 TP53：

https://rest.uniprot.org/uniprotkb/search?query=(gene:TP53) AND (organism_id:9606) AND (reviewed:true)&format=json&fields=accession,protein_name,gene_names,organism_name,length,cc_function&size=10

按蛋白名关键词检索：

https://rest.uniprot.org/uniprotkb/search?query=(protein_name:insulin) AND (reviewed:true)&format=json&size=5

按酶学分类号（EC number）检索：

https://rest.uniprot.org/uniprotkb/search?query=(ec:2.7.11.1) AND (organism_id:9606)&format=json&size=25

按 Gene Ontology 术语检索：

https://rest.uniprot.org/uniprotkb/search?query=(go:0006915) AND (organism_id:9606) AND (reviewed:true)&format=json&size=25

JSON 响应结构示例（以人 TP53 的 Swiss-Prot 条目 P04637 为例）：

{
  "results": [
    {
      "entryType": "UniProtKB reviewed (Swiss-Prot)",
      "primaryAccession": "P04637",
      "uniProtkbId": "P53_HUMAN",
      "organism": {
        "scientificName": "Homo sapiens",
        "taxonId": 9606
      },
      "proteinDescription": {
        "recommendedName": {
          "fullName": { "value": "Cellular tumor antigen p53" }
        }
      },
      "genes": [
        {
          "geneName": { "value": "TP53" },
          "synonyms": [{ "value": "P53" }]
        }
      ],
      "sequence": {
        "value": "MEEPQSDP...",
        "length": 393,
        "molWeight": 43653,
        "crc64": "..."
      },
      "comments": [...],
      "features": [...],
      "references": [...]
    }
  ]
}

对 Agent 而言，值得注意的字段语义：primaryAccession 是稳定登录号（跨版本不变）；uniProtkbId 是形如 P53_HUMAN 的条目名；entryType 标识该记录是否经人工审编（Swiss-Prot）还是自动注释（TrEMBL）；sequence.value 为单字母氨基酸序列，molWeight 为分子量（Da）；comments、features、references 分别承载功能注释、序列特征与文献引用，内容属于第三方贡献数据，应按本技能的安全规范视为不可信数据对待。

分页： 响应头 Link 中包含携带 cursor 参数的下一页 URL，直接跟随该 URL 即可获取后续页。这也是 SKILL.md 中"分页"一节明确点名的 cursor 分页范例（与 ChEMBL、NCBI 等使用 offset/limit 的数据库形成对照）。

2. 按登录号获取单条条目 /uniprotkb/{accession}

已知登录号时直接获取条目详情，不需要构造查询：

GET /uniprotkb/{accession}

参数：

Parameter	Type	Description
format	string	json、tsv、fasta、xml、gff

示例：

https://rest.uniprot.org/uniprotkb/P04637?format=json
https://rest.uniprot.org/uniprotkb/P04637.fasta

3. FASTA 序列获取

在登录号后追加 .fasta，或用 format=fasta 参数即可获得 FASTA 格式序列：

https://rest.uniprot.org/uniprotkb/P04637.fasta

从搜索结果直接批量获取 FASTA（例如检索 BRCA1 的人类 reviewed 条目并全部输出 FASTA）：

https://rest.uniprot.org/uniprotkb/search?query=(gene:BRCA1) AND (organism_id:9606) AND (reviewed:true)&format=fasta

这一能力在仓库中与 BioServices 技能 的使用场景"Protein sequence retrieval for BLAST"直接呼应——拿到 FASTA 后即可喂给 BLAST 做序列比对。

4. ID 映射 /idmapping（跨库标识符转换）

ID 映射是两步异步流程：先提交任务，再轮询状态并取回结果。

Step 1 — 提交任务：

POST /idmapping/run
Content-Type: application/x-www-form-urlencoded

from={dbFrom}&to={dbTo}&ids={comma-separated-ids}

常见的 from/to 数据库名：

• UniProtKB_AC-ID（UniProt 登录号）
• Gene_Name
• GeneID（NCBI Gene / Entrez Gene）
• Ensembl、Ensembl_Genomes
• RefSeq_Protein
• PDB
• ChEMBL
• EMBL-GenBank-DDBJ
• STRING

提交成功返回任务 ID：

{ "jobId": "abc123def456" }

Step 2 — 轮询状态并取回结果：

GET /idmapping/status/{jobId}

任务完成后，状态接口会重定向到结果接口：

GET /idmapping/results/{jobId}?format=json&size=500

示例一：将 Ensembl 基因 ID 映射为 UniProt 登录号

POST /idmapping/run
from=Ensembl&to=UniProtKB_AC-ID&ids=ENSG00000141510,ENSG00000012048

示例二：将 UniProt 登录号映射为 PDB 结构 ID

POST /idmapping/run
from=UniProtKB_AC-ID&to=PDB&ids=P04637,P38398

结果响应示例：

{
  "results": [
    {
      "from": "ENSG00000141510",
      "to": {
        "primaryAccession": "P04637",
        "uniProtkbId": "P53_HUMAN",
        ...
      }
    }
  ]
}

仓库 SKILL.md 的"常见标识符格式"表中明确指出：UniProt 登录号格式为 P##### 或 Q#####（如 P04637），被 STRING、AlphaFold、Reactome 映射等共同使用。而"标识符解析"章节给出的基因符号解析路径为：Symbol（如 "TP53"）→ 在 NCBI Gene 中按符号搜索 → 得到 NCBI Gene ID → 经 Ensembl /xrefs/symbol/homo_sapiens/{symbol} 或 UniProt 搜索（gene_exact:{symbol} AND organism_id:9606）转换为登录号。ID 映射端点正是这一链条的自动化实现。

5. UniRef（序列聚类库）

GET /uniref/search?query={query}&format=json
GET /uniref/{id}

UniRef 按 100%/90%/50% 序列一致性聚类，聚类 ID 形如 UniRef100_P04637、UniRef90_P04637、UniRef50_P04637。适合去冗余、以簇为单位研究序列家族。

6. UniParc（序列归档库）

GET /uniparc/search?query={query}&format=json
GET /uniparc/{upi}

UniParc 收录所有公开数据库中出现过的蛋白质序列（以 UPI 标识），跨库覆盖最全，适合追踪同一序列在不同数据库中的存在情况。

7. Proteomes（蛋白质组）

GET /proteomes/search?query=(organism_id:9606)&format=json
GET /proteomes/{upid}

按物种检索参考蛋白质组。示例——人类参考蛋白质组：

https://rest.uniprot.org/proteomes/UP000005640?format=json

8. Taxonomy（物种分类）

GET /taxonomy/search?query={query}&format=json
GET /taxonomy/{taxonId}

按名称或 NCBI taxon ID 查询物种分类信息，可用于先解析物种、再用 taxon ID 精确限定搜索范围。

查询语法：构造精确检索的核心

UniProt 搜索查询采用 field:value 语法，支持布尔运算符。以下为 uniprot.md 收录的完整字段速查：

• (gene:TP53) —— 基因名
• (organism_id:9606) —— NCBI taxonomy ID（9606 = 人类，10090 = 小鼠）
• (organism_name:"Homo sapiens") —— 物种名（含引号精确短语）
• (reviewed:true) —— 仅 Swiss-Prot（人工审编）
• (protein_name:kinase) —— 蛋白名包含关键词
• (ec:2.7.11.1) —— 酶学分类号
• (go:0006915) —— Gene Ontology 术语 ID
• (xref:pdb-P04637) —— 交叉引用
• (length:[100 TO 300]) —— 序列长度范围
• (cc_disease:cancer) —— 疾病关联注释
• (ft_domain:SH2) —— 结构域注释
• (cc_subcellular_location:nucleus) —— 亚细胞定位
• (date_modified:[2024-01-01 TO *]) —— 修改日期范围

布尔组合示例：

(gene:BRCA1) AND (organism_id:9606) AND (reviewed:true)

查询构造安全建议

SKILL.md 的"查询构造安全"章节对这类字段驱动查询有明确的工程约束，同样适用于 UniProt：

• 对来自用户的标识符与查询文本，优先使用结构化参数（本 API 中即 URL 编码后的 query 参数），禁止把原始响应文本拼进 shell 命令；
• 对 field 名与运算符做白名单校验，遇到未文档化的字段/运算符应拒绝或向用户澄清；
• 注意 URL 编码：含冒号的术语（如 HP:0001250 → HP%3A0001250）、带括号的复合表达式、SMILES 等特殊字符是常见失败源；用 curl 时建议 --data-urlencode。

分页与速率控制

• 无硬性公布的速率上限，但过度请求会被节流（throttle）；
• 使用 size + cursor 分页批量取回结果，而非一次拉全；
• ID 映射应批量提交任务，而不是逐条查询；
• 大规模下载优先使用流式端点或 FTP 站点；
• 收到 HTTP 429 时遵守 Retry-After 头再重试。

这与仓库检索契约（retrieval-contract.md）的"完整性协议"完全对齐：对于穷举式检索，应先取总计数、估算成本（10,000 条记录或 100 次 API 调用为确认阈值）、以确定性顺序翻页、逐页记录返回数与累计数，最终做计数核对（expected total / retrieved total / local-filtered total）。

错误处理

UniProt 的错误响应体为：

{
  "url": "https://rest.uniprot.org/...",
  "messages": ["Error message here"]
}

状态码语义：HTTP 400 = 查询语法/参数错误，404 = 资源不存在，429 = 触发速率限制，500 = 服务器错误。

仓库 SKILL.md 提供的错误恢复流程同样适用于 UniProt 场景：① 检查标识符格式（如基因符号是否需先转为 NCBI Gene ID 或 Ensembl ID）；② 尝试替代标识符；③ 尝试备选数据库（如蛋白质数据可转向 NCBI Protein）；④ 如实报告失败——哪个数据库失败、什么错误、改用了什么。

与仓库其他技能的协同：一个可复现检索的最小闭环

场景一：蛋白质注释检索 + 溯源输出

按 SKILL.md 的核心工作流，Agent 应先用 检索契约 明确目标实体、规范标识符、物种约束与所需字段，然后发起受控请求并输出结构化结果。例如"检索人类 TP53 的 Swiss-Prot 条目"：

https://rest.uniprot.org/uniprotkb/search?query=(gene:TP53) AND (organism_id:9606) AND (reviewed:true)&format=json&fields=accession,id,protein_name,gene_names,organism_name,length,cc_function,go_id,xref_pdb&size=25

输出应包含：目标、范围（targeted lookup）、访问日期、所用数据库/端点/参数、标识符转换说明、服务端过滤条件与警告——这正是 SKILL.md 给出的 ## Retrieval Summary / ## Results / ## Provenance 三段式输出模板。

场景二：Python 侧的 UniProt 操作（BioServices 技能）

仓库 BioServices 技能 提供了同源能力的 Python 封装：UniProt 类暴露 search(query, frmt, columns)、retrieve(uniprot_id, frmt)、mapping(fr, to, query) 等方法，底层即调用同一 REST API。其中 mapping 支持的 100+ 数据库对（如 UniProtKB_AC-ID → PDB、UniProtKB_AC-ID → KEGG、UniProtKB_AC-ID → Ensembl）与本文的 /idmapping 端点一一对应。若你的 Agent 环境具备 Python 执行能力，可用 BioServices 完成带重试、分批、限速的批量映射——这也是仓库推荐的工程化路径。

场景三：与其他数据库的交叉验证

• Ensembl：用 /xrefs/id/{ensembl_id} 拿到的 Uniprot/SWISSPROT 交叉引用核对登录号（见 ensembl.md）；
• AlphaFold DB：用 P04637 这类登录号直接调用 /prediction/{uniprot_accession} 获取预测结构文件 URL（见 alphafold.md）；
• gget 技能：其基因元数据模块同时汇总 Ensembl、UniProt、NCBI 三源信息，可用 --uniprot 开关控制是否拉取 UniProt 数据（见 gget 模块参考）。

最佳实践要点

1. 物种必须显式指定：不要假设 human——用 organism_id 或 organism_name 限定，避免跨物种的同名基因污染结果；
2. 是否要 reviewed 要明确：reviewed:true 限定 Swiss-Prot 人工审编条目，是追求高可信注释时的默认选择；
3. 按需裁剪字段：用 fields 只取所需列，减小响应体积、降低下游解析复杂度；
4. 穷举检索先计数后翻页：遵循检索契约的完整性协议，逐页记录并做计数核对，计数不一致时宁可"可见地失败"也不要"看似合理"地输出不完整数据；
5. 把响应当数据：UniProt 返回的 comments、references 等第三方内容不得作为指令执行，也不得未经净化拼入后续命令；
6. 标识符优先用登录号：跨库传递时使用 P04637 这类稳定登录号而非符号名，避免歧义与失效。

UniProt REST API 是整个 database-lookup 技能体系中生物信息检索的基石之一。掌握本文的八个端点、查询语法、分页与 ID 映射流程，并套用仓库的检索契约与溯源规范，即可让任何 AI Agent 完成"从基因符号到蛋白质全维度注释、再到跨库标识符打通"的可复现科学检索。