Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

AlphaFold 3

AlphaFold 3 è un modello di deep learning sviluppato da Google DeepMind e Isomorphic Labs. È progettato per prevedere le strutture e le interazioni tridimensionali di proteine, DNA, RNA, ligandi e ioni. Questo documento descrive come eseguire il deployment e utilizzare il modello AlphaFold 3 utilizzando Model Garden su Gemini Enterprise Agent Platform.

Funzionalità chiave

Il deployment di AlphaFold 3 su Agent Platform fornisce le seguenti funzionalità necessarie per la ricerca e lo sviluppo (R&S) avanzati e per i workflow commerciali di scoperta di farmaci:

Uso commerciale: AlphaFold 3 su Model Garden è disponibile per l'uso commerciale.
Ligandi personalizzati arbitrari: AlphaFold 3 supporta il ripiegamento unificato di proteine, DNA e RNA insieme a ligandi personalizzati definiti utilizzando stringhe SMILES o codici CIF Chemical Component Dictionary (CCD).
Flessibilità del flusso di lavoro: AlphaFold 3 su Model Garden supporta la pipeline di folding end-to-end completa (che combina la ricerca nel database e la previsione del modello) o una modalità solo inferenza in cui puoi fornire allineamenti MSA precalcolati per ottimizzare il tempo di esecuzione e l'utilizzo della GPU.

Considerazioni

Quando valuti AlphaFold 3 per i carichi di lavoro, tieni presente i seguenti vincoli:

Concurrency: l'endpoint AlphaFold 3 ha un limite di concorrenza di uno per nodo. Per una maggiore concorrenza, gli endpoint possono essere scalati a più nodi. Se viene inviata una richiesta di previsione mentre un'altra previsione è in esecuzione, l'endpoint rifiuta la nuova richiesta con un errore HTTP 429 Too Many Requests se il numero di richieste è superiore al numero di nodi.
Limiti di token: la durata massima della previsione sugli endpoint di Agent Platform è di 60 minuti. A causa dell'overhead variabile della ricerca MSA, la dimensione massima della sequenza supportata sulle GPU A3 è di circa 4500 token biologici (come amminoacidi, nucleotidi o atomi di ligando). Fornire allineamenti precalcolati aggira l'esecuzione della ricerca MSA, il che consente un folding complesso fino al limite hardware di circa 5400 token.
Limiti del payload: le richieste REST di previsione standard hanno un limite di dimensione di 8 MB. Se utilizzi la modalità di sola inferenza, è necessario fare riferimento a grandi allineamenti precalcolati (file .a3m) utilizzando URI Cloud Storage anziché incorporarli come stringhe inline per evitare il rifiuto del payload.
Configurazione di rete: poiché le previsioni sono operazioni di lunga durata che possono richiedere fino a 60 minuti per essere completate, devi eseguire il deployment dell'endpoint con Private Service Connect (PSC) per bypassare i limiti di timeout standard dell'endpoint di 10 minuti.

Istruzioni per il deployment

Questa sezione descrive in dettaglio il deployment di AlphaFold 3 su un endpoint fornito da Agent Platform in un progetto Google Cloud .

Prima di iniziare

Prima di eseguire il deployment di AlphaFold 3, devi:

Richiedi l'accesso al modello.
Acquista risorse GPU.
Configura le autorizzazioni Identity and Access Management (IAM) richieste:
- Crea un account di servizio con il ruolo IAM Agent Platform Administrator.
- Assicurati che la tua entità IAM disponga del ruolo roles/iam.serviceAccountCreator per agire comeaccount di serviziot durante il deployment del modello.
Verifica le quote delle risorse.

Requisiti delle risorse

AlphaFold 3 richiede una macchina virtuale (VM) a3-highgpu-1g.

Prima del deployment, assicurati che il tuo progetto Google Cloud disponga di una quota sufficiente nella regione di deployment di destinazione per le seguenti risorse:

Acceleratori: almeno un tipo di macchina a3-highgpu-1g.
SSD locale: la VM A3 viene sottoposta a provisioning con 750 GB di spazio SSD locale. Questo è necessario per memorizzare nella cache in modo permanente i database delle sequenze di riferimento (UniProt, MGnify, Rfam), consentendo letture a bassa latenza durante le ricerche nei database genetici (Jackhmmer/Nhmmer) in tutte le richieste di previsione.

Bucket Cloud Storage

AlphaFold 3 richiede un bucket Cloud Storage per archiviare i file MSA forniti ed esportare gli output di previsione completi. Per evitare trasferimenti tra regioni, ti consigliamo di utilizzare un bucket Cloud Storage nella stessa regione dell'endpoint o un bucket multiregionale.

Ruoli Identity and Access Management

Configura i seguenti ruoli per le identità partecipanti:

Deployment del modello (noto anche come amministratore IT): l'identità che esegue il deployment del modello richiede l'autorizzazione roles/aiplatform.admin per creare endpoint e gestire i deployment.
Identità di pubblicazione: durante l'esecuzione dell'inferenza, gli endpoint AlphaFold 3 scrivono le strutture di output direttamente in Cloud Storage utilizzando il account di servizio del progetto tenant. Il account di servizio corrispondente richiede roles/storage.objectUser nel bucket Cloud Storage di destinazione.
Utenti modello: gli account che avviano le previsioni richiedono quanto segue:
- roles/aiplatform.user per inviare richieste di previsione all'endpoint.
- roles/storage.objectUser per accedere agli output di previsione nel bucket Cloud Storage.

Esegui il deployment di AlphaFold 3

Esegui il deployment di AlphaFold 3 a livello di programmazione utilizzando l'SDK Agent Platform come endpoint Google Cloud dedicato o come endpoint Private Service Connect. A seconda della disponibilità della GPU, potrebbero essere necessari 10-15 minuti prima che l'endpoint sia pronto per l'inferenza.

Di seguito è riportato un esempio di snippet Python che mostra come eseguire il deployment del modello in un progetto Google Cloud , inclusa un'estensione del timeout di inferenza:

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}")

Riferimento API

Questa sezione descrive la posizione dell'endpoint, il formato dell'URL, i parametri di percorso e lo schema del payload della richiesta.

Richiesta HTTP

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

Sostituisci quanto segue:

HOST: l'host dell'endpoint di servizio. Ciò dipende dal fatto che il tipo di deployment sia un endpoint pubblico dedicato o utilizzi Private Service Connect.
PROJECT_ID: l' Google Cloud ID progetto che ospita l'endpoint di cui è stato eseguito il deployment.
LOCATION: la Google Cloud regione in cui viene eseguito il deployment dell'endpoint (ad esempio us-central1).
ENDPOINT_ID: l'identificatore univoco dell'endpoint Agent Platform di cui è stato eseguito il deployment.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura 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
  }
}

Campi di richiesta di primo livello

Campo	Tipo	Descrizione
`instances`	`array`	Obbligatorio. L'elenco delle configurazioni delle sequenze biologiche da prevedere. Questo elenco deve contenere esattamente un elemento. Il passaggio di zero o più di un elemento genera un errore `HTTP 422 Unprocessable Entity`. Il corpo di `instances` deve specificare gli input in base alle specifiche pubblicate nella documentazione di AlphaFold 3.
`parameters`	`object`	Facoltativo. Un oggetto contenente parametri di esecuzione per configurare l'esecuzione della previsione (ad esempio `dry_run`, `output_dir`).

Parametri

Configura i flag di esecuzione per l'esecuzione di AlphaFold 3.

Campo	Tipo	Valore predefinito	Descrizione
`dry_run`	`boolean`	`false`	Facoltativo. Se `true`, l'API esegue la convalida della richiesta, ma ignora l'esecuzione del modello e restituisce immediatamente una risposta vuota. Utile per i controlli di connettività e sintassi.
`run_data_pipeline`	`boolean`	`true`	Facoltativo. Se `true`, esegue la pipeline completa (ricerca e inferenza MSA). Se `false`, esegue solo l'inferenza (salta la ricerca nel database; richiede MSA precalcolati). Per ulteriori dettagli, consulta la documentazione su GitHub.
`output_dir`	`string`	`null`	Facoltativo. L'URI Cloud Storage (ad esempio `gs://bucket/path`) in cui vengono caricati i file di output non elaborati completi (inclusi i CSV di strutture CIF, PAE e ranking) dopo l'esecuzione riuscita.
`force_output_dir`	`boolean`	`false`	Facoltativo. Se `true`, consente di sovrascrivere i file esistenti nel `output_dir` specificato. Se `false`, l'API restituisce immediatamente un errore `HTTP 400 Bad Request` se il percorso Cloud Storage non è vuoto per evitare la perdita accidentale di dati.
`resolve_msa_overlaps`	`boolean`	`true`	Facoltativo. Se deduplicare o meno gli MSA non accoppiati rispetto a quelli accoppiati. Per le best practice, consulta le linee guida nella documentazione di GitHub AlphaFold 3.
`max_template_date`	`string`	`null`	Facoltativo. Data di rilascio massima del modello da considerare nel formato `YYYY-MM-DD` (ad esempio, `"2024-05-15"`). La convalida non riesce e viene visualizzato un errore `HTTP 422` se la formattazione non è corretta.
`conformer_max_iterations`	`integer`	`null`	Facoltativo. Override per il numero massimo di iterazioni da eseguire per la ricerca di conformeri RDKit. Deve essere un numero intero non negativo (maggiore o uguale a zero). La convalida non riesce e restituisce un errore `HTTP 422` per i valori negativi.
`fix_standalone_glycans`	`boolean`	`false`	Facoltativo. Consente il fissaggio indipendente della posizione del glicano.
`flash_attention_implementation`	`string`	`null`	Facoltativo. Implementazione del backend di Flash Attention da utilizzare. I valori consentiti sono `"triton"`, `"cudnn"`, `"xla"`.
`num_recycles`	`integer`	`10`	Facoltativo. Numero di iterazioni di riciclo da utilizzare durante l'inferenza. Deve essere un numero intero positivo (maggiore di zero). Consulta la sezione delle best practice per scoprire i compromessi.
`num_diffusion_samples`	`integer`	`5`	Facoltativo. Numero di campioni di diffusione da generare. Deve essere un numero intero positivo (maggiore di zero). Consulta la sezione delle best practice per scoprire i compromessi.
`save_embeddings`	`boolean`	`false`	Facoltativo. Se salvare gli incorporamenti finali del tronco singolo e della coppia nella posizione `output_dir`. Se `true`, gli incorporamenti vengono scritti come file `.npz` in una sottocartella denominata `seed-{SEED}_embeddings/` (ad esempio `outputs_config_job_seed-50_embeddings.npz`).
`save_distogram`	`boolean`	`false`	Facoltativo. Indica se salvare il distogramma finale previsto nella posizione `output_dir`. Se `true`, gli incorporamenti vengono scritti come file `.npz` in una sottocartella denominata `seed-{SEED}_embeddings/` (ad esempio, `outputs_config_job_seed-50_embeddings.npz`).
`compress_large_output_files`	`boolean`	`false`	Facoltativo. Se `true`, comprime i file di output di grandi dimensioni (strutture mmCIF e JSON di confidenza) utilizzando zstandard. Vengono generati file con estensioni `.cif.zst` e `.json.zst` anziché `.cif` e `.json`. I file di piccole dimensioni (ad esempio `ranking_scores.csv`) rimangono non compressi.
`num_seeds`	`integer`	`null`	Facoltativo. Numero di seed casuali da utilizzare per l'inferenza. In generale, devi impostare i valori iniziali all'interno del campo `instances.modelSeeds` per la riproducibilità. Consulta la sezione delle best practice per scoprire i compromessi.

Risposta (output)

Questa sezione descrive i campi restituiti nella risposta dell'API dopo l'esecuzione riuscita.

Corpo della risposta

Se l'esecuzione va a buon fine, l'endpoint restituisce la risposta nel formato dello schema di previsione online standard di 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"
    }
  ]
}

Campi di risposta di primo livello

Campo	Tipo	Descrizione
`deployedModelId`	`string`	L'ID del modello di cui è stato eseguito il deployment sull'endpoint Agent Platform.
`model`	`string`	Il nome risorsa completo del modello.
`modelDisplayName`	`string`	Il nome visualizzato del modello di cui è stato eseguito il deployment (sempre `"alphafold3"`).
`modelVersionId`	`string`	L'ID versione del modello di cui è stato eseguito il deployment.
`predictions`	`array`	L'elenco dei risultati della previsione. Per AlphaFold 3, questo array contiene esattamente un oggetto risultato della previsione.

Dettagli del risultato della previsione (`predictions[]`)

L'endpoint di previsione di AlphaFold 3 restituisce una risposta JSON HTTP 200 contenente un array predictions con coordinate strutturali e metriche di confidenza per il candidato con il ranking più alto. Per definizioni complete dei campi e specifiche dei file di output, consulta la documentazione ufficiale di AlphaFold 3 su GitHub.

A seconda che parameters.output_dir sia fornito nella richiesta, la struttura dell'output nella risposta API può variare:

Previsione nella risposta HTTP: la risposta inline restituisce metriche di riepilogo globali (summary), coordinate della struttura 3D (structure_cif), punteggi di confidenza per atomo (plddt) e la matrice di errore di allineamento previsto 2D (pae) direttamente nel corpo del payload della risposta JSON HTTP. Quando viene specificata una directory di output, i campi di payload di grandi dimensioni (structure_cif, plddt e pae) vengono omessi (null) dal payload della risposta HTTP per evitare colli di bottiglia di serializzazione. Al contrario, tutti gli output del modello non elaborati vengono esportati in modo asincrono nel bucket Cloud Storage specificato.

Nota :la matrice pae viene scalata in modo quadratico con la lunghezza della sequenza N. Per sequenze di grandi dimensioni o assemblaggi complessi, la restituzione della matrice PAE N x N completa in linea genera payload JSON di grandi dimensioni che causano ritardi nella serializzazione HTTP o attivano errori di dimensione del payload del gateway. Per le sequenze di grandi dimensioni, parameters.output_dir deve essere specificato.
Artefatto salvato nel bucket Cloud Storage: quando viene specificata una directory di output (parameters.output_dir), i risultati della previsione completa vengono caricati in Cloud Storage. La cartella di output contiene i dati in base alla specifica pubblicata nella documentazione di AlphaFold 3 su GitHub.

Fai previsioni

Il deployment di Model Garden semplifica l'esecuzione della pipeline di previsione end-to-end, inclusi la pipeline di dati e l'inferenza del modello in una singola chiamata API. Il seguente diagramma mostra l'architettura di alto livello delle previsioni di AlphaFold 3:

Fig. 1 Pipeline di previsione completa

Quando esegui le previsioni, ti consigliamo vivamente di fornire un bucket Cloud Storage direttamente nei parametri per esportare l'intero set di dati non elaborati, incluse le sottodirectory per campione, i manifest di ranking e gli output non elaborati. Per un'analisi completa di tutti i campi di richiesta configurabili, inclusa la regolazione dei parametri per il campionamento multi-seed, il riciclo neurale, le traiettorie di diffusione e i legami covalenti personalizzati, consulta la sezione Riferimento API.

Prima di avviare job di folding a esecuzione prolungata o pipeline batch, puoi eseguire un dry run per verificare rapidamente l'autenticazione, le autorizzazioni IAM e la connettività di rete degli endpoint.

Opzioni di previsione

A seconda del flusso di lavoro, l'elaborazione di AlphaFold 3 può essere organizzata in quattro modalità di esecuzione distinte:

Modalità dry run
Modalità di previsione end-to-end
Inferenza solo con MSA e modelli precalcolati
Esecuzione senza MSA e modelli

Modalità dry run

Per verificare la connettività API, l'autenticazione, il networking e gli schemi JSON senza avviare la pipeline di previsione, puoi inviare una richiesta con "dry_run": true nell'oggetto parameters. L'endpoint esegue tutte le routine di convalida (inclusa la verifica delle autorizzazioni di scrittura del bucket Cloud Storage e la convalida dei caratteri di sequenza), ma salta l'esecuzione, restituendo immediatamente una risposta di previsione vuota.

Di seguito è riportato un esempio di script Python per la modalità dry run:

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)

Modalità di previsione end-to-end

Per eseguire la previsione end-to-end, invia sequenze biologiche non elaborate (proteine, DNA, RNA, ligandi e PTM) in un'unica richiesta. L'endpoint esegue automaticamente la ricerca nel database genetico seguita immediatamente dall'inferenza del modello. Questa opzione è consigliata per i lavori di piegatura senza allineamenti preesistenti.

Di seguito è riportato un esempio di script Python per la modalità di previsione end-to-end:

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)

Solo inferenza con MSA e modelli precalcolati

Potresti già disporre di modelli MSA e mmCIF precalcolati da un'esecuzione precedente o generati al di fuori dell'endpoint del modello. In questi scenari, la ricerca nel database genetico può essere ignorata completamente fornendo gli allineamenti e i modelli, indirizzando la richiesta direttamente per la previsione della struttura. In questo modo, è possibile ridurre in modo significativo anche il tempo di risposta dell'inferenza. Questo è il percorso consigliato nei seguenti scenari:

Quando vengono agganciati più ligandi di piccole molecole diversi a un singolo target proteico statico, gli MSA possono essere riutilizzati.
Eseguire la stessa sequenza di molecole su più seed casuali, in modo iterativo, per mappare la flessibilità strutturale.
Allineamento offline delle sequenze con database genomici privati e non pubblici.
Ottimizzazione delle risorse GPU per AlphaFold 3, per concentrarsi solo sulla generazione della struttura.

Di seguito è riportato un esempio di script Python per la modalità di sola inferenza:

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)

Esecuzione senza MSA e modelli

Esiste anche l'opzione in cui la ricerca nel database genetico e la corrispondenza dei modelli possono essere completamente ignorate. Il modello prevede la struttura 3D utilizzando solo la sequenza di query, senza sequenze omologhe o informazioni coevolutive. Per attivare questa modalità, fornisci stringhe vuote per i parametri MSA unpairedMsa e pairedMsa e un elenco vuoto per templates nell'istanza e imposta run_data_pipeline su false nei parametri. Questo può essere utile per la progettazione di molecole sintetiche o ingegnerizzate o per testare le previsioni strutturali in assenza di un contesto evolutivo.

Di seguito è riportato un esempio di script Python per l'esecuzione di AlphaFold 3 MSA- e senza modelli:

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)

Per specifiche dettagliate, parametri delle entità e metriche di confidenza dell'output, consulta la documentazione di AlphaFold 3 su GitHub.

Output di previsione

Il servizio di previsione AlphaFold 3 fornisce due meccanismi di distribuzione complementari per recuperare gli output di previsione. Per impostazione predefinita, la risposta API restituisce i risultati della previsione in linea in modo sincrono per il candidato con il ranking più alto. Facoltativamente, puoi specificare una directory Cloud Storage.

La sezione seguente fornisce una panoramica dell'output della previsione. Per maggiori dettagli, consulta la documentazione di AlphaFold 3 su GitHub.

Risposta in linea e artefatti salvati

Il servizio di previsioni AlphaFold 3 supporta due pattern di output principali:

Risposta incorporata: restituisce le coordinate della struttura 3D e le metriche di confidenza solo per il candidato con il ranking più alto direttamente all'interno del payload della risposta HTTP REST. È ideale per la prototipazione interattiva rapida o per le query a sequenza singola.
Artefatti salvati (Cloud Storage): se specifichi una directory di output, l'intero set di dati multi-sample viene esportato in Cloud Storage. Sono inclusi file di coordinate individuali, file JSON di confidenza, distogrammi, incorporamenti e metriche di riepilogo per ogni seed casuale e campione di diffusione generato. L'utilizzo di Cloud Storage è consigliato per i carichi di lavoro di produzione, la mappatura di insiemi conformazionali e l'aggiramento del limite di dimensioni del payload della richiesta.

Di seguito è riportato un esempio Python di come recuperare gli artefatti salvati da Cloud Storage per l'analisi downstream:

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")

Poiché AlphaFold 3 utilizza un modello di diffusione generativa, ogni esecuzione di previsione genera un insieme di strutture 3D candidate tra i seed e le traiettorie di campionamento. La valutazione e il confronto di queste esecuzioni candidate possono aiutarti a interpretare gli output di previsione prima di eseguire un'analisi strutturale dettagliata.

Puoi esaminare il set di dati completo dell'artefatto multi-sample utilizzando tre file principali:

ranking_scores.csv: il registro principale che elenca ogni coppia di traiettorie generate e il relativo ranking_score. Le righe vengono salvate nell'ordine di esecuzione della traiettoria (ordinate in base al seme in ordine crescente, poi all'indice del campione in ordine crescente), non preordinate in base al punteggio. Gli utenti devono ordinare in ordine decrescente in base a ranking_score per identificare i ranking dei candidati.
summary_confidences.json: contiene metriche di qualità globali (pTM, ipTM, has_clash, fraction_disordered) per il candidato migliore.
Per campione summary_confidences.json: si trova all'interno delle singole cartelle seed-{SEED}_sample-{INDEX}/, consentendoti di esaminare le matrici pTM e ipTM a livello di catena per specifiche esecuzioni non principali candidate, se necessario.

Il seguente esempio di Python analizza ranking_scores.csv e summary_confidences.json per classificare i campioni candidati e convalidare la qualità del candidato migliore:

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}")

Per le specifiche dello schema esaustive dei file salvati e degli attributi mmCIF, consulta la documentazione di AlphaFold 3 su GitHub. Consulta anche la guida Come valutare la qualità delle previsioni di AlphaFold 3 su EMBL-EBI per capire come valutare la qualità delle previsioni.

Best practice

Le sezioni seguenti descrivono le best practice per l'utilizzo di AlphaFold 3 su Agent Platform:

Mitigare i timeout delle richieste

Gli endpoint sulla piattaforma Agent Platform applicano un timeout di esecuzione massimo predefinito di 60 minuti per richiesta. Per assicurarti che le previsioni vengano completate correttamente senza timeout, segui queste linee guida:

Evita un campionamento eccessivo in una singola richiesta: l'inizializzazione di una vasta gamma di seed o parametri di diffusione inversa eccessivamente elevati in una singola chiamata API può causare il superamento del limite di tempo di esecuzione di 60 minuti.
Decomporre le scansioni di grandi dimensioni: per gli studi su larga scala, dividi le scansioni di semi e parametri in più payload di previsione più piccoli e inviali come job separati. In questo modo vengono sfruttate anche le capacità di scalabilità automatica dell'endpoint.

Ignora ricerca MSA

La pipeline di ricerca nel database genetico è la fase più lunga della pipeline AlphaFold. Quando esegui previsioni iterative sulla stessa sequenza (ad esempio, esegui scansioni di screening dei ligandi su un target proteico fisso), puoi ottimizzare notevolmente i tempi di esecuzione ignorando completamente la ricerca nel database:

Estrai l'MSA: esegui una previsione end-to-end iniziale con una directory di output di Cloud Storage (output_dir) specificata. Scarica il file {JOB_NAME}_data.json generato dal bucket Cloud Storage di output.
Invia previsioni solo di inferenza: individua i campi unpairedMsa e pairedMsa all'interno del file JSON. Estrai queste stringhe MSA e passale alle richieste di previsione successive utilizzando unpairedMsaPath e pairedMsaPath che puntano agli URI Cloud Storage.

In alternativa, puoi eseguire la ricerca MSA sulla tua infrastruttura e inserire i modelli MSA precalcolati nella richiesta di previsione.

Gestire le esecuzioni con confidenza bassa

Quando gli output di previsione generano metriche di bassa confidenza, anziché trattarli come errori di previsione irrecuperabili, puoi tentare una correzione mirata. L'ottimizzazione di parametri specifici consente di analizzare traiettorie latenti alternative. Questa sezione elenca alcuni approcci per il recupero in caso di previsioni con bassa confidenza.

Utilizzare il campionamento multi-seed

AlphaFold 3 inizializza la generazione di coordinate 3D dal rumore casuale nello spazio latente. Quando una previsione viene inviata con un singolo seme certo, la traiettoria di diffusione potrebbe seguire un percorso diverso rispetto a un altro seme. Il passaggio di un array di seed forza il modello a campionare traiettorie a partire da stati diversi.

Il campionamento multi-seed offre due vantaggi fondamentali: verifica la coerenza strutturale tra esecuzioni indipendenti e analizza la dinamica conformazionale funzionale. Se, ad esempio, tutti e cinque i punti di partenza convergono su coordinate 3D identiche, puoi avere un'alta confidenza nella piega globale. Al contrario, se semi diversi producono pose di legame distinte e ad alta confidenza, l'ensemble potrebbe rivelare stati conformazionali biologicamente significativi, come anse del sito attivo aperte e chiuse o dimeri alternativi con scambio di domini.

Espandi le traiettorie di diffusione

Mentre modelSeeds altera lo stato del rumore iniziale nello spazio latente, il parametro num_diffusion_samples (valore predefinito 5) controlla il numero di strutture 3D candidate generate per seme durante il processo di diffusione inversa. Per le regioni di loop flessibili o le tasche di legame superficiale, l'aumento del campionamento espande il pool di candidati per ogni seme. Ciò è particolarmente efficace quando i punteggi di confidenza locali scendono in loop specifici (pLDDT < 70) mentre la piega complessiva del dominio rimane affidabile (pTM > 0,80). Ciò può contribuire a scoprire strutture di candidati con un'alta probabilità di successo che sarebbero state trascurate nell'esecuzione iniziale.

Aumenta le iterazioni di riciclo

Prima che il modulo di diffusione generi le coordinate 3D, AlphaFold 3 elabora le funzionalità di sequenza e a coppie. Il parametro num_recycles determina quante volte le rappresentazioni della struttura intermedia e gli incorporamenti spaziali accoppiati vengono reinseriti iterativamente nella rete.

Per molecole grandi e complesse o target con segnali di coevoluzione deboli, l'aumento di num_recycles offre alla rete principale iterazioni aggiuntive per risolvere le relazioni spaziali tra catene distanti prima di passare gli input al modulo di diffusione. Questo approccio può essere tentato quando le matrici PAE non diagonali mostrano un'elevata incertezza intercatena (> 15 Å) nonostante le singole catene mostrino un'elevata confidenza di ripiegamento locale (pLDDT > 70). Tieni presente che l'aumento dei ricicli aumenta linearmente il tempo di esecuzione della previsione, pertanto deve essere riservato a target dell'interfaccia difficili.

Utilizzare una pipeline di allineamento personalizzata

AlphaFold 3 esegue automaticamente la pipeline di ricerca nel database genetico per generare modelli MSA. Gli utenti possono anche fornire allineamenti personalizzati privati, precalcolati, in formato .a3m utilizzando gli URI Cloud Storage con unpairedMsaPath e pairedMsaPath. Fornire allineamenti multipli profondi fornisce forti vincoli coevolutivi, convertendo spesso le previsioni con scarsa confidenza in modelli con elevata confidenza.