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 화학 성분 사전 (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 요청의 크기 제한은 8MB입니다. 추론 전용 모드를 사용하는 경우 페이로드 거부를 방지하려면 대규모 사전 계산된 정렬(.a3m 파일)을 인라인 문자열로 삽입하는 대신 Cloud Storage URI를 사용하여 참조해야 합니다.

  • 네트워크 구성: 예측은 완료하는 데 최대 60분이 걸릴 수 있는 장기 실행 작업이므로 Private Service Connect (PSC)를 사용하여 엔드포인트를 배포하여 표준 엔드포인트 제한 시간인 10분을 우회해야 합니다.

배포 안내

이 섹션에서는 Google Cloud 프로젝트의 Agent Platform에서 제공하는 엔드포인트에 AlphaFold 3를 배포하는 방법을 자세히 설명합니다.

시작하기 전에

AlphaFold 3를 배포하기 전에 다음을 충족해야 합니다.

  • 모델 액세스 권한을 요청합니다.
  • GPU 리소스를 조달합니다.
  • 필요한 ID 및 액세스 관리 (IAM) 권한을 구성합니다.
    • Agent Platform 관리자 IAM 역할이 있는 서비스 계정을 만듭니다.
    • 모델을 배포하는 동안 서비스 계정 역할을 할 수 있는 roles/iam.serviceAccountCreator 역할이 IAM 주 구성원에 있는지 확인합니다.
  • 리소스 할당량을 확인합니다.

리소스 요구사항

AlphaFold 3에는 a3-highgpu-1g 가상 머신 (VM)이 필요합니다.

배포하기 전에 Google Cloud 프로젝트에 다음 리소스에 대한 대상 배포 리전의 할당량이 충분한지 확인합니다.

  • 가속기: a3-highgpu-1g 머신 유형이 하나 이상 있어야 합니다.

  • 로컬 SSD: A3 VM에는 750GB의 로컬 SSD 공간이 프로비저닝됩니다. 이는 모든 예측 요청에서 유전 데이터베이스 검색 (Jackhmmer/Nhmmer) 중에 지연 시간이 짧은 읽기를 지원하기 위해 참조 시퀀스 데이터베이스(UniProt, MGnify, Rfam)를 영구적으로 캐시하는 데 필요합니다.

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를 사용하여 엔드포인트에 예측 요청을 보냅니다.
    • roles/storage.objectUser를 사용하여 Cloud Storage 버킷의 예측 출력에 액세스합니다.

AlphaFold 3 배포

Google Cloud 전용 엔드포인트 또는 Private Service Connect 엔드포인트로만 Agent Platform SDK를 사용하여 AlphaFold 3를 프로그래매틱 방식으로 배포합니다. GPU 사용 가능 여부에 따라 엔드포인트가 추론을 위해 준비되는 데 10~15분이 걸릴 수 있습니다.

다음은 추론 시간 제한 확장을 포함하여 Google Cloud 프로젝트에 모델을 배포하는 방법을 보여주는 샘플 Python 스니펫입니다.

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 필수. 예측할 생물학적 서열 구성 목록입니다. 이 목록에는 정확히 하나의 요소가 포함되어야 합니다. 요소를 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 선택사항. 사용할 플래시 어텐션 백엔드 구현입니다. 허용되는 값은 "triton", "cudnn", "xla"입니다.
num_recycles integer 10 선택사항. 추론 중에 사용할 재활용 반복 횟수입니다. 양의 정수 (0보다 큼)여야 합니다. 권장사항 섹션에서 장단점을 알아보세요.
num_diffusion_samples integer 5 선택사항. 생성할 확산 샘플 수입니다. 양의 정수 (0보다 큼)여야 합니다. 권장사항 섹션에서 장단점을 알아보세요.
save_embeddings boolean false 선택사항. 최종 트렁크 싱글 및 페어 임베딩을 output_dir 위치에 저장할지 여부입니다. true인 경우 임베딩은 seed-{SEED}_embeddings/라는 하위 폴더 아래에 .npz 파일로 작성됩니다 (예: outputs_config_job_seed-50_embeddings.npz).
save_distogram boolean false 선택사항. 최종 예측 디스토그램을 output_dir 위치에 저장할지 여부입니다. true인 경우 임베딩은 seed-{SEED}_embeddings/라는 하위 폴더 아래에 .npz 파일로 작성됩니다 (예: outputs_config_job_seed-50_embeddings.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의 경우 이 배열에는 정확히 하나의 예측 결과 객체가 포함됩니다.

예측 결과 세부정보 (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 배포를 사용하면 데이터 파이프라인과 모델 추론을 포함한 엔드 투 엔드 예측 파이프라인을 단일 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 예측 서비스는 예측 출력을 가져오기 위한 두 가지 보완적인 전송 메커니즘을 제공합니다. 기본적으로 API 응답은 순위가 가장 높은 후보에 대해 동기식으로 인라인 예측 결과를 반환합니다. 필요한 경우 Cloud Storage 디렉터리를 지정할 수 있습니다.

다음 섹션에서는 예측 출력에 대해 간략하게 설명합니다. 자세한 내용은 GitHub의 AlphaFold 3 문서를 참고하세요.

인라인 응답과 저장된 아티팩트 비교

AlphaFold 3 예측 서비스는 두 가지 기본 출력 패턴을 지원합니다.

  • 인라인 응답: HTTP REST 응답 페이로드 내에서 직접 상위 순위 후보의 3D 구조 좌표와 신뢰도 측정항목만 반환합니다. 이는 빠른 대화형 프로토타입 제작이나 단일 시퀀스 쿼리에 적합합니다.
  • 저장된 아티팩트 (Cloud Storage): 출력 디렉터리를 지정하면 전체 다중 샘플 데이터 세트가 Cloud Storage로 내보내집니다. 여기에는 생성된 모든 무작위 시드와 확산 샘플의 개별 좌표 파일, 신뢰도 JSON, 디스토그램, 삽입, 요약 측정항목이 포함됩니다. 프로덕션 워크로드, 컨포메이션 앙상블 매핑, 요청 페이로드 크기 제한 우회에는 Cloud Storage를 사용하는 것이 좋습니다.

다음은 다운스트림 분석을 위해 Cloud Storage에서 저장된 아티팩트를 가져오는 방법을 보여주는 Python 예시입니다.

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 예측 품질 평가 방법 가이드도 참고하세요.

권장사항

다음 섹션에서는 에이전트 플랫폼에서 AlphaFold 3를 사용할 때의 권장사항을 설명합니다.

요청 제한 시간 완화

Agent Platform의 엔드포인트는 요청당 기본 최대 실행 제한 시간을 60분으로 적용합니다. 예측이 시간 초과 없이 성공적으로 완료되도록 하려면 다음 가이드라인을 준수하세요.

  • 단일 요청에서 과도한 샘플링 방지: 단일 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 좌표 생성을 초기화합니다. 특정 시드 하나로 예측을 제출하면 확산 궤적이 다른 시드와 다른 경로를 따를 수 있습니다. 시드 배열을 전달하면 모델이 서로 다른 상태에서 시작하는 궤적을 샘플링합니다.

멀티 시드 샘플링은 독립적인 실행 전반에서 구조적 일관성을 검증하고 기능적 컨포메이션 역학을 조사하는 두 가지 중요한 이점을 제공합니다. 예를 들어 5개의 시드가 모두 동일한 3D 좌표로 수렴되면 전역 폴드에 대한 신뢰도가 높아집니다. 반대로 서로 다른 시드에서 명확하고 신뢰도가 높은 결합 포즈가 생성되면 앙상블이 열린 활성 부위 루프와 닫힌 활성 부위 루프 또는 대체 도메인 스왑 이합체와 같은 생물학적으로 의미 있는 컨포메이션 상태를 나타낼 수 있습니다.

확산 궤적 펼치기

modelSeeds는 잠재 공간에서 시작 노이즈 상태를 변경하는 반면 num_diffusion_samples 매개변수 (기본값 5)는 역확산 프로세스 중에 시드당 생성되는 후보 3D 구조의 수를 제어합니다. 유연한 루프 영역이나 얕은 결합 포켓의 경우 샘플링을 늘리면 각 시드의 후보 풀이 확장됩니다. 이는 전체 도메인 폴드가 신뢰할 수 있는 상태 (pTM > 0.80)인 반면 특정 루프에서 로컬 신뢰도 점수가 떨어지는 경우 (pLDDT < 70) 특히 효과적입니다. 이를 통해 초기 실행에서 누락되었을 수 있는 신뢰도가 높은 후보 구조를 발견할 수 있습니다.

재활용 반복 증가

확산 모듈이 3D 좌표를 생성하기 전에 AlphaFold 3는 시퀀스와 쌍별 특징을 처리합니다. num_recycles 매개변수는 중간 구조 표현과 쌍별 공간 삽입이 네트워크를 통해 반복적으로 다시 공급되는 횟수를 지정합니다.

크고 복잡한 분자 또는 공진화 신호가 약한 타겟의 경우 num_recycles를 늘리면 트렁크 네트워크가 확산 모듈에 입력을 전달하기 전에 먼 체인 간의 공간적 관계를 해결하기 위한 추가 반복이 제공됩니다. 이 접근 방식은 개별 체인이 높은 로컬 폴드 신뢰도(pLDDT > 70)를 보이는 데도 비대각 PAE 행렬이 높은 체인 간 불확실성(> 15 Å)을 보이는 경우 시도할 수 있습니다. 재활용을 늘리면 예측 런타임이 선형으로 증가하므로 어려운 인터페이스 타겟에만 사용해야 합니다.

맞춤 정렬 파이프라인 사용

AlphaFold 3는 유전 데이터베이스 검색 파이프라인을 자동으로 실행하여 MSA 템플릿을 생성합니다. 사용자는 unpairedMsaPath 및 pairedMsaPath를 사용하여 Cloud Storage URI를 통해 .a3m 형식으로 사전 계산된 비공개 맞춤 정렬을 제공할 수도 있습니다. 심층 MSA를 제공하면 강력한 공진화 제약 조건이 제공되어 신뢰도가 낮은 예측이 신뢰도가 높은 모델로 변환되는 경우가 많습니다.