用途
RFD4-Proteina NIM 用于通过 NVIDIA 发布的 RFD4-Proteina NIM 生成蛋白质结构与序列。该技能面向联合的蛋白质结构与序列设计、条件生成以及奖励引导搜索，覆盖条件化蛋白质和小分子结合体、基序与酶骨架搭建、抗体/CDR 设计、部分扩散、逆折叠和奖励引导的束搜索等任务。
主要能力
- 联合生成蛋白质结构与序列。
- 条件化生成：通过输入中的条件定义设计目标。
- 奖励引导搜索：支持束搜索，可能返回多个存活结果和保留的中间产物。
- 支持多种设计场景：蛋白质与小分子结合体、基序与酶骨架、抗体/CDR、部分扩散、逆折叠。
- 提供托管（NVIDIA API）与本地（用户自建 NIM）两种运行目标。
使用方式
前置条件
- Python 3.10 或更高版本；客户端仅使用标准库。
- 托管推理需要从产品页面获取密钥，设置为 NVIDIA_API_KEY（NGC_API_KEY 可作为回退）。密钥应通过用户的密钥机制提供，而非提示词或命令行参数。
- 离线准备和已保存响应提取无需凭据。
- 使用已有本地 NIM 时，使用其 base URL。启动新容器还需要 Docker、NVIDIA Container Toolkit、受支持的 GPU/驱动以及 NGC 访问权限。
端点与凭据
- 托管（默认）：推理端点为 https://health.api.nvidia.com/v1/biology/ipd/rfd4-proteina/generative，认证方式为 Authorization: Bearer <NVIDIA_API_KEY>；当第一个变量缺失或为空时回退到 NGC_API_KEY。
- 本地：推理端点为 http://localhost:8000/biology/ipd/rfd4-proteina/generative，客户端不发送 API 密钥。
- 托管 URL 包含 /v1，本地路由不包含。本地 base URL 的确定顺序为 --base-url、RFD4_NIM_URL、http://localhost:8000。这些设置不会覆盖托管目标。
- 托管请求发送 NVCF-POLL-SECONDS: 300；默认 socket 超时为 600 秒。
- NGC_API_KEY 也用于公共容器下载模型。Python 客户端仅将凭据转发到固定的托管端点，绝不发送到本地 URL 或重定向。客户端执行一次 POST，不自动重试。
输入与任务边界
- input.format="annotated_cif" 在 input.file 中携带带注释的 mmCIF。
- input.format="condition_spec" 在 input.spec 中携带解析后的对象，在 input.files 中携带完整文件。条件规范无法从服务器读取文件。
- task 选择采样器；输入中的条件定义设计。蛋白质结合体使用 generation，而非自创的 binder 任务。
- 框架和目标保留必须编码在提供的输入中。
- 保留注释列、分子上下文、键、电荷以及序列/坐标约束。即使是无条件生成也需要合适的输入模板。不要用 PDB 或旧版 RFdiffusion 字段（如 contigs、input_pdb、hotspot_res）替换 mmCIF。
- 内置的 PD-1 请求来自公开 Deploy 标签页，是该目标的完整示例，不能替代用户的目标。除非用户要求不同的受支持设置，否则使用其 thinking_medium 调度。
可用脚本
scripts/design.py：用于预检、提交一次或提取已保存响应。
- 必需参数：--request、--output-dir。
- 可选参数：--mode hosted|local、--base-url、--timeout；--dry-run / --response-json 互斥。
示例
从技能目录运行命令，或显式解析其路径。
准备公开示例而不发起网络请求：
python scripts/design.py --dry-run
--request assets/requests/16_ppi_binder.json
--output-dir /tmp/rfd4-binder-prepared
当请求托管执行且已设置 NVIDIA_API_KEY 时：
python scripts/design.py --mode hosted
--request assets/requests/16_ppi_binder.json
--output-dir /tmp/rfd4-binder-run
对于已有的本地部署：
python scripts/design.py --mode local --base-url http://localhost:8000
--request assets/requests/16_ppi_binder.json
--output-dir /tmp/rfd4-local-run
始终选择新的输出目录。--dry-run 执行基本线路检查；应报告为已准备，而非已提交。它不验证所有服务器规则或生物条件，也不生成设计。--response-json /path/to/response.json 离线提取已保存响应，并将其来源标记为 saved_response。
输出与验证
辅助脚本保存精确的 request.json 字节、transport.json、接收到的 response.raw、解析后的 response.json、返回的 design_0000.cif 文件、请求时的 sequences.fasta，以及包含每个设计指标、来源、诊断、验证错误和模型/运行时/调度来源的 summary.json。文件取决于模式和响应。
仅当 transport.json 具有 source="network"、http_status=200 且 status="completed"，并且 summary.json 具有 status="completed" 且无验证错误时，才报告推理已完成。对于 source="saved_response"，报告已提取保存的响应；这不是新的推理运行。仅退出代码为零不能确立任一结果。
普通采样应返回 sampling.num_replicates 个设计。搜索可能返回多个存活结果和保留的中间产物；保留 origin 和 replicate_index。将服务器 ID 视为不透明，使用客户端分配的文件名。序列可能覆盖整个设计并包含非蛋白质 X 标记；在报告仅结合体序列之前，先在 mmCIF 中识别链。
空指标表示不可用，而非零。聚合 n 计数贡献值，可能少于返回的设计数。辅助脚本检查基本响应完整性和服务器的有限坐标标志；它不证明折叠或结合。公共 API 没有内置重折叠预言机：在引用 pLDDT 或重折叠指标之前，检查 model.oracle 和实际结果。将生成的结构描述为未经验证的设计候选。没有单独证据及其来源，不要称其为已验证结合体或声称亲和力、折叠成功或实验活性。
适用场景
- 需要联合设计蛋白质结构与序列的研究或工程任务。
- 条件化蛋白质与小分子结合体设计。
- 基序与酶骨架搭建。
- 抗体/CDR 设计。
- 部分扩散与逆折叠。
- 奖励引导的束搜索。
限制
- 生成结果属于未经实验验证的设计候选，不应直接称为已验证结合体或声称亲和力、折叠成功或实验活性。
- 公共 API 没有内置重折叠预言机。
- 空指标表示不可用，而非零。
- 条件规范无法从服务器读取文件。
- 客户端执行一次 POST，不自动重试。
- 托管请求的轮询与超时行为受服务端设置约束。
- 本地部署需要 Docker、NVIDIA Container Toolkit、受支持的 GPU/驱动以及 NGC 访问权限。
- 技能的工具声明不强制主机隔离。
故障排除
- 退出 0：离线准备或提取了通过基本检查的响应；在报告结果前应用上述状态和来源检查。
- 退出 3 / HTTP 202：待处理。保留请求 ID 和原始响应。获取服务文档化的完成机制；不要自创轮询 URL 或自动重复 POST。咨询产品 API 文档或部署操作员，并提供保存的请求 ID。如果该部署没有文档化的检索途径，停止并报告未解决的待处理任务。
- 退出 1：请求、传输、响应、验证或文件系统失败。检查保存的诊断信息；不要用示例替代生成结果。
- 退出 2：无效的 CLI 参数。
- 401/403：检查 NVIDIA API 密钥和对所选服务的授权。仅注册表登录不能确立托管 API 访问权限。
- 413：检查请求大小、令牌数、批大小和搜索预算。
- 422：将输入、支持的任务、调度、附件和指标可用性与已发布的 API 或运行容器的模式进行比较。
- 429、5xx 或超时：保留错误和任何 Retry-After 头；在接受状态未知时不要重新提交。仅超时、经过的保持时间或 Retry-After 值不能证明原始请求被拒绝。仅在服务文档化的状态或操作员确认原始请求未被接受或已最终失败且无可恢复输出后，才再次提交；遵守任何重试延迟。否则停止并报告未解决状态及保存的诊断信息。