AlphaFold 3

חשוב: AlphaFold 3 הוא כלי מחקר ולא מיועד לשימוש באבחון קליני.

‫AlphaFold 3 הוא מודל למידה עמוקה שפותח על ידי Google DeepMind ו-Isomorphic Labs. הוא נועד לחזות את המבנים והאינטראקציות התלת-ממדיים של חלבונים, DNA, ‏ RNA, ליגנדים ויונים. במאמר הזה מוסבר איך לפרוס את מודל AlphaFold 3 ולהשתמש בו באמצעות Model Garden בפלטפורמת הסוכנים של Gemini Enterprise.

חשוב: ‏ AlphaFold 3 זמין לכולם (GA), אבל הגישה אליו מוגבלת לרשימת היתרים. כדי לקבל גישה מסחרית ל-AlphaFold 3, צריך למלא את טופס הבקשה ולעבוד עם צוות ניהול החשבון של Google Cloud כדי לקבל מינוי מסחרי ולהתווסף לרשימת ההיתרים. למחקר אקדמי לשימוש לא מסחרי, אפשר לגשת למשקלים ישירות ב-GitHub.

יכולות מרכזיות

פריסת AlphaFold 3 ב-Agent Platform מספקת את היכולות הבאות שנדרשות למחקר ופיתוח מתקדמים (R&D) ולתהליכי עבודה מסחריים לגילוי תרופות:

• שימוש מסחרי: AlphaFold 3 ב-Model Garden זמין לשימוש מסחרי.

• ליגנדים מותאמים אישית שרירותיים: ‏AlphaFold 3 תומך בקיפול משותף מאוחד של חלבונים, DNA ו-RNA לצד ליגנדים מותאמים אישית שמוגדרים באמצעות מחרוזות SMILES או קודי CIF Chemical Component Dictionary (מילון רכיבים כימיים).

• גמישות בתהליך העבודה: AlphaFold 3 ב-Model Garden תומך בצינור מלא של קיפול מקצה לקצה (שילוב של חיפוש במסד נתונים וחיזוי מודל) או במצב של הסקה בלבד, שבו אפשר לספק יישור MSA שחושב מראש כדי לייעל את זמן הביצוע ואת השימוש ב-GPU.

לתשומת ליבכם

כשמעריכים את AlphaFold 3 לעומסי עבודה, חשוב לזכור את המגבלות הבאות:

• מקביליות: לנקודת הקצה של AlphaFold 3 יש מגבלת מקביליות של אחת לכל צומת. כדי להגדיל את מספר הבקשות שאפשר להריץ בו-זמנית, אפשר להרחיב את נקודות הקצה לכמה צמתים. אם נשלחת בקשה לחיזוי בזמן שחיזוי אחר פועל, נקודת הקצה דוחה את הבקשה החדשה עם שגיאה HTTP 429 Too Many Requests אם מספר הבקשות גדול ממספר הצמתים.

• מגבלות על טוקנים: משך החיזוי המקסימלי בנקודות הקצה של Agent Platform הוא 60 דקות. בגלל התקורה המשתנה של חיפוש MSA, גודל הרצף המקסימלי שנתמך במעבדי GPU מסוג A3 הוא תקורה של כ-4,500 אסימונים ביולוגיים (כמו חומצות אמינו, נוקלאוטידים או אטומי ליגנד). אספקת יישור מחושב מראש מדלגת על ביצוע החיפוש של MSA, מה שמאפשר קיפול מורכב עד למגבלת החומרה של כ-5,400 טוקנים.

• מגבלות על מטען ייעודי (payload): בקשות REST רגילות לחיזוי מוגבלות לגודל של 8MB. אם משתמשים במצב של הסקת מסקנות בלבד, צריך להפנות ליישור גדול שחושב מראש (קבצים מסוג .a3m) באמצעות URI של Cloud Storage ולא להטמיע אותו כמחרוזות מוטמעות, כדי להימנע מדחיית מטען ייעודי.

• הגדרת רשת: חיזויים הם פעולות ממושכות שיכולות להימשך עד 60 דקות. לכן, מומלץ לפרוס את נקודת הקצה (endpoint) באמצעות Private Service Connect ‏(PSC) כדי לעקוף את מגבלות הזמן הקצוב לתפוגה הרגילות של נקודות קצה (10 דקות).

הוראות פריסה

בקטע הזה מוסבר איך פורסים את AlphaFold 3 לנקודת קצה שסופקה על ידי Agent Platform בפרויקט ב- Google Cloud .

לפני שמתחילים

לפני שמבצעים פריסה של AlphaFold 3, צריך:

• שליחת בקשה לגישה למודל.
• רכישת משאבי GPU.
• מגדירים את ההרשאות הנדרשות לניהול זהויות והרשאות גישה (IAM):
  • יוצרים חשבון שירות עם התפקיד Agent Platform Administrator ב-IAM.
  • מוודאים שלחשבון הראשי ב-IAM יש את התפקיד roles/iam.serviceAccountCreator כדי לפעול כחשבון השירות בזמן פריסת המודל.
• מאמתים את מכסות המשאבים.

משאבים נדרשים

‫AlphaFold 3 דורש מכונה וירטואלית (VM) של a3-highgpu-1g.

לפני הפריסה, מוודאים שלפרויקט Google Cloud יש מכסה מספקת באזור הפריסה של היעד למשאבים הבאים:

• מאיצים: לפחות סוג מכונה אחד מסוג a3-highgpu-1g.

• ‫Local SSD: מכונת ה-VM מסוג A3 מוקצית עם נפח של 750GB של Local SSD. הדרישה הזו נובעת מהצורך לשמור במטמון באופן קבוע את מסדי הנתונים של רצפי ההפניה (UniProt,‏ MGnify, ‏ Rfam), כדי לאפשר קריאות עם זמן אחזור נמוך במהלך חיפושים במסדי נתונים גנטיים (Jackhmmer/Nhmmer) בכל בקשות החיזוי.

קטגוריה של Cloud Storage

כדי להשתמש ב-AlphaFold 3, צריך קטגוריה של Cloud Storage לאחסון קובצי MSA שסופקו ולייצוא של פלט חיזוי מלא. כדי להימנע מהעברות בין אזורים, מומלץ להשתמש בקטגוריה של Cloud Storage באותו אזור כמו נקודת הקצה, או להשתמש בקטגוריה שפועלת במספר אזורים.

תפקידים בניהול זהויות והרשאות גישה (IAM)

מגדירים את התפקידים הבאים בכל הזהויות המשתתפות:

• מפיץ המודל (נקרא גם אדמין IT): הזהות שמפיצה את המודל צריכה את ההרשאה roles/aiplatform.admin כדי ליצור נקודות קצה ולנהל פריסות.

• זהות ההגשה: כשמריצים הסקה, נקודות הקצה של AlphaFold 3 כותבות מבני פלט ישירות ל-Cloud Storage באמצעות חשבון השירות של פרויקט הדייר. חשבון השירות המתאים צריך לקבל את ההרשאה roles/storage.objectUser בדלי היעד ב-Cloud Storage.

• משתמשים במודל: החשבונות שמתחילים את התחזיות צריכים לעמוד בדרישות הבאות:

  • ‫roles/aiplatform.user כדי לשלוח בקשות לחיזוי לנקודת הקצה.
  • ‫roles/storage.objectUser כדי לגשת לפלט של התחזיות בקטגוריה של Cloud Storage.

פריסת AlphaFold 3

אפשר לפרוס את AlphaFold 3 באופן פרוגרמטי באמצעות Agent Platform SDK רק כנקודת קצה (endpoint) ייעודית של Google Cloud או כנקודת קצה (endpoint) של Private Service Connect. יכול להיות שיחלפו 10-15 דקות עד שהנקודה תהיה מוכנה להסקת מסקנות, בהתאם לזמינות של ה-GPU.

חשוב: מומלץ לפרוס את המודל באופן פרוגרמטי ולעדכן באופן מפורש את הזמן הקצוב לתפוקת המסקנות ל-3,600 שניות. אם משתמשים במסוףGoogle Cloud כדי לפרוס את המודל, המסוף Google Cloud אוכף פסק זמן קפדני של 600 שניות להסקת מסקנות. כדי לפתור את הבעיה, אפשר להאריך את זמן הקצוב לתפוגה של ההסקה ל-3,600 שניות באמצעות תכנות.

בקטע הקוד הבא ב-Python אפשר לראות איך פורסים את המודל בפרויקט Google Cloud , כולל הארכה של הזמן הקצוב לתפוקה:

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

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

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

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

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

מאמרי העזרה של ה-API

בקטע הזה מתואר מיקום נקודת הקצה, פורמט כתובת ה-URL, פרמטרים של נתיב וסכמת מטען הנתונים של הבקשה.

בקשת HTTP

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫HOST: המארח של נקודת הקצה של השירות. הדבר תלוי בשאלה אם סוג הפריסה הוא נקודת קצה ציבורית ייעודית או אם נעשה שימוש ב-Private Service Connect.

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud שבו מתארחת נקודת הקצה שנפרסה.

• ‫LOCATION: Google Cloud האזור שבו נקודת הקצה פרוסה (למשל us-central1).

• ‫ENDPOINT_ID: המזהה הייחודי של נקודת הקצה של Agent Platform שנפרסה.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה JSON הבא:

{
  "instances": [
    {
      # The AlphaFold 3 input JSON - see the input documentation at
      # https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md
    }
  ],
  "parameters": {
    "output_dir": "string",
    "dry_run": boolean,
    "run_data_pipeline": boolean,
    "force_output_dir": boolean,
    "resolve_msa_overlaps": boolean,
    "max_template_date": "string",
    "conformer_max_iterations": integer,
    "fix_standalone_glycans": boolean,
    "flash_attention_implementation": "string",
    "num_recycles": integer,
    "num_diffusion_samples": integer,
    "save_embeddings": boolean,
    "save_distogram": boolean,
    "compress_large_output_files": boolean,
    "num_seeds": integer
  }
}

שדות של בקשה ברמה העליונה

שדה	סוג	תיאור
instances	array	חובה. רשימת ההגדרות של רצפים ביולוגיים לחיזוי. הרשימה הזו חייבת להכיל בדיוק רכיב אחד. העברת אפס או יותר מרכיב אחד גורמת לשגיאה HTTP 422 Unprocessable Entity. בגוף הבקשה instances צריך לציין את נתוני הקלט בהתאם למפרט שפורסם במסמכי AlphaFold 3.
parameters	object	אופציונלי. אובייקט שמכיל פרמטרים של הפעלה להגדרת ההרצה של התחזית (כמו dry_run, output_dir).

פרמטרים

מגדירים את דגלי ההרצה של AlphaFold 3.

שדה	סוג	ערך ברירת המחדל	תיאור
dry_run	boolean	false	אופציונלי. אם הערך הוא true, ה-API מבצע אימות של הבקשה, אבל מדלג על הפעלת המודל ומחזיר תגובה ריקה באופן מיידי. האפשרות הזו שימושית לבדיקת הקישוריות והתחביר.
run_data_pipeline	boolean	true	אופציונלי. אם true, מופעל צינור מלא (חיפוש MSA והסקת מסקנות). אם false, מריץ הסקה בלבד (מדלג על חיפוש במסד הנתונים; נדרשים MSA מחושבים מראש). פרטים נוספים זמינים במאמרי העזרה ב-GitHub.
output_dir	string	null	אופציונלי. ה-URI של Cloud Storage (לדוגמה, gs://bucket/path) שאליו מועלים קובצי הפלט המלאים (כולל מבני CIF, ‏ PAE וקובצי CSV של דירוג) אחרי ביצוע מוצלח.
force_output_dir	boolean	false	אופציונלי. אם true, מאפשרת דריסת קבצים קיימים ב-output_dir שצוין. אם false, ה-API מחזיר שגיאה HTTP 400 Bad Request באופן מיידי אם הנתיב ב-Cloud Storage לא ריק, כדי למנוע אובדן נתונים לא מכוון.
resolve_msa_overlaps	boolean	true	אופציונלי. האם לבטל כפילויות של הסכמי MSA לא משויכים בהשוואה להסכמי MSA משויכים. במסמכי התיעוד של GitHub AlphaFold 3 מפורטות שיטות מומלצות.
max_template_date	string	null	אופציונלי. תאריך ההפצה המקסימלי של התבנית שצריך לקחת בחשבון בפורמט YYYY-MM-DD (לדוגמה, "2024-05-15"). אם הפורמט שגוי, האימות נכשל עם שגיאה HTTP 422.
conformer_max_iterations	integer	null	אופציונלי. החלפת הערך של המספר המקסימלי של איטרציות להרצה בחיפוש אחר קונפורמציה ב-RDKit. הערך חייב להיות מספר שלם לא שלילי (גדול מ-0 או שווה לו). האימות נכשל עם שגיאה HTTP 422 במקרה של ערכים שליליים.
fix_standalone_glycans	boolean	false	אופציונלי. הפעלת תיקון מיקום גליקן עצמאי.
flash_attention_implementation	string	null	אופציונלי. הטמעה של קצה עורפי של Flash attention לשימוש. הערכים המותרים הם "triton", ‏ "cudnn",‏ "xla".
num_recycles	integer	10	אופציונלי. מספר האיטרציות של המיחזור שבהן יש להשתמש במהלך ההסקה. הערך חייב להיות מספר שלם חיובי (גדול מאפס). בקטע השיטות המומלצות מוסבר על היתרונות והחסרונות של כל אחת מהאפשרויות.
num_diffusion_samples	integer	5	אופציונלי. מספר הדוגמאות של הדיפוזיה שייווצרו. הערך חייב להיות מספר שלם חיובי (גדול מאפס). בקטע השיטות המומלצות מוסבר על היתרונות והחסרונות של כל אחת מהאפשרויות.
save_embeddings	boolean	false	אופציונלי. האם לשמור את ההטמעות הסופיות של הענף הראשי, של ההטמעה הבודדת ושל ההטמעה הזוגית במיקום output_dir. אם true, ההטמעות נכתבות כקבצים מסוג .npz בתיקיית משנה בשם seed-{SEED}_embeddings/ (לדוגמה, outputs_config_job_seed-50_embeddings.npz).
save_distogram	boolean	false	אופציונלי. האם לשמור את הדיסטוגרמה הסופית שחוזה את המרחק במיקום output_dir. אם true, ההטמעות נכתבות כקבצים מסוג .npz בתיקיית משנה בשם seed-{SEED}_embeddings/ (לדוגמה, outputs_config_job_seed-50_embeddings.npz).
compress_large_output_files	boolean	false	אופציונלי. אם true, דוחס את קובצי הפלט הגדולים (מבני mmCIF וקובצי JSON של רמות הביטחון) באמצעות zstandard. הפלט יהיה קבצים עם הסיומות .cif.zst ו-.json.zst במקום .cif ו-.json. קבצים קטנים (כמו ranking_scores.csv) לא נדחסים.
num_seeds	integer	null	אופציונלי. מספר הזרעים האקראיים שבהם יש להשתמש להסקת מסקנות. באופן כללי, כדאי להגדיר ערכי seed בשדה instances.modelSeeds כדי לשחזר את התוצאות. בקטע השיטות המומלצות מוסבר על היתרונות והחסרונות של כל אחת מהאפשרויות.

הערה: כשמציינים את output_dir, חשוב לוודא שלסוכן השירות של Agent Platform ([e-mail])) יש את התפקיד roles/storage.objectUser כדי לגשת לקטגוריה של Cloud Storage. בלי קישור התפקיד הזה, העלאות של תחזיות ל-Cloud Storage נכשלות עם שגיאה HTTP 403

.

תשובה (פלט)

בקטע הזה מתוארים השדות שמוחזרים בתגובת ה-API אחרי ביצוע מוצלח.

גוף התשובה

אחרי ביצוע מוצלח, נקודת הקצה מחזירה את התגובה בפורמט סכמת החיזוי אונליין של Agent Platform:

{
  "deployedModelId": "string",
  "model": "string",
  "modelDisplayName": "string",
  "modelVersionId": "string",
  "predictions": [
    {
      "structure_cif": "string",
      "plddt": [
        number
      ],
      "pae": [
        [
          number
        ]
      ],
      "summary": {
        "ptm": number,
        "iptm": number,
        "fraction_disordered": number,
        "has_clash": boolean,
        "ranking_score": number,
        "chain_pair_pae_min": [
          [
            number
          ]
        ],
        "chain_pair_iptm": [
          [
            number
          ]
        ],
        "chain_ptm": [
          number
        ],
        "chain_iptm": [
          number
        ],
        "chain_ids": [
          string
        ]
      },
      "output_dir": "string"
    }
  ]
}

שדות תשובה ברמה העליונה

שדה	סוג	תיאור
deployedModelId	string	המזהה של המודל שנפרס בנקודת הקצה של Agent Platform.
model	string	שם המשאב המוגדר במלואו של המודל.
modelDisplayName	string	השם המוצג של המודל שנפרס (תמיד "alphafold3").
modelVersionId	string	מזהה הגרסה של המודל שנפרס.
predictions	array	רשימת תוצאות התחזית. ב-AlphaFold 3, המערך הזה מכיל בדיוק אובייקט אחד של תוצאת חיזוי.

פרטים של תוצאת החיזוי (predictions[])

נקודת הקצה של התחזית של AlphaFold 3 מחזירה HTTP 200 תגובת JSON שמכילה predictions מערך עם קואורדינטות מבניות ומדדי מהימנות למועמד שדורג במקום הראשון. הגדרות מקיפות של השדות ומפרטים של קובץ הפלט מופיעים במסמכי AlphaFold 3 הרשמיים ב-GitHub.

בהתאם לכך אם parameters.output_dir מסופק בבקשה, מבנה הפלט בתגובת ה-API יכול להשתנות:

• חיזוי בתגובת HTTP: התגובה המוטבעת מחזירה מדדי סיכום גלובליים (summary), קואורדינטות של מבנה תלת-ממדי (structure_cif), ציוני מהימנות לכל אטום (plddt) ואת מטריצת השגיאות החזויות של היישור הדו-ממדי (pae) ישירות בגוף של מטען הנתונים של תגובת ה-JSON של HTTP. כשמציינים ספריית פלט, שדות גדולים של מטען ייעודי (structure_cif, plddt ו-pae) מושמטים (null) ממטען ייעודי של תגובת HTTP כדי למנוע צווארי בקבוק בסריאליזציה. במקום זאת, כל נתוני הפלט הגולמיים של המודל מיוצאים באופן אסינכרוני לקטגוריה של Cloud Storage שצוינה.

  הערה: המטריצה pae גדלה באופן ריבועי עם אורך הרצף N. במקרים של רצפים גדולים או הרכבות מורכבות, החזרת מטריצת ה-PAE המלאה בגודל N x N בשורה יוצרת מטען ייעודי (payload) גדול של JSON שגורם לעיכובים בסריאליזציה של HTTP או מפעיל שגיאות בגודל המטען הייעודי (payload) של שער. בסדרות גדולות, צריך לציין את parameters.output_dir.

• Saved artifact in Cloud Storage bucket: כשמציינים ספריית פלט (parameters.output_dir), תוצאות החיזוי המקיפות מועלות לקטגוריה של Cloud Storage. תיקיית הפלט מכילה נתונים בהתאם למפרט שפורסם במסמכי AlphaFold 3 ב-GitHub.

יצירת תחזיות

פריסה של Model Garden מפשטת את הביצוע של פייפליין חיזוי מקצה לקצה, כולל פייפליין נתונים והיקש של מודל בקריאה ל-API אחת. התרשים הבא מציג את הארכיטקטורה ברמה גבוהה של תחזיות AlphaFold 3:

איור 1. צינור תחזיות מלא

כשמבצעים חיזויים, מומלץ מאוד לספק קטגוריה של Cloud Storage ישירות בפרמטרים כדי לייצא את מערך הנתונים הגולמי המלא, כולל ספריות משנה לכל דגימה, מניפסטים של דירוג ותוצאות גולמיות. פירוט מלא של כל השדות של הבקשה שאפשר להגדיר, כולל כוונון פרמטרים לדגימה של כמה ערכי התחלה, שימוש חוזר ברשתות עצביות, מסלולי דיפוזיה וקשרים קוולנטיים בהתאמה אישית, מופיע במאמרי העזרה של ה-API.

לפני שמפעילים משימות ארוכות טווח של קיפול או צינורות להרצת אצווה, אפשר להריץ ניסיון הרצה כדי לאמת במהירות את האימות, את הרשאות IAM ואת קישוריות הרשת של נקודת הקצה.

אפשרויות חיזוי

בהתאם לתהליך העבודה, אפשר לארגן את העיבוד של AlphaFold 3 בארבעה מצבי הפעלה נפרדים:

• מצב פרימטר לבדיקות
• מצב חיזוי מקצה לקצה
• הסקת מסקנות בלבד עם הסכמי MSA ותבניות שחושבו מראש
• הפעלת שיוך ללא MSA וללא תבנית

מצב הרצה יבשה

כדי לאמת את הקישוריות ל-API, את האימות, את הרשת ואת סכימות ה-JSON בלי להפעיל את צינור העיבוד של התחזיות, אפשר לשלוח בקשה עם "dry_run": true באובייקט parameters. נקודת הקצה מפעילה את כל שגרות האימות (כולל בדיקת הרשאות כתיבה לקטגוריה של Cloud Storage ואימות של תווים ברצף), אבל מדלגת על ההפעלה ומחזירה מיד תגובה ריקה של חיזוי.

הנה דוגמה לסקריפט Python במצב הרצה יבשה:

from google.cloud import aiplatform

PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
ENDPOINT_ID = "YOUR_ENDPOINT_ID"

# Initialize AI Platform SDK
aiplatform.init(project=PROJECT_ID, location=LOCATION)

# Connect to Dedicated Endpoint
endpoint = aiplatform.Endpoint(ENDPOINT_ID)

# Define prediction payload
instances = [
    {
        "name": "preflight_check",
        "dialect": "alphafold3",
        "version": 4,
        "modelSeeds": [1],
        "sequences": [
            {
                "protein": {
                    "id": "A",
                    "sequence": "PVLSCGEWQL",
                }
            }
        ],
    }
]

parameters = {
    "dry_run": True,
}

# Execute prediction request
response = endpoint.predict(
    instances=instances,
    parameters=parameters
)
print(response.predictions)

מצב חיזוי מקצה לקצה

כדי להריץ חיזוי מקצה לקצה, שולחים רצפים ביולוגיים גולמיים (חלבונים, DNA,‏ RNA, ליגנדים ו-PTM) בבקשה אחת. נקודת הקצה מבצעת באופן אוטומטי חיפוש במסד נתונים גנטי, ואחריו מיד הסקת מסקנות על ידי המודל. מומלץ להשתמש באפשרות הזו כשממזגים משרות שלא קיימות בהן התאמות מראש.

הנה דוגמה לסקריפט Python למצב חיזוי מקצה לקצה:

from google.cloud import aiplatform

# Configuration
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
ENDPOINT_ID = "YOUR_ENDPOINT_ID"
STORAGE_OUTPUT_DIR = "gs://YOUR_BUCKET_NAME/alphafold_output/"

# Initialize AI Platform SDK
aiplatform.init(project=PROJECT_ID, location=LOCATION)

# Instantiate Endpoint reference
endpoint = aiplatform.Endpoint(ENDPOINT_ID)

# Define Prediction Payload
instances = [
    {
        "name": "e2e_protein_ligand_complex",
        "dialect": "alphafold3",
        "version": 4,
        "modelSeeds": [1],
        "sequences": [
            {
                "protein": {
                    "id": "A",
                    "sequence": "PVLSCGEWQL",
                    "modifications": [
                        {"ptmType": "HY3", "ptmPosition": 1}
                    ],
                }
            },
            {
                "ligand": {
                    "id": "B",
                    "ccdCodes": ["MG"],
                }
            },
        ],
    }
]

parameters = {
    "output_dir": STORAGE_OUTPUT_DIR,
}

# Execute Prediction
response = endpoint.predict(
    instances=instances,
    parameters=parameters
)

print(response.predictions)

הסקה בלבד עם תבניות ו-MSA שחושבו מראש

יכול להיות שכבר יש לכם תבניות MSA ו-mmCIF שחושבו מראש מהרצה קודמת או שנוצרו מחוץ לנקודת הקצה של המודל. במקרים כאלה, אפשר לעקוף לחלוטין את החיפוש במסד הנתונים הגנטי על ידי אספקת ההתאמות והתבניות, והפניית הבקשה ישירות לחיזוי המבנה. ההגדרה הזו יכולה גם להפחית באופן משמעותי את זמן התגובה של ההסקה. זהו הנתיב המומלץ בתרחישים הבאים:

• כשמבצעים עגינה של כמה ליגנדים שונים של מולקולות קטנות ליעד חלבון סטטי יחיד, אפשר לעשות שימוש חוזר ב-MSA.
• הרצת אותו רצף מולקולות על פני מספר זרעים אקראיים, באופן איטרטיבי, כדי למפות גמישות מבנית.
• השוואת רצפים אופליין למאגרי מידע גנומיים פרטיים ולא ציבוריים.
• אופטימיזציה של משאבי GPU ל-AlphaFold 3, כדי להתמקד רק ביצירת מבנים.

דוגמה לסקריפט Python במצב הסקה בלבד:

from google.cloud import aiplatform

# Configuration
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-west1"
ENDPOINT_ID = "YOUR_ENDPOINT_ID"
STORAGE_OUTPUT_DIR = "gs://YOUR_BUCKET_NAME/af3_results/inference_only"

# Initialize AI Platform SDK
aiplatform.init(project=PROJECT_ID, location=LOCATION)

# Instantiate Endpoint reference
endpoint = aiplatform.Endpoint(ENDPOINT_ID)

# Define Prediction Payload
instances = [
    {
        "name": "inference_protein_ligand_complex",
        "dialect": "alphafold3",
        "version": 4,
        "modelSeeds": [1],
        "sequences": [
            {
                "protein": {
                    "id": "A",
                    "sequence": "PVLSCGEWQL",
                    "modifications": [
                        {"ptmType": "HY3", "ptmPosition": 1}
                    ],
                    "unpairedMsaPath": "gs://YOUR_BUCKET_NAME/path/to/unpaired.a3m",
                    "pairedMsa": "",
                    "templates": [],
                }
            },
            {
                "ligand": {
                    "id": "B",
                    "ccdCodes": ["MG"],
                }
            },
        ],
    }
]

parameters = {
    "run_data_pipeline": False,
    "output_dir": STORAGE_OUTPUT_DIR,
    "force_output_dir": True,
}

# Execute Prediction
response = endpoint.predict(
    instances=instances,
    parameters=parameters
)

print(response.predictions)

הערה: כשמציינים את STORAGE_OUTPUT_DIR, חשוב לוודא שלסוכן השירות של Agent Platform ([e-mail])) יש את התפקיד roles/storage.objectUser כדי לגשת לקטגוריה של Cloud Storage. בלי קישור התפקיד הזה, העלאות של תחזיות ל-Cloud Storage נכשלות עם שגיאה HTTP 403

.

הפעלת MSA ללא תבנית

יש גם אפשרות לעקוף לחלוטין את החיפוש במסד נתונים גנטי ואת ההתאמה לתבנית. המודל חוזה את המבנה התלת-ממדי רק על סמך רצף השאילתה, ללא רצפים הומולוגיים או מידע על קו-אבולוציה. כדי להפעיל את המצב הזה, צריך לספק מחרוזות ריקות לפרמטרים של MSA‏ unpairedMsa ו-pairedMsa, ורשימה ריקה לפרמטר templates במופע, ולהגדיר את run_data_pipeline ל-false בפרמטרים. האפשרות הזו יכולה להיות שימושית לעיצוב מולקולות סינתטיות או מולקולות מהונדסות, או לבדיקת תחזיות מבניות ללא הקשר אבולוציוני.

הנה דוגמה לסקריפט Python להרצת AlphaFold 3 MSA ללא תבנית:

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)

מפרטים מפורטים, פרמטרים של ישויות ומדדי מהימנות של הפלט זמינים במאמרי העזרה של AlphaFold 3 ב-GitHub.

פלטים של תחזיות

שירות החיזוי של AlphaFold 3 מספק שני מנגנוני מסירה משלימים לאחזור פלטים של חיזויים. כברירת מחדל, תגובת ה-API מחזירה את תוצאות התחזית באופן מוטבע ובאופן סינכרוני, לגבי המועמד שמדורג במקום הראשון. אפשר גם לציין ספרייה ב-Cloud Storage.

בקטע הבא מוצגת סקירה כללית של פלט החיזוי. פרטים נוספים זמינים במאמרי העזרה של AlphaFold 3 ב-GitHub.

תגובה בתוך השורה לעומת ארטיפקטים שנשמרו

שירות החיזוי של AlphaFold 3 תומך בשתי תבניות פלט עיקריות:

• תשובה מוטמעת: מחזירה את הקואורדינטות של מבנה התלת-ממד ומדדי מהימנות רק עבור המועמד בעל הדירוג הגבוה ביותר, ישירות במטען הייעודי (payload) של תשובת HTTP REST. האפשרות הזו אידיאלית ליצירת אב טיפוס אינטראקטיבי מהיר או לשאילתות של רצף יחיד.
• פריטים שנשמרו (Cloud Storage): אם מציינים ספריית פלט, מערך הנתונים המלא של כמה דגימות מיוצא ל-Cloud Storage. הנתונים האלה כוללים קבצים של קואורדינטות בודדות, קובצי JSON של רמת הביטחון, דיסטוגרמות, הטמעות ומדדי סיכום לכל זרע אקראי שנוצר ולכל דגימה של דיפוזיה. מומלץ להשתמש ב-Cloud Storage לעומסי עבודה של ייצור, למיפוי של קבוצות קונפורמציה ולעקיפת המגבלה על גודל מטען הבקשה.

הדוגמה הבאה היא של קוד Python שמראה איך לאחזר פריטי מידע שנשמרו מ-Cloud Storage לצורך ניתוח בהמשך:

from google.cloud import storage

BUCKET_NAME = "your-bucket-name"
JOB_NAME = "my_alphafold_job"
STORAGE_PREFIX = f"af3_results/my_folder/{JOB_NAME}"

# Initialize GCS client
client = storage.Client(project="your-project-id")
bucket = client.bucket(BUCKET_NAME)

# Download the top-ranked 3D structure and global ranking ledger
bucket.blob(f"{STORAGE_PREFIX}/{JOB_NAME}_model.cif").download_to_filename("model.cif")
bucket.blob(f"{STORAGE_PREFIX}/{JOB_NAME}_ranking_scores.csv").download_to_filename("ranking_scores.csv")
bucket.blob(f"{STORAGE_PREFIX}/{JOB_NAME}_summary_confidences.json").download_to_filename("summary.json")

מכיוון ש-AlphaFold 3 משתמש במודל גנרטיבי של דיפוזיה, כל הרצה של חיזוי יוצרת קבוצה של מבני תלת-ממד פוטנציאליים על פני זרעים ומסלולי דגימה. הערכה והשוואה של הריצות האלה יכולות לעזור לכם להבין את התוצאות של התחזיות לפני שתבצעו ניתוח מבני מפורט.

אפשר לבדוק את מערך הנתונים המלא של ארטיפקטים מריבוי דגימות באמצעות שלושה קובצי ליבה:

• ‫ranking_scores.csv: ספר החשבונות הראשי שבו מפורטים כל זוג של מסלול שנוצר והרכיב המשולב שלו ranking_score. השורות נשמרות בסדר הביצוע של המסלול (ממוינות לפי seed בסדר עולה, ואז לפי אינדקס הדגימה בסדר עולה), ולא ממוינות מראש לפי ציון. המשתמשים צריכים למיין לפי ranking_score בסדר יורד כדי לזהות את הדירוגים האפשריים.

• ‫summary_confidences.json: מכיל מדדי איכות גלובליים (pTM,‏ ipTM, ‏ has_clash, ‏ fraction_disordered) לגבי המועמד המוביל.

• ‫Per-Sample summary_confidences.json: נמצא בתוך תיקיות seed-{SEED}_sample-{INDEX}/ נפרדות, ומאפשר לבדוק מטריצות של pTM ו-ipTM ברמת השרשרת עבור ריצות ספציפיות של מועמדים לא מובילים, אם צריך.

בדוגמה הבאה של Python מתבצע ניתוח של ranking_scores.csv ושל summary_confidences.json כדי לדרג דוגמאות פוטנציאליות ולאמת את האיכות של הדוגמה הפוטנציאלית המובילה:

import csv
import json

print("=== Candidate Samples Ledger (ranking_scores.csv) ===")
with open("ranking_scores.csv", "r", newline="", encoding="utf-8") as f:
    rows = sorted(
        csv.DictReader(f), key=lambda x: float(x["ranking_score"]), reverse=True
    )

# Calculate column widths cleanly and readably
headers = list(rows[0].keys())
widths = {}
for col in headers:
    lengths = [len(col)] + [len(r[col]) for r in rows]
    widths[col] = max(lengths)

print("  ".join(col.rjust(widths[col]) for col in headers))
for r in rows:
    print("  ".join(r[col].rjust(widths[col]) for col in headers))

top = rows[0]
print(
    f"\nPromoted Top Candidate: Seed {int(top['seed'])}, Sample"
    f" {int(top['sample'])} (Score: {float(top['ranking_score']):.4f})"
)

print("\n=== Top Candidate Quality Validation (summary.json) ===")
with open("summary.json", "r", encoding="utf-8") as f:
    summary = json.load(f)

clash_str = (
    "DETECTED (FAIL)" if summary.get("has_clash") else "None Detected (PASS)"
)
print("Top Candidate Metrics:")
print(f"  • Ranking Score : {summary.get('ranking_score', 'N/A')}")
print(f"  • Global pTM    : {summary.get('ptm', 'N/A')}")
print(f"  • Interface ipTM: {summary.get('iptm', 'N/A')}")
print(f"  • Steric Clash  : {clash_str}")

מפרטים מלאים של הסכימה של הקבצים שנשמרו ושל מאפייני mmCIF זמינים במאמרי העזרה של AlphaFold 3 ב-GitHub. בנוסף, אפשר לעיין במדריך How to assess the quality of AlphaFold 3 predictions (איך להעריך את איכות התחזיות של AlphaFold 3) באתר EMBL-EBI כדי להבין איך להעריך את איכות התחזיות.

שיטות מומלצות

בקטעים הבאים מתוארות שיטות מומלצות לשימוש ב-AlphaFold 3 ב-Agent Platform:

צמצום הסיכון לזמני קצובים לתפוגה של בקשות

נקודות קצה בפלטפורמת הסוכן אוכפות זמן קצוב מקסימלי לביצוע של 60 דקות לכל בקשה כברירת מחדל. כדי לוודא שהתחזיות יושלמו בהצלחה בלי שיתרחש פסק זמן, צריך לפעול לפי ההנחיות הבאות:

• מומלץ להימנע מדגימת יתר בבקשה אחת: הפעלה של סריקה רחבה של ערכי seed או של פרמטרים גבוהים מדי של דיפוזיה הפוכה בקריאה ל-API אחת עלולה לגרום לזמן הביצוע לחרוג מהמגבלה של 60 דקות.
• פירוק של סריקות גדולות: במחקרים בקנה מידה גדול, צריך לפצל את ערכי ה-seed ואת סריקות הפרמטרים למספר מטען ייעודי קטן יותר של תחזיות ולשלוח אותם כמשימות נפרדות. השיטה הזו גם מנצלת את היכולות של קנה המידה האוטומטי של נקודת הקצה.

דילוג על חיפוש MSA

צינור עיבוד הנתונים של חיפוש במסד נתונים גנטי הוא השלב שלוקח הכי הרבה זמן בצינור עיבוד הנתונים של AlphaFold. כשמריצים חיזויים איטרטיביים על אותה רצף (למשל, כשמבצעים סריקות של ליגנדים על חלבון מטרה קבוע), אפשר לשפר באופן משמעותי את זמני הביצוע על ידי דילוג על החיפוש במסד הנתונים:

• שליפת ה-MSA: מריצים חיזוי ראשוני מקצה לקצה עם ספריית פלט ב-Cloud Storage (output_dir) שצוינה. מורידים את קובץ {JOB_NAME}_data.json שנוצר מקטגוריית הפלט ב-Cloud Storage.
• שליחת תחזיות של הסקה בלבד: מאתרים את השדות unpairedMsa ו-pairedMsa בקובץ ה-JSON. מחלקים את המחרוזות האלה של MSA ומעבירים אותן לבקשות חיזוי הבאות באמצעות unpairedMsaPath ו-pairedMsaPath שמפנים ל-URI של Cloud Storage.

אפשרות אחרת היא להריץ חיפוש MSA בתשתית שלכם ולהזין את תבניות ה-MSA שחושבו מראש בבקשת החיזוי.

טיפול בהרצות עם רמת סמך נמוכה

אם מדדי מהימנות התוצאות של התחזיות נמוכים, במקום להתייחס לזה כאל כשלים בתחזיות שלא ניתן לתקן, אפשר לנסות לתקן את הבעיה באופן ממוקד. אופטימיזציה של פרמטרים ספציפיים מאפשרת לבדוק מסלולים חלופיים של זמן האחזור. בקטע הזה מפורטות כמה דרכים לשחזור במקרה של תחזיות עם רמת מהימנות נמוכה.

שימוש בדגימה עם כמה נקודות התחלה

‫AlphaFold 3 מאתחל יצירה של קואורדינטות תלת-ממדיות מרעש אקראי במרחב לטנטי. כששולחים חיזוי עם זרע מסוים יחיד, יכול להיות שמסלול הדיפוזיה יהיה שונה בהשוואה לזרע אחר. העברת מערך של ערכי seed מאלצת את המודל לדגום מסלולים שמתחילים ממצבים שונים.

לדגימה עם כמה זרעים יש שני יתרונות חשובים: היא מאמתת את העקביות המבנית בין ריצות עצמאיות ובודקת את הדינמיקה של קונפורמציות פונקציונליות. לדוגמה, אם כל חמשת הזרעים מתכנסים לקואורדינטות תלת-ממדיות זהות, אפשר להיות בטוחים בקיפול הגלובלי. לעומת זאת, אם זרעים שונים מניבים תנוחות קשירה שונות עם רמת מהימנות גבוהה, יכול להיות שהאנסמבל חושף מצבי קונפורמציה בעלי משמעות ביולוגית, כמו לולאות פתוחות לעומת סגורות של אתר פעיל או דימרים חלופיים עם החלפת דומיינים.

הרחבת מסלולי הדיפוזיה

הפרמטר modelSeeds משנה את מצב הרעש ההתחלתי במרחב הסמוי, והפרמטר num_diffusion_samples (ברירת המחדל היא 5) קובע כמה מבני תלת-ממד פוטנציאליים נוצרים לכל seed במהלך תהליך הדיפוזיה ההפוכה. באזורים של לולאות גמישות או בכיסי קשירה רדודים, הגדלת הדגימה מרחיבה את מאגר המועמדים לכל זרע. השיטה הזו יעילה במיוחד כשהערכים של מדדי מהימנות מקומיים יורדים בלולאות ספציפיות (pLDDT < 70) בזמן שהקיפול הכולל של הדומיין נשאר מהימן (pTM > 0.80). כך אפשר לגלות מבנים פוטנציאליים עם רמת מהימנות גבוהה, שלא זוהו בהרצה הראשונית.

הגדלת מספר מחזורי המיחזור

לפני שמודול הדיפוזיה יוצר קואורדינטות תלת-ממדיות, AlphaFold 3 מעבד רצפים ותכונות של זוגות. הפרמטר num_recycles קובע כמה פעמים ייצוגים של מבנים ביניים והטמעות מרחביות של זוגות יוחזרו באופן איטרטיבי דרך הרשת.

במולקולות גדולות ומורכבות, או במטרות עם אותות חלשים של קו-אבולוציה, הגדלת הערך של num_recycles נותנת לרשת הראשית עוד איטרציות כדי לפתור את היחסים המרחביים בין שרשראות מרוחקות לפני העברת נתוני הקלט למודול הדיפוזיה. אפשר לנסות את הגישה הזו כשמטריצות PAE לא אלכסוניות מציגות אי-ודאות גבוהה בין השרשראות (> 15 Å) למרות ששרשראות בודדות מציגות מהימנות גבוהה של קיפול מקומי (pLDDT > 70). הערה: הגדלה של מספר המיחזורים מגדילה באופן ליניארי את זמן הריצה של החיזוי, ולכן כדאי להשתמש בה רק במקרים של יעדי ממשק קשים.

שימוש בצינור עיבוד נתונים להתאמה אישית

‫AlphaFold 3 מריץ באופן אוטומטי את צינור העיבוד של חיפוש מסד הנתונים הגנטי כדי ליצור תבניות MSA. משתמשים יכולים גם לספק התאמות פרטיות, מחושבות מראש ומותאמות אישית בפורמט .a3m באמצעות כתובות URI של Cloud Storage באמצעות unpairedMsaPath ו-pairedMsaPath. אספקת נתוני MSA מעמיקים מספקת אילוצים חזקים של קו-אבולוציה, ולעתים קרובות הופכת תחזיות עם רמת מהימנות נמוכה למודלים עם רמת מהימנות גבוהה.