AlphaFold 3

AlphaFold 3 是由 Google DeepMind 和 Isomorphic Labs 开发的深度学习模型。它旨在预测蛋白质、DNA、RNA、配体和离子的 3D 结构和相互作用。本文档介绍了如何使用 Gemini Enterprise Agent Platform 上的 Model Garden 部署和使用 AlphaFold 3 模型。

主要功能

在 Agent Platform 上部署 AlphaFold 3 可提供以下功能，满足高级研究和开发 (R&D) 以及商业药物发现工作流程的需求：

  • 商业用途：Model Garden 中的 AlphaFold 3 可用于商业用途。

  • 任意自定义配体：AlphaFold 3 支持蛋白质、DNA 和 RNA 与使用 SMILES 字符串或 CIF 化学组件字典 (CCD) 代码定义的自定义配体进行统一的共同折叠。

  • 工作流灵活性：Model Garden 中的 AlphaFold 3 支持完整的端到端折叠流水线（结合了数据库搜索和模型预测），或者仅推理模式，您可以在其中提供预先计算的 MSA 对齐，以优化执行时间和 GPU 利用率。

注意事项

在评估 AlphaFold 3 是否适合工作负载时，请注意以下限制：

  • 并发性：AlphaFold 3 端点的并发性限制为每个节点一个。为了提高并发性，可以将端点扩展到多个节点。如果在另一个预测正在积极运行时发送预测请求，则当请求数量超过节点数量时，端点会拒绝新请求并返回 HTTP 429 Too Many Requests 错误。

  • Token 数量上限：Agent Platform 端点的最长预测时长为 60 分钟。由于 MSA 搜索开销不确定，A3 GPU 支持的最大序列大小约为 4,500 个生物学标记（例如氨基酸、核苷酸或配体原子）开销。提供预先计算的对齐可绕过 MSA 搜索执行，从而实现复杂的折叠，最多可达到硬件限制（大约 5,400 个令牌）。

  • 载荷限制：标准预测 REST 请求的大小限制为 8 MB。如果您使用仅推理模式，则必须使用 Cloud Storage URI 引用大型预计算对齐（.a3m 文件），而不是将其嵌入为内嵌字符串，以避免有效载荷被拒绝。

  • 网络配置：由于预测是长时间运行的操作，可能需要长达 60 分钟才能完成，因此您应仅部署具有 Private Service Connect (PSC) 的端点，以绕过 10 分钟的标准端点超时限制。

部署说明

本部分详细介绍了如何将 AlphaFold 3 部署到 Google Cloud 项目中由 Agent Platform 提供的端点。

准备工作

在部署 AlphaFold 3 之前，您必须：

  • 申请模型访问权限。
  • 获取 GPU 资源。
  • 配置所需的 Identity and Access Management (IAM) 权限：
    • 创建具有 Agent Platform Administrator IAM 角色的服务账号。
    • 确保您的 IAM 主账号具有 roles/iam.serviceAccountCreator 角色，以便在部署模型时充当服务账号。
  • 验证资源配额。

资源要求

AlphaFold 3 需要 a3-highgpu-1g 虚拟机 (VM)。

在部署之前，请确保您的 Google Cloud 项目在目标部署区域中拥有足够的配额来支持以下资源：

  • 加速器：至少一种 a3-highgpu-1g 机器类型。

  • 本地 SSD：A3 虚拟机预配了 750 GB 的本地 SSD 空间。这是持久缓存参考序列数据库（UniProt、MGnify、Rfam）所必需的，可在所有预测请求中实现低延迟读取，从而在基因数据库搜索（Jackhmmer/Nhmmer）期间实现低延迟读取。

Cloud Storage 存储桶

AlphaFold 3 需要一个 Cloud Storage 存储桶来存储所有提供的 MSA 文件，并导出完整的预测输出。为避免跨区域传输，我们建议您使用与端点位于同一区域的 Cloud Storage 存储桶，或使用多区域存储桶。

Identity and Access Management 角色

为参与身份配置以下角色：

  • 模型部署者（也称为 IT 管理员）：部署模型的身份需要 roles/aiplatform.admin 权限才能创建端点和管理部署。

  • 服务身份：在运行推理时，AlphaFold 3 端点使用租户项目服务账号将输出结构直接写入 Cloud Storage。相应的服务账号需要对目标 Cloud Storage 存储桶拥有 roles/storage.objectUser 权限。

  • 模型用户：启动预测的账号需要满足以下条件：

    • roles/aiplatform.user 向端点发送预测请求。
    • roles/storage.objectUser，用于访问 Cloud Storage 存储桶中的预测输出。

部署 AlphaFold 3

使用 Agent Platform SDK 以编程方式部署 AlphaFold 3，但只能部署为 Google Cloud Dedicated 端点或 Private Service Connect 端点。端点可能需要 10-15 分钟才能准备好进行推理，具体取决于 GPU 可用性。

以下是一个 Python 代码段示例，展示了如何在 Google Cloud 项目中部署模型，包括延长推理超时时间：

import google.auth
from google.auth.transport.requests import AuthorizedSession
import vertexai
from vertexai import model_garden

PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
MODEL_ID = "google/alphafold3@v3_0_4"
MACHINE_TYPE = "a3-highgpu-1g"

vertexai.init(project=PROJECT_ID, location=LOCATION)

# 1. Deploy Model Garden OpenModel to Dedicated Endpoint
af3_model = model_garden.OpenModel(MODEL_ID)
endpoint = af3_model.deploy(
    endpoint_display_name="af3-dedicated-ep",
    model_display_name="af3-on-mg",
    machine_type=MACHINE_TYPE,
    accelerator_type="NVIDIA_H100_80GB",
    accelerator_count=1,
    reservation_affinity_type="ANY_RESERVATION",
    use_dedicated_endpoint=True,
    accept_eula=True,
    min_replica_count=1,
    max_replica_count=1,
    serving_container_deployment_timeout=3600,
)

# 2. Update inference timeout to 3,600 seconds
credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
session = AuthorizedSession(credentials)
url = f"https://{LOCATION}-aiplatform.googleapis.com/v1/{endpoint.resource_name}:update"
payload = {
    "endpoint": {
        "name": endpoint.resource_name,
        "clientConnectionConfig": {
            "inferenceTimeout": {
                "seconds": 3600
            }
        }
    }
}
response = session.post(url, json=payload)
response.raise_for_status()
print(f"Endpoint Resource Name: {endpoint.resource_name}")

API 参考文档

本部分介绍了端点位置、网址格式、路径参数和请求载荷架构。

HTTP 请求

POST https://HOST/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID:predict

替换以下内容：

  • HOST：服务端点主机。这取决于部署类型是专用公共端点还是使用 Private Service Connect。

  • PROJECT_ID：托管已部署端点的 Google Cloud 项目 ID。

  • LOCATION：端点部署到的 Google Cloud 区域（例如 us-central1）。

  • ENDPOINT_ID：已部署的 Agent Platform 端点的唯一标识符。

请求正文

请求正文包含的数据采用以下 JSON 结构：

{
  "instances": [
    {
      # The AlphaFold 3 input JSON - see the input documentation at
      # https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md
    }
  ],
  "parameters": {
    "output_dir": "string",
    "dry_run": boolean,
    "run_data_pipeline": boolean,
    "force_output_dir": boolean,
    "resolve_msa_overlaps": boolean,
    "max_template_date": "string",
    "conformer_max_iterations": integer,
    "fix_standalone_glycans": boolean,
    "flash_attention_implementation": "string",
    "num_recycles": integer,
    "num_diffusion_samples": integer,
    "save_embeddings": boolean,
    "save_distogram": boolean,
    "compress_large_output_files": boolean,
    "num_seeds": integer
  }
}

顶级请求字段

字段 类型 说明
instances array 必需。要预测的生物序列配置列表。此列表必须包含一个元素。传递零个或多个元素会导致 HTTP 422 Unprocessable Entity 错误。instances 正文应按照 AlphaFold 3 文档中发布的规范指定输入。
parameters object 可选。一个包含执行参数的对象，用于配置预测运行（例如 dry_run、output_dir）。

参数

为 AlphaFold 3 运行配置执行标志。

字段 类型 默认值 说明
dry_run boolean false 可选。如果值为 true，API 会执行请求验证，但会绕过模型执行并立即返回空响应。有助于检查连接和语法。
run_data_pipeline boolean true 可选。如果值为 true，则运行整个流水线（MSA 搜索和推理）。如果值为 false，则仅运行推理（跳过数据库搜索；需要预先计算的 MSA）。如需了解详情，请参阅 GitHub 上的文档。
output_dir string null 可选。Cloud Storage URI（例如 gs://bucket/path），用于在成功执行后上传完整的原始输出文件（包括 CIF 结构、PAE 和排名 CSV）。
force_output_dir boolean false 可选。如果为 true，则允许覆盖指定 output_dir 中的现有文件。如果值为 false，则当 Cloud Storage 路径不为空时，API 会立即返回 HTTP 400 Bad Request 错误，以防止意外丢失数据。
resolve_msa_overlaps boolean true 可选。是否针对配对的 MSA 对未配对的 MSA 进行去重。如需了解最佳实践，请参阅 GitHub AlphaFold 3 文档中的相关指南。
max_template_date string null 可选。要考虑的最大模板发布日期，格式为 YYYY-MM-DD（例如 "2024-05-15"）。如果格式不正确，验证会失败并显示 HTTP 422 错误。
conformer_max_iterations integer null 可选。替换 RDKit 构象异构体搜索要运行的最大迭代次数。必须是非负整数（大于或等于零）。对于负值，验证失败并显示 HTTP 422 错误。
fix_standalone_glycans boolean false 可选。启用独立的聚糖位置固定。
flash_attention_implementation string null 可选。要使用的 Flash attention 后端实现。允许的值包括 "triton"、"cudnn"、"xla"。
num_recycles integer 10 可选。推理期间要使用的回收迭代次数。 必须是正整数（大于零）。请参阅最佳实践部分，了解相关权衡取舍。
num_diffusion_samples integer 5 可选。要生成的扩散样本数量。必须是正整数（大于零）。请参阅最佳实践部分，了解相关权衡取舍。
save_embeddings boolean false 可选。是否将最终主干单嵌入和对嵌入保存到 output_dir 位置。如果值为 true，则嵌入会以 .npz 文件的形式写入名为 seed-{SEED}_embeddings/ 的子文件夹下（例如 outputs_config_job_seed-50_embeddings.npz）。
save_distogram boolean false 可选。是否将最终预测的距离图保存到 output_dir 位置。如果值为 true，则嵌入会以 .npz 文件的形式写入名为 seed-{SEED}_embeddings/ 的子文件夹下（例如 outputs_config_job_seed-50_embeddings.npz）。
compress_large_output_files boolean false 可选。如果为 true，则使用 zstandard 压缩大型输出文件（mmCIF 结构和置信度 JSON）。此命令会输出扩展名为 .cif.zst 和 .json.zst 的文件，而不是 .cif 和 .json。小文件（例如 ranking_scores.csv）保持未压缩状态。
num_seeds integer null 可选。用于推理的随机种子数。一般来说，您应该在 instances.modelSeeds 字段中设置种子，以实现可重现性。请参阅最佳实践部分，了解相关权衡取舍。

响应（输出）

本部分介绍了成功执行后在 API 响应中返回的字段。

响应正文

成功执行后，端点会以标准 Agent Platform 在线预测架构格式返回响应：

{
  "deployedModelId": "string",
  "model": "string",
  "modelDisplayName": "string",
  "modelVersionId": "string",
  "predictions": [
    {
      "structure_cif": "string",
      "plddt": [
        number
      ],
      "pae": [
        [
          number
        ]
      ],
      "summary": {
        "ptm": number,
        "iptm": number,
        "fraction_disordered": number,
        "has_clash": boolean,
        "ranking_score": number,
        "chain_pair_pae_min": [
          [
            number
          ]
        ],
        "chain_pair_iptm": [
          [
            number
          ]
        ],
        "chain_ptm": [
          number
        ],
        "chain_iptm": [
          number
        ],
        "chain_ids": [
          string
        ]
      },
      "output_dir": "string"
    }
  ]
}

顶级响应字段

字段 类型 说明
deployedModelId string Agent Platform 端点上已部署的模型的 ID。
model string 模型的完全限定资源名称。
modelDisplayName string 已部署模型的显示名称（始终为 "alphafold3"）。
modelVersionId string 已部署模型的版本 ID。
predictions array 预测结果列表。对于 AlphaFold 3，此数组包含一个预测结果对象。

预测结果详情 (predictions[])

AlphaFold 3 预测端点会返回一个 HTTP 200 JSON 响应，其中包含一个 predictions 数组，该数组包含排名最高的候选对象的结构坐标和置信度指标。如需查看全面的字段定义和输出文件规范，请参阅 GitHub 上的官方 AlphaFold 3 文档。

API 响应中的输出结构可能会因请求中是否提供 parameters.output_dir 而异：

  • HTTP 响应中的预测：内嵌响应直接在 HTTP JSON 响应载荷正文中返回全局摘要指标 (summary)、3D 结构坐标 (structure_cif)、每原子置信度得分 (plddt) 和 2D 预测对齐误差矩阵 (pae)。指定输出目录后，HTTP 响应载荷中会省略（设为 null）大型载荷字段（structure_cif、plddt 和 pae），以防止出现序列化瓶颈。相反，所有原始模型输出都会异步导出到指定的 Cloud Storage 存储桶。

  • Cloud Storage 存储桶中的已保存制品：指定输出目录 (parameters.output_dir) 后，系统会将全面的预测结果上传到 Cloud Storage。输出文件夹包含的数据符合 GitHub 上的 AlphaFold 3 文档中发布的规范。

做出预测

Model Garden 部署简化了端到端预测流水线的执行，包括通过单个 API 调用实现数据流水线和模型推理。下图展示了 AlphaFold 3 预测的概要架构：

AlphaFold 3 流水线的流程图。阶段 1（遗传数据库搜索流水线）使用 Jackhmmer 等搜索引擎和 UniProt 等数据库来输出 MSA 和结构模板。阶段 2（结构模型推理流水线）使用 AlphaFold 3 扩散 Transformer 神经网络处理这些输入。生成的 3D mmCIF 结构和置信度得分（pLDDT、PAE、ipTM）会保存到 Cloud Storage。

图 1. 完整的预测流水线

执行预测时，强烈建议直接在参数中提供 Cloud Storage 存储桶，以导出完整的原始数据集，包括每个样本的子目录、排名清单和原始输出。如需详细了解所有可配置的请求字段，包括针对多种子抽样、神经循环、扩散轨迹和自定义共价键的参数调整，请参阅 API 参考部分。

在启动长时间运行的折叠作业或批处理流水线之前，您可以执行试运行，以快速验证身份验证、IAM 权限和端点网络连接。

预测选项

根据工作流，AlphaFold 3 处理可分为四种不同的执行模式：

试运行模式

如需在不启动预测流水线的情况下验证 API 连接、身份验证、网络和 JSON 架构，您可以在 parameters 对象中提交包含 "dry_run": true 的请求。端点会执行所有验证例程（包括检查 Cloud Storage 存储桶写入权限和验证序列字符），但会跳过执行，立即返回空的预测响应。

以下是用于试运行模式的 Python 脚本示例：

from google.cloud import aiplatform

PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
ENDPOINT_ID = "YOUR_ENDPOINT_ID"

# Initialize AI Platform SDK
aiplatform.init(project=PROJECT_ID, location=LOCATION)

# Connect to Dedicated Endpoint
endpoint = aiplatform.Endpoint(ENDPOINT_ID)

# Define prediction payload
instances = [
    {
        "name": "preflight_check",
        "dialect": "alphafold3",
        "version": 4,
        "modelSeeds": [1],
        "sequences": [
            {
                "protein": {
                    "id": "A",
                    "sequence": "PVLSCGEWQL",
                }
            }
        ],
    }
]

parameters = {
    "dry_run": True,
}

# Execute prediction request
response = endpoint.predict(
    instances=instances,
    parameters=parameters
)
print(response.predictions)

端到端预测模式

如需运行端到端预测，请在单个请求中提交原始生物序列（蛋白质、DNA、RNA、配体和 PTM）。端点会自动执行遗传数据库搜索，然后立即执行模型推理。建议将此方法用于没有预先存在比对的折叠作业。

以下是端到端预测模式的 Python 脚本示例：

from google.cloud import aiplatform

# Configuration
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
ENDPOINT_ID = "YOUR_ENDPOINT_ID"
STORAGE_OUTPUT_DIR = "gs://YOUR_BUCKET_NAME/alphafold_output/"

# Initialize AI Platform SDK
aiplatform.init(project=PROJECT_ID, location=LOCATION)

# Instantiate Endpoint reference
endpoint = aiplatform.Endpoint(ENDPOINT_ID)

# Define Prediction Payload
instances = [
    {
        "name": "e2e_protein_ligand_complex",
        "dialect": "alphafold3",
        "version": 4,
        "modelSeeds": [1],
        "sequences": [
            {
                "protein": {
                    "id": "A",
                    "sequence": "PVLSCGEWQL",
                    "modifications": [
                        {"ptmType": "HY3", "ptmPosition": 1}
                    ],
                }
            },
            {
                "ligand": {
                    "id": "B",
                    "ccdCodes": ["MG"],
                }
            },
        ],
    }
]

parameters = {
    "output_dir": STORAGE_OUTPUT_DIR,
}

# Execute Prediction
response = endpoint.predict(
    instances=instances,
    parameters=parameters
)

print(response.predictions)

仅使用预先计算的 MSA 和模板进行推理

您可能已经通过之前的执行或在模型端点之外生成了预计算的 MSA 和 mmCIF 模板。在这些情况下，可以通过提供比对和模板来完全绕过遗传数据库搜索，直接将请求路由到结构预测。这还可以显著缩短推理响应时间。在以下情况下，建议采用此路径：

  • 当针对单个静态蛋白质靶标对接多种不同的小分子配体时，可以重复使用 MSA。
  • 在多个随机种子中迭代运行相同的分子序列，以绘制结构灵活性图。
  • 离线将序列与私有非公开基因组数据库进行比对。
  • 优化了 AlphaFold 3 的 GPU 资源，使其仅专注于结构生成。

以下是仅用于推理模式的 Python 脚本示例：

from google.cloud import aiplatform

# Configuration
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
ENDPOINT_ID = "YOUR_ENDPOINT_ID"
STORAGE_OUTPUT_DIR = "gs://YOUR_BUCKET_NAME/af3_results/inference_only"

# Initialize AI Platform SDK
aiplatform.init(project=PROJECT_ID, location=LOCATION)

# Instantiate Endpoint reference
endpoint = aiplatform.Endpoint(ENDPOINT_ID)

# Define Prediction Payload
instances = [
    {
        "name": "inference_protein_ligand_complex",
        "dialect": "alphafold3",
        "version": 4,
        "modelSeeds": [1],
        "sequences": [
            {
                "protein": {
                    "id": "A",
                    "sequence": "PVLSCGEWQL",
                    "modifications": [
                        {"ptmType": "HY3", "ptmPosition": 1}
                    ],
                    "unpairedMsaPath": "gs://YOUR_BUCKET_NAME/path/to/unpaired.a3m",
                    "pairedMsa": "",
                    "templates": [],
                }
            },
            {
                "ligand": {
                    "id": "B",
                    "ccdCodes": ["MG"],
                }
            },
        ],
    }
]

parameters = {
    "run_data_pipeline": False,
    "output_dir": STORAGE_OUTPUT_DIR,
    "force_output_dir": True,
}

# Execute Prediction
response = endpoint.predict(
    instances=instances,
    parameters=parameters
)

print(response.predictions)

运行 MSA 和无模板

此外，还可以选择完全绕过遗传数据库搜索和模板匹配。该模型仅使用查询序列来预测 3D 结构，而无需同源序列或共同进化信息。如需触发此模式，请在实例中为 MSA 参数 unpairedMsa 和 pairedMsa 提供空字符串，并为 templates 提供空列表，然后在参数中将 run_data_pipeline 设置为 false。这对于合成或工程化分子设计或在没有进化背景的情况下测试结构预测非常有用。

以下是运行 AlphaFold 3 MSA 和无模板的 Python 脚本示例：

from google.cloud import aiplatform

# Configuration
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
ENDPOINT_ID = "YOUR_ENDPOINT_ID"
STORAGE_OUTPUT_DIR = "gs://YOUR_BUCKET_NAME/af3_results/inference_only_gcs_job"

# Initialize AI Platform SDK
aiplatform.init(project=PROJECT_ID, location=LOCATION)

# Instantiate Endpoint reference
endpoint = aiplatform.Endpoint(ENDPOINT_ID)

# Define Prediction Payload
instances = [
    {
        "name": "inference_only_gcs_job",
        "dialect": "alphafold3",
        "version": 4,
        "modelSeeds": [1, 2, 3],
        "sequences": [
            {
                "protein": {
                    "id": "A",
                    "sequence": "PVLSCGEWQL",
                    "unpairedMsa": "",
                    "pairedMsa": "",
                    "templates": [],
                }
            }
        ],
    }
]

parameters = {
    "output_dir": STORAGE_OUTPUT_DIR,
    "run_data_pipeline": False,
}

# Execute Prediction
response = endpoint.predict(
    instances=instances,
    parameters=parameters,
    timeout=3600.0,
)

print(response.predictions)

如需详细了解规范、实体参数和输出置信度指标，请参阅 GitHub 上的 AlphaFold 3 文档。

预测输出

AlphaFold 3 预测服务提供了两种互补的交付机制，用于检索预测输出。默认情况下，API 响应会同步内嵌返回排名最高的候选对象的预测结果。您可以选择指定 Cloud Storage 目录。

以下部分简要介绍了预测输出。如需了解详情，请参阅 GitHub 上的 AlphaFold 3 文档。

内嵌回答与已保存的制品

AlphaFold 3 预测服务支持两种主要输出模式：

  • 内嵌响应：仅在 HTTP REST 响应载荷中直接返回排名最高的候选对象的 3D 结构坐标和置信度指标。这非常适合快速交互式原型设计或单序列查询。
  • 已保存的制品 (Cloud Storage)：指定输出目录会将完整的多样本数据集导出到 Cloud Storage。这包括每个生成的随机种子和扩散样本的各个坐标文件、置信度 JSON、距离图、嵌入和摘要指标。建议使用 Cloud Storage 来处理生产工作负载、映射构象系综，并绕过请求载荷大小限制。

以下是一个 Python 示例，展示了如何从 Cloud Storage 中检索已保存的制品以进行下游分析：

from google.cloud import storage

BUCKET_NAME = "your-bucket-name"
JOB_NAME = "my_alphafold_job"
STORAGE_PREFIX = f"af3_results/my_folder/{JOB_NAME}"

# Initialize GCS client
client = storage.Client(project="your-project-id")
bucket = client.bucket(BUCKET_NAME)

# Download the top-ranked 3D structure and global ranking ledger
bucket.blob(f"{STORAGE_PREFIX}/{JOB_NAME}_model.cif").download_to_filename("model.cif")
bucket.blob(f"{STORAGE_PREFIX}/{JOB_NAME}_ranking_scores.csv").download_to_filename("ranking_scores.csv")
bucket.blob(f"{STORAGE_PREFIX}/{JOB_NAME}_summary_confidences.json").download_to_filename("summary.json")

由于 AlphaFold 3 采用生成式扩散模型，因此每次预测运行都会生成一组候选 3D 结构，这些结构涵盖不同的随机种子和抽样轨迹。评估和比较这些候选运行有助于在执行详细的结构分析之前解读预测输出。

您可以使用以下三个核心文件来调查完整的多样本制品数据集：

  • ranking_scores.csv：主要账本，列出了每个生成的轨迹对及其复合 ranking_score。行按轨迹执行顺序（先按种子升序排序，再按样本指数升序排序）保存，而不是按得分预先排序。用户应按 ranking_score 降序排序，以确定候选排名。

  • summary_confidences.json：包含最佳候选者的全局质量指标（pTM、ipTM、has_clash、fraction_disordered）。

  • 每个样本的 summary_confidences.json：位于各个 seed-{SEED}_sample-{INDEX}/ 文件夹内，可让您根据需要检查特定非热门候选运行的链级 pTM 和 ipTM 矩阵。

以下 Python 示例会解析 ranking_scores.csv 和 summary_confidences.json，以对候选样本进行排名并验证排名靠前的候选样本的质量：

import csv
import json

print("=== Candidate Samples Ledger (ranking_scores.csv) ===")
with open("ranking_scores.csv", "r", newline="", encoding="utf-8") as f:
    rows = sorted(
        csv.DictReader(f), key=lambda x: float(x["ranking_score"]), reverse=True
    )

# Calculate column widths cleanly and readably
headers = list(rows[0].keys())
widths = {}
for col in headers:
    lengths = [len(col)] + [len(r[col]) for r in rows]
    widths[col] = max(lengths)

print("  ".join(col.rjust(widths[col]) for col in headers))
for r in rows:
    print("  ".join(r[col].rjust(widths[col]) for col in headers))

top = rows[0]
print(
    f"\nPromoted Top Candidate: Seed {int(top['seed'])}, Sample"
    f" {int(top['sample'])} (Score: {float(top['ranking_score']):.4f})"
)

print("\n=== Top Candidate Quality Validation (summary.json) ===")
with open("summary.json", "r", encoding="utf-8") as f:
    summary = json.load(f)

clash_str = (
    "DETECTED (FAIL)" if summary.get("has_clash") else "None Detected (PASS)"
)
print("Top Candidate Metrics:")
print(f"  • Ranking Score : {summary.get('ranking_score', 'N/A')}")
print(f"  • Global pTM    : {summary.get('ptm', 'N/A')}")
print(f"  • Interface ipTM: {summary.get('iptm', 'N/A')}")
print(f"  • Steric Clash  : {clash_str}")

如需查看保存的文件和 mmCIF 属性的详尽架构规范，请参阅 GitHub 上的 AlphaFold 3 文档。另请参阅 EMBL-EBI 上的如何评估 AlphaFold 3 预测的质量指南，了解如何评估预测的质量。

最佳做法

以下部分介绍了在 Agent Platform 上使用 AlphaFold 3 时的最佳实践：

缓解请求超时问题

Agent Platform 上的端点会为每个请求强制执行默认的最长执行超时时间（60 分钟）。为确保预测成功完成且不会超时，请遵循以下准则：

  • 避免在单个请求中过度采样：在单个 API 调用中初始化大量种子或过高的反向扩散参数可能会导致执行时间超过 60 分钟的限制。
  • 分解大规模扫描：对于大规模研究，请将种子和形参扫描拆分为多个较小的预测载荷，并将其作为单独的作业提交。此操作还会利用端点的自动扩缩功能。

遗传数据库搜索流水线是 AlphaFold 流水线中最耗时的阶段。在同一序列上运行迭代预测（例如，对固定蛋白质靶标执行配体过滤扫描）时，您可以通过完全绕过数据库搜索来大幅优化执行时间：

  • 提取 MSA：运行初始端到端预测，并指定 Cloud Storage 输出目录 (output_dir)。从输出 Cloud Storage 存储桶下载生成的 {JOB_NAME}_data.json 文件。
  • 提交仅用于推理的预测：找到 JSON 文件中的 unpairedMsa 和 pairedMsa 字段。提取这些 MSA 字符串，然后使用指向 Cloud Storage URI 的 unpairedMsaPath 和 pairedMsaPath 将它们传递到后续的预测请求中。

或者，您也可以在自己的基础设施上执行 MSA 搜索，并在预测请求中输入预先计算的 MSA 模板。

处理低置信度运行

当预测输出产生低置信度指标时，您不必将其视为不可恢复的预测失败，而是可以尝试有针对性的补救措施。通过优化特定形参，您可以探索其他潜在轨迹。本部分列出了一些在预测置信度较低时进行恢复的方法。

使用多种子抽样

AlphaFold 3 从潜在空间中的随机噪声开始初始化 3D 坐标生成。如果提交预测时使用单个确定性种子，扩散轨迹可能会与使用其他种子时不同。传递种子数组会强制模型从不同状态开始对轨迹进行抽样。

多种子抽样具有两个关键优势：它可以验证独立运行之间的结构一致性，并探测功能构象动力学。例如，如果所有 5 个种子都收敛到相同的 3D 坐标，那么您就可以对全局折叠充满信心。相反，如果不同的种子产生不同的、高置信度的结合姿势，则集成可能揭示了具有生物学意义的构象状态，例如开放与闭合的活性位点环或替代的结构域交换二聚体。

扩展扩散轨迹

虽然 modelSeeds 会改变潜在空间中的初始噪声状态，但 num_diffusion_samples 参数（默认值为 5）会控制在反向扩散过程中，每个种子生成的候选 3D 结构的数量。对于柔性环状区域或浅绑定口袋，增加抽样会扩大每个种子的候选池。当特定环路的局部置信度得分较低 (pLDDT < 70) 而整个网域折叠的置信度仍然较高 (pTM > 0.80) 时，这种方法尤其有效。这有助于发现初始运行中可能会遗漏的高可信度候选结构。

增加回收迭代次数

在扩散模块生成 3D 坐标之前，AlphaFold 3 会处理序列和成对特征。num_recycles 参数决定了中间结构表示和成对空间嵌入通过网络迭代反馈的次数。

对于大型复杂分子或具有弱共进化信号的靶标，增加 num_recycles 可为主干网络提供额外的迭代次数，以便在将输入传递给扩散模块之前解析远距离链之间的空间关系。如果非对角线 PAE 矩阵显示出较高的链间不确定性（> 15 Å），但各个链却显示出较高的局部折叠置信度（pLDDT > 70），则可以尝试此方法。请注意，增加回收次数会线性增加预测运行时，因此应仅在界面目标较难时使用。

使用自定义对齐流水线

AlphaFold 3 会自动执行基因数据库搜索流水线，以生成 MSA 模板。用户还可以使用 unpairedMsaPath 和 pairedMsaPath 通过 Cloud Storage URI 提供 .a3m 格式的私有预计算自定义对齐。提供深度 MSA 可带来强大的共同进化限制，从而经常将低置信度预测转化为高置信度模型。