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 3D et les interactions 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 fournit les fonctionnalités suivantes, nécessaires pour les workflows avancés de recherche et développement (R&D) 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-repliement unifié des protéines, de l'ADN et de l'ARN, ainsi que des 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 un pipeline de repliement complet de bout en bout (combinant la recherche dans la base de données et la prédiction du modèle) ou 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 des charges de travail, tenez compte des contraintes suivantes :
Simultanéité : le point de terminaison AlphaFold 3 est limité à une requête simultanée par nœud. Pour une simultanéité 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 prédiction 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 la plate-forme d'agent est de 60 minutes. En raison de la surcharge variable de la recherche MSA, la taille maximale de séquence compatible avec les GPU A3 est d'environ 4 500 jetons biologiques (tels que des acides aminés, des nucléotides ou des atomes de ligand). Fournir des alignements précalculés permet de contourner l'exécution de la recherche MSA, 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 d'inférence uniquement, les alignements précalculés volumineux (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 du 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 avant expiration standard des points de terminaison 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.
- Procurez-vous des ressources GPU.
- Configurez les autorisations IAM (Identity and Access Management) 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 requêtes 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 situé dans la même région que votre point de terminaison ou d'utiliser 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 le rôle
roles/storage.objectUsersur le bucket Cloud Storage cible.Utilisateurs du modèle : les comptes qui lancent des prédictions doivent disposer des éléments suivants :
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 Dedicated, soit en tant que point de terminaison Private Service Connect uniquement. La préparation du point de terminaison pour l'inférence peut prendre entre 10 et 15 minutes, selon la disponibilité de votre GPU.
Voici un exemple d'extrait de code Python qui montre comment déployer le modèle dans un projet Google Cloud , y compris une extension du délai avant expiration 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 de la charge utile 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 Private Service Connect.PROJECT_ID: ID du projet Google Cloud hébergeant le point de terminaison déployé.LOCATION: région Google Cloud où 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 présentant 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 est générée. 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 options 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 valide la requête, mais contourne l'exécution du modèle et renvoie immédiatement une réponse vide. Utile pour les vérifications de connectivité et de syntaxe.
|
run_data_pipeline |
boolean |
true |
Facultatif. Si la valeur est true, le pipeline complet est exécuté (recherche MSA et inférence). Si la valeur est false, l'inférence est exécutée uniquement (la recherche dans la base de données est ignorée ; nécessite des MSA précalculés). Pour en savoir plus, consultez la
documentation sur GitHub.
|
output_dir |
string |
null |
Facultatif. URI Cloud Storage (par exemple, gs://bucket/path) où les fichiers de sortie bruts complets (y compris les structures CIF, PAE et les fichiers CSV de classement) sont importés une fois l'exécution réussie.
|
force_output_dir |
boolean |
false |
Facultatif. Si la valeur est true, permet d'écraser les 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 accidentelle de données.
|
resolve_msa_overlaps |
boolean |
true |
Facultatif. Indique si les MSA non associés doivent être dédupliqués par rapport aux MSA associés. Pour connaître les bonnes pratiques, consultez les consignes de la documentation GitHub sur 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"). Échec de la validation avec une erreur HTTP 422 si la mise en forme est incorrecte.
|
conformer_max_iterations |
integer |
null |
Facultatif. Remplacement du 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). Échoue à la validation avec une erreur HTTP 422 pour les valeurs négatives.
|
fix_standalone_glycans |
boolean |
false |
Facultatif. Active la correction de la position des glycanes autonomes. |
flash_attention_implementation |
string |
null |
Facultatif. Implémentation du backend Flash Attention à utiliser. Les valeurs autorisées sont "triton", "cudnn", "xla".
|
num_recycles |
integer |
10 |
Facultatif. Nombre d'itérations de recyclage à utiliser pendant 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 de tronc unique et de paire doivent être enregistrés 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).
|
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, compresse les fichiers de sortie volumineux (structures mmCIF et JSON de confiance) à 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 graines aléatoires à utiliser pour l'inférence. En général, vous devez définir des valeurs de départ 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 d'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 de ressource complet 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 du résultat de la 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 champs complètes et des spécifications de fichiers de sortie, consultez la documentation officielle d'AlphaFold 3 sur GitHub.
Selon que parameters.output_dir est fourni ou non dans la requête, la structure de sortie de la réponse de l'API peut varier :
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 d'alignement prédite 2D (pae) directement dans le corps de la charge utile de la réponse JSON HTTP. Lorsqu'un répertoire de sortie est spécifié, les champs de charge utile volumineux (structure_cif,plddtetpae) sont omis (null) de la charge utile de réponse HTTP pour éviter les goulots d'étranglement de sérialisation. À la place, toutes les sorties brutes du modèle sont exportées de manière asynchrone vers le bucket Cloud Storage spécifié.Artefact enregistré dans un bucket Cloud Storage : lorsqu'un répertoire de sortie (
parameters.output_dir) est spécifié, les résultats complets de la prédiction 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 d'un 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 schéma suivant illustre l'architecture générale des prédictions AlphaFold 3 :
Fig. 1 Pipeline de prédiction complet
Lors de l'exécution de prédictions, il est vivement recommandé de fournir un bucket Cloud Storage directement dans les paramètres pour exporter l'ensemble de données brutes complet, y compris les sous-répertoires par échantillon, les fichiers manifestes de classement et les sorties brutes. Pour obtenir une documentation de référence complète de tous les champs de requête configurables, y compris le réglage des paramètres pour l'échantillonnage multi-graine, le recyclage neuronal, les trajectoires de diffusion et les liaisons covalentes personnalisées, consultez la documentation de référence de l'API.
Avant de lancer des jobs de repliement ou des pipelines par lot de longue durée, vous pouvez exécuter un dry run 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 dry run
- Mode de prédiction de bout en bout
- Inférence uniquement avec des MSA et des modèles précalculés
- Exécution sans MSA ni modèle
Mode dry run
Pour vérifier la connectivité de l'API, l'authentification, la mise en réseau et les schémas JSON 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 du bucket Cloud Storage et la validation des caractères de séquence), mais ignore l'exécution, en renvoyant 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étique, suivie immédiatement de l'inférence du modèle. Cette option est recommandée pour les jobs de repliement 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 MSA et de modèles mmCIF précalculés, provenant d'une exécution précédente ou 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étique peut être entièrement contournée en fournissant les alignements et les modèles, ce qui permet d'acheminer la requête directement pour la prédiction de structure. Cela peut également réduire considérablement le temps de réponse de l'inférence. Il s'agit de la méthode recommandée dans les scénarios suivants :
- Lorsque vous arrimez plusieurs ligands de petites molécules différents à une seule cible protéique statique, les MSA peuvent être réutilisés.
- Exécuter la même séquence moléculaire sur plusieurs graines aléatoires, de manière itérative, pour cartographier la flexibilité structurelle.
- Aligner 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 d'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écution sans MSA ni modèle
Il est également possible de contourner complètement la recherche dans la base de données génétique et la mise en 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 co-évolutives. Pour déclencher ce mode, fournissez des chaînes vides pour les paramètres MSA unpairedMsa et pairedMsa, et une liste vide pour templates dans l'instance, puis 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 des prédictions structurelles en l'absence de contexte évolutif.
Voici un exemple de script Python permettant d'exécuter AlphaFold 3 sans MSA ni 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.
Résultats 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 pour le candidat le mieux classé. Vous pouvez éventuellement spécifier un répertoire Cloud Storage.
La section suivante présente le résultat de la 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édictions AlphaFold 3 accepte 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. Cette option est idéale pour le prototypage interactif rapide ou les requêtes à séquence unique.
- Artefacts enregistrés (Cloud Storage) : spécifier un répertoire de sortie exporte l'ensemble de données multi-échantillons complet 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 graine aléatoire et échantillon de diffusion générés. L'utilisation de Cloud Storage est recommandée pour les charges de travail de production, le mappage d'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 des artefacts enregistrés à partir de 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 Cloud Storage 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")
Comme AlphaFold 3 utilise un modèle de diffusion génératif, chaque exécution de prédiction génère un ensemble de structures 3D candidates à partir de graines et de 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 de données d'artefacts multi-échantillons complet à l'aide de trois fichiers principaux :
ranking_scores.csv: registre 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 graine, puis par ordre croissant d'index d'échantillon), et non pré-triées par score. Les utilisateurs doivent trier parranking_scorepar ordre décroissant pour identifier les rangs des candidats.summary_confidences.json: contient les métriques de qualité globales (pTM,ipTM,has_clash,fraction_disordered) pour le meilleur candidat.summary_confidences.jsonpar échantillon : situés dans des dossiersseed-{SEED}_sample-{INDEX}/individuels, ils vous permettent d'inspecter les matrices pTM et ipTM au niveau de la chaîne pour des exécutions de candidats spécifiques qui ne sont pas les meilleures, si nécessaire.
L'exemple Python suivant analyse ranking_scores.csv et summary_confidences.json pour classer les échantillons de 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 des fichiers enregistrés et des attributs mmCIF, consultez la documentation AlphaFold 3 sur GitHub. Consultez également le guide How to assess the quality of AlphaFold 3 predictions (Comment é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 pour utiliser AlphaFold 3 sur Agent Platform :
Limiter les délais avant expiration des requêtes
Les points de terminaison sur 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 expiration, respectez les consignes suivantes :
- Évitez le suréchantillonnage dans une seule requête : l'initialisation d'un large balayage de graines ou de paramètres de diffusion inverse excessivement élevés dans un seul appel d'API peut entraîner un dépassement de la limite de 60 minutes pour le temps d'exécution.
- Déconstruire les grands balayages : pour les études à grande échelle, divisez vos graines et vos balayages de paramètres en plusieurs charges utiles de prédiction plus petites et envoyez-les en tant que jobs distincts. Cela permet également de profiter des capacités d'autoscaling de votre point de terminaison.
Contourner la recherche MSA
Le pipeline de recherche dans la base de données génétique est la phase la plus chronophage du pipeline AlphaFold. Lorsque vous exécutez des prédictions itératives sur la même séquence (par exemple, en exécutant 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 l'alignement de séquences multiples : 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 : recherchez les champs
unpairedMsaetpairedMsadans le fichier JSON. Extrayez ces chaînes MSA et transmettez-les aux requêtes de prédiction suivantes à 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, plutôt que de les traiter comme des échecs de prédiction irrécupérables, vous pouvez tenter une correction ciblée. L'optimisation de paramètres spécifiques vous permet d'explorer d'autres trajectoires latentes. Cette section présente quelques approches pour récupérer des prédictions de faible confiance.
Utiliser l'échantillonnage multi-seed
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 envoyée avec une seule graine, la trajectoire de diffusion peut suivre un chemin différent de celui d'une autre graine. La transmission d'un tableau de graines force le modèle à échantillonner des trajectoires à partir de différents états.
L'échantillonnage multi-seed 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 valeurs de départ produisent des poses de liaison distinctes et de haute confiance, 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 à échange de domaine.
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 (par défaut 5) contrôle le nombre de structures 3D candidates générées par graine pendant le 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. Cette approche est particulièrement efficace lorsque les scores de confiance locaux chutent dans des boucles spécifiques (pLDDT < 70), tandis que le repli global du domaine reste fiable (pTM > 0,80). Cela peut aider à découvrir des structures candidates à haut niveau de confiance qui auraient été manquées lors de l'exécution initiale.
Augmenter les 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 de paires. Le paramètre num_recycles détermine le nombre de fois où les représentations de structure intermédiaires et les embeddings spatiaux par paires sont réinjectés de manière itérative dans le réseau.
Pour les molécules complexes de grande taille ou les cibles présentant des signaux de coévolution faibles, l'augmentation de num_recycles donne au réseau principal 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 Å) malgré des chaînes individuelles présentant une confiance de pliage locale élevée (pLDDT > 70). Notez que l'augmentation du nombre de recyclages augmente de manière linéaire l'environnement 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 de base de données génétique pour générer des modèles MSA. Les utilisateurs peuvent également fournir des alignements personnalisés privés précalculés au format .a3m à l'aide d'URI Cloud Storage à l'aide de unpairedMsaPath et pairedMsaPath. La fourniture d'alignements de séquences multiples (MSA) profonds fournit des contraintes co-évolutives fortes, convertissant fréquemment les prédictions à faible niveau de confiance en modèles à niveau de confiance élevé.