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 BankPDB公开 API 的完整用法。你将掌握如何用 Data API 查询条目、聚合物实体与组装体元数据如何用 Search API 的 JSON 查询 DSL 做全文、序列与结构相似性检索如何下载 PDB/mmCIF 结构文件以及如何通过 GraphQL 精简字段查询。同时结合本仓库的检索契约与溯源规范学会把每一次结构检索变成可审计、可复现的科学结论。PDB 在本仓库中的定位在 database-lookup 技能中PDB 是实验测定的三维蛋白质结构的首选权威数据源。该技能目录的 数据库选择指南 明确给出了检索决策路径用户询问…首选数据库备选3D 蛋白质结构实验测定PDB (RCSB)EMDB3D 蛋白质结构预测AlphaFold DBPDBEM 图谱、冷冻电镜结构EMDBPDB也就是说当用户要的是实验解析的结构时RCSB PDB 是第一选择当需要预测结构时才转向 AlphaFold DB 参考AlphaFold DB 的比对结果也会回链到 PDB 条目。在开始任何 API 调用前技能要求先读取对应参考文件——即本仓库中的 pdb.md它是本篇指南的核心依据。Base URL 总览PDB 提供四类互补的接口参考文档 pdb.md 给出的基础地址如下接口地址用途Data APIhttps://data.rcsb.org/rest/v1按 ID 精确查询条目/实体/组装体元数据Search APIhttps://search.rcsb.org/rcsbsearch/v2/query全文、序列、结构相似性检索POSTGraphQLhttps://data.rcsb.org/graphql自定义字段的精简查询文件服务https://files.rcsb.org下载 PDB / mmCIF 结构文件认证与限速认证完全公开无需任何 API Key。这也是本仓库database-lookup技能中无需密钥即可匿名访问类数据库的典型代表与 SKILL.md 中 FRED、NCBI、OpenFDA 等需要免费注册密钥的数据库形成对比。限速官方没有公布硬性限制但参考文档明确要求保持礼貌的访问频率大约每秒几个请求。大规模批量获取时应改用 FTP 方式下载全库数据而不是逐条循环调用 REST 接口。一、Data API按 ID 查元数据Data API 的路径模式统一为{服务}/{对象类型}/{对象ID}三个核心端点如下。1. 条目查询Entry LookupGET https://data.rcsb.org/rest/v1/core/entry/{entry_id}示例血红蛋白PDB 条目4HHBGET 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/4HHB2. 聚合物实体查询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 APIJSON 查询 DSLSearch 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/query5. 序列检索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_cutoffE 值阈值这里为 0.1控制比对的显著性门槛identity_cutoff序列一致度阈值0.9 表示要求 90% 以上一致sequence_type序列类型蛋白质用proteinvalue目标氨基酸序列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_idassembly_id指定返回结果为组装体级。三、下载结构文件结构坐标文件通过文件服务获取GET https://files.rcsb.org/download/{entry_id}.cif GET https://files.rcsb.org/download/{entry_id}.pdbcurl示例# 下载 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/graphqlGraphQL 的entry(entry_id: ...)查询字段与 Data API 的对象模型一一对应熟悉 REST 端点后可自然迁移。五、return_type取值与检索粒度Search API 中return_type决定结果 ID 的粒度参考文档给出三档return_type返回 ID 示例适用场景entry4HHB只要 PDB 条目 IDpolymer_entity4HHB_1需要定位到具体链/分子实体assembly4HHB_1组装体级需要生物学组装体选择原则目标分析只关心整个结构就选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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考