proteinmpnn-nim

ProteinMPNN NIM

为给定的骨架 PDB 设计蛋白质序列。请使用本指南进行初步的托管／本地使用；仅在需要时加载补充文件：

• references/api.md：精确的端点、架构、Docker 标志和响应字段。
• references/science.md：逆折叠的用途、局限性和验证。
• references/parameters.md：设计控制项、固定位置和采样。
• references/validation.md：FASTA、评分和结构检查。
• references/examples.md：精简的托管／本地请求模式。

选择模式

遵循用户明确指定的模式；否则使用已配置的运行时。NIM_API_MODE=local 表示使用 PROTEINMPNN_NIM_URL 指定的本地服务；如果 NIM 在同一主机或容器中运行，URL 默认为 http://localhost:8000。只有在环境和用户请求都无法明确模式时才询问：

托管的 NVIDIA API，还是本地 Docker NIM？

• 托管：https://health.api.nvidia.com/v1/biology/ipd/proteinmpnn/predict
• 本地：在 PROTEINMPNN_NIM_URL 后附加 /biology/ipd/proteinmpnn/predict （默认基础 URL：http://localhost:8000）。

本地推理路径不包含 /v1/。托管请求使用 Authorization: Bearer $NGC_API_KEY。受支持的本地 Docker 启动流程使用 NGC_API_KEY（或通过预检使用 NVIDIA_API_KEY）进行注册表登录、授权检查和首次模型下载；请使用 -e NGC_API_KEY 将其传入容器。就绪后，本地推理请求无需身份验证标头。热缓存下无需密钥即可启动的方式因镜像／版本而异，不应默认认为可用。

数据传输和授权

发送托管请求前，请告知用户：整个 PDB 文件和设计参数都会上传到上述端点所示的 NVIDIA 托管 API。如果用户已明确要求托管处理该 PDB，或已批准传输，则继续操作；否则请在提交前征求确认。对于机密结构，建议在用户批准的环境中使用本地 NIM。已配置的本地 URL 可能指向另一台机器；只能使用已配置或由用户选择的目标位置。未经用户授权，不得从本地处理切换为托管处理。

客户端从环境中读取 NIM_API_MODE、PROTEINMPNN_NIM_URL，以及托管模式下的 NGC_API_KEY。它只会通过 HTTPS Authorization 标头将密钥发送到托管端点；本地推理不会发送密钥。请勿将凭据写入日志或保存的构件。输出目录中的 request.json 包含完整的输入 PDB 文件，以及返回的序列和评分，因此请将输出保存到适合输入敏感级别的位置。有关端点和数据处理的详情，请参阅 references/api.md。

本地 Docker

进行本地设置时，请执行完整流程——环境预检、docker login、docker run、就绪循环，然后发送无需身份验证的 localhost 请求；不要只提供 localhost Python 请求。有关精确的预检（.env 加载、NGC_API_KEY／NVIDIA_API_KEY 处理，以及 nvcr.io/nim/ipd/proteinmpnn:latest 的 docker run），请逐字复制 references/api.md 中 Docker Reference 下的命令块。此 NIM 的缓存挂载路径是 /home/nvs/.cache/nim，不是 /opt/nim/.cache。如果已提供 PROTEINMPNN_NIM_URL，则表示服务已在其他位置托管；请使用该 URL，不要再启动另一个 Docker 容器。

就绪状态：

proteinmpnn_nim_url="${PROTEINMPNN_NIM_URL:-http://localhost:8000}"
until curl -sf "${proteinmpnn_nim_url%/}/v1/health/ready"; do sleep 5; done

使用说明

收到执行设计的请求时，请运行 scripts/design.py 并检查结果。仅编写请求脚本并不算完成执行请求。如果用户只要求代码或设置说明，请直接提供，不要提交推理请求。

1. 使用用户提供的 PDB 路径和指定的序列数量。客户端会将整个 PDB 读入 input_pdb；不要替换或截断提供的骨架。
2. 选择 --mode hosted 或 --mode local，并在提交前遵循上文的数据传输与授权说明。托管模式会将 PDB 上传到文档中指定的 NVIDIA 端点，并要求环境中设置 NGC_API_KEY。只检查密钥是否已设置；不要打印密钥、转储环境变量或保存身份验证标头。本地推理不会发送授权标头。
3. 每个请求都选择一个新的 --output-dir。客户端会在提交前预留该目录，保留原始响应以供诊断，并在报告完成前验证设计序列数量和分数对应关系。
4. 读取 summary.json，并报告下文所述的实际结果。如果请求或验证失败，请报告失败情况和诊断路径；不要用示例序列替代，也不要反复提交相同请求。

示例

在此技能目录中运行，或使用 scripts/design.py 的绝对路径。 替换为用户的输入路径和一个新的输出目录：

python scripts/design.py --mode hosted \
  --pdb /path/to/backbone.pdb --num-sequences 10 \
  --temperature 0.1 --output-dir /path/to/new-design-run

对于运行中的本地 NIM，请使用 --mode local；客户端会遵循 PROTEINMPNN_NIM_URL。若要仅设计链 A、排除半胱氨酸或请求可溶模型，请分别添加 --chains A、--omit-aas C 或 --soluble。 --seed 用于设置 random_seed；--ca-only 用于选择仅 CA 模型。辅助脚本每个请求仅使用一个温度；若要扫描多个温度，请分别使用不同的输出目录。对于高级 JSONL 控制或自定义批量请求，请参阅 references/api.md 和 references/examples.md 中的响应后示例。

保存并报告输出

客户端会将 request.json、response.raw、response.json、 designed_sequences.fa 和 summary.json 写入指定的输出目录。 FASTA 会保留完整返回的 mfasta，包括其中存在的天然型/WT 条目。摘要仅包含设计序列，并为每条序列配上其实际分数，同时记录分数来自 JSON 数组还是 FASTA 标头。保存并检查文件后，也会打印摘要。

在最终回复中，请报告：

• 设计序列的数量，不包括天然型/WT 参考序列。
• 每个设计的标识符、实际返回的分数及其序列（对于长序列，请提供明确标注的预览并链接到完整 FASTA）。
• 已保存的 FASTA 和摘要路径，以及用于溯源的原始响应路径。
• 说明这些是逆折叠候选序列；除非确实提出并运行了折回验证，否则不得声称已进行验证。

不要将分数视为序列能够折叠或结合的证明。使用 Boltz2 或 OpenFold3 进行进一步验证是可选的后续步骤。有关 FASTA/分数的合理性检查，请阅读 references/validation.md。

限制与故障排查

• 最低 GPU 显存：约 3 GB。
• sampling_temp 必须是列表，即使只有一个值也是如此。
• mfasta 为空：检查 input_pdb 是否非空，以及 num_seq_per_target >= 1。
• PDB 解析错误：请使用有效的 PDB ATOM 记录。
• 本地 URL 返回 404 通常意味着误加了 /v1/ 前缀。
• 缓存挂载错误：请在容器内使用 /home/nvs/.cache/nim。