הרצת Python באותו מיקום עם Pathways

כדי להימנע מניתוב עבודה שקשורה למארח, כמו טעינת נתונים ונקודות בקרה, דרך בקר Pathways יחיד ב-Google Kubernetes Engine (GKE), צריך להריץ את הפונקציות האלה במכונות הווירטואליות של ה-worker ב-Cloud TPU באמצעות ה-API של JAX בשפת Python באותו מיקום.

במאמר הזה, שמיועד למהנדסי למידת מכונה, מוסבר איך Python במיקום משותף פועל עם Pathways. תלמדו איך ליצור, לפרוס ולאמת קונטיינר משני (sidecar) באמצעות מניפסט של JobSet או Cluster Toolkit.

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

מבצעים את הפעולות הבאות:

התפקידים הנדרשים

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

  • חשבון המשתמש שלכם:
    • Artifact Registry Writer (roles/artifactregistry.writer) בפרויקט Google Cloud כדי להעביר קובצי אימג' של קונטיינרים מותאמים אישית ל-Artifact Registry.
    • Kubernetes Engine Developer (roles/container.developer) בפרויקט Google Cloud כדי לפרוס משאבי JobSet, להעביר יציאות ולקרוא יומני Pod ב-GKE.
  • ‫חשבון שירות של מאגר צמתים ב-GKE: פודים של Pathways משתמשים בחשבון השירות הזה כשמאגרי הצמתים משתמשים בדגל --workload-metadata=GCE_METADATA, כמו שמוגדר בקטע יצירת אשכול GKE עם Pathways:
    • Artifact Registry Reader (roles/artifactregistry.reader) בפרויקט Google Cloud שמארח את המאגר הפרטי, כדי לשלוף קובצי אימג' בהתאמה אישית של קונטיינר Sidecar.
    • אדמין של אובייקט אחסון (roles/storage.objectAdmin) בקטגוריית ה-scratch של Cloud Storage, בשביל המטמון של הקומפילציה וקבצים זמניים אחרים.

אופציונלי: כדי לאפשר לקונטיינר של מנהל המשאבים של Pathways‏ (pathways-rm) להוסיף כלל למחזור החיים של הקטגוריה, שגורם לתפוגה של רשומות ישנות במטמון של הקומפילציה, צריך לתת גם את התפקיד אדמין של Storage ‏(roles/storage.admin) בקטגוריית הטיוטה. בלי התפקיד הזה, מאגר התגים pathways-rm מתעד אזהרה ביומן וממשיך להשתמש במטמון. כדי לדלג על עדכון מחזור החיים, מעבירים את הדגל --enable_gcs_olm=false לקונטיינר pathways-rm.

אם מאגרי הצמתים משתמשים באיחוד זהויות של עומסי עבודה ל-GKE, צריך להקצות את התפקיד של קטגוריית הסקראץ' לחשבון השירות של Kubernetes שבו משתמשים ה-Pods של Pathways, או לחשבון השירות המקושר של IAM. כברירת מחדל, פודים של Pathways משתמשים בחשבון השירות default, אלא אם במניפסט של JobSet מוגדר השדה serviceAccountName. משאירים את התפקיד "קריאה מ-Artifact Registry" בחשבון השירות של מאגר הצמתים.

איך Python באותו מיקום פועל עם Pathways

ב-Pathways, הסקריפט של בקר JAX פועל במארח CPU יחיד, בזמן ש-Pod של Cloud TPU worker מריץ את קונטיינר pathways-worker של C++‎. כדי להריץ פונקציות של @colocated_python ו-methods של @colocated_python_class במארחים של ה-workers, פייתון באותו מיקום משתמש ברכיבים הבאים:

  • בקר JAX: משתמש במודול jax.experimental.colocated_python כדי להתאים כל שבב Cloud TPU למכשיר מעבד מארח, וליצור סריאליזציה של פונקציית Python ומטא-נתונים של סוגים באמצעות הספרייה cloudpickle.
  • הקונטיינר pathways-proxy (ב-Pod‏ pathways-head): מקבל את הפונקציה שעברה סריאליזציה דרך gRPC ומנתב אותה לקונטיינר pathways-worker במכונות הווירטואליות של ה-worker שבבעלותן מכשירי ה-CPU של הקלט של הקריאה. העברת הדגל --sidecar_name=external מגדירה את הקונטיינר pathways-proxy לטירגוט הקונטיינר colocated-python-sidecar.
  • הקונטיינר pathways-worker (בכל Pod של Worker): טוען את הפונקציה שעברה סריאליזציה לקונטיינר המשני המקומי, מפעיל את ההרצה דרך gRPC מקומי ומחליף מאגרי מערכים דרך אמצעי אחסון משותף בזיכרון emptyDir (medium: Memory).
  • הקונטיינר colocated-python-sidecar (בכל Pod של Worker): פורק ומריץ את הפונקציה בסביבת זמן ריצה מבודדת של Python 3.12 פעם אחת לכל VM, בכל השארדים המקומיים של אותו VM, וכותב מערכי פלט ישירות לזיכרון המארח המשותף.

כאן מוסבר על הרכיבים של Pathways.

תהליך הביצוע

כשמפעילים פונקציה מעוטרת, Pathways מריץ אותה באשכול בשני שלבים:

  1. ניתוב פונקציות: המודול jax.experimental.colocated_python אורז את הפונקציה בתוכנית Interim Framework Runtime (IFRT)‎ ושולח אותה לקונטיינר pathways-proxy. שרת ה-proxy מעביר את התוכנית רק ל-worker VMs שמכילות את חלקי הקלט, והיא פועלת פעם אחת בכל VM בכל החלקים המקומיים.
  2. הפעלה של זיכרון משותף: מאגר pathways-worker כותב פיצולי קלט לנפח המשותף בזיכרון (/tmp/sidecar או /tmp/shared-memory) ומפעיל את מאגר colocated-python-sidecar באמצעות TCP של לולאה חזרה (localhost:50051) או שקע דומיין של Unix‏ (/sock/sidecar.sock). מערכי פלט מוחזרים דרך זיכרון משותף ללא עותקי gRPC ועוברים ישירות לזיכרון ברוחב פס גבוה (HBM) של Cloud TPU כשהם ממוקמים במכשירי Cloud TPU.

במדריך JAX colocated Python מוסבר איך משתמשים ב-JAX API, למשל כדי לגלות מכשירי CPU באותו מיקום ולהצהיר על מפרטי פלט לשיגור אסינכרוני.

הנחיות לעיצוב

כשכותבים פונקציות Python באותו מיקום, צריך לפעול לפי ההנחיות הבאות:

  • צמצום המשתנים שנלכדים: מעבירים נתוני מערך כארגומנטים של jax.Array עם פיצול, במקום ללכוד מערכים גדולים או אובייקטים שלא ניתנים לסריאליזציה (כמו קבצים פתוחים או לקוחות רשת) בסגירות. פותחים קבצים או לקוחות בתוך מכונה של @colocated_python_class ב-worker.
  • יצירה מחדש של המצב של @colocated_python_class אחרי הפעלה מחדש: אובייקטים של Stateful sidecar נשמרים בזיכרון בין השלבים, אבל לא נשמרים באופן אוטומטי אם פוד של Worker מופעל מחדש או אם מספר הפרוסות משתנה במהלך אימון גמיש. ליצור מחדש אובייקטים עם שמירת מצב מנקודת בדיקה אחרי שינוי קנה מידה או הפעלה מחדש.

תגים ותמונות מובנים מראש

Google Cloud מפרסמת קובצי אימג' של Pathways שנוצרו מראש במאגר ציבורי של Artifact Registry:

  • ‫Colocated Python sidecar: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG
  • מנהל המשאבים וה-worker של Pathways: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG
  • שרת proxy של IFRT: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG

משתמשים בתגים תואמים בתמונות של server, proxy_server ו-colocated_python_sidecar.

תמונות קונטיינר sidecar מובנות תומכות בגרסאות JAX‏ 0.10.1,‏ 0.10.2,‏ 0.11.0,‏ 0.11.1,‏ 0.11.2,‏ 0.12.0 ו-0.12.0.1. מחליפים את TAG באחד מהפורמטים הבאים של תגים:

  • ‫jax-JAX_VERSION (מומלץ): תג מתגלגל לגרסה ספציפית של JAX, כמו jax-0.12.0.1.
  • ‫YYYYMMDD-jax_JAX_VERSION: תג build עם חותמת זמן, כמו 20261110-jax_0.12.0.1.

אם אתם צריכים גרסת אימג' מדויקת שלא משתנה אף פעם, הצמידו את האימג' לפי סיכום ה-SHA-256 שלו. כדי לחפש תקציר של קובץ אימג', משתמשים בפקודה gcloud artifacts docker images describe:

IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"
gcloud artifacts docker images describe \
    "${IMAGE_REPO}/colocated_python_sidecar:jax-JAX_VERSION" \
    --format="value(image_summary.digest)"

מחליפים את JAX_VERSION בגרסת JAX, למשל 0.12.0.1.

יצירת קובץ אימג' בהתאמה אישית של קונטיינר sidecar

תמונת ה-sidecar שנוצרה מראש כוללת את החבילות jax,‏ jaxlib,‏ numpy,‏ scipy,‏ ml-dtypes,‏ opt-einsum,‏ cloudpickle ו-absl-py. אם פונקציות ה-Python שממוקמות באותו מקום משתמשות רק בחבילות האלה, דלגו לפריסת JobSet של Pathways עם ה-sidecar או לפריסה באמצעות Cluster Toolkit.

כדי להוסיף יחסי תלות מותאמים אישית של Python, צריך להוסיף אותם בשכבות לקובץ האימג' הבנוי מראש שתואם לגרסת JAX:

  1. בספריית build ריקה, יוצרים קובץ requirements.txt לחבילות הנוספות. משמיטים את החבילות jax ו-jaxlib, שכבר מותקנות ומוצמדות בקובץ /opt/venv/server_constraints.txt:

    grain
    
  2. יוצרים Dockerfile שמתקין את החבילות בקובץ requirements.txt, בהתאם למגבלות בקובץ /opt/venv/server_constraints.txt:

    ARG JAX_VERSION=0.12.0.1
    ARG IMAGE_REPO=us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways
    FROM ${IMAGE_REPO}/colocated_python_sidecar:jax-${JAX_VERSION}
    
    WORKDIR /app
    COPY requirements.txt .
    
    RUN uv pip install -r requirements.txt \
            -c /opt/venv/server_constraints.txt && \
        uv cache clean
    

    לא לשנות את ההוראות ENTRYPOINT ו-CMD של תמונת הבסיס. אם הקובץ requirements.txt מתקין חבילות מכתובות URL של Git, צריך להוסיף את ההוראה RUN הבאה לפני ההוראה uv pip install RUN, כי קובץ האימג' הבסיסי הקטן משמיט את הכלי git:

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. מאמתים את Docker באזור של Artifact Registry באמצעות הפקודה gcloud auth configure-docker:

    gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.dev
    

    מחליפים את REGISTRY_LOCATION במיקום של Artifact Registry, למשל us או us-central1.

  4. יוצרים קובץ אימג' בהתאמה אישית של קונטיינר sidecar ודוחפים אותו:

    export JAX_VERSION=JAX_VERSION
    IMAGE_PREFIX=REGISTRY_LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY
    export SIDECAR_IMAGE="${IMAGE_PREFIX}/colocated-sidecar:jax-${JAX_VERSION}"
    
    docker build --build-arg JAX_VERSION="${JAX_VERSION}" \
        --tag "${SIDECAR_IMAGE}" .
    docker push "${SIDECAR_IMAGE}"
    

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

    • ‫JAX_VERSION: גרסת ה-JAX, למשל 0.12.0.1.
    • ‫REGISTRY_LOCATION: המיקום של Artifact Registry, למשל us או us-central1.
    • ‫PROJECT_ID: מזהה הפרויקט ב-Google Cloud .
    • ‫REPOSITORY: שם המאגר של Docker ב-Artifact Registry.

פריסת JobSet של Pathways עם קובץ העזר

כדי לפרוס את Pathways עם ה-sidecar, אתם יכולים להחיל מניפסט של JobSet באמצעות כלי שורת הפקודה kubectl בקטע הזה, או לשלוח את המשימה ישירות באמצעות ה-CLI של gcluster בפריסה באמצעות Cluster Toolkit.

כדי ליצור ולהחיל מניפסט של JobSet, מבצעים את השלבים הבאים:

  1. יוצרים מניפסט JobSet (pathways-colocated-jobset.yaml) באמצעות אחד מהכלים הבאים:

    • ה-builder של pathways-utils ב-Python: מגדירים JobSet באמצעות ה-builder של PathwaysJobSet על ידי קריאה ל-methods‏ .add_colocated_python("SIDECAR_IMAGE") ו-.export_yaml("pathways-colocated-jobset.yaml"). אם אתם משתמשים בחבילה pathwaysutils (גרסה 0.1.14 או גרסה קודמת מ-PyPI), צריך גם להעביר את הארגומנט proxy_container_kwargs={"args": ["--sidecar_name=external"]} ל-constructor של PathwaysJobSet, או להתקין את החבילה pathways-utils מההסתעפות main.
    • ‫Cluster Toolkit (gcluster): מריצים את הפקודה gcluster job submit עם הדגל --pathways-colocated-python-sidecar-image ומוסיפים את הדגל --dry-run-out=pathways-colocated-jobset.yaml כדי ליצור את המניפסט באופן מקומי בלי לשלוח את המשימה.

    מחליפים את SIDECAR_IMAGE ב-URI של קובץ ה-sidecar בהתאמה אישית או ב-URI של קובץ ה-colocated_python_sidecar שנוצר מראש.

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

    • מריצים את הקונטיינר colocated-python-sidecar בשדה initContainers עם restartPolicy: Always בכל Pod של Worker. ב-CLI של gcluster, המשימה המשוכפלת של ה-worker נקראת worker, ואילו ב-builder של PathwaysJobSet היא נקראת pathways-worker.
    • מעבירים את הדגל --sidecar_name=external לקונטיינר pathways-proxy, ומחברים את הקונטיינר pathways-worker ל-sidecar דרך loopback TCP ב-localhost:50051. כשמריצים את הקונטיינר pathways-proxy בשדה initContainers, הוא משתמש גם ב-restartPolicy: Always.
    • טוענים נפח emptyDir בזיכרון עם medium: Memory בשני מארזי Pod של ה-worker: ב-/tmp/sidecar במניפסטים של gcluster, או ב-/tmp/shared-memory במניפסטים של PathwaysJobSet. שני הגנרטורים גם מגדירים את משתנה הסביבה CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY ב-sidecar ואת הדגל --cloud_pathways_sidecar_shm_directory בקונטיינר pathways-worker.
  2. מחילים את המניפסט JobSet ומחכים שה-Pods יגיעו לסטטוס Running:

    kubectl apply -f pathways-colocated-jobset.yaml
    kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAME
    

    מחליפים את JOBSET_NAME בערך metadata.name של JobSet.

מריצים סשן אחד של לקוח JAX לכל פריסה של JobSet. אחרי שהלקוח מתנתק, קונטיינר pathways-worker שהופעל מחדש לא יכול להשתמש שוב ב-sidecar שפועל. צריך למחוק את JobSet וליצור אותו מחדש לפני שמתחילים סשן אחר.

קבצים בנפח emptyDir בזיכרון נכללים בשימוש בזיכרון של Pod. מגדירים את השדה emptyDir.sizeLimit (למשל 175Gi) בנפח הזיכרון המשותף כדי להגביל את השימוש בכל צומת. כברירת מחדל, שני הקונטיינרים שומרים את הזיכרון המשותף שהתפנה למשך 30 שניות של זמן חוסר פעילות, כדי שיהיה אפשר להשתמש בו שוב. כדי לשנות את החלון הזה, מגדירים גם את הדגל --pathways_sidecar_shared_memory_idle_release_secs=SECONDS בשדה args של מאגר התגים colocated-python-sidecar (לצד הדגל --port=50051 או --unix_domain_socket_path) וגם את הדגל --cloud_pathways_shared_memory_idle_release_secs=SECONDS בשדה args של מאגר התגים pathways-worker. מחליפים את SECONDS בזמן הקצוב לתפוגה במצב חוסר פעילות, בשניות. אם מגדירים את שני הדגלים לערך 0, דפים שהתפנו משתחררים תוך כשנייה אחת, מה שמפחית את השימוש בזיכרון על חשבון תקורה נוספת של הקצאה.

אופציונלי: שימוש בשקע דומיין של Unix

כדי להשתמש בשקע דומיין של Unix‏ (UDS) ב-/sock/sidecar.sock במקום לפתוח יציאת TCP ב-Pods של ה-worker שמגדירים את hostNetwork: true, צריך להחיל את השינויים הבאים על המניפסט של JobSet לפני שמריצים את הפקודה kubectl apply:

  • מגדירים ווליום emptyDir: {} בשם sidecar-socket ב-/sock גם בקונטיינר pathways-worker וגם בקונטיינר colocated-python-sidecar.
  • מגדירים את args: ["--unix_domain_socket_path=/sock/sidecar.sock"] ואת exec startupProbe (test -S /sock/sidecar.sock) במאגר colocated-python-sidecar.
  • מוסיפים את הדגל --cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock לשדה args של מאגר ה-pathways-proxy.

פריסה באמצעות Cluster Toolkit

ב-Cluster Toolkit (גרסה gcluster 1.108.0 ואילך), העברת הדגל --pathways-colocated-python-sidecar-image לפקודה gcluster job submit מגדירה את מאגר colocated-python-sidecar דרך loopback TCP (localhost:50051), טוענת את הנפח בזיכרון ב-/tmp/sidecar ומגדירה את הדגל --sidecar_name=external. מעבירים את הדגלים --pathways-server-image ו---pathways-proxy-server-image באופן מפורש, כדי שכל שלוש התמונות ישתמשו בתגי cloud-pathways תואמים.

מפעילים פריסה של Pathways ללא ממשק משתמש עם קובץ האימג' של ה-sidecar, כדי שתוכלו להריץ מולו סקריפטים אינטראקטיביים של לקוח:

IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"

gcluster job submit \
    --pathways \
    --pathways-headless \
    --pathways-gcs-location="gs://BUCKET_NAME/pathways-artifacts" \
    --pathways-server-image="${IMAGE_REPO}/server:jax-JAX_VERSION" \
    --pathways-proxy-server-image="${IMAGE_REPO}/proxy_server:jax-JAX_VERSION" \
    --pathways-colocated-python-sidecar-image="SIDECAR_IMAGE" \
    --name=WORKLOAD \
    --cluster=CLUSTER \
    --project=PROJECT_ID \
    --location=LOCATION \
    --num-slices=WORKLOAD_NODEPOOL_COUNT \
    --compute-type=COMPUTE_TYPE \
    --topology=TOPOLOGY

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

  • ‫BUCKET_NAME: קטגוריית ה-scratch שלכם ב-Cloud Storage.
  • ‫JAX_VERSION: גרסת ה-JAX, למשל 0.12.0.1.
  • ‫SIDECAR_IMAGE: ה-URI של קובץ האימג' של ה-sidecar, בהתאמה אישית או מוגדר מראש.
  • ‫WORKLOAD: שם ייחודי של JobSet (עד 22 תווים).
  • ‫CLUSTER: השם של אשכול GKE.
  • ‫PROJECT_ID: מזהה הפרויקט ב-Google Cloud .
  • ‫LOCATION: האזור או התחום של אשכול GKE.
  • ‫WORKLOAD_NODEPOOL_COUNT: מספר הפרוסות של Cloud TPU, למשל 1.
  • ‫COMPUTE_TYPE: סוג המכונה של Cloud TPU, למשל ct5lp-hightpu-4t או ct6e-standard-4t.
  • ‫TOPOLOGY: הטופולוגיה של פרוסת Cloud TPU, כמו 4x8 או 2x4.

אפשר גם להתאים אישית את האופן שבו הפקודה gcluster job submit מריצה או מייצאת את המשימה:

  • עומסי עבודה באצווה: כדי להריץ משימת אצווה בקונטיינר בתוך ה-Pod של pathways-head במקום פריסה ללא ממשק משתמש, מחליפים את הדגל --pathways-headless בדגלים --image="CLIENT_IMAGE" ו---command="COMMAND". משתמשים בתמונת לקוח של Python 3.12 JAX שנוצרה עם פינים של server_constraints.txt ומעבירים את פקודת הכניסה (למשל python colocated_example.py).
  • עיבוד מניפסט מקומי: מוסיפים את הדגל --dry-run-out=pathways-colocated-jobset.yaml כדי לעבד את המניפסט של JobSet באופן מקומי בלי לשלוח אותו.
  • סשנים ללא ממשק משתמש (headless): מריצים את הפקודה gcluster job cancel ושולחים מחדש את המשימה לפני שמתחילים סשן נוסף של הלקוח.

הרצת עומס עבודה של Python באותו מיקום

מריצים את הסקריפט של לקוח JAX עם משתנה הסביבה JAX_PLATFORMS=proxy בקונטיינר pathways-proxy, בקונטיינר של עומס העבודה (workload) ב-pathways-head או באמצעות העברה ליציאה אחרת:

  1. כדי להתאים את יחסי התלות של הסדרה לתמונת ה-sidecar, מחלצים את הקובץ /opt/venv/server_constraints.txt ומתקינים חבילות תואמות בסביבה וירטואלית של Python 3.12:

    IMAGE_REPO="us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways"
    docker run --rm --entrypoint cat \
        "${IMAGE_REPO}/colocated_python_sidecar:jax-JAX_VERSION" \
        /opt/venv/server_constraints.txt > constraints.txt
    python3.12 -m venv .venv
    source .venv/bin/activate
    python -m pip install -c constraints.txt \
        jax jaxlib cloudpickle pathwaysutils
    

    מחליפים את JAX_VERSION בגרסת ה-JAX, למשל 0.12.0.1.

  2. אם מריצים את הלקוח מחוץ ל-Pod של pathways-head, מעבירים את היציאה המקומית 29000 למאגר pathways-proxy בטרמינל נפרד:

    JOBSET_LABEL="jobset.sigs.k8s.io/jobset-name=JOBSET_NAME"
    ROLE_LABEL="jobset.sigs.k8s.io/replicatedjob-name=pathways-head"
    HEAD_POD=$(kubectl get pods -l "${JOBSET_LABEL},${ROLE_LABEL}" \
        -o jsonpath='{.items[0].metadata.name}')
    kubectl port-forward "${HEAD_POD}" 29000:29000
    

    מחליפים את JOBSET_NAME בערך של metadata.name של JobSet (או בשם של WORKLOAD שהעברתם לפקודה gcluster job submit).

  3. שומרים את הסקריפט הבא בתור colocated_example.py. הסקריפט הזה מקצה מערך NumPy בנפח 4MiB בזיכרון המארח המשותף במכשיר ה-CPU המשותף של כל וורקר ב-Cloud TPU, ומעביר אותו ל-Cloud TPU HBM:

    import jax
    from jax.experimental import colocated_python
    import numpy as np
    import pathwaysutils
    
    pathwaysutils.initialize()
    
    @colocated_python.colocated_python
    def make_host_array(seed_arr: jax.Array) -> jax.Array:
      host_array = np.full(
          (1024, 1024), fill_value=float(seed_arr), dtype=np.float32
      )
      return jax.device_put(host_array, seed_arr.device)
    
    tpu_devices = jax.devices()
    cpu_devices = colocated_python.colocated_cpu_devices(tpu_devices)
    print(
        f"TPU devices: {len(tpu_devices)}, "
        f"colocated CPU devices: {len(cpu_devices)}"
    )
    
    host_arrays = [
        make_host_array(jax.device_put(np.int32(i + 1), cpu_dev))
        for i, cpu_dev in enumerate(cpu_devices)
    ]
    tpu_arrays = [
        jax.device_put(host_arr, tpu_dev)
        for host_arr, tpu_dev in zip(host_arrays, tpu_devices)
    ]
    for arr in tpu_arrays:
      arr.block_until_ready()
    
    print(
        f"Transferred {len(tpu_arrays)} arrays of shape {tpu_arrays[0].shape} "
        f"to TPU HBM; sample sum={float(tpu_arrays[0].sum()):.1f}"
    )
    
  4. מריצים את הסקריפט מול שרת ה-proxy של IFRT:

    JAX_PLATFORMS=proxy JAX_BACKEND_TARGET=grpc://127.0.0.1:29000 \
        python colocated_example.py
    

    הפלט אמור להיראות כך:

    TPU devices: 8, colocated CPU devices: 8
    Transferred 8 arrays of shape (1024, 1024) to TPU HBM; sample sum=1048576.0
    

    בעומסי עבודה של ייצור בריבוי-פרוסות, מעבירים ארגומנט jax.Array מפוצל שמוצב במכשירים שמוחזרים על ידי הקריאה ל-colocated_python.colocated_cpu_devices(mesh), ומגדירים את הפרמטר out_specs_fn באמצעות השיטה .specialize(out_specs_fn=...) כדי ש-Pathways יריץ קריאה מקבילה אחת בכל ה-sidecars של ה-workers בלי להמתין.

    אל תריצו סקריפטים של לקוח בתוך Pod של worker עם משתנה הסביבה JAX_PLATFORMS=cpu, כי ההגדרה הזו מריצה את JAX באופן מקומי במעבד (CPU) אחד ועוקפת את Pathways. אפשר להתעלם מההודעה IFRT proxy server disconnected: CANCELLED שמוצגת ביציאה.

לדפוסי שימוש נוספים, אפשר לעיין במקורות המידע הבאים:

אימות הפריסה של ה-sidecar

מריצים את הפקודה kubectl logs ב-JobSet ללא ממשק משתמש לפני שמבטלים או מוחקים אותו, או בזמן שעומס עבודה באצווה עדיין פועל. בפריסות של JobSet באצווה, הבקר של JobSet מוחק את הפודים של worker ברגע שהמשימה של pathways-head מסתיימת. במקום זאת, אפשר להציג יומני אצווה שהושלמו ב-Cloud Logging, כפי שמתואר במאמר פתרון בעיות ב-Pathways ב-Cloud.

כדי לאמת פריסה פעילה באמצעות כלי שורת הפקודה kubectl:

  1. בודקים את יומני הקונטיינר של colocated-python-sidecar:

    JOBSET_LABEL="jobset.sigs.k8s.io/jobset-name=JOBSET_NAME"
    ROLE_LABEL="jobset.sigs.k8s.io/replicatedjob-name=worker"
    WORKER_POD=$(kubectl get pods -l "${JOBSET_LABEL},${ROLE_LABEL}" \
        -o jsonpath='{.items[0].metadata.name}')
    kubectl logs "${WORKER_POD}" -c colocated-python-sidecar
    

    מחליפים את JOBSET_NAME בערך של metadata.name של JobSet (או בשם של WORKLOAD שהעברתם לפקודה gcluster job submit). אם יצרתם את המניפסט באמצעות הכלי ליצירת PathwaysJobSet, צריך להגדיר את replicatedjob-name=pathways-worker במשתנה ROLE_LABEL.

    הפלט אמור להיראות כך:

    Started SidecarGrpcServer on localhost:50051
    ...
    SidecarServer agreed on protocol version: 6
    Installed shared memory allocator for colocated Python using file /tmp/sidecar/pathways_shm_sidecar
    

    מוודאים שהפלט מציג את הודעת ההפעלה של gRPC, ואחרי הקריאה הראשונה ל-@colocated_python, את ההודעה של מקצה הזיכרון המשותף. מניפסטים שנוצרו באמצעות ה-builder של PathwaysJobSet משתמשים בספרייה /tmp/shared-memory, ופריסות UDS מתעדות ביומן את unix:/sock/sidecar.sock במקום את localhost:50051.

  2. בודקים את יומני הקונטיינר pathways-worker באותו Pod:

    kubectl logs "${WORKER_POD}" -c pathways-worker \
        | grep -iE "shared memory|external sidecar"
    

    הפלט אמור להיראות כך:

    Enabled shared memory for external sidecar in /tmp/sidecar
    External sidecar connected to backing GRPC sidecar at localhost:50051
    

    מוודאים שהקונטיינר pathways-worker הפעיל את הזיכרון המשותף והתחבר ל-sidecar.

כשמריצים את הפקודה kubectl exec כדי לבדוק את ספריית הזיכרון המשותף, צריך לטרגט את מאגר colocated-python-sidecar באמצעות הדגל -c colocated-python-sidecar, כי מאגר pathways-worker לא כולל מעטפת.

פתרון בעיות ב-Python באותו מיקום

בקטעים הבאים מוסבר איך לפתור בעיות נפוצות ב-Python באותו מיקום.

שגיאה אחת (Unable to unpickle)

אם עומס העבודה נכשל עם השגיאה הבאה, גרסאות Python או החבילה שונות בין לקוח JAX לבין הקונטיינר המשני (sidecar):

jax.errors.JaxRuntimeError: UNKNOWN: Unable to unpickle the callable and specialization

מוודאים שהלקוח מריץ את Python 3.12‏ (python --version) ומתקינים חבילות לקוח עם הדגל -c constraints.txt שחולץ מתמונת ה-sidecar. מידע נוסף זמין במאמר הרצת עומס עבודה של Python באותו מיקום.

התנגשות בין יחסי תלות במהלך הפעלה של docker build

אם הפקודה uv pip install נכשלת ומוצגת השגיאה No solution found when resolving dependencies, יש התנגשות בין קוד אימות בקובץ requirements.txt לבין הקובץ /opt/venv/server_constraints.txt. מסירים את החבילות jax ו-jaxlib מהקובץ requirements.txt, ומקלים על הצמדת הגרסאות בחבילות כמו numpy,‏ ml-dtypes או scipy.

השגיאה "Sidecar לא מופעל"

אם הקונטיינר pathways-proxy נסגר עם השגיאה Sidecar create args were set, but sidecar was not enabled, מוסיפים את הדגל --sidecar_name=external לשדה args של הקונטיינר pathways-proxy.

שגיאה אחת (Sidecar already initialized)

אם עומס העבודה נכשל עם השגיאה FAILED_PRECONDITION: Sidecar already initialized, ניתוק מוקדם יותר של הלקוח הפעיל מחדש את מאגר ה-pathways-worker בזמן שמאגר ה-colocated-python-sidecar נשאר מאותחל. למחוק וליצור מחדש את JobSet לפני שמתחילים סשן לקוח נוסף.

שגיאות בזיכרון המשותף או בחיבור ל-Sidecar

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

  • ‫Failed to stat sidecar_shm_directory: טוענים את אמצעי האחסון של הזיכרון המשותף emptyDir בנתיב התואם (/tmp/sidecar או /tmp/shared-memory) גם בקונטיינר pathways-worker וגם בקונטיינר colocated-python-sidecar.
  • ‫Timed out connecting to sidecar gRPC service או Failed to connect to external sidecar: מוודאים שהמאגר של colocated-python-sidecar פועל בשדה initContainers עם restartPolicy: Always, ושלכל שלוש התמונות של cloud-pathways יש תגים תואמים. מוודאים שהגדרות ה-TCP (--port=50051) או ה-UDS (נפח /sock ו---unix_domain_socket_path=/sock/sidecar.sock) תואמות בין הקונטיינרים pathways-proxy ו-colocated-python-sidecar.
  • מארח ה-worker חורג ממגבלת הזיכרון אחרי פרצי מערכים גדולים: מגדירים את הדגל --pathways_sidecar_shared_memory_idle_release_secs=0 בקונטיינר colocated-python-sidecar (לצד הדגל --port=50051 או --unix_domain_socket_path) ואת הדגל --cloud_pathways_shared_memory_idle_release_secs=0 בקונטיינר pathways-worker. הגדרת שני הדגלים לערך 0 משחררת זיכרון משותף שלא בשימוש תוך כשנייה אחת. לחלופין, אפשר להקטין את כמות הנתונים המקסימלית של מערך המארח שעומס העבודה שומר בזיכרון בו-זמנית.

הסרת המשאבים

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

  • מניפסט של JobSet: מוחקים את המשאב של JobSet:

    kubectl delete jobset JOBSET_NAME
    

    מחליפים את JOBSET_NAME בערך metadata.name של JobSet.

  • ‫Cluster Toolkit: ביטול המשימה שנפרסה:

    gcluster job cancel WORKLOAD \
        --cluster=CLUSTER \
        --project=PROJECT_ID \
        --location=LOCATION
    

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

    • ‫WORKLOAD: השם של המשימה ב-Pathways.
    • ‫CLUSTER: השם של אשכול GKE.
    • ‫PROJECT_ID: מזהה הפרויקט ב-Google Cloud .
    • ‫LOCATION: האזור או התחום של אשכול GKE.

אופציונלי: מוחקים את כל קובצי האימג' של קונטיינר ה-sidecar בהתאמה אישית ב-Artifact Registry, ומסירים אובייקטים זמניים בקטגוריית ה-scratch של Cloud Storage. כשתסיימו להשתמש באשכול GKE, מחקו אותו לפי השלבים שמפורטים בקטע ניקוי במאמר יצירת אשכול GKE באמצעות Pathways.

המאמרים הבאים