כדי להימנע מניתוב עבודה שקשורה למארח, כמו טעינת נתונים ונקודות בקרה, דרך בקר Pathways יחיד ב-Google Kubernetes Engine (GKE), צריך להריץ את הפונקציות האלה במכונות הווירטואליות של ה-worker ב-Cloud TPU באמצעות ה-API של JAX בשפת Python באותו מיקום.
במאמר הזה, שמיועד למהנדסי למידת מכונה, מוסבר איך Python במיקום משותף פועל עם Pathways. תלמדו איך ליצור, לפרוס ולאמת קונטיינר משני (sidecar) באמצעות מניפסט של JobSet או Cluster Toolkit.
לפני שמתחילים
מבצעים את הפעולות הבאות:
- יצירת אשכול GKE באמצעות Pathways.
- מתקינים את כלי שורת הפקודה
kubectlואת הפלאגיןgke-gcloud-auth-plugin. - מתקינים את Google Cloud CLI.
- מתקינים את Docker.
- מפעילים את Kubernetes Engine API ואת Artifact Registry API.
- יוצרים קטגוריה זמנית ב-Cloud Storage לקבצים זמניים של Pathways.
- אם אתם מתכננים ליצור קובץ אימג' בהתאמה אישית של קונטיינר Sidecar, צרו מאגר Docker ב-Artifact Registry.
- מתקינים את Python 3.12 בסביבת הלקוח שבה פועל עומס העבודה של JAX.
- אופציונלי: כדי לפרוס באמצעות Cluster Toolkit, מתקינים את גרסה 1.108.0 ואילך של ה-CLI של
gcluster.
התפקידים הנדרשים
מקצים את התפקידים הבאים בממשק לניהול הזהויות והרשאות הגישה (IAM):
- חשבון המשתמש שלכם:
- Artifact Registry Writer (
roles/artifactregistry.writer) בפרויקט Google Cloud כדי להעביר קובצי אימג' של קונטיינרים מותאמים אישית ל-Artifact Registry. - Kubernetes Engine Developer (
roles/container.developer) בפרויקט Google Cloud כדי לפרוס משאביJobSet, להעביר יציאות ולקרוא יומני Pod ב-GKE.
- Artifact Registry Writer (
- חשבון שירות של מאגר צמתים ב-GKE: פודים של Pathways משתמשים בחשבון השירות הזה כשמאגרי הצמתים משתמשים בדגל
--workload-metadata=GCE_METADATA, כמו שמוגדר בקטע יצירת אשכול GKE עם Pathways:- Artifact Registry Reader (
roles/artifactregistry.reader) בפרויקט Google Cloud שמארח את המאגר הפרטי, כדי לשלוף קובצי אימג' בהתאמה אישית של קונטיינר Sidecar. - אדמין של אובייקט אחסון (
roles/storage.objectAdmin) בקטגוריית ה-scratch של Cloud Storage, בשביל המטמון של הקומפילציה וקבצים זמניים אחרים.
- Artifact Registry Reader (
אופציונלי: כדי לאפשר לקונטיינר של מנהל המשאבים של 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(ב-Podpathways-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 מריץ אותה באשכול בשני שלבים:
- ניתוב פונקציות: המודול
jax.experimental.colocated_pythonאורז את הפונקציה בתוכנית Interim Framework Runtime (IFRT) ושולח אותה לקונטיינרpathways-proxy. שרת ה-proxy מעביר את התוכנית רק ל-worker VMs שמכילות את חלקי הקלט, והיא פועלת פעם אחת בכל VM בכל החלקים המקומיים. - הפעלה של זיכרון משותף: מאגר
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:
בספריית build ריקה, יוצרים קובץ
requirements.txtלחבילות הנוספות. משמיטים את החבילותjaxו-jaxlib, שכבר מותקנות ומוצמדות בקובץ/opt/venv/server_constraints.txt:grainיוצרים
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 installRUN, כי קובץ האימג' הבסיסי הקטן משמיט את הכליgit:RUN apt-get update && \ apt-get install -y --no-install-recommends git && \ rm -rf /var/lib/apt/lists/*מאמתים את Docker באזור של Artifact Registry באמצעות הפקודה
gcloud auth configure-docker:gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.devמחליפים את
REGISTRY_LOCATIONבמיקום של Artifact Registry, למשלusאוus-central1.יוצרים קובץ אימג' בהתאמה אישית של קונטיינר 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, מבצעים את השלבים הבאים:
יוצרים מניפסט
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.
- ה-builder של
מחילים את המניפסט
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"]ואתexecstartupProbe(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 או באמצעות העברה ליציאה אחרת:
כדי להתאים את יחסי התלות של הסדרה לתמונת ה-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.אם מריצים את הלקוח מחוץ ל-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).שומרים את הסקריפט הבא בתור
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}" )מריצים את הסקריפט מול שרת ה-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שמוצגת ביציאה.
לדפוסי שימוש נוספים, אפשר לעיין במקורות המידע הבאים:
- JAX colocated Python notebook: התמחות בפונקציות ואובייקטים של
@colocated_python_classעם שמירת מצב (stateful) - מודול
multihost_dataloading.pyשל MaxText:RemoteIteratorצינור עיבוד נתונים של קלט ממספר מארחים שמשתמש ב-Python באותו מיקום - נקודות בקרה של Orbax Pathways ונקודות בקרה בכמה רמות עם Pathways: נקודות בקרה מבוזרות ב-sidecars של ה-worker עם הקריאה
orbax.checkpoint.pathways.register_type_handlers(checkpointing_impl=CheckpointingImpl.COLOCATED_PYTHON)(או ההגדרהcolocated_python_checkpointing=Trueב-MaxText) והאפשרותuse_colocated_python=Trueלנקודות בקרה בכמה רמות
אימות הפריסה של ה-sidecar
מריצים את הפקודה kubectl logs ב-JobSet ללא ממשק משתמש לפני שמבטלים או מוחקים אותו, או בזמן שעומס עבודה באצווה עדיין פועל. בפריסות של JobSet באצווה, הבקר של JobSet מוחק את הפודים של worker ברגע שהמשימה של pathways-head מסתיימת. במקום זאת, אפשר להציג יומני אצווה שהושלמו ב-Cloud Logging, כפי שמתואר במאמר פתרון בעיות ב-Pathways ב-Cloud.
כדי לאמת פריסה פעילה באמצעות כלי שורת הפקודה kubectl:
בודקים את יומני הקונטיינר של
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.בודקים את יומני הקונטיינר
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.
המאמרים הבאים
- העברת עומסי עבודה של JAX ל-Pathways
- אימון עמיד באמצעות Pathways
- הרצת עומס עבודה באצווה באמצעות Pathways
- הרצת עומס עבודה אינטראקטיבי באמצעות Pathways
- פתרון בעיות ב-Pathways on Cloud
- הפעלת עומסי עבודה עם Pathways ב-Cluster Toolkit