化学 AI 应用中的科学 API：PubChem 与 RCSB PDB 入门

为什么 API 仍然是化学 AI 技术栈的一部分

化学助手应检索科学记录，而不是依靠模型记忆重新构造这些记录。API 为开发者提供了获取服务提供方标识符、选定字段和结构化响应的明确途径。随后，应用可以在呈现科学答案前核验这些响应。

PubChem PUG REST 提供针对特定化学记录的请求。RCSB PDB Data API 提供已识别结构及其组分的元数据。这两者都不能将检索变成实验验证、结构预测或药物疗效证据。

如果需要可预测的请求和可检查的响应，请从直接调用 API 开始。若助手需要在已公开的工具中进行选择，可以考虑 MCP 封装器。API 仍是上游数据接口；封装器则增加了另一份契约和一个故障边界。API、MCP、Skills 与智能体指南 说明了这些角色，化学领域中的 MCP 则提供更广泛的集成背景。

相关指南：RDKit AI 工作流 · 蛋白质与结构生物学工作流 · 化学 AI Agent 技术栈。

选择工具前先定义接口契约

首先明确科学任务：解析化合物标识符、检索某项性质、检查聚合物序列，还是追踪数据库交叉引用。写明结果可以支持什么，以及绝不能暗示什么。

建议的最低限度契约包括：

• **输入：**标识符命名空间及其值、请求字段、输出格式和筛选条件。
• **输出：**服务提供方标识符、返回的表示形式、适用时的数值和单位、可用来源引用、检索时间和结果状态。
• **缺失值：**分别处理字段缺失、显式 null、空结果和数值零。
• **身份：**在保留内部标识符的同时保留服务提供方标识符。
• **完整性：**说明响应是完整、部分、分页还是来自缓存。

确定应用需要精确的化学实体，还是更广义的相关形式集合。盐组分、电荷和立体化学信息不应因未说明的规范化步骤而消失。同样，不能仅因条目标识符、实体标识符和链标识符出现在同一结构记录中，就将它们视为可以互换。

按服务角色进行选择

这些资源处于不同的处理阶段。下表比较的是文档所述能力，并非经过测试的互操作性。

资源	来源所述角色	适用输入或输出	集成边界
PubChem PUG REST	托管式化学数据 API	CID、名称或结构输入；选定记录和性质	不提供完整的 PUG View 摘要报告
RCSB PDB Data API	托管式结构元数据 API	已识别的条目、实体、实例、装配体和化学组分；JSON	发现功能由单独的 Search API 提供；元数据不是坐标文件下载
UniProt MCP (cyanheads)	第三方蛋白质数据封装器	蛋白质查询、登录号、映射任务、注释和序列	映射可能需要轮询和继续获取分页结果
RCSB MCP (cnyambura)	第三方检索与下载封装器	PDB 条目和聚合物查询；已下载文件的状态和本地路径	生物体搜索工具返回的是操作说明，而不是已检索的匹配项
RDKit MCP Server (TandemAI)	RDKit 函数的软件接口	已公开的 RDKit 工具结果和客户端响应	此处未确定各分子输入模式和完整工具覆盖范围

单独的 rcsb-api Python 客户端可访问 RCSB Search 和 Data API；它不是托管式 Data API 的实现。同样，MCP 服务器是可执行软件，并非仅仅是 Skill 指令文档。加载工作流说明并不会安装依赖项，也不能证明与宿主环境兼容。选择这一附加层时，请参阅 MCP 选择指南 和 智能体与 Skills 指南。

从有针对性的 PubChem REST 请求开始

PUG REST 路径将请求分为输入、操作和输出。化合物输入包括 CID、名称、SMILES、InChI、InChIKey 和分子式。文档所述操作包括记录、同义词、标识符、性质、测定摘要，以及结构身份或相似性搜索。输出格式取决于具体操作。

两个官方示例适合作为入门：

• 向 CID 2244 性质请求 发送 HTTP GET，以 JSON 请求 MolecularFormula 和 InChIKey。
• 向 CID 2244 SDF 请求 发送 HTTP GET，以请求文档所述的阿司匹林结构记录。

这些示例展示了同一标识符对应的不同输出；本指南并未报告实际执行结果。接受任一响应前，应检查 HTTP 状态、响应格式、返回的标识符以及请求字段是否存在。

应对 URL 中的特殊字符进行编码，不要未经处理就将分子表示形式插入 URL。规范要求通过 POST 传送 InChI 和 SDF 输入。进行结构搜索时，应区分身份标准与相似性标准：候选结构相似并不意味着可以将记录合并为同一化合物。实施前，请在规范中确认具体操作和参数。

PUG REST 通过有针对性的同步请求返回选定信息。PUG View 提供更完整的摘要报告和第三方注释。因此，性质查询不应被描述为完整的 PubChem 报告。如需进一步规划应用，请参阅 PubChem 智能体集成指南。

在正确的层级检索 RCSB 元数据

RCSB REST 支持使用特定资源路径的 GET 请求，并返回 JSON。其官方示例包括：

• 条目 4HHB：条目级元数据，包括实验详情。
• 聚合物实体 4HHB/1：关于一种独立高分子实体的信息。
• 聚合物实例 4HHB/A：关于该聚合物特定副本的信息。

在实例端点中，链标识符对应 PDBx/mmCIF 中的 _label_asym_id。将元数据与结构文件关联时，应保留这一命名空间。

REST 返回固定的对象表示形式。GraphQL 允许选择字段并遍历相互关联的层级，包括多个已识别对象。需要直接查询对象时选择 REST；应用需要跨关系选取有限字段时，可以考虑 GraphQL。两种接口查询的是相同的底层数据。

将发现与检索分开处理。Search API 查找匹配标识符列表；Data API 则检索所提供标识符的信息。GraphQL 不提供查询全部对象的功能。覆盖整个档案的工作流应从单独的 Holdings 服务开始，再分批检索元数据。

Data API 覆盖常用注释，但并非所有 PDBx/mmCIF 条目。坐标文件也属于单独的检索事项。RCSB MCP 封装器说明支持文件下载，但成功的元数据请求本身并不能证明已获得坐标文件。

发现候选记录时，按 Search API 文档选择属性、序列或结构搜索服务，声明 return_type，并在 request_options 中限定分页。保留查询和返回标识符的命名空间，再通过 Data API 获取元数据。搜索匹配项仍是需要科学解释的候选记录。

建议示例：化合物与结构证据卡

设想一个拟议的内部应用，有两个相互独立的输入：PubChem CID 2244 和 PDB 条目 4HHB。将它们一起使用是为了说明接口设计，并不表示两者存在化合物—蛋白质关系。

1. 请求文档所述的 PubChem 属性 JSON；如有需要，再请求 SDF。保留 CID、返回的描述符和检索时间。
2. 请求 RCSB 条目元数据。根据返回的实体标识符继续查询，不要假设每个条目都使用相同的实体编号方式。
3. 同时需要序列级和链特异性注释时，检索选定的聚合物实体及实例。
4. 分别显示化合物和结构面板，并为每个面板标注数据提供方和状态。
5. 只有在关系得到独立支持后，才将两个面板合并为生物学结论。

**建议的输出：**标识符、请求值、表示形式、所提供的实验或模型背景、引用、完整性和警告。**决策点：**身份核验是否通过？所需背景是否齐全？交叉引用是否足以支持预期的关联？如果不足，应返回歧义状态或将记录分开保留。

作为建议的评估步骤，可将代表性响应与官方记录页面进行比较，并纳入无效标识符、缺失字段、带电化合物和立体化学变体。本指南不声称进行过科学测试或完成了集成。

添加封装器和智能体，同时不掩盖上游证据

UniProt MCP 可提供蛋白质注释和交叉引用，并附带整理状态指标以及可用的 PubMed/ECO 证据。一种建议的扩展方案是：沿返回的 PDB 引用查询 RCSB 元数据，然后在接受关联前核验生物体、序列和标识符范围。应分别处理现有映射任务的继续轮询和已完成结果的后续分页获取；不要反复提交相同任务。

RCSB MCP 提供条目和聚合物检索、自定义查询以及结构下载。其自定义端点示例中的标识符标点格式与官方 REST 路径示例不同。应检查封装器如何构造请求，不要假设这些字符串可以直接粘贴到上游 REST URL 中。

RDKit MCP 提供工具列表功能和评估套件。提出规范化或描述符计算方案前，应先检查实际工具清单。完整覆盖 RDKit 函数只是目标，并非已展示的覆盖范围。应将计算结果与服务提供方返回的字段分开保留。

对于本地部署 UniProt，请先解决前置条件之间的差异：README 允许使用 Bun v1.3.0 或更高版本，而包元数据要求 Bun >=1.4.0。配置说明并不能证明其与所选宿主环境经过兼容性测试。

处理限制、故障和变化中的响应

配置共享请求调度、超时和有上限的重试。PubChem 说明了请求限制和动态节流；应采用其教程所述方法，而不是不受限制地并行逐条调用；批量数据则应选择批量下载工作流。RCSB 建议对大型请求进行分批处理，并缓存重复检索结果。这些建议都不构成吞吐量保证。

应明确呈现有意义的状态，例如已找到、未找到、存在歧义、输入无效、拒绝访问、部分结果和暂时不可用。RCSB REST 说明，数据或端点不存在时会返回 404。GraphQL 错误可能与 HTTP 200 和部分数据同时出现，因此在宣布成功前应检查响应正文。

仅对暂时性故障进行重试。保留分页完整性，并为缓存响应标注观测时间；如果陈旧数据会使任务失效，应明确报错。必要时将凭据保留在服务器端，并限制用户触发的操作，尤其是自定义端点和文件目标位置。记录诊断信息时，不要包含机密或不必要的敏感输入。

保留来源信息，并使用简明的就绪检查清单

保留数据提供方、记录标识符、影响结果的请求参数、观测时间以及可用的引文元数据。将规范化结构、转换后的单位和计算得出的摘要标记为派生内容。在线记录可能发生变化；保留许可范围内的固定样本或快照，并记录历史可复现性的限制。

检索并不能证明生物活性、验证计算模型，也不能确立注释的再利用权利。应分别核查软件、数据库、注释和托管服务的条款。来源可用本身并不等于获得许可认定。数据集来源记录指南 对这种记录方法有更详细的说明。

继续之前：

• 声明标识符命名空间和化学身份规则。
• 确认字段、单位、缺失值处理和输出格式。
• 将 Search API 发现与 Data API 检索分开。
• 检查错误、部分结果和分页情况。
• 制定节流、重试、缓存和超时策略。
• 检查封装器工具输入输出模式和部署要求。
• 保留引用并标记转换操作。
• 记录尚未解决的科学限制和再利用限制。

来源

PubChem 规范、教程 和程序化访问概览支持请求示例、有针对性检索的范围以及操作边界。RCSB Data API 文档支持层级结构、REST 示例、GraphQL 处理方式，以及 Search 与 Data 的区别。

封装器能力信息来自以下项目 README：UniProt MCP、RCSB MCP 和 RDKit MCP。UniProt 包元数据支持上文讨论的运行时要求差异。