使用 QuickGO 蛋白质功能注释 API：在 scientific-agent-skills 中实现可复现的 GO 检索

使用 QuickGO 蛋白质功能注释 API：在 scientific-agent-skills 中实现可复现的 GO 检索

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

导读

本文以 skills/database-lookup/references/quickgo.md 为骨架，系统讲解 EMBL-EBI QuickGO 注释浏览器的 REST API：从基础 URL、无需鉴权的访问方式、核心端点，到注释检索的参数语义、响应结构与公平使用限制。你将学会如何在 scientific-agent-skills 仓库的database-lookup技能框架下，用curl或 Python 完成 GO 术语查询、按基因/物种/证据代码过滤注释，并输出带完整溯源（provenance）的可审计检索结果。

QuickGO 是什么：GO 注释检索的首选入口

Gene Ontology（GO）是描述基因产物在**生物过程（biological_process）、分子功能（molecular_function）、细胞组分（cellular_component）**三个命名空间中的功能的标准词汇体系。而 QuickGO 是 EMBL-EBI 提供的 GO 注释浏览与检索服务，其 REST 服务地址为：

https://www.ebi.ac.uk/QuickGO/services/

在 database_selection_guide.md 的"Biology & Genomics"分组中，QuickGO 被明确列为"Gene function annotations (GO terms)" 类问题的主数据库，Gene Ontology 本体服务（api.geneontology.org）作为备选。选择 QuickGO 的理由在 gene-ontology.md 中有明确说明：QuickGO（EBI）在注释查询上更稳定、文档更完善，而 GO API 本体端点在部分场景下可能返回 403。因此，凡涉及"某基因/蛋白有哪些 GO 注释""某 GO 术语注释了哪些基因"这类查询，应优先走 QuickGO。

认证与访问前提

QuickGO 无需任何 API Key，全部端点公开可访问。这意味着它可以直接用curl或任意 HTTP GET 工具调用，不存在凭证管理负担。

不过要注意 SKILL.md 中关于 API 调用工具链的约定：Claude Code 可用WebFetch、Gemini CLI 用web_fetch、Cursor 与 Codex CLI 没有专用抓取工具时一律回退到curl。示例模板：

curl -s -H "Accept: application/json" "https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0008150"

核心端点一览

quickgo.md 给出了四个核心端点，结合 gene-ontology.md 可进一步扩充为完整的端点矩阵：

GO 术语详情：terms 端点

GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0008150

一次可携带最多 25 个逗号分隔的 GO ID，例如GO:0008150,GO:0006915。返回 JSON 中包含术语名称、定义、命名空间与同义词。

子术语与祖先术语

# 子术语 GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0008150/children # 祖先术语（图表视图，限定关系类型） GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0006915/ancestors?relations=is_a,part_of

关键词搜索

GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/search?query=apoptosis&limit=5

当用户只给出口语化描述（如"细胞凋亡相关过程"）而不知道确切 GO ID 时，先用该端点解析出规范 ID，再进入后续注释检索。

注释搜索参数全解

/annotation/search是 QuickGO 的核心检索端点。quickgo.md 与 gene-ontology.md 的参数合并后如下：

两个关键参数的语义值得展开：

• goUsage=descendants：表示"该 GO 术语及其全部后代术语的注释都算"，是实现包含子术语的功能富集类检索的标准做法。若不指定则默认为精确匹配该术语本身。
• evidenceCode：使用 ECO（Evidence and Conclusion Ontology）代码，而不是旧式 GO 证据码。ECO:0000269代表实验证据（对应传统 IDA/IMP/IGI 等实验类证据的合集）；常见传统证据码还包括 IEA（电子注释，可信度较低）等，检索时可通过该参数剔除或仅保留特定证据级别。

完整调用示例

quickgo.md 中给出的三个示例调用如下：

# 1. GO 术语详情 curl -s "https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0003723" # 2. 人类 RNA 结合（GO:0003723）注释，取前 10 条 curl -s "https://www.ebi.ac.uk/QuickGO/services/annotation/search?goId=GO:0003723&taxonId=9606&limit=10" # 3. 关键词搜索 curl -s "https://www.ebi.ac.uk/QuickGO/services/ontology/go/search?query=apoptosis&limit=5"

再补充 gene-ontology.md 中的进阶组合示例——按基因产物 + 后代术语 + 证据代码三重过滤：

curl -s "https://www.ebi.ac.uk/QuickGO/services/annotation/search?geneProductId=P04637&goUsage=descendants&evidenceCode=ECO:0000269&limit=25"

以及按 GO 术语 + 物种的组合：

curl -s "https://www.ebi.ac.uk/QuickGO/services/annotation/search?goId=GO:0006915&taxonId=9606&limit=25"

URL 编码注意事项

GO ID 形如GO:0008150，冒号在 URL 路径中通常可直接使用（QuickGO 支持），但在查询参数中建议按 SKILL.md 的通用约定编码为GO%3A0008150。使用curl时可用--data-urlencode或-G组合确保安全。其他标识符（SMILES、含括号的化合物名）同理。

响应格式与字段解读

QuickGO 返回 JSON。注释搜索端点的典型响应结构（见 gene-ontology.md）：

{ "numberOfHits": 1234, "results": [ { "geneProductId": "P04637", "symbol": "TP53", "goId": "GO:0006915", "goName": "apoptotic process", "evidenceCode": "ECO:0000269", "goAspect": "biological_process", "taxonId": 9606, "reference": "PMID:12345678", "assignedBy": "UniProt" } ] }

关键字段语义：

• numberOfHits：命中总数，是判断分页是否取完的核心依据（见下文"分页与完整性"）。
• goAspect：GO 命名空间，取值即前述三种 aspect。
• evidenceCode：ECO 证据代码，反映注释来源的实验支持强度。
• reference：支撑该注释的文献/数据库引用（如 PMID）。
• assignedBy：注释归属来源（如 UniProt），可用于溯源。

分页、计数与完整性协议

SKILL.md 与 retrieval-contract.md 对这类分页式 API 提出了明确的完整性协议，QuickGO 完全适用：

1. 先取数再翻页：QuickGO 是limit + page型分页（limit最大 100，page从 1 起），响应中的numberOfHits即总数。先用一个小limit请求拿到总数，估算需要的请求次数。
2. 循环直至计数吻合：累加每页返回条数，与numberOfHits比对；若中途停止或数量对不上，必须显式报告不一致，而不是给出看似合理的结果。
3. 设定工作上限：按技能约定，检索超过 10,000 条记录、100 次 API 调用或超出该 API 文档化的大批量使用指引时，必须先向用户确认检索计划。
4. 大批量走官方下载端点：quickgo.md 明确提示"EBI fair-use policy. Use download endpoint for large result sets"——当用户确实需要全量注释集时，应优先使用 EBI 官方 bulk/download 通道，而不是逐页爬取。

标识符体系：GO 术语、UniProt 与 NCBI 分类

SKILL.md 的 Common Identifier Formats 表为 QuickGO 涉及的三类标识符给出了规范格式：

在database-lookup技能工作流中，若用户只给基因符号（如 "TP53"），应先在NCBI Gene解析出 ID、在UniProt解析出登录号（gene_exact:TP53 AND organism_id:9606），再携带解析结果进入 QuickGO 的geneProductId参数。这正是技能第 2 步"选主库、用交叉库做标识符解析"的典型场景。

在 database-lookup 技能框架中的完整调用流程

结合 SKILL.md 的核心工作流，一次合格的 QuickGO 检索应遵循：

1. 定义检索契约（retrieval-contract.md）：明确目标实体（基因/蛋白/GO 术语）、规范标识符、物种约束、证据类型过滤、需要穷尽还是定向查询。缺少物种约束时（如"TP53 的注释"未说明人/鼠）应提问而非猜测。
2. 选库：QuickGO 作为 GO 注释主库。
3. 阅读参考文件：调用前先读 quickgo.md 与 retrieval-contract.md。
4. 规划过滤语义：区分服务端过滤（goId、taxonId、evidenceCode、aspect等 QuickGO 直接支持的参数）与本地过滤（如"只保留最新 GO 版本中仍有效的注释"这类 API 无法表达的条件）。
5. 有界调用：先取numberOfHits，估算成本后分页。
6. 把外部响应当不可信数据：QuickGO 返回的注释文本、文献引用是第三方内容，不得把响应原文拼进 shell 命令或当作指令执行；只抽取所需字段。
7. 输出可审计结果：按技能规定的模板给出检索摘要、结果、溯源（端点、参数、标识符转换、计数对账、本地过滤、警告）。

推荐的curl落地调用（带分页与计数对账）：

# 第 1 步：取总数与第一页 curl -s -H "Accept: application/json" \ "https://www.ebi.ac.uk/QuickGO/services/annotation/search?goId=GO:0006915&taxonId=9606&limit=100&page=1" # 第 2 步：按 numberOfHits 循环翻页，page 递增，直至累计 == numberOfHits curl -s -H "Accept: application/json" \ "https://www.ebi.ac.uk/QuickGO/services/annotation/search?goId=GO:0006915&taxonId=9606&limit=100&page=2"

用 Python 访问：bioservices 封装的 QuickGO 客户端

仓库中另一个技能 skills/bioservices/references/services_reference.md 提供了 QuickGO 的 Python 编程入口，适合将 GO 注释检索嵌入本地分析流程：

from bioservices import QuickGO g = QuickGO() # 获取 GO 术语信息（返回 OBO 格式的术语定义与元数据） g.Term("GO:0008150", frmt="obo") # 按蛋白或 GO ID 获取注释（TSV 格式） g.Annotation(protein="P04637", goid=None, format="tsv")

该方法面覆盖三个 GO 命名空间（BP/MF/CC），典型应用场景是功能注释（functional annotation）与富集分析（enrichment analysis）。这印证了 QuickGO 在仓库生态中既是database-lookup技能记录的 REST 数据源，也被bioservices技能作为 Python 库级客户端纳入。

速率限制与负责任使用

quickgo.md 对速率限制的描述是：遵循 EBI 公平使用政策（fair-use policy），大批量结果请使用 download 端点。gene-ontology.md 补充说明 QuickGO 未公布硬性限流，但建议合理使用。

实操层面的建议：批量注释检索时控制并发与翻页频率；遇到 HTTP 429/503 时短暂等待后重试一次（SKILL.md 通用约定）；需要全量 GO 注释集（如构建基准数据集）时，转向 EBI 官方批量下载通道，避免对服务造成压力。同时注意 SKILL.md 的并发约定：跨不同数据库的独立请求最多同时保持 5 个在途，对 QuickGO 这类公共服务更应保守。

常见错误排查

当 QuickGO 调用无结果或报错时，按 SKILL.md 的错误恢复流程排查：

1. 检查标识符格式：GO ID 是否为GO:#######七位数字规范格式；蛋白是否用 UniProt 登录号（P04637）而非基因符号（TP53）；物种是否用 NCBI 整数 taxon ID（9606）而非名称。
2. 检查 URL 编码：查询参数中的冒号（GO%3A0008150）与特殊字符是否已正确编码。
3. 检查过滤语义：goUsage=descendants会显著扩大结果集；aspect若与目标 GO 术语的命名空间不符会得到空集。
4. 更换数据库：本体结构遍历类需求（祖先/子图）可改用 gene-ontology.md 中的 GO API/api/ontology/term/{go_id}/graph端点。
5. 显式报告失败：告知用户哪个端点失败、错误内容、已尝试的替代方案。

延伸阅读

• skills/database-lookup/references/quickgo.md — 本文主文档，QuickGO 端点速查
• skills/database-lookup/references/gene-ontology.md — GO 本体 API 与 QuickGO 补充参数、响应样例
• skills/database-lookup/references/database_selection_guide.md — 含"GO 功能注释查询首选 QuickGO"的选库依据
• skills/database-lookup/references/retrieval-contract.md — 检索契约与审计清单
• skills/database-lookup/SKILL.md — 78 个公开数据库的统一检索工作流、分页与溯源约定
• skills/bioservices/references/services_reference.md — 用 Pythonbioservices.QuickGO访问 GO 注释

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills