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 は、SMILES 文字列または CIF Chemical Component Dictionary（CCD）コードを使用して定義されたカスタム リガンドとともに、タンパク質、DNA、RNA の統一された共折り畳みをサポートしています。

  • ワークフローの柔軟性: Model Garden の AlphaFold 3 は、完全なエンドツーエンドのフォールディング パイプライン（データベース検索とモデル予測の組み合わせ）または推論専用モードをサポートしています。このモードでは、事前に計算された MSA アライメントを提供して、実行時間と GPU 使用率を最適化できます。

考慮事項

ワークロードで AlphaFold 3 を評価する際は、次の制約事項に注意してください。

  • 同時実行: AlphaFold 3 エンドポイントの同時実行の上限はノードあたり 1 つです。同時実行性を高めるために、エンドポイントを複数のノードにスケーリングできます。別の予測がアクティブに実行されているときに予測リクエストが送信されると、リクエストの数がノードの数を超える場合、エンドポイントは HTTP 429 Too Many Requests エラーで新しいリクエストを拒否します。

  • トークンの上限: Agent Platform エンドポイントの最大予測期間は 60 分です。MSA 検索のオーバーヘッドは変動するため、A3 GPU でサポートされる最大シーケンス サイズは約 4,500 個の生物学的トークン（アミノ酸、ヌクレオチド、リガンド原子など）のオーバーヘッドです。事前計算されたアライメントを提供すると、MSA 検索の実行がバイパスされ、約 5,400 個のトークンのハードウェア上限まで複雑なフォールディングが可能になります。

  • ペイロードの上限: 標準予測 REST リクエストのサイズの上限は 8 MB です。推論専用モードを使用する場合は、ペイロードの拒否を回避するために、大きな事前計算されたアライメント（.a3m ファイル）をインライン文字列として埋め込むのではなく、Cloud Storage URI を使用して参照する必要があります。

  • ネットワーク構成: 予測は完了までに最大 60 分かかる可能性がある長時間実行オペレーションであるため、Private Service Connect（PSC）を使用してエンドポイントをデプロイし、標準のエンドポイント タイムアウト制限である 10 分を回避する必要があります。

デプロイ手順

このセクションでは、 Google Cloud プロジェクトの Agent Platform が提供するエンドポイントに AlphaFold 3 をデプロイする方法について説明します。

始める前に

AlphaFold 3 をデプロイする前に、次のことを行う必要があります。

  • モデルへのアクセスをリクエストします。
  • GPU リソースを調達します。
  • 必要な Identity and Access Management（IAM）権限を構成します。
    • Agent Platform 管理者 IAM ロールを持つサービス アカウントを作成します。
    • モデルのデプロイ時にサービス アカウントとして機能する roles/iam.serviceAccountCreator ロールが IAM プリンシパルに付与されていることを確認します。
  • リソース割り当てを確認します。

リソース要件

AlphaFold 3 には a3-highgpu-1g 仮想マシン（VM）が必要です。

デプロイする前に、 Google Cloud プロジェクトのターゲット デプロイ リージョンに次のリソースの十分な割り当てがあることを確認します。

  • アクセラレータ: 少なくとも 1 つの a3-highgpu-1g マシンタイプ。

  • ローカル SSD: A3 VM には 750 GB のローカル SSD 容量がプロビジョニングされます。これは、参照シーケンス データベース（UniProt、MGnify、Rfam）を永続的にキャッシュに保存するために必要です。これにより、すべての予測リクエストで遺伝子データベース検索（Jackhmmer/Nhmmer）中に低レイテンシの読み取りが可能になります。

Cloud Storage バケット

AlphaFold 3 では、指定された MSA ファイルを保存し、完全な予測出力をエクスポートするために Cloud Storage バケットが必要です。リージョン間の転送を回避するには、エンドポイントと同じリージョンにある Cloud Storage バケットを使用するか、マルチリージョン バケットを使用することをおすすめします。

Identity and Access Management ロール

参加する ID 全体で次のロールを構成します。

  • モデル デプロイ担当者（IT 管理者）: モデルをデプロイする ID には、エンドポイントの作成とデプロイの管理を行うための roles/aiplatform.admin 権限が必要です。

  • サービング ID: 推論の実行時に、AlphaFold 3 エンドポイントはテナント プロジェクト サービス アカウントを使用して、出力構造を Cloud Storage に直接書き込みます。対応するサービス アカウントには、ターゲット Cloud Storage バケットに対する roles/storage.objectUser が必要です。

  • モデルユーザー: 予測を開始するアカウントには、次のものが必要です。

    • roles/aiplatform.user: 予測リクエストをエンドポイントに送信します。
    • Cloud Storage バケットの予測出力にアクセスする roles/storage.objectUser。

AlphaFold 3 をデプロイする

Agent Platform SDK を使用して、Google Cloud 専用エンドポイントまたは Private Service Connect エンドポイントとしてのみ、AlphaFold 3 をプログラムでデプロイします。GPU の可用性によっては、エンドポイントで推論の準備が整うまでに 10 ～ 15 分かかることがあります。

次の 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 リファレンス

このセクションでは、エンドポイントの場所、URL 形式、パス パラメータ、リクエスト ペイロード スキーマについて説明します。

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 必須。予測する生物学的配列構成のリスト。このリストには、1 つだけの要素を含める必要があります。要素を 0 個または 2 個以上渡すと、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 省略可。実行が成功したときに、完全な未加工の出力ファイル（CIF 構造、PAE、ランキング CSV を含む）がアップロードされる Cloud Storage URI（gs://bucket/path など）。
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 コンフォーマー検索で実行する反復処理の最大数をオーバーライドします。非負の整数（0 以上）を指定する必要があります。負の値に対して HTTP 422 エラーで検証に失敗します。
fix_standalone_glycans boolean false 省略可。スタンドアロンのグリカン位置固定を有効にします。
flash_attention_implementation string null 省略可。使用する Flash 注意バックエンド実装。使用できる値は "triton"、"cudnn"、"xla" です。
num_recycles integer 10 省略可。推論中に使用するリサイクルの反復回数。正の整数（0 より大きい）を指定する必要があります。トレードオフについては、ベスト プラクティスのセクションをご覧ください。
num_diffusion_samples integer 5 省略可。生成する拡散サンプルの数。正の整数（0 より大きい）を指定する必要があります。トレードオフについては、ベスト プラクティスのセクションをご覧ください。
save_embeddings boolean false 省略可。最終的なトランクのシングル エンベディングとペア エンベディングを output_dir の場所に保存するかどうか。true の場合、エンベディングは seed-{SEED}_embeddings/ という名前のサブフォルダ（outputs_config_job_seed-50_embeddings.npz など）の下に .npz ファイルとして書き込まれます。
save_distogram boolean false 省略可。最終予測ディストグラムを output_dir の場所に保存するかどうか。true の場合、エンベディングは seed-{SEED}_embeddings/ という名前のサブフォルダ（outputs_config_job_seed-50_embeddings.npz など）の下に .npz ファイルとして書き込まれます。
compress_large_output_files boolean false 省略可。true の場合、zstandard を使用して大きな出力ファイル（mmCIF 構造と信頼度 JSON）を圧縮します。これにより、.cif と .json ではなく、.cif.zst と .json.zst の拡張子を持つファイルが出力されます。小さなファイル（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 の場合、この配列には正確に 1 つの予測結果オブジェクトが含まれます。

予測結果の詳細（predictions[]）

AlphaFold 3 予測エンドポイントは、最上位の候補の構造座標と信頼度指標を含む predictions 配列を含む HTTP 200 JSON レスポンスを返します。フィールドの定義と出力ファイル仕様の詳細については、GitHub の公式 AlphaFold 3 ドキュメントをご覧ください。

リクエストで parameters.output_dir が指定されているかどうかによって、API レスポンスの出力構造は異なります。

  • HTTP レスポンスの予測: インライン レスポンスは、HTTP JSON レスポンス ペイロード本文内で、グローバルな概要指標（summary）、3D 構造の座標（structure_cif）、原子ごとの信頼スコア（plddt）、2D 予測アラインメント エラー行列（pae）を直接返します。出力ディレクトリが指定されている場合、シリアル化のボトルネックを回避するため、大きなペイロード フィールド（structure_cif、plddt、pae）は HTTP レスポンス ペイロードから省略（null）されます。代わりに、すべての未加工のモデル出力が指定された Cloud Storage バケットに非同期でエクスポートされます。

  • Cloud Storage バケットに保存されたアーティファクト: 出力ディレクトリ（parameters.output_dir）が指定されている場合、包括的な予測結果が Cloud Storage にアップロードされます。出力フォルダには、GitHub の AlphaFold 3 ドキュメントで公開されている仕様に沿ったデータが含まれています。

予測の実行

Model Garden のデプロイにより、データ パイプラインやモデル推論などのエンドツーエンドの予測パイプラインを 1 回の API 呼び出しで簡単に実行できます。次の図は、AlphaFold 3 予測のアーキテクチャの概要を示しています。

AlphaFold 3 パイプラインのフローチャート。ステージ 1（遺伝子データベース検索パイプライン）では、Jackhmmer などの検索エンジンと UniProt などのデータベースを使用して、MSA と構造テンプレートを出力します。ステージ 2（構造モデル推論パイプライン）では、AlphaFold 3 拡散変換ニューラル ネットワークを使用してこれらの入力が処理されます。生成された 3D mmCIF 構造と信頼スコア（pLDDT、PAE、ipTM）は Cloud Storage に保存されます。

図 1. 予測パイプラインの完成

予測を実行する場合は、パラメータで Cloud Storage バケットを直接指定して、サンプルごとのサブディレクトリ、ランキング マニフェスト、未加工の出力など、未加工のデータセット全体をエクスポートすることを強くおすすめします。マルチシード サンプリング、ニューラル リサイクル、拡散軌跡、カスタム共有結合のパラメータ チューニングなど、構成可能なすべてのリクエスト フィールドの詳細な内訳については、API リファレンス セクションをご覧ください。

長時間実行されるフォールディング ジョブやバッチ パイプラインを起動する前に、ドライランを実行して、認証、IAM 権限、エンドポイントのネットワーク接続をすばやく確認できます。

予測オプション

ワークフローに応じて、AlphaFold 3 の処理は 4 つの異なる実行モードに分類できます。

ドライラン モード

予測パイプラインを開始せずに 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 と 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 予測サービスには、予測出力を取得するための 2 つの補完的な配信メカニズムが用意されています。デフォルトでは、API レスポンスは上位候補の予測結果を同期的にインラインで返します。必要に応じて、Cloud Storage ディレクトリを指定できます。

次のセクションでは、予測出力の概要について説明します。詳細については、GitHub の AlphaFold 3 のドキュメントをご覧ください。

インライン レスポンスと保存されたアーティファクト

AlphaFold 3 予測サービスは、次の 2 つの主要な出力パターンをサポートしています。

  • インライン レスポンス: 上位の候補の 3D 構造座標と信頼度指標のみを HTTP REST レスポンス ペイロード内で直接返します。これは、迅速なインタラクティブ プロトタイピングや単一シーケンス クエリに最適です。
  • 保存されたアーティファクト（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 構造のアンサンブルが生成されます。これらの候補実行を評価して比較すると、詳細な構造分析を行う前に予測出力を解釈するのに役立ちます。

次の 3 つのコアファイルを使用して、マルチサンプル アーティファクト データセット全体を調べることができます。

  • 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 分に設定されています。予測がタイムアウトせずに正常に完了するようにするには、次のガイドラインに沿ってください。

  • 1 回のリクエストで過剰なサンプリングを避ける: 1 回の API 呼び出しでシードの広範囲なスイープを初期化したり、逆拡散パラメータを過度に高く設定したりすると、実行時間が 60 分の上限を超える可能性があります。
  • 大規模なスイープを分解する: 大規模なスタディの場合は、シードとパラメータ スイープを複数の小さな予測ペイロードに分割し、個別のジョブとして送信します。また、エンドポイントの自動スケーリング容量も活用します。

遺伝子データベース検索パイプラインは、AlphaFold パイプラインの中で最も時間のかかるフェーズです。同じシーケンスで反復予測を実行する場合（固定されたタンパク質ターゲットでリガンド スクリーニング スイープを実行するなど）、データベース検索を完全にバイパスすることで、実行時間を大幅に最適化できます。

  • MSA を抽出する: Cloud Storage 出力ディレクトリ（output_dir）を指定して、初期のエンドツーエンド予測を実行します。生成された {JOB_NAME}_data.json ファイルを出力 Cloud Storage バケットからダウンロードします。
  • 推論のみの予測を送信する: JSON ファイル内の unpairedMsa フィールドと pairedMsa フィールドを見つけます。これらの MSA 文字列を抽出し、Cloud Storage URI を指す unpairedMsaPath と pairedMsaPath を使用して、後続の予測リクエストに渡します。

また、独自のインフラストラクチャで MSA 検索を実行し、事前計算された MSA テンプレートを予測リクエストに入力することもできます。

信頼度の低い実行を処理する

予測出力で信頼度の低い指標が生成された場合は、回復不能な予測エラーとして処理するのではなく、対象を絞った修復を試すことができます。特定のパラメータを最適化すると、代替の潜在軌跡を調べることができます。このセクションでは、信頼度の低い予測が発生した場合の復元方法をいくつか紹介します。

マルチシード サンプリングを使用する

AlphaFold 3 は、潜在空間のランダム ノイズから 3D 座標生成を初期化します。特定のシードを 1 つだけ使用して予測を送信すると、拡散軌道が別のシードとは異なるパスをたどる可能性があります。シードの配列を渡すと、モデルは異なる状態から始まる軌跡をサンプリングします。

マルチシード サンプリングには、独立した実行間で構造の整合性を検証し、機能的なコンフォメーション ダイナミクスをプローブするという 2 つの重要な利点があります。たとえば、5 つのシードがすべて同じ 3D 座標に収束した場合、グローバル フォールドの信頼性は高くなります。逆に、異なるシードから明確で信頼性の高い結合ポーズが生成される場合、アンサンブルは、開いた状態と閉じた状態の活性部位ループや、代替のドメイン交換二量体など、生物学的に意味のあるコンフォメーション状態を明らかにしている可能性があります。

拡散軌道を拡張する

modelSeeds は潜在空間の開始ノイズ状態を変更しますが、num_diffusion_samples パラメータ（デフォルトは 5）は、逆拡散プロセス中にシードごとに生成される 3D 構造の候補数を制御します。柔軟なループ領域または浅いバインディング ポケットの場合、サンプリングを増やすと、各シードの候補プールが拡大されます。これは、特定のループでローカル信頼スコアが低下している（pLDDT < 70）一方で、ドメイン全体のフォールドの信頼度が高い（pTM > 0.80）場合に特に効果的です。これにより、最初の実行で見逃された信頼性の高い候補構造を見つけることができます。

リサイクルの反復回数を増やす

拡散モジュールが 3D 座標を生成する前に、AlphaFold 3 はシーケンスとペアワイズの特徴を処理します。num_recycles パラメータは、中間構造表現とペアワイズ空間エンベディングがネットワークを介して反復的にフィードバックされる回数を決定します。

大きな複雑な分子や、共進化シグナルが弱いターゲットの場合、num_recycles を大きくすると、拡散モジュールに入力を渡す前に、遠い鎖間の空間関係を解決するための追加の反復処理がトランク ネットワークに与えられます。このアプローチは、個々のチェーンで高いローカル フォールド信頼度（pLDDT > 70）が示されているにもかかわらず、オフ対角 PAE 行列で高いチェーン間不確実性（> 15 Å）が示されている場合に試すことができます。リサイクルを増やすと予測の実行時間が線形に増加するため、難しいインターフェース ターゲット用に予約する必要があります。

カスタム アライメント パイプラインを使用する

AlphaFold 3 は、遺伝子データベース検索パイプラインを自動的に実行して MSA テンプレートを生成します。ユーザーは、unpairedMsaPath と pairedMsaPath を使用して、Cloud Storage URI を使用して .a3m 形式でプライベートな事前計算されたカスタム アライメントを指定することもできます。深い MSA を提供すると、強い共進化制約が提供され、信頼度の低い予測が信頼度の高いモデルに変換されることがよくあります。