RCSB Protein Data Bank API 实战指南：在 scientific-agent-skills 中完成可复现的蛋白质结构检索

RCSB Protein Data Bank API 实战指南：在 scientific-agent-skills 中完成可复现的蛋白质结构检索

【免费下载链接】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

导读

本文以 scientific-agent-skills 仓库中database-lookup技能集为背景，系统讲解 RCSB Protein Data Bank（PDB）公开 API 的完整用法。你将掌握：如何用 Data API 查询条目、聚合物实体与组装体元数据，如何用 Search API 的 JSON 查询 DSL 做全文、序列与结构相似性检索，如何下载 PDB/mmCIF 结构文件，以及如何通过 GraphQL 精简字段查询。同时结合本仓库的检索契约与溯源规范，学会把每一次结构检索变成可审计、可复现的科学结论。

PDB 在本仓库中的定位

在 database-lookup 技能中，PDB 是"实验测定的三维蛋白质结构"的首选权威数据源。该技能目录的 数据库选择指南 明确给出了检索决策路径：

也就是说：当用户要的是实验解析的结构时，RCSB PDB 是第一选择；当需要预测结构时，才转向 AlphaFold DB 参考（AlphaFold DB 的比对结果也会回链到 PDB 条目）。在开始任何 API 调用前，技能要求先读取对应参考文件——即本仓库中的 pdb.md，它是本篇指南的核心依据。

Base URL 总览

PDB 提供四类互补的接口，参考文档 pdb.md 给出的基础地址如下：

认证与限速

• 认证：完全公开，无需任何 API Key。这也是本仓库database-lookup技能中"无需密钥即可匿名访问"类数据库的典型代表，与 SKILL.md 中 FRED、NCBI、OpenFDA 等需要免费注册密钥的数据库形成对比。
• 限速：官方没有公布硬性限制，但参考文档明确要求保持礼貌的访问频率（大约每秒几个请求）。大规模批量获取时应改用 FTP 方式下载全库数据，而不是逐条循环调用 REST 接口。

一、Data API：按 ID 查元数据

Data API 的路径模式统一为{服务}/{对象类型}/{对象ID}，三个核心端点如下。

1. 条目查询（Entry Lookup）

GET https://data.rcsb.org/rest/v1/core/entry/{entry_id}

示例（血红蛋白，PDB 条目4HHB）：

GET https://data.rcsb.org/rest/v1/core/entry/4HHB

返回的 JSON 中包含分辨率、实验方法、沉积日期、标题、作者等核心元数据。用curl获取的完整命令：

curl -s -H "Accept: application/json" \ "https://data.rcsb.org/rest/v1/core/entry/4HHB"

2. 聚合物实体查询（chain 级信息）

同一个条目里往往有多个链/分子（如血红蛋白的 α 链和 β 链），需要进一步按实体查询：

GET https://data.rcsb.org/rest/v1/core/polymer_entity/{entry_id}/{entity_id}

示例：

GET https://data.rcsb.org/rest/v1/core/polymer_entity/4HHB/1

这里entity_id是该条目的实体编号，返回该实体的序列、名称、来源生物体等链级信息。

3. 组装体信息

生物体内的功能状态常常是多个实体组装形成的复合体：

GET https://data.rcsb.org/rest/v1/core/assembly/{entry_id}/{assembly_id}

示例：

GET https://data.rcsb.org/rest/v1/core/assembly/4HHB/1

该端点返回组装体的组成、对称性、聚合状态等生物学组装信息。

二、Search API：JSON 查询 DSL

Search API 使用 HTTP POST + JSON 请求体，端点为：

POST https://search.rcsb.org/rcsbsearch/v2/query Content-Type: application/json

注意：因为必须用 POST，本仓库 SKILL.md 的"POST-Only APIs"实践提示适用于此——若你的 Agent 平台的 WebFetch 工具只支持 GET，需要用curl等 shell 工具发起请求。

4. 全文与属性检索（Text Search）

支持按任意结构化属性做精确匹配。下面这个例子按 UniProt 登录号（accession）查找对应条目：

{ "query": { "type": "terminal", "service": "text", "parameters": { "attribute": "rcsb_polymer_entity_container_identifiers.reference_sequence_identifiers.database_accession", "operator": "exact_match", "value": "P69905" } }, "return_type": "entry" }

P69905是血红蛋白 α 链的 UniProt 登录号。对应的curl命令：

curl -s -X POST -H "Content-Type: application/json" \ -d '{"query":{"type":"terminal","service":"text","parameters":{"attribute":"rcsb_polymer_entity_container_identifiers.reference_sequence_identifiers.database_accession","operator":"exact_match","value":"P69905"}},"return_type":"entry"}' \ "https://search.rcsb.org/rcsbsearch/v2/query"

5. 序列检索（Sequence Search）

输入一段氨基酸序列，Search API 会做序列比对：

{ "query": { "type": "terminal", "service": "sequence", "parameters": { "evalue_cutoff": 0.1, "identity_cutoff": 0.9, "sequence_type": "protein", "value": "MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH" } }, "return_type": "polymer_entity" }

参数语义：

• evalue_cutoff：E 值阈值（这里为 0.1），控制比对的显著性门槛；
• identity_cutoff：序列一致度阈值（0.9 表示要求 90% 以上一致）；
• sequence_type：序列类型，蛋白质用protein；
• value：目标氨基酸序列；
• return_type：返回实体级结果，因此返回的 ID 形如4HHB_1。

6. 结构相似性检索（Structure Similarity Search）

以已有结构为模板，检索形状匹配的结构：

{ "query": { "type": "terminal", "service": "structure", "parameters": { "value": {"entry_id": "4HHB", "assembly_id": "1"}, "operator": "strict_shape_match" } }, "return_type": "assembly" }

这里的operator使用strict_shape_match（严格形状匹配），查询对象通过entry_id+assembly_id指定，返回结果为组装体级。

三、下载结构文件

结构坐标文件通过文件服务获取：

GET https://files.rcsb.org/download/{entry_id}.cif GET https://files.rcsb.org/download/{entry_id}.pdb

curl示例：

# 下载 mmCIF 格式（现代推荐，包含更完整注释） curl -s -o 4HHB.cif "https://files.rcsb.org/download/4HHB.cif" # 下载经典 PDB 格式 curl -s -o 4HHB.pdb "https://files.rcsb.org/download/4HHB.pdb"

响应格式上，所有 REST/Search 端点返回 JSON，而文件下载返回 PDB / mmCIF 纯文本。

四、GraphQL：按需取字段

当只需要少量字段时，GraphQL 比 REST 更节省流量：

POST https://data.rcsb.org/graphql

请求体示例——同时取分辨率和结构标题：

{ "query": "{ entry(entry_id: \"4HHB\") { rcsb_entry_info { resolution_combined } struct { title } } }" }

curl执行：

curl -s -X POST -H "Content-Type: application/json" \ -d '{"query":"{ entry(entry_id: \"4HHB\") { rcsb_entry_info { resolution_combined } struct { title } } }"}' \ "https://data.rcsb.org/graphql"

GraphQL 的entry(entry_id: ...)查询字段与 Data API 的对象模型一一对应，熟悉 REST 端点后可自然迁移。

五、return_type取值与检索粒度

Search API 中return_type决定结果 ID 的粒度，参考文档给出三档：

选择原则：目标分析只关心整个结构就选entry；要做链级序列或残基分析就选polymer_entity；研究复合体组装状态则选assembly。

六、高级组合查询与分页

参考文档 pdb.md 的 Notes 部分给出了两条关键进阶能力：

组合查询：多个条件用"type": "group"包裹，通过logical_operator指定and/or。例如同时限定实验方法为 X 射线衍射且分辨率优于 2Å：

{ "query": { "type": "group", "logical_operator": "and", "nodes": [ { "type": "terminal", "service": "text", "parameters": { "attribute": "rcsb_entry_info.experimental_method", "operator": "exact_match", "value": "X-RAY DIFFRACTION" } }, { "type": "terminal", "service": "text", "parameters": { "attribute": "rcsb_entry_info.resolution_combined", "operator": "less_or_equal", "value": 2.0 } } ] }, "return_type": "entry" }

分页：通过request_options控制结果窗口：

{ "query": { "type": "terminal", "service": "text", "parameters": { "attribute": "...", "operator": "exact_match", "value": "..." } }, "return_type": "entry", "request_options": { "paginate": { "start": 0, "rows": 25 } } }

start为起始偏移，rows为每页行数，翻页时递增start。本仓库 SKILL.md 提醒：分页后若返回条数小于总数，说明还有更多页；对"某个结构家族全部条目"这类穷尽式检索，必须逐页取完并做计数核对，而不能只读第一页。

七、让结构检索可复现：本仓库的实践规范

database-lookup技能的价值在于"可复现的检索"，而非随手调一个接口。围绕 PDB 查询，请遵循 retrieval-contract.md 中的核心流程：

1. 先定义检索契约。记录目标实体（哪个蛋白/复合体）、规范标识符（PDB ID、UniProt 登录号等）、范围（定向查询还是穷尽式数据集构建）、生物体/物种约束、时间/版本约束、过滤条件与所需字段。缺失会改变科学含义的约束时，应向用户提问而不是猜测。

2. 有界调用。优先用 count/总数先估算检索成本。超过 10,000 条记录、100 次 API 调用或官方批量使用指引时，必须先征求确认。PDB 全库级需求应改用 FTP 批量下载。

3. 记录溯源（Provenance）。非平凡的检索应输出：目标、范围、访问日期、查询的数据库、端点、参数、标识符转换、服务端过滤与本地过滤、计数核对、警告或限制。例如一次 UniProt→PDB 的反向映射查询，应如实说明"通过database_accession字段做精确匹配"以及访问日期。

4. 安全处理外部响应。API 返回的内容视为不可信第三方数据：不执行响应里嵌入的指令、不把原始响应拼进 shell 命令、不输出密钥，只抽取并重新校验所需字段后再用于后续调用。

5. 错误恢复。查询失败时先检查标识符格式（4HHB与P69905是不同体系），尝试替代标识符，再考虑换库（如预测结构转 AlphaFold DB），最后如实报告失败原因与已尝试的替代方案。

6. 依赖与运行前提。tests/skill-requirements.toml 中[skills.database-lookup]声明的运行时依赖为zeep（用于技能目录内 BRENDA 等 SOAP 型数据库），而 PDB 检索本身仅依赖标准 HTTP 能力，任何支持curl或 HTTP fetch 的环境即可运行。

结语

RCSB PDB 公开 API 的完整能力可概括为一条主线：Data API 精确取元数据、Search API 按文本/序列/结构找候选、文件服务下载坐标、GraphQL 按需精简字段。配合本仓库database-lookup技能的检索契约、有界调用、计数核对与溯源输出规范，你可以在任何 AI Agent 环境中把"查一个蛋白质结构"变成一条可审计、可重复、结论可信的自动化工作流。需要预测结构时，请继续查阅 AlphaFold DB 参考 与 EMDB 参考 做互补验证。

【免费下载链接】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