Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

AlphaFold 3

AlphaFold 3 ist ein Deep-Learning-Modell, das von Google DeepMind und Isomorphic Labs entwickelt wurde. Es wurde entwickelt, um die 3D-Strukturen und Interaktionen von Proteinen, DNA, RNA, Liganden und Ionen vorherzusagen. In diesem Dokument wird beschrieben, wie Sie das AlphaFold 3-Modell mit Model Garden auf der Gemini Enterprise Agent Platform bereitstellen und verwenden.

Hauptmerkmale

Die Bereitstellung von AlphaFold 3 auf der Agent Platform bietet die folgenden Funktionen, die für fortschrittliche Forschungs- und Entwicklungs- (F&E) und kommerzielle Workflows zur Arzneimittelentwicklung erforderlich sind:

Kommerzielle Nutzung: AlphaFold 3 in Model Garden ist für die kommerzielle Nutzung verfügbar.
Beliebige benutzerdefinierte Liganden: AlphaFold 3 unterstützt das einheitliche Co-Folding von Proteinen, DNA und RNA zusammen mit benutzerdefinierten Liganden, die mit SMILES-Strings oder CIF-CCD-Codes (Chemical Component Dictionary) definiert werden.
Workflow-Flexibilität: AlphaFold 3 im Model Garden unterstützt die vollständige End-to-End-Faltungs-Pipeline (Kombination aus Datenbanksuche und Modellvorhersage) oder einen reinen Inferenzmodus, in dem Sie vorab berechnete MSA-Abstimmungen bereitstellen können, um die Ausführungszeit und die GPU-Auslastung zu optimieren.

Hinweise

Beachten Sie bei der Bewertung von AlphaFold 3 für Arbeitslasten die folgenden Einschränkungen:

Nebenläufigkeit: Für den AlphaFold 3-Endpunkt gilt ein Gleichzeitigkeitslimit von einem pro Knoten. Für eine höhere Parallelität können Endpunkte auf mehrere Knoten skaliert werden. Wenn eine Vorhersageanfrage gesendet wird, während eine andere Vorhersage aktiv ausgeführt wird, lehnt der Endpunkt die neue Anfrage mit einem HTTP 429 Too Many Requests-Fehler ab, wenn die Anzahl der Anfragen die Anzahl der Knoten überschreitet.
Tokenlimits: Die maximale Vorhersagedauer für Agent Platform-Endpunkte beträgt 60 Minuten. Aufgrund des variablen MSA-Suchaufwands beträgt die maximale Sequenzgröße, die auf A3-GPUs unterstützt wird, etwa 4.500 biologische Tokens (z. B. Aminosäuren, Nukleotide oder Ligandenatome). Durch die Bereitstellung vorab berechneter Ausrichtungen wird die Ausführung der MSA-Suche umgangen, was komplexes Falten bis zur Hardwaregrenze von etwa 5.400 Tokens ermöglicht.
Nutzlastlimits: Standardmäßige REST-Anfragen für Vorhersagen haben ein Größenlimit von 8 MB. Wenn Sie den reinen Inferenzmodus verwenden, müssen große vorab berechnete Ausrichtungen (.a3m-Dateien) über Cloud Storage-URIs referenziert und dürfen nicht als Inline-Strings eingebettet werden, um die Ablehnung von Nutzlasten zu vermeiden.
Netzwerkkonfiguration: Da Vorhersagen Vorgänge mit langer Ausführungszeit sind, die bis zu 60 Minuten dauern können, sollten Sie den Endpunkt nur mit Private Service Connect (PSC) bereitstellen, um die standardmäßigen Endpunkt-Zeitlimitüberschreitungen von 10 Minuten zu umgehen.

Anleitung zur Bereitstellung

In diesem Abschnitt wird beschrieben, wie Sie AlphaFold 3 in einem Google Cloud Projekt auf einem von Agent Platform bereitgestellten Endpunkt bereitstellen.

Hinweis

Bevor Sie AlphaFold 3 bereitstellen, müssen Sie Folgendes tun:

Modellzugriff anfordern.
GPU-Ressourcen beschaffen
Konfigurieren Sie die erforderlichen IAM-Berechtigungen (Identity and Access Management):
- Erstellen Sie ein Dienstkonto mit der IAM-Rolle Agent Platform Administrator.
- Achten Sie darauf, dass Ihr IAM-Hauptkonto die Rolle roles/iam.serviceAccountCreator hat, um beim Bereitstellen des Modells als Dienstkonto zu fungieren.
Ressourcenkontingente prüfen

Ressourcenanforderungen

Für AlphaFold 3 ist eine a3-highgpu-1g-VM erforderlich.

Prüfen Sie vor der Bereitstellung, ob Ihr Google Cloud Projekt in der Zielbereitstellungsregion über ein ausreichendes Kontingent für die folgenden Ressourcen verfügt:

Beschleuniger: Mindestens ein a3-highgpu-1g-Maschinentyp.
Lokale SSD: Die A3-VM wird mit 750 GB lokalem SSD-Speicherplatz bereitgestellt. Dies ist erforderlich, um die Referenzsequenzdatenbanken (UniProt, MGnify, Rfam) dauerhaft zu cachen und so bei allen Vorhersageanfragen Lesevorgänge mit niedriger Latenz bei der Suche in genetischen Datenbanken (Jackhmmer/Nhmmer) zu ermöglichen.

Cloud Storage-Bucket

Für AlphaFold 3 ist ein Cloud Storage-Bucket erforderlich, in dem alle bereitgestellten MSA-Dateien gespeichert und vollständige Vorhersageausgaben exportiert werden. Um regionsübergreifende Übertragungen zu vermeiden, empfehlen wir, entweder einen Cloud Storage-Bucket in derselben Region wie Ihr Endpunkt oder einen multiregionalen Bucket zu verwenden.

Identitäts- und Zugriffsverwaltungsrollen

Konfigurieren Sie die folgenden Rollen für die beteiligten Identitäten:

Modellbereitsteller (auch als IT-Administrator bezeichnet): Die Identität, die das Modell bereitstellt, benötigt die Berechtigung roles/aiplatform.admin, um Endpunkte zu erstellen und Bereitstellungen zu verwalten.
Serving-Identität: Beim Ausführen von Inferenz schreiben die AlphaFold 3-Endpunkte Ausgabestrukturen direkt in Cloud Storage. Dazu wird das Dienstkonto des Mandantenprojekts verwendet. Das entsprechende Dienstkonto benötigt die roles/storage.objectUser für den Cloud Storage-Ziel-Bucket.
Modellnutzer: Für die Konten, mit denen Vorhersagen gestartet werden, sind folgende Voraussetzungen erforderlich:
- roles/aiplatform.user, um Vorhersageanfragen an den Endpunkt zu senden.
- roles/storage.objectUser, um auf Vorhersageausgaben im Cloud Storage-Bucket zuzugreifen.

AlphaFold 3 bereitstellen

Stellen Sie AlphaFold 3 programmgesteuert mit dem Agent Platform SDK bereit, entweder als dedizierten Google Cloud-Endpunkt oder als Private Service Connect-Endpunkt. Je nach GPU-Verfügbarkeit kann es 10 bis 15 Minuten dauern, bis der Endpunkt für die Inferenz bereit ist.

Das folgende Python-Snippet zeigt, wie Sie das Modell in einem Google Cloud -Projekt bereitstellen, einschließlich einer Verlängerung des Inferenz-Timeouts:

import google.auth
from google.auth.transport.requests import AuthorizedSession
import vertexai
from vertexai import model_garden

PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
MODEL_ID = "google/alphafold3@v3_0_4"
MACHINE_TYPE = "a3-highgpu-1g"

vertexai.init(project=PROJECT_ID, location=LOCATION)

# 1. Deploy Model Garden OpenModel to Dedicated Endpoint
af3_model = model_garden.OpenModel(MODEL_ID)
endpoint = af3_model.deploy(
    endpoint_display_name="af3-dedicated-ep",
    model_display_name="af3-on-mg",
    machine_type=MACHINE_TYPE,
    accelerator_type="NVIDIA_H100_80GB",
    accelerator_count=1,
    reservation_affinity_type="ANY_RESERVATION",
    use_dedicated_endpoint=True,
    accept_eula=True,
    min_replica_count=1,
    max_replica_count=1,
    serving_container_deployment_timeout=3600,
)

# 2. Update inference timeout to 3,600 seconds
credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
session = AuthorizedSession(credentials)
url = f"https://{LOCATION}-aiplatform.googleapis.com/v1/{endpoint.resource_name}:update"
payload = {
    "endpoint": {
        "name": endpoint.resource_name,
        "clientConnectionConfig": {
            "inferenceTimeout": {
                "seconds": 3600
            }
        }
    }
}
response = session.post(url, json=payload)
response.raise_for_status()
print(f"Endpoint Resource Name: {endpoint.resource_name}")

API-Referenz

In diesem Abschnitt werden der Endpunkt, das URL-Format, die Pfadparameter und das Schema der Anfrage-Nutzlast beschrieben.

HTTP-Anfrage

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

Ersetzen Sie Folgendes:

HOST: der Host des Dienstendpunkts. Das hängt davon ab, ob der Bereitstellungstyp ein dedizierter öffentlicher Endpunkt ist oder Private Service Connect verwendet.
PROJECT_ID: die Google Cloud Projekt-ID des Projekts, in dem der bereitgestellte Endpunkt gehostet wird.
LOCATION: die Google Cloud Region, in der der Endpunkt bereitgestellt wird (z. B. us-central1).
ENDPOINT_ID: Die eindeutige Kennung des bereitgestellten Agent Platform-Endpunkts.

Anfragetext

Der Anfragetext enthält Daten mit folgender JSON-Struktur:

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

Anfragefelder der obersten Ebene

Feld	Typ	Beschreibung
`instances`	`array`	Erforderlich. Die Liste der zu prognostizierenden Konfigurationen für biologische Sequenzen. Diese Liste muss genau ein Element enthalten. Wenn Sie null oder mehr als ein Element übergeben, wird ein `HTTP 422 Unprocessable Entity`-Fehler ausgegeben. Im `instances`-Body sollten die Eingaben gemäß der in der AlphaFold 3-Dokumentation veröffentlichten Spezifikation angegeben werden.
`parameters`	`object`	Optional. Ein Objekt mit Ausführungsparametern zum Konfigurieren des Vorhersagelaufs (z. B. `dry_run`, `output_dir`).

Parameter

Konfigurieren Sie Ausführungs-Flags für den AlphaFold 3-Lauf.

Feld	Typ	Standardwert	Beschreibung
`dry_run`	`boolean`	`false`	Optional. Wenn `true`, führt die API die Anfragevalidierung aus, umgeht aber die Modellausführung und gibt sofort eine leere Antwort zurück. Nützlich für Konnektivitäts- und Syntaxprüfungen.
`run_data_pipeline`	`boolean`	`true`	Optional. Wenn `true`, wird die gesamte Pipeline ausgeführt (MSA-Suche und ‑Inferenz). Wenn `false`, wird nur die Inferenz ausgeführt (die Datenbanksuche wird übersprungen; es sind vorab berechnete MSAs erforderlich). Weitere Informationen finden Sie in der Dokumentation auf GitHub.
`output_dir`	`string`	`null`	Optional. Der Cloud Storage-URI (z. B. `gs://bucket/path`), in den die vollständigen Rohausgabedateien (einschließlich CIF-Strukturen, PAE und Ranking-CSVs) nach erfolgreicher Ausführung hochgeladen werden.
`force_output_dir`	`boolean`	`false`	Optional. Bei `true` können vorhandene Dateien im angegebenen `output_dir` überschrieben werden. Wenn `false`, gibt die API sofort einen `HTTP 400 Bad Request`-Fehler zurück, wenn der Cloud Storage-Pfad nicht leer ist, um versehentlichen Datenverlust zu verhindern.
`resolve_msa_overlaps`	`boolean`	`true`	Optional. Gibt an, ob nicht gekoppelte MSAs im Vergleich zu gekoppelten MSAs dedupliziert werden sollen. Best Practices finden Sie in den Richtlinien in der GitHub-Dokumentation zu AlphaFold 3.
`max_template_date`	`string`	`null`	Optional. Maximales Veröffentlichungsdatum der Vorlage im Format `YYYY-MM-DD` (z. B. `"2024-05-15"`). Die Validierung schlägt mit dem Fehler `HTTP 422` fehl, wenn die Formatierung falsch ist.
`conformer_max_iterations`	`integer`	`null`	Optional. Überschreiben der maximalen Anzahl von Iterationen, die für die RDKit-Konformersuche ausgeführt werden sollen. Muss eine nicht negative Ganzzahl (größer oder gleich null) sein. Die Validierung schlägt mit einem `HTTP 422`-Fehler für negative Werte fehl.
`fix_standalone_glycans`	`boolean`	`false`	Optional. Ermöglicht die eigenständige Korrektur der Glykanposition.
`flash_attention_implementation`	`string`	`null`	Optional. Zu verwendende Backend-Implementierung für Flash Attention. Zulässige Werte sind `"triton"`, `"cudnn"` und `"xla"`.
`num_recycles`	`integer`	`10`	Optional. Anzahl der Recycling-Iterationen, die während der Inferenz verwendet werden sollen. Muss eine positive Ganzzahl (größer als null) sein. Weitere Informationen zu den Kompromissen finden Sie im Abschnitt zu Best Practices.
`num_diffusion_samples`	`integer`	`5`	Optional. Anzahl der zu generierenden Diffusionsstichproben. Muss eine positive Ganzzahl (größer als null) sein. Weitere Informationen zu den Kompromissen finden Sie im Abschnitt zu Best Practices.
`save_embeddings`	`boolean`	`false`	Optional. Gibt an, ob die endgültigen Trunk-Einzel- und ‑Paareinbettungen am Speicherort `output_dir` gespeichert werden sollen. Wenn `true`, werden die Einbettungen als `.npz`-Dateien in einem Unterordner mit dem Namen `seed-{SEED}_embeddings/` geschrieben (z. B. `outputs_config_job_seed-50_embeddings.npz`).
`save_distogram`	`boolean`	`false`	Optional. Gibt an, ob das endgültige vorhergesagte Distogramm am Speicherort `output_dir` gespeichert werden soll. Wenn `true`, werden die Einbettungen als `.npz`-Dateien in einem Unterordner mit dem Namen `seed-{SEED}_embeddings/` geschrieben (z. B. `outputs_config_job_seed-50_embeddings.npz`).
`compress_large_output_files`	`boolean`	`false`	Optional. Wenn `true`, werden die großen Ausgabedateien (mmCIF-Strukturen und JSON-Dateien mit Konfidenzwerten) mit zstandard komprimiert. Dadurch werden Dateien mit den Erweiterungen `.cif.zst` und `.json.zst` anstelle von `.cif` und `.json` ausgegeben. Kleine Dateien wie `ranking_scores.csv` bleiben unkomprimiert.
`num_seeds`	`integer`	`null`	Optional. Anzahl der Zufalls-Seeds, die für die Inferenz verwendet werden sollen. Im Allgemeinen sollten Sie für die Reproduzierbarkeit Seeds im Feld `instances.modelSeeds` festlegen. Weitere Informationen zu den Kompromissen finden Sie im Abschnitt zu Best Practices.

Antwort (Ausgabe)

In diesem Abschnitt werden die Felder beschrieben, die bei erfolgreicher Ausführung in der API-Antwort zurückgegeben werden.

Antworttext

Bei erfolgreicher Ausführung gibt der Endpunkt die Antwort im Standardformat des Schemas für Onlinevorhersagen der Agent Platform zurück:

{
  "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"
    }
  ]
}

Antwortfelder der obersten Ebene

Feld	Typ	Beschreibung
`deployedModelId`	`string`	Die ID des bereitgestellten Modells am Agent Platform-Endpunkt.
`model`	`string`	Der voll qualifizierte Ressourcenname des Modells.
`modelDisplayName`	`string`	Der Anzeigename des bereitgestellten Modells (immer `"alphafold3"`).
`modelVersionId`	`string`	Die Versions-ID des bereitgestellten Modells.
`predictions`	`array`	Die Liste der Vorhersageergebnisse. Für AlphaFold 3 enthält dieses Array genau ein Vorhersageergebnisobjekt.

Details zum Vorhersageergebnis (`predictions[]`)

Der AlphaFold 3-Vorhersageendpunkt gibt eine HTTP 200-JSON-Antwort zurück, die ein predictions-Array mit Strukturkoordinaten und Vertrauensmetriken für den bestplatzierten Kandidaten enthält. Umfassende Felddefinitionen und Spezifikationen für Ausgabedateien finden Sie in der offiziellen AlphaFold 3-Dokumentation auf GitHub.

Je nachdem, ob parameters.output_dir in der Anfrage angegeben ist, kann die Ausgabestruktur in der API-Antwort variieren:

Vorhersage in HTTP-Antwort: Die Inline-Antwort gibt globale Zusammenfassungsstatistiken (summary), Koordinaten der 3D-Struktur (structure_cif), Konfidenzwerte pro Atom (plddt) und die 2D-Matrix für den vorhergesagten ausgerichteten Fehler (pae) direkt im Textkörper der HTTP-JSON-Antwortnutzlast zurück. Wenn ein Ausgabeverzeichnis angegeben wird, werden große Nutzlastfelder (structure_cif, plddt und pae) aus der HTTP-Antwortnutzlast entfernt (null), um Engpässe bei der Serialisierung zu vermeiden. Stattdessen werden alle Rohmodellausgaben asynchron in den angegebenen Cloud Storage-Bucket exportiert.

Hinweis: Die pae-Matrix skaliert quadratisch mit der Sequenzlänge N. Bei großen Sequenzen oder komplexen Baugruppen führt die Inline-Rückgabe der vollständigen N × N-PAE-Matrix zu großen JSON-Nutzlasten, die HTTP-Serialisierungsverzögerungen verursachen oder Gateway-Fehler aufgrund der Nutzlastgröße auslösen. Bei langen Sequenzen muss parameters.output_dir angegeben werden.
Gespeichertes Artefakt im Cloud Storage-Bucket: Wenn ein Ausgabeverzeichnis (parameters.output_dir) angegeben ist, werden die umfassenden Vorhersageergebnisse in Cloud Storage hochgeladen. Der Ausgabefolder enthält Daten gemäß der Spezifikation, die in der AlphaFold 3-Dokumentation auf GitHub veröffentlicht wurde.

Vorhersagen treffen

Die Bereitstellung von Model Garden vereinfacht die Ausführung von End-to-End-Vorhersagepipelines, einschließlich Datenpipeline und Modellinferenz, in einem einzigen API-Aufruf. Das folgende Diagramm zeigt die allgemeine Architektur von AlphaFold 3-Vorhersagen:

Abbildung 1. Vollständige Vorhersagepipeline

Beim Ausführen von Vorhersagen wird dringend empfohlen, einen Cloud Storage-Bucket direkt in den Parametern anzugeben, um den vollständigen Rohdatensatz zu exportieren, einschließlich Unterverzeichnissen pro Stichprobe, Ranking-Manifesten und Rohausgaben. Eine vollständige Aufschlüsselung aller konfigurierbaren Anfragefelder, einschließlich der Parameteroptimierung für Multi-Seed-Sampling, Neural Recycling, Diffusionspfade und benutzerdefinierte kovalente Bindungen, finden Sie im API-Referenzabschnitt.

Bevor Sie lang andauernde Faltungsjobs oder Batch-Pipelines starten, können Sie einen Probelauf ausführen, um Ihre Authentifizierung, IAM-Berechtigungen und Endpunkt-Netzwerkverbindung schnell zu überprüfen.

Vorhersageoptionen

Je nach Workflow kann die Verarbeitung von AlphaFold 3 in vier verschiedene Ausführungsmodi unterteilt werden:

Probelaufmodus
Durchgängiger Vorhersagemodus
Nur Inferenz mit vorab berechneten MSAs und Vorlagen
Ohne MSA und Vorlage

Probelaufmodus

Wenn Sie API-Verbindung, Authentifizierung, Netzwerk und JSON-Schemas prüfen möchten, ohne die Vorhersagepipeline zu starten, können Sie eine Anfrage mit "dry_run": true im Objekt parameters senden. Der Endpunkt führt alle Validierungsroutinen aus (einschließlich der Prüfung der Schreibberechtigungen für Cloud Storage-Bucket und der Validierung von Sequenzzeichen), überspringt aber die Ausführung und gibt sofort eine leere Vorhersageantwort zurück.

Das folgende Beispiel zeigt ein Python-Skript für den Probelaufmodus:

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)

End-to-End-Vorhersagemodus

Für die End-to-End-Vorhersage senden Sie Rohdaten biologischer Sequenzen (Proteine, DNA, RNA, Liganden und PTMs) in einer einzelnen Anfrage. Am Endpunkt wird automatisch eine Suche in der genetischen Datenbank und direkt danach die Modellinferenz ausgeführt. Dies wird für Faltungsjobs ohne vorhandene Ausrichtungen empfohlen.

Das folgende Beispiel zeigt ein Python-Skript für den End-to-End-Vorhersagemodus:

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)

Nur Inferenz mit vorab berechneten MSAs und Vorlagen

Möglicherweise haben Sie bereits vorab berechnete MSAs und mmCIF-Vorlagen aus einer früheren Ausführung oder die außerhalb des Modellendpunkts generiert wurden. In diesen Fällen kann die Suche in der genetischen Datenbank vollständig umgangen werden, indem die Alignments und Vorlagen bereitgestellt werden. Die Anfrage wird dann direkt an die Strukturvorhersage weitergeleitet. Dadurch kann auch die Reaktionszeit für die Inferenz deutlich verkürzt werden. Dies ist in den folgenden Szenarien der empfohlene Weg:

Wenn mehrere verschiedene niedermolekulare Liganden an ein einzelnes statisches Protein-Target angedockt werden, können die MSAs wiederverwendet werden.
Die gleiche Molekülsequenz wird iterativ für mehrere zufällige Ausgangswerte ausgeführt, um die strukturelle Flexibilität abzubilden.
Sequenzen werden offline mit privaten, nicht öffentlichen Genomdatenbanken abgeglichen.
GPU-Ressourcen für AlphaFold 3 optimieren, um sich nur auf die Strukturgenerierung zu konzentrieren.

Das folgende Beispiel zeigt ein Python-Skript für den reinen Inferenzmodus:

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)

Ohne MSA und Vorlage

Es gibt auch die Möglichkeit, die Suche in der Gendatenbank und den Vorlagenabgleich vollständig zu umgehen. Das Modell sagt die 3D-Struktur nur anhand der Anfragesequenz voraus, ohne homologe Sequenzen oder Informationen zur Co-Evolution. Um diesen Modus auszulösen, geben Sie in der Instanz leere Strings für die MSA-Parameter unpairedMsa und pairedMsa sowie eine leere Liste für templates an und legen Sie in den Parametern run_data_pipeline auf false fest. Das kann nützlich sein, wenn Sie synthetische oder künstliche Moleküle entwerfen oder Strukturvorhersagen ohne evolutionären Kontext testen möchten.

Das folgende Beispiel zeigt ein Python-Skript zum Ausführen von AlphaFold 3 ohne MSA und Vorlagen:

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)

Ausführliche Spezifikationen, Einheitsparameter und Konfidenzmesswerte für die Ausgabe finden Sie in der AlphaFold 3-Dokumentation auf GitHub.

Vorhersageausgaben

Der AlphaFold 3-Vorhersagedienst bietet zwei sich ergänzende Bereitstellungsmechanismen zum Abrufen von Vorhersageergebnissen. Standardmäßig werden in der API-Antwort Vorhersageergebnisse für den am höchsten eingestuften Kandidaten synchron inline zurückgegeben. Optional können Sie ein Cloud Storage-Verzeichnis angeben.

Im folgenden Abschnitt finden Sie eine Übersicht über die Vorhersageausgabe. Weitere Informationen finden Sie in der AlphaFold 3-Dokumentation auf GitHub.

Inline-Antworten im Vergleich zu gespeicherten Artefakten

Der AlphaFold 3-Vorhersagedienst unterstützt zwei primäre Ausgabemuster:

Inline-Antwort: Gibt die Koordinaten der 3D-Struktur und die Vertrauensmesswerte nur für den bestplatzierten Kandidaten direkt in der HTTP-REST-Antwortnutzlast zurück. Das ist ideal für schnelles interaktives Prototyping oder Anfragen mit einer einzelnen Sequenz.
Gespeicherte Artefakte (Cloud Storage): Wenn Sie ein Ausgabeverzeichnis angeben, wird das vollständige Dataset mit mehreren Stichproben in Cloud Storage exportiert. Dazu gehören einzelne Koordinatendateien, JSON-Dateien mit Konfidenzwerten, Distogramme, Einbettungen und Zusammenfassungsmesswerte für jeden generierten zufälligen Seed und jede Diffusionsprobe. Die Verwendung von Cloud Storage wird für Produktionsarbeitslasten, die Zuordnung von Konformationsensembles und die Umgehung des Limits für die Größe der Anfrage-Payload empfohlen.

Im Folgenden finden Sie ein Python-Beispiel dafür, wie Sie gespeicherte Artefakte aus Cloud Storage für die Downstream-Analyse abrufen:

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

Da AlphaFold 3 ein generatives Diffusionsmodell verwendet, wird bei jedem Vorhersagelauf ein Ensemble von Kandidaten für 3D-Strukturen über verschiedene Ausgangswerte und Sampling-Trajektorien hinweg generiert. Durch die Bewertung und den Vergleich dieser Kandidatenläufe können Sie die Vorhersageergebnisse interpretieren, bevor Sie eine detaillierte Strukturanalyse durchführen.

Sie können das vollständige Dataset mit Artefakten aus mehreren Stichproben anhand von drei Kern-Dateien untersuchen:

ranking_scores.csv: Das Hauptregister mit allen generierten Trajektorienpaaren und dem zugehörigen zusammengesetzten ranking_score. Die Zeilen werden in der Reihenfolge der Trajektorausführung gespeichert (aufsteigend nach Seed und dann aufsteigend nach Stichprobenindex sortiert), nicht nach dem Score vorsortiert. Nutzer sollten nach ranking_score absteigend sortieren, um infrage kommende Ränge zu ermitteln.
summary_confidences.json: Enthält globale Qualitätsmesswerte (pTM, ipTM, has_clash, fraction_disordered) für den besten Kandidaten.
Pro-Sample-summary_confidences.json: Diese befinden sich in den einzelnen seed-{SEED}_sample-{INDEX}/-Ordnern. So können Sie bei Bedarf die pTM- und ipTM-Matrizen auf Chainebene für bestimmte Läufe mit nicht optimalen Kandidaten untersuchen.

Im folgenden Python-Beispiel werden ranking_scores.csv und summary_confidences.json geparst, um Kandidatenbeispiele zu bewerten und die Qualität des Top-Kandidaten zu validieren:

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

Ausführliche Schemaspezifikationen der gespeicherten Dateien und mmCIF-Attribute finden Sie in der AlphaFold 3-Dokumentation auf GitHub. Im Leitfaden zum Bewerten der Qualität von AlphaFold 3-Vorhersagen auf EMBL-EBI erfahren Sie, wie Sie die Qualität der Vorhersagen bewerten können.

Best Practices

In den folgenden Abschnitten werden Best Practices für die Verwendung von AlphaFold 3 auf der Agent Platform beschrieben:

Zeitlimits für Anfragen vermeiden

Für Endpunkte auf der Agent Platform gilt ein standardmäßiges maximales Ausführungs-Zeitlimit von 60 Minuten pro Anfrage. Damit Ihre Vorhersagen erfolgreich abgeschlossen werden, ohne dass es zu einem Zeitüberschreitungsfehler kommt, sollten Sie die folgenden Richtlinien beachten:

Übermäßiges Sampling in einer einzelnen Anfrage vermeiden: Wenn Sie in einem einzelnen API-Aufruf eine große Anzahl von Ausgangsbildern oder übermäßig hohe Parameter für die Rückwärtsdiffusion festlegen, kann die Ausführungszeit das Limit von 60 Minuten überschreiten.
Umfangreiche Sweeps aufteilen: Bei groß angelegten Studien sollten Sie Ihre Seeds und Parameter-Sweeps in mehrere kleinere Vorhersage-Payloads aufteilen und als separate Jobs einreichen. Dabei wird auch die Autoscaling-Kapazität Ihres Endpunkts genutzt.

MSA-Suche umgehen

Die Suche in der genetischen Datenbank ist die zeitaufwendigste Phase der AlphaFold-Pipeline. Wenn Sie iterative Vorhersagen für dieselbe Sequenz ausführen (z. B. Ligand-Screening-Sweeps für ein festes Proteinziel), können Sie die Ausführungszeiten erheblich optimieren, indem Sie die Datenbanksuche vollständig umgehen:

MSA extrahieren: Führen Sie eine erste End-to-End-Vorhersage mit einem angegebenen Cloud Storage-Ausgabeverzeichnis (output_dir) aus. Laden Sie die generierte Datei {JOB_NAME}_data.json aus dem Cloud Storage-Ausgabe-Bucket herunter.
Nur Inferenzvorhersagen einreichen: Suchen Sie in der JSON-Datei nach den Feldern unpairedMsa und pairedMsa. Extrahieren Sie diese MSA-Strings und übergeben Sie sie in nachfolgenden Vorhersageanfragen mit unpairedMsaPath und pairedMsaPath, die auf Cloud Storage-URIs verweisen.

Alternativ können Sie die MSA-Suche auf Ihrer eigenen Infrastruktur ausführen und die vorab berechneten MSA-Vorlagen in die Vorhersageanfrage eingeben.

Läufe mit geringer Zuverlässigkeit verarbeiten

Wenn bei der Ausgabe von Vorhersagen Messwerte mit geringer Zuverlässigkeit ausgegeben werden, können Sie versuchen, das Problem gezielt zu beheben, anstatt von einem nicht behebaren Vorhersagefehler auszugehen. Durch die Optimierung bestimmter Parameter können Sie alternative latente Trajektorien untersuchen. In diesem Abschnitt werden einige Ansätze zur Wiederherstellung bei Vorhersagen mit geringer Konfidenz aufgeführt.

Stichprobenerhebung mit mehreren Ausgangspunkten verwenden

AlphaFold 3 initialisiert die Generierung von 3D-Koordinaten aus zufälligem Rauschen im latenten Raum. Wenn eine Vorhersage mit einem einzelnen bestimmten Seed eingereicht wird, kann die Diffusionskurve im Vergleich zu einem anderen Seed einen anderen Pfad verfolgen. Wenn Sie ein Array von Ausgangswerten übergeben, wird das Modell gezwungen, Trajektorien ab verschiedenen Zuständen zu ziehen.

Die Multi-Seed-Stichprobenerhebung bietet zwei entscheidende Vorteile: Sie überprüft die strukturelle Konsistenz über unabhängige Läufe hinweg und untersucht die funktionelle konformationelle Dynamik. Wenn beispielsweise alle fünf Seeds zu identischen 3D-Koordinaten konvergieren, können Sie sich auf die globale Faltung verlassen. Wenn umgekehrt verschiedene Seeds unterschiedliche, hochkonfidente Bindungsposen erzeugen, kann das Ensemble biologisch sinnvolle Konformationszustände aufzeigen, z. B. offene und geschlossene Active-Site-Schleifen oder alternative domänengetauschte Dimere.

Diffusionspfade erweitern

Während modelSeeds den Startrauschzustand im latenten Raum ändert, steuert der Parameter num_diffusion_samples (Standardwert 5), wie viele 3D-Strukturkandidaten pro Seed während des umgekehrten Diffusionsprozesses generiert werden. Bei flexiblen Schleifenregionen oder flachen Bindungstaschen wird durch eine Erhöhung der Anzahl der Stichproben der Kandidatenpool für jeden Seed erweitert. Dies ist besonders effektiv, wenn die lokalen Konfidenzwerte in bestimmten Schleifen sinken (pLDDT < 70), während die Faltung der gesamten Domäne weiterhin zuverlässig ist (pTM > 0,80). So lassen sich Kandidatenstrukturen mit hoher Wahrscheinlichkeit aufdecken, die beim ersten Durchlauf übersehen wurden.

Anzahl der Recycling-Iterationen erhöhen

Bevor das Diffusionsmodul 3D-Koordinaten generiert, verarbeitet AlphaFold 3 Sequenz- und paarweise Merkmale. Der Parameter num_recycles bestimmt, wie oft Zwischenstrukturdarstellungen und paarweise räumliche Einbettungen iterativ durch das Netzwerk geleitet werden.

Bei großen, komplexen Molekülen oder Zielen mit schwachen koevolutionären Signalen werden durch eine Erhöhung von num_recycles zusätzliche Iterationen für das Trunk-Netzwerk ermöglicht, um räumliche Beziehungen zwischen entfernten Ketten aufzulösen, bevor Eingaben an das Diffusionsmodul übergeben werden. Dieser Ansatz kann versucht werden, wenn die nicht diagonalen PAE-Matrizen trotz hoher lokaler Faltungszuverlässigkeit einzelner Ketten (pLDDT > 70) eine hohe Unsicherheit zwischen den Ketten (> 15 Å) aufweisen. Wenn Sie die Anzahl der Wiederholungen erhöhen, verlängert sich die Vorhersagezeit linear. Daher sollten Sie diese Option nur für schwierige Schnittstellenziele verwenden.

Benutzerdefinierte Abstimmungs-Pipeline verwenden

AlphaFold 3 führt automatisch die Pipeline für die Suche in der genetischen Datenbank aus, um MSA-Vorlagen zu generieren. Nutzer können auch private, vorab berechnete benutzerdefinierte Ausrichtungen im .a3m-Format mit Cloud Storage-URIs über unpairedMsaPath und pairedMsaPath angeben. Die Bereitstellung von tiefen MSAs bietet starke koevolutionäre Einschränkungen, die häufig Vorhersagen mit geringem Konfidenzwert in Modelle mit hohem Konfidenzwert umwandeln.