AlphaFold 3 est un modèle de deep learning développé par Google DeepMind et Isomorphic Labs. Il est conçu pour prédire les structures et les interactions 3D des protéines, de l'ADN, de l'ARN, des ligands et des ions. Ce document explique comment déployer et utiliser le modèle AlphaFold 3 à l'aide de Model Garden sur Gemini Enterprise Agent Platform.
Capacités clés
Le déploiement d'AlphaFold 3 sur Agent Platform offre les fonctionnalités suivantes, nécessaires pour les workflows de recherche et développement (R&D) avancés et de découverte de médicaments commerciaux :
Utilisation commerciale : AlphaFold 3 sur Model Garden est disponible pour une utilisation commerciale.
Ligands personnalisés arbitraires : AlphaFold 3 est compatible avec le co-pliage unifié des protéines, de l'ADN et de l'ARN, ainsi qu'avec les ligands personnalisés définis à l'aide de chaînes SMILES ou de codes CIF Chemical Component Dictionary (CCD).
Flexibilité du workflow : AlphaFold 3 sur Model Garden est compatible avec le pipeline de pliage complet de bout en bout (combinant la recherche dans la base de données et la prédiction du modèle) ou avec un mode d'inférence uniquement, dans lequel vous pouvez fournir des alignements MSA précalculés pour optimiser le temps d'exécution et l'utilisation du GPU.
Remarques
Lorsque vous évaluez AlphaFold 3 pour les charges de travail, gardez à l'esprit les contraintes suivantes :
Simultanéité : le point de terminaison AlphaFold 3 est limité à une simultanéité par nœud. Pour une concurrence plus élevée, les points de terminaison peuvent être mis à l'échelle sur plusieurs nœuds. Si une requête de prédiction est envoyée alors qu'une autre est en cours d'exécution, le point de terminaison rejette la nouvelle requête avec une erreur
HTTP 429 Too Many Requestssi le nombre de requêtes est supérieur au nombre de nœuds.Limites de jetons : la durée maximale de prédiction sur les points de terminaison de l'Agent Platform est de 60 minutes. En raison de la surcharge variable de la recherche MSA, la taille de séquence maximale acceptée sur les GPU A3 est d'environ 4 500 jetons biologiques (tels que les acides aminés, les nucléotides ou les atomes de ligand). Si vous fournissez des alignements précalculés, l'exécution de la recherche MSA est contournée,ce qui permet un repliement complexe jusqu'à la limite matérielle d'environ 5 400 jetons.
Limites de charge utile : les requêtes REST de prédiction standards sont limitées à 8 Mo. Si vous utilisez le mode inférence uniquement, les grands alignements précalculés (fichiers
.a3m) doivent être référencés à l'aide d'URI Cloud Storage plutôt qu'intégrés en tant que chaînes intégrées pour éviter le rejet de la charge utile.Configuration réseau : étant donné que les prédictions sont des opérations de longue durée qui peuvent prendre jusqu'à 60 minutes, vous ne devez déployer le point de terminaison qu'avec Private Service Connect (PSC) pour contourner les limites de délai d'expiration standard de 10 minutes.
Instructions de déploiement
Cette section explique comment déployer AlphaFold 3 sur un point de terminaison fourni par Agent Platform dans un projet Google Cloud .
Avant de commencer
Avant de déployer AlphaFold 3, vous devez :
- Demandez l'accès au modèle.
- Obtenez des ressources GPU.
- Configurez les autorisations Identity and Access Management (IAM) requises :
- Créez un compte de service avec le rôle IAM Administrateur Agent Platform.
- Assurez-vous que votre compte principal IAM dispose du rôle
roles/iam.serviceAccountCreatorpour agir en tant que compte de service lors du déploiement du modèle.
- Vérifiez vos quotas de ressources.
Ressources nécessaires
AlphaFold 3 nécessite une machine virtuelle (VM) a3-highgpu-1g.
Avant le déploiement, assurez-vous que votre projet Google Cloud dispose d'un quota suffisant dans la région de déploiement cible pour les ressources suivantes :
Accélérateurs : au moins un type de machine
a3-highgpu-1g.SSD local : la VM A3 est provisionnée avec 750 Go d'espace SSD local. Cela est nécessaire pour mettre en cache de manière persistante les bases de données de séquences de référence (UniProt, MGnify, Rfam), ce qui permet des lectures à faible latence lors des recherches dans les bases de données génétiques (Jackhmmer/Nhmmer) pour toutes les demandes de prédiction.
Bucket Cloud Storage
AlphaFold 3 nécessite un bucket Cloud Storage pour stocker les fichiers MSA fournis et exporter les résultats de prédiction complets. Pour éviter les transferts interrégionaux, nous vous recommandons d'utiliser un bucket Cloud Storage dans la même région que votre point de terminaison ou un bucket multirégional.
Rôles de gestion de l'authentification et des accès (IAM)
Configurez les rôles suivants pour les identités participantes :
Déployeur de modèle (également appelé administrateur informatique) : l'identité qui déploie le modèle nécessite l'autorisation
roles/aiplatform.adminpour créer des points de terminaison et gérer les déploiements.Identité de diffusion : lors de l'exécution de l'inférence, les points de terminaison AlphaFold 3 écrivent les structures de sortie directement dans Cloud Storage à l'aide du compte de service du projet locataire. Le compte de service correspondant nécessite l'autorisation
roles/storage.objectUsersur le bucket Cloud Storage cible.Utilisateurs du modèle : les comptes qui lancent des prédictions doivent répondre aux exigences suivantes :
roles/aiplatform.userpour envoyer des requêtes de prédiction au point de terminaison.roles/storage.objectUserpour accéder aux résultats de prédiction dans le bucket Cloud Storage.
Déployer AlphaFold 3
Déployez AlphaFold 3 de manière programmatique à l'aide du SDK Agent Platform, soit en tant que point de terminaison Google Cloud dédié, soit en tant que point de terminaison Private Service Connect uniquement. Selon la disponibilité de votre GPU, le point de terminaison peut prendre entre 10 et 15 minutes pour être prêt pour l'inférence.
Voici un exemple d'extrait de code Python montrant comment déployer le modèle dans un projet Google Cloud , y compris une extension du délai d'inactivité de l'inférence :
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}")
Documentation de référence de l'API
Cette section décrit l'emplacement du point de terminaison, le format de l'URL, les paramètres de chemin d'accès et le schéma du corps de la requête.
Requête HTTP
POST https://HOST/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID:predict
Remplacez les éléments suivants :
HOST: hôte du point de terminaison du service. Cela dépend du type de déploiement (point de terminaison public dédié ou utilisation de Private Service Connect).PROJECT_ID: ID du projet Google Cloud qui héberge le point de terminaison déployé.LOCATION: région Google Cloud dans laquelle le point de terminaison est déployé (par exemple,us-central1).ENDPOINT_ID: identifiant unique du point de terminaison Agent Platform déployé.
Corps de la requête
Le corps de la requête contient des données respectant la structure JSON suivante :
{
"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
}
}
Champs de requête de premier niveau
| Champ | Type | Description |
|---|---|---|
instances |
array |
Obligatoire. Liste des configurations de séquences biologiques à prédire. Cette liste doit contenir exactement un élément. Si vous transmettez zéro ou plusieurs éléments, une erreur HTTP 422 Unprocessable
Entity se produit. Le corps instances doit spécifier les entrées conformément à la spécification publiée dans la
documentation AlphaFold 3.
|
parameters |
object |
Facultatif. Objet contenant des paramètres d'exécution pour configurer l'exécution de la prédiction (par exemple, dry_run, output_dir).
|
Paramètres
Configurez les indicateurs d'exécution pour l'exécution d'AlphaFold 3.
| Champ | Type | Valeur par défaut | Description |
|---|---|---|---|
dry_run |
boolean |
false |
Facultatif. Si la valeur est true, l'API exécute la validation de la requête, mais contourne l'exécution du modèle et renvoie immédiatement une réponse vide. Utile pour vérifier la connectivité et la syntaxe.
|
run_data_pipeline |
boolean |
true |
Facultatif. Si la valeur est true, exécute l'intégralité du pipeline (recherche et inférence MSA). Si la valeur est false, l'inférence est exécutée seule (la recherche dans la base de données est ignorée ; des MSA précalculées sont requises). Pour en savoir plus, consultez la
documentation sur GitHub.
|
output_dir |
string |
null |
Facultatif. URI Cloud Storage (tel que gs://bucket/path) où les fichiers de sortie bruts complets (y compris les structures CIF, les fichiers CSV PAE et de classement) sont importés en cas d'exécution réussie.
|
force_output_dir |
boolean |
false |
Facultatif. Si la valeur est true, autorise l'écrasement des fichiers existants dans le output_dir spécifié. Si la valeur est false, l'API renvoie immédiatement une erreur HTTP 400 Bad Request si le chemin d'accès Cloud Storage n'est pas vide, afin d'éviter toute perte de données accidentelle.
|
resolve_msa_overlaps |
boolean |
true |
Facultatif. Indique s'il faut dédupliquer les MSA non appariées par rapport aux MSA appariées. Pour connaître les bonnes pratiques, consultez les consignes de la documentation GitHub AlphaFold 3. |
max_template_date |
string |
null |
Facultatif. Date de disponibilité maximale du modèle à prendre en compte, au format YYYY-MM-DD (par exemple, "2024-05-15"). La validation échoue et une erreur HTTP 422 s'affiche si le format est incorrect.
|
conformer_max_iterations |
integer |
null |
Facultatif. Remplace le nombre maximal d'itérations à exécuter pour la recherche de conformères RDKit. Doit être un entier non négatif (supérieur ou égal à zéro). La validation échoue et renvoie une erreur HTTP 422 pour les valeurs négatives.
|
fix_standalone_glycans |
boolean |
false |
Facultatif. Active la fixation autonome de la position des glycans. |
flash_attention_implementation |
string |
null |
Facultatif. Implémentation du backend Flash Attention à utiliser. Les valeurs autorisées sont "triton", "cudnn" et "xla".
|
num_recycles |
integer |
10 |
Facultatif. Nombre d'itérations de recyclage à utiliser lors de l'inférence. Doit être un entier positif (supérieur à zéro). Consultez la section Bonnes pratiques pour en savoir plus sur les compromis. |
num_diffusion_samples |
integer |
5 |
Facultatif. Nombre d'échantillons de diffusion à générer. Doit être un entier positif (supérieur à zéro). Consultez la section Bonnes pratiques pour en savoir plus sur les compromis. |
save_embeddings |
boolean |
false |
Facultatif. Indique si les embeddings finaux du single et de la paire de trunk doivent être enregistrés dans l'emplacement output_dir. Si true, les embeddings sont écrits sous forme de fichiers .npz dans un sous-dossier nommé seed-{SEED}_embeddings/ (par exemple, outputs_config_job_seed-50_embeddings.npz).
|
save_distogram |
boolean |
false |
Facultatif. Indique si le distogramme prédit final doit être enregistré dans l'emplacement output_dir. Si la valeur est true, les embeddings sont écrits sous forme de fichiers .npz dans un sous-dossier nommé seed-{SEED}_embeddings/ (par exemple, outputs_config_job_seed-50_embeddings.npz).
|
compress_large_output_files |
boolean |
false |
Facultatif. Si la valeur est true, les fichiers de sortie volumineux (structures mmCIF et JSON de confiance) sont compressés à l'aide de zstandard. Cela génère des fichiers avec les extensions .cif.zst et .json.zst au lieu de .cif et .json. Les petits fichiers (comme ranking_scores.csv) ne sont pas compressés.
|
num_seeds |
integer |
null |
Facultatif. Nombre de valeurs aléatoires à utiliser pour l'inférence. En général, vous devez définir des graines dans le champ instances.modelSeeds pour la reproductibilité. Consultez la section Bonnes pratiques pour en savoir plus sur les compromis.
|
Réponse (sortie)
Cette section décrit les champs renvoyés dans la réponse de l'API en cas d'exécution réussie.
Corps de la réponse
En cas d'exécution réussie, le point de terminaison renvoie la réponse au format de schéma de prédiction en ligne standard de l'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"
}
]
}
Champs de réponse de premier niveau
| Champ | Type | Description |
|---|---|---|
deployedModelId |
string |
ID du modèle déployé sur le point de terminaison Agent Platform. |
model |
string |
Nom complet de la ressource du modèle. |
modelDisplayName |
string |
Nom à afficher du modèle déployé (toujours "alphafold3").
|
modelVersionId |
string |
ID de version du modèle déployé. |
predictions |
array |
Liste des résultats de prédiction. Pour AlphaFold 3, ce tableau contient exactement un objet de résultat de prédiction. |
Détails des résultats de prédiction (predictions[])
Le point de terminaison de prédiction AlphaFold 3 renvoie une réponse JSON HTTP 200 contenant un tableau predictions avec les coordonnées structurelles et les métriques de confiance pour le candidat le mieux classé. Pour obtenir des définitions de champ complètes et des spécifications de fichier de sortie, consultez la documentation officielle d'AlphaFold 3 sur GitHub.
La structure de sortie dans la réponse de l'API peut varier selon que parameters.output_dir est fourni ou non dans la requête :
Prédiction dans la réponse HTTP : la réponse intégrée renvoie des métriques récapitulatives globales (
summary), des coordonnées de structure 3D (structure_cif), des scores de confiance par atome (plddt) et la matrice d'erreur alignée prédite en 2D (pae) directement dans le corps de la charge utile de la réponse HTTP JSON. Lorsqu'un répertoire de sortie est spécifié, les grands champs de charge utile (structure_cif,plddtetpae) sont omis (null) de la charge utile de la réponse HTTP pour éviter les goulots d'étranglement de sérialisation. Au lieu de cela, toutes les sorties brutes du modèle sont exportées de manière asynchrone vers le bucket Cloud Storage spécifié.Artefact enregistré dans le bucket Cloud Storage : lorsqu'un répertoire de sortie (
parameters.output_dir) est spécifié, les résultats de prédiction complets sont importés dans Cloud Storage. Le dossier de sortie contient des données conformes aux spécifications publiées dans la documentation AlphaFold 3 sur GitHub.
Faire des prédictions
Le déploiement de Model Garden simplifie l'exécution du pipeline de prédiction de bout en bout, y compris le pipeline de données et l'inférence de modèle, en un seul appel d'API. Le diagramme suivant illustre l'architecture générale des prédictions AlphaFold 3 :
Fig. 1 Pipeline de prédiction complet
Lorsque vous exécutez des prédictions, il est fortement recommandé de fournir un bucket Cloud Storage directement dans les paramètres pour exporter l'ensemble des données brutes, y compris les sous-répertoires par échantillon, les fichiers manifeste de classement et les sorties brutes. Pour obtenir une description détaillée de tous les champs de requête configurables, y compris le réglage des paramètres pour l'échantillonnage multi-seed, le recyclage neuronal, les trajectoires de diffusion et les liaisons covalentes personnalisées, consultez la section de référence de l'API.
Avant de lancer des jobs de pliage ou des pipelines par lot de longue durée, vous pouvez effectuer un test à blanc pour vérifier rapidement votre authentification, vos autorisations IAM et la connectivité réseau de votre point de terminaison.
Options de prédiction
Selon le workflow, le traitement AlphaFold 3 peut être organisé en quatre modes d'exécution distincts :
- Mode de simulation
- Mode de prédiction de bout en bout
- Inférence uniquement avec les MSA et les modèles précalculés
- Exécuter sans MSA ni modèle
Mode dry run
Pour vérifier la connectivité, l'authentification, la mise en réseau et les schémas JSON de l'API sans démarrer le pipeline de prédiction, vous pouvez envoyer une requête avec "dry_run":
true dans l'objet parameters. Le point de terminaison exécute toutes les routines de validation (y compris la vérification des autorisations d'écriture dans le bucket Cloud Storage et la validation des caractères de séquence), mais ignore l'exécution et renvoie immédiatement une réponse de prédiction vide.
Voici un exemple de script Python pour le mode de simulation :
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)
Mode de prédiction de bout en bout
Pour exécuter une prédiction de bout en bout, envoyez des séquences biologiques brutes (protéines, ADN, ARN, ligands et PTM) dans une seule requête. Le point de terminaison exécute automatiquement la recherche dans la base de données génétiques, puis l'inférence du modèle. Cette option est recommandée pour les jobs de pliage sans alignements préexistants.
Voici un exemple de script Python pour le mode de prédiction de bout en bout :
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)
Inférence uniquement avec des MSA et des modèles précalculés
Vous disposez peut-être déjà de modèles MSA et mmCIF précalculés, soit à partir d'une exécution précédente, soit générés en dehors du point de terminaison du modèle. Dans ces scénarios, la recherche dans la base de données génétiques peut être entièrement contournée en fournissant les alignements et les modèles, en acheminant la demande directement pour la prédiction de la structure. Cela peut également réduire considérablement le temps de réponse de l'inférence. Il s'agit du chemin d'accès recommandé dans les scénarios suivants :
- Lorsque vous ancrer plusieurs ligands de petites molécules différents à une seule cible protéique statique, vous pouvez réutiliser les MSA.
- Exécuter la même séquence de molécules sur plusieurs graines aléatoires, de manière itérative, pour cartographier la flexibilité structurelle.
- Alignement des séquences hors connexion sur des bases de données génomiques privées et non publiques.
- Optimisation des ressources GPU pour AlphaFold 3, afin de se concentrer uniquement sur la génération de structures.
Voici un exemple de script Python pour le mode inférence uniquement :
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)
Exécuter l'analyse sans MSA ni modèle
Il est également possible de contourner complètement la recherche dans la base de données génétiques et la correspondance des modèles. Le modèle prédit la structure 3D en utilisant uniquement la séquence de requête, sans séquences homologues ni informations sur la coévolution. Pour déclencher ce mode, fournissez des chaînes vides pour les paramètres MSA unpairedMsa et pairedMsa, ainsi qu'une liste vide pour templates dans l'instance, et définissez run_data_pipeline sur false dans les paramètres. Cela peut être utile pour la conception de molécules synthétiques ou artificielles, ou pour tester les prédictions structurelles en l'absence de contexte évolutif.
Voici un exemple de script Python pour exécuter AlphaFold 3 MSA et sans modèle :
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)
Pour obtenir des spécifications détaillées, des paramètres d'entité et des métriques de confiance de sortie, consultez la documentation AlphaFold 3 sur GitHub.
Sorties de prédiction
Le service de prédiction AlphaFold 3 propose deux mécanismes de diffusion complémentaires pour récupérer les résultats de prédiction. Par défaut, la réponse de l'API renvoie les résultats de prédiction de manière synchrone et intégrée pour le candidat le mieux classé. Si vous le souhaitez, vous pouvez spécifier un répertoire Cloud Storage.
La section suivante présente la sortie de prédiction. Pour en savoir plus, consultez la documentation AlphaFold 3 sur GitHub.
Réponse intégrée ou artefacts enregistrés
Le service de prédiction AlphaFold 3 est compatible avec deux principaux modèles de sortie :
- Réponse intégrée : renvoie les coordonnées de la structure 3D et les métriques de confiance uniquement pour le candidat le mieux classé directement dans la charge utile de la réponse HTTP REST. C'est idéal pour le prototypage interactif rapide ou les requêtes à séquence unique.
- Artefacts enregistrés (Cloud Storage) : si vous spécifiez un répertoire de sortie, l'ensemble de données multisamples complet est exporté vers Cloud Storage. Cela inclut les fichiers de coordonnées individuels, les fichiers JSON de confiance, les distogrammes, les embeddings et les métriques récapitulatives pour chaque échantillon de diffusion et chaque seed aléatoire générés. Nous vous recommandons d'utiliser Cloud Storage pour les charges de travail de production, le mappage des ensembles conformationnels et le contournement de la limite de taille de la charge utile de la requête.
Voici un exemple Python montrant comment récupérer les artefacts enregistrés dans Cloud Storage pour une analyse en aval :
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")
Étant donné qu'AlphaFold 3 utilise un modèle de diffusion générative, chaque prédiction génère un ensemble de structures 3D candidates pour les graines et les trajectoires d'échantillonnage. L'évaluation et la comparaison de ces exécutions candidates peuvent aider à interpréter les résultats de prédiction avant d'effectuer une analyse structurelle détaillée.
Vous pouvez examiner l'ensemble complet de données d'artefacts multi-échantillons à l'aide de trois fichiers principaux :
ranking_scores.csv: grand livre principal listant chaque paire de trajectoires générée et sonranking_scorecomposite. Les lignes sont enregistrées dans l'ordre d'exécution de la trajectoire (triées par ordre croissant de la valeur initiale, puis par ordre croissant de l'index d'échantillon), et non pré-triées par score. Les utilisateurs doivent trier les données parranking_score(ordre décroissant) pour identifier les rangs candidats.summary_confidences.json: contient les métriques de qualité globales (pTM,ipTM,has_clash,fraction_disordered) pour le candidat principal.summary_confidences.jsonpar échantillon : situé dans les dossiersseed-{SEED}_sample-{INDEX}/individuels, ce fichier vous permet d'inspecter les matrices pTM et ipTM au niveau de la chaîne pour des exécutions de candidats non principaux spécifiques, si nécessaire.
L'exemple Python suivant analyse ranking_scores.csv et summary_confidences.json pour classer les exemples candidats et valider la qualité des meilleurs candidats :
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}")
Pour obtenir des spécifications de schéma exhaustives sur les fichiers enregistrés et les attributs mmCIF, consultez la documentation AlphaFold 3 sur GitHub. Consultez également le guide Évaluer la qualité des prédictions AlphaFold 3 sur EMBL-EBI pour comprendre comment évaluer la qualité des prédictions.
Bonnes pratiques
Les sections suivantes décrivent les bonnes pratiques à suivre lorsque vous utilisez AlphaFold 3 sur Agent Platform :
Atténuer les délais avant expiration des requêtes
Les points de terminaison de l'Agent Platform appliquent un délai d'exécution maximal par défaut de 60 minutes par requête. Pour vous assurer que vos prédictions se terminent correctement sans délai d'expiration, respectez les consignes suivantes :
- Évitez le suréchantillonnage dans une même requête : l'initialisation d'une large plage de valeurs de départ ou de paramètres de diffusion inverse excessivement élevés dans un même appel d'API peut entraîner un dépassement de la limite de temps d'exécution de 60 minutes.
- Déconstruisez les balayages importants : pour les études à grande échelle, divisez vos graines et vos balayages de paramètres en plusieurs charges utiles de prédiction plus petites, puis envoyez-les en tant que jobs distincts. Cela tire également parti des capacités d'autoscaling de votre point de terminaison.
Contourner la recherche de contrats-cadres de services
Le pipeline de recherche dans la base de données génétiques est la phase la plus longue du pipeline AlphaFold. Lorsque vous exécutez des prédictions itératives sur la même séquence (par exemple, en effectuant des balayages de criblage de ligands sur une cible protéique fixe), vous pouvez optimiser considérablement les temps d'exécution en contournant complètement la recherche dans la base de données :
- Extraire le MSA : exécutez une prédiction de bout en bout initiale avec un répertoire de sortie Cloud Storage (
output_dir) spécifié. Téléchargez le fichier{JOB_NAME}_data.jsongénéré à partir du bucket Cloud Storage de sortie. - Envoyer des prédictions d'inférence uniquement : localisez les champs
unpairedMsaetpairedMsadans le fichier JSON. Extrayez ces chaînes MSA et transmettez-les dans les requêtes de prédiction ultérieures à l'aide deunpairedMsaPathetpairedMsaPathpointant vers des URI Cloud Storage.
Vous pouvez également exécuter la recherche MSA sur votre propre infrastructure et saisir les modèles MSA précalculés dans la requête de prédiction.
Gérer les exécutions peu fiables
Lorsque les résultats de prédiction génèrent des métriques de faible confiance, vous pouvez tenter une correction ciblée au lieu de les traiter comme des échecs de prédiction irrécupérables. L'optimisation de paramètres spécifiques vous permet d'explorer d'autres trajectoires latentes. Cette section liste quelques approches pour récupérer les prédictions à faible confiance.
Utiliser l'échantillonnage multisemences
AlphaFold 3 initialise la génération de coordonnées 3D à partir d'un bruit aléatoire dans l'espace latent. Lorsqu'une prédiction est soumise avec une seule graine certaine, la trajectoire de diffusion peut suivre un chemin différent par rapport à une autre graine. Le fait de transmettre un tableau de graines force le modèle à échantillonner des trajectoires à partir de différents états.
L'échantillonnage multisemences offre deux avantages essentiels : il vérifie la cohérence structurelle entre les exécutions indépendantes et sonde la dynamique conformationnelle fonctionnelle. Par exemple, si les cinq graines convergent vers des coordonnées 3D identiques, vous pouvez avoir une grande confiance dans le repliement global. À l'inverse, si différentes graines produisent des poses de liaison distinctes et très fiables, l'ensemble peut révéler des états conformationnels biologiquement significatifs, tels que des boucles de site actif ouvertes ou fermées, ou des dimères alternatifs à domaine inversé.
Développer les trajectoires de diffusion
Alors que modelSeeds modifie l'état de bruit de départ dans l'espace latent, le paramètre num_diffusion_samples (valeur par défaut : 5) contrôle le nombre de structures 3D candidates générées par seed au cours du processus de diffusion inverse. Pour les régions de boucle flexibles ou les poches de liaison peu profondes, l'augmentation de l'échantillonnage élargit le pool de candidats pour chaque graine. Cela est particulièrement efficace lorsque les scores de confiance locaux chutent dans des boucles spécifiques (pLDDT < 70) alors que le repliement global du domaine reste fiable (pTM > 0,80). Cela peut aider à découvrir des structures candidates à haute fiabilité qui auraient été manquées lors de l'exécution initiale.
Augmenter le nombre d'itérations de recyclage
Avant que le module de diffusion ne génère des coordonnées 3D, AlphaFold 3 traite les caractéristiques de séquence et par paires. Le paramètre num_recycles détermine le nombre de fois où les représentations de structure intermédiaire et les embeddings spatiaux par paires sont réinjectés de manière itérative dans le réseau.
Pour les grandes molécules complexes ou les cibles avec des signaux de coévolution faibles, l'augmentation de num_recycles donne au réseau de tronc des itérations supplémentaires pour résoudre les relations spatiales entre les chaînes distantes avant de transmettre les entrées au module de diffusion. Cette approche peut être tentée lorsque les matrices PAE hors diagonale présentent une incertitude inter-chaîne élevée (> 15 Å) alors que les chaînes individuelles présentent une confiance de repliement local élevée (pLDDT > 70). Notez que l'augmentation des recyclages augmente linéairement le temps d'exécution de la prédiction. Elle doit donc être réservée aux cibles d'interface difficiles.
Utiliser un pipeline d'alignement personnalisé
AlphaFold 3 exécute automatiquement le pipeline de recherche dans la base de données génétiques pour générer des modèles MSA. Les utilisateurs peuvent également fournir des alignements personnalisés privés et précalculés au format .a3m à l'aide d'URI Cloud Storage avec unpairedMsaPath et pairedMsaPath. L'utilisation d'alignements de séquences multiples (MSA) profonds fournit de fortes contraintes de coévolution, ce qui permet souvent de convertir des prédictions peu fiables en modèles très fiables.