Menjalankan Python yang ditempatkan bersama dengan Pathways

Untuk menghindari perutean pekerjaan yang terikat host seperti pemuatan data dan checkpointing melalui satu pengontrol Pathways di Google Kubernetes Engine (GKE), jalankan fungsi tersebut pada VM worker Cloud TPU Anda menggunakan Python API yang ditempatkan bersama JAX.

Dokumen ini, yang ditujukan untuk engineer machine learning, menjelaskan cara kerja Python yang ditempatkan bersama dengan Pathways. Anda akan mempelajari cara membangun, men-deploy, dan memverifikasi container sidecar dengan manifes JobSet atau Cluster Toolkit.

Sebelum memulai

Selesaikan prasyarat berikut:

Peran yang diperlukan

Berikan peran Identity and Access Management (IAM) berikut:

  • Akun pengguna Anda:
    • Artifact Registry Writer (roles/artifactregistry.writer) di project Google Cloud Anda untuk mengirim image sidecar kustom ke Artifact Registry.
    • Kubernetes Engine Developer (roles/container.developer) di project Google Cloud Anda untuk men-deploy resource JobSet, meneruskan port, dan membaca log Pod di GKE.
  • Akun layanan node pool GKE: Pod Pathways menggunakan akun layanan ini saat node pool Anda menggunakan flag --workload-metadata=GCE_METADATA, seperti yang dikonfigurasi di Membuat cluster GKE dengan Pathways:
    • Artifact Registry Reader (roles/artifactregistry.reader) di project Google Cloud yang menghosting repositori pribadi Anda untuk mengambil image sidecar kustom.
    • Storage Object Admin (roles/storage.objectAdmin) di bucket scratch Cloud Storage Anda untuk cache kompilasi dan file sementara lainnya.

Opsional: Untuk mengizinkan container pengelola resource Pathways (pathways-rm) menambahkan aturan siklus proses bucket yang mengakhiri masa berlaku entri cache kompilasi lama, berikan juga peran Storage Admin (roles/storage.admin) di bucket scratch. Tanpa peran ini, container pathways-rm akan mencatat peringatan ke dalam log dan terus menggunakan cache. Untuk melewati update siklus proses, teruskan flag --enable_gcs_olm=false ke container pathways-rm.

Jika node pool Anda menggunakan Workload Identity Federation for GKE, berikan peran bucket sementara ke akun layanan Kubernetes yang digunakan Pod Pathways, atau ke akun layanan IAM yang terikat. Secara default, Pod Pathways menggunakan akun layanan default, kecuali jika manifes JobSet Anda menetapkan kolom serviceAccountName. Pertahankan peran Artifact Registry Reader di akun layanan node pool.

Cara kerja Python yang ditempatkan bersama dengan Pathways

Di Pathways, skrip pengontrol JAX Anda berjalan di satu host CPU, sementara Pod worker Cloud TPU menjalankan container pathways-worker C++. Untuk menjalankan fungsi @colocated_python dan metode @colocated_python_class di host worker, Python yang ditempatkan bersama menggunakan komponen berikut:

  • Pengontrol JAX Anda: Menggunakan modul jax.experimental.colocated_python untuk menyambungkan setiap chip Cloud TPU dengan perangkat CPU host dan melakukan serialisasi fungsi Python dan metadata jenis Anda dengan library cloudpickle.
  • Container pathways-proxy (di Pod pathways-head): Menerima fungsi yang diserialisasi melalui gRPC dan merutekannya ke container pathways-worker di worker VM yang memiliki perangkat CPU input panggilan. Meneruskan flag --sidecar_name=external akan mengonfigurasi container pathways-proxy untuk menargetkan container colocated-python-sidecar.
  • Container pathways-worker (di setiap Pod worker): Memuat fungsi yang diserialisasi ke dalam container sidecar lokal, memicu eksekusi melalui gRPC lokal, dan bertukar buffer array melalui volume emptyDir dalam memori bersama (medium: Memory).
  • Container colocated-python-sidecar (di setiap Pod worker): Membuka paket dan menjalankan fungsi dalam runtime Python 3.12 yang terisolasi satu kali per VM di seluruh shard lokal VM tersebut, dengan menulis array output langsung ke memori host bersama.

Untuk mempelajari lebih lanjut arsitektur Pathways, lihat Komponen Pathways.

Alur eksekusi

Saat Anda memanggil fungsi yang didekorasi, Pathways akan menjalankannya di seluruh cluster dalam dua tahap:

  1. Perutean fungsi: Modul jax.experimental.colocated_python mengemas fungsi ke dalam program Interim Framework Runtime (IFRT) dan mengirimkannya ke container pathways-proxy. Proxy meneruskan program hanya ke worker VM yang menyimpan shard input, yang berjalan sekali per VM di semua shard lokal.
  2. Eksekusi memori bersama: Container pathways-worker menulis shard input ke volume bersama dalam memori (/tmp/sidecar atau /tmp/shared-memory) dan memanggil container colocated-python-sidecar melalui TCP loopback (localhost:50051) atau soket domain Unix (/sock/sidecar.sock). Array output ditampilkan melalui memori bersama tanpa salinan gRPC dan dipindahkan langsung ke memori bandwidth tinggi (HBM) Cloud TPU saat ditempatkan di perangkat Cloud TPU.

Untuk penggunaan JAX API seperti menemukan perangkat CPU yang ditempatkan bersama dan mendeklarasikan spesifikasi output untuk pengiriman asinkron, lihat panduan Python yang ditempatkan bersama JAX.

Pedoman desain

Saat Anda menulis fungsi Python yang ditempatkan bersama, ikuti panduan berikut:

  • Minimalkan variabel yang diambil: Teruskan data array sebagai argumen jax.Array yang di-sharding, bukan mengambil array besar atau objek yang tidak dapat diserialisasi (seperti file terbuka atau klien jaringan) dalam closure. Buka file atau klien di dalam instance @colocated_python_class pada worker.
  • Membuat ulang status @colocated_python_class setelah dimulai ulang: Objek sidecar stateful dipertahankan di seluruh langkah dalam memori, tetapi tidak disimpan secara otomatis jika Pod worker dimulai ulang atau jumlah slice berubah selama pelatihan elastis. Buat ulang objek stateful dari checkpoint setelah penskalaan ulang atau mulai ulang.

Image dan tag bawaan

Google Cloud memublikasikan image Pathways bawaan di repositori Artifact Registry publik:

  • Sidecar Python yang ditempatkan bersama: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG
  • Resource manager dan worker Pathways: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG
  • Server proxy IFRT: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG

Gunakan tag yang cocok di seluruh image server, proxy_server, dan colocated_python_sidecar.

Image file bantuan bawaan mendukung JAX versi 0.10.1, 0.10.2, 0.11.0, 0.11.1, 0.11.2, 0.12.0, dan 0.12.0.1. Ganti TAG dengan salah satu format tag berikut:

  • jax-JAX_VERSION (direkomendasikan): tag berkelanjutan untuk rilis JAX tertentu, seperti jax-0.12.0.1.
  • YYYYMMDD-jax_JAX_VERSION: tag build yang diberi stempel tanggal, seperti 20261110-jax_0.12.0.1.

Jika Anda memerlukan versi image yang sama persis dan tidak pernah berubah, sematkan image berdasarkan ringkasan SHA-256-nya. Untuk mencari cepat ringkasan image, gunakan perintah 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)"

Ganti JAX_VERSION dengan versi JAX Anda, seperti 0.12.0.1.

Membangun image sidecar kustom

Image file bantuan bawaan mencakup paket jax, jaxlib, numpy, scipy, ml-dtypes, opt-einsum, cloudpickle, dan absl-py. Jika fungsi Python yang ditempatkan bersama hanya menggunakan paket ini, lanjutkan ke Men-deploy JobSet Pathways dengan sidecar atau Men-deploy dengan Cluster Toolkit.

Untuk menambahkan dependensi Python kustom, lapisi dependensi tersebut ke image bawaan yang cocok dengan versi JAX Anda:

  1. Di direktori build kosong, buat file requirements.txt untuk paket tambahan Anda. Hilangkan paket jax dan jaxlib, yang sudah diinstal dan disematkan dalam file /opt/venv/server_constraints.txt:

    grain
    
  2. Buat Dockerfile yang menginstal paket dalam file requirements.txt, yang dibatasi oleh file /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
    

    Jangan ubah petunjuk ENTRYPOINT dan CMD image dasar. Jika file requirements.txt menginstal paket dari URL Git, tambahkan petunjuk RUN berikut sebelum petunjuk uv pip install RUN, karena image dasar slim menghilangkan alat git:

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. Autentikasi Docker ke region Artifact Registry Anda menggunakan perintah gcloud auth configure-docker:

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

    Ganti REGISTRY_LOCATION dengan lokasi Artifact Registry Anda, seperti us atau us-central1.

  4. Bangun dan kirim image sidecar kustom Anda:

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

    Ganti kode berikut:

    • JAX_VERSION: versi JAX Anda, seperti 0.12.0.1.
    • REGISTRY_LOCATION: lokasi Artifact Registry Anda, seperti us atau us-central1.
    • PROJECT_ID:Google Cloud project ID Anda.
    • REPOSITORY: nama repositori Docker Artifact Registry Anda.

Men-deploy JobSet Pathways dengan file bantuan

Anda dapat men-deploy Pathways dengan file bantuan dengan menerapkan manifes JobSet menggunakan alat command line kubectl di bagian ini, atau dengan mengirimkan tugas secara langsung dengan gcluster CLI di Men-deploy dengan Cluster Toolkit.

Untuk membuat dan menerapkan manifes JobSet, selesaikan langkah-langkah berikut:

  1. Buat manifes JobSet (pathways-colocated-jobset.yaml) dengan salah satu alat berikut:

    • Builder Python pathways-utils: Konfigurasikan JobSet dengan builder PathwaysJobSet dengan memanggil metode .add_colocated_python("SIDECAR_IMAGE") dan .export_yaml("pathways-colocated-jobset.yaml"). Jika Anda menggunakan paket pathwaysutils (versi 0.1.14 atau yang lebih lama dari PyPI), teruskan juga argumen proxy_container_kwargs={"args": ["--sidecar_name=external"]} ke konstruktor PathwaysJobSet, atau instal paket pathways-utils dari cabang main.
    • Cluster Toolkit (gcluster): Jalankan perintah gcluster job submit dengan flag --pathways-colocated-python-sidecar-image dan tambahkan flag --dry-run-out=pathways-colocated-jobset.yaml untuk merender manifes secara lokal tanpa mengirimkan tugas.

    Ganti SIDECAR_IMAGE dengan URI image file bantuan kustom Anda atau URI image colocated_python_sidecar bawaan.

    Kedua generator mengonfigurasi manifes untuk melakukan hal berikut:

    • Jalankan container colocated-python-sidecar di kolom initContainers dengan restartPolicy: Always di setiap Pod worker. gcluster CLI memberi nama tugas yang direplikasi worker worker, sedangkan builder PathwaysJobSet memberinya nama pathways-worker.
    • Teruskan flag --sidecar_name=external ke container pathways-proxy, dan hubungkan container pathways-worker ke sidecar melalui TCP loopback di localhost:50051. Saat container pathways-proxy berjalan di kolom initContainers, container tersebut juga menggunakan restartPolicy: Always.
    • Instal volume emptyDir dalam memori dengan medium: Memory di kedua container Pod worker: di /tmp/sidecar dalam manifes gcluster, atau di /tmp/shared-memory dalam manifes PathwaysJobSet. Kedua generator juga menetapkan variabel lingkungan CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY pada sidecar dan flag --cloud_pathways_sidecar_shm_directory pada container pathways-worker.
  2. Terapkan manifes JobSet dan tunggu hingga Pod mencapai status Running:

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

    Ganti JOBSET_NAME dengan nilai metadata.name dari JobSet Anda.

Jalankan satu sesi klien JAX per deployment JobSet. Setelah klien terputus, container pathways-worker yang dimulai ulang tidak dapat menggunakan kembali sidecar yang sedang berjalan. Hapus dan buat ulang JobSet sebelum memulai sesi lain.

File dalam volume emptyDir dalam memori diperhitungkan dalam penggunaan memori Pod. Tetapkan kolom emptyDir.sizeLimit (seperti 175Gi) pada volume memori bersama untuk membatasi penggunaan per node. Secara default, kedua container mempertahankan memori bersama yang dikosongkan selama 30 detik waktu tidak ada aktivitas untuk digunakan kembali. Untuk mengubah periode tersebut, tetapkan flag --pathways_sidecar_shared_memory_idle_release_secs=SECONDS di kolom args pada container colocated-python-sidecar (bersama dengan flag --port=50051 atau --unix_domain_socket_path) dan flag --cloud_pathways_shared_memory_idle_release_secs=SECONDS di kolom args pada container pathways-worker. Ganti SECONDS dengan waktu tunggu tidak ada aktivitas dalam detik. Menetapkan kedua flag ke 0 akan merilis halaman yang dikosongkan dalam waktu sekitar 1 detik, yang mengurangi penggunaan memori dengan mengorbankan overhead alokasi tambahan.

Opsional: Menggunakan soket domain Unix

Untuk menggunakan soket domain Unix (UDS) di /sock/sidecar.sock, alih-alih membuka port TCP di Pod worker yang menetapkan hostNetwork: true, terapkan penggantian berikut ke manifes JobSet Anda sebelum menjalankan perintah kubectl apply:

  • Pasang volume emptyDir: {} bernama sidecar-socket di /sock dalam container pathways-worker dan colocated-python-sidecar.
  • Tetapkan args: ["--unix_domain_socket_path=/sock/sidecar.sock"] dan exec startupProbe (test -S /sock/sidecar.sock) di penampung colocated-python-sidecar.
  • Tambahkan flag --cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock ke kolom args pada container pathways-proxy.

Men-deploy dengan Cluster Toolkit

Di Cluster Toolkit (gcluster versi 1.108.0 atau yang lebih baru), meneruskan flag --pathways-colocated-python-sidecar-image ke perintah gcluster job submit akan mengonfigurasi container colocated-python-sidecar melalui TCP loopback (localhost:50051), memasang volume dalam memori di /tmp/sidecar, dan menetapkan flag --sidecar_name=external. Teruskan flag --pathways-server-image dan --pathways-proxy-server-image secara eksplisit agar ketiga image menggunakan tag cloud-pathways yang cocok.

Kirim deployment Pathways headless dengan image sidecar Anda sehingga Anda dapat menjalankan skrip klien interaktif terhadapnya:

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

Ganti kode berikut:

  • BUCKET_NAME: bucket scratch Cloud Storage Anda.
  • JAX_VERSION: versi JAX Anda, seperti 0.12.0.1.
  • SIDECAR_IMAGE: URI image sidecar kustom atau bawaan Anda.
  • WORKLOAD: nama JobSet unik (maksimal 22 karakter).
  • CLUSTER: nama cluster GKE Anda.
  • PROJECT_ID:Google Cloud project ID Anda.
  • LOCATION: region atau zona cluster GKE Anda.
  • WORKLOAD_NODEPOOL_COUNT: jumlah slice Cloud TPU, seperti 1.
  • COMPUTE_TYPE: jenis mesin Cloud TPU, seperti ct5lp-hightpu-4t atau ct6e-standard-4t.
  • TOPOLOGY: topologi slice Cloud TPU, seperti 4x8 atau 2x4.

Anda juga dapat menyesuaikan cara perintah gcluster job submit menjalankan atau mengekspor tugas:

  • Workload batch: Untuk menjalankan tugas batch dalam container di dalam Pod pathways-head, bukan deployment headless, ganti flag --pathways-headless dengan flag --image="CLIENT_IMAGE" dan --command="COMMAND". Gunakan image klien JAX Python 3.12 yang dibuat dengan pin server_constraints.txt dan teruskan perintah entri Anda (seperti python colocated_example.py).
  • Rendering manifes lokal: Tambahkan flag --dry-run-out=pathways-colocated-jobset.yaml untuk merender manifes JobSet secara lokal tanpa mengirimkannya.
  • Sesi headless berikutnya: Jalankan perintah gcluster job cancel dan kirim ulang tugas sebelum memulai sesi klien lain.

Menjalankan workload Python yang dicolokasikan

Jalankan skrip klien JAX Anda dengan variabel lingkungan JAX_PLATFORMS=proxy terhadap container pathways-proxy, baik di container workload pathways-head atau melalui penerusan port:

  1. Untuk menyelaraskan dependensi serialisasi dengan image file bantuan Anda, ekstrak file /opt/venv/server_constraints.txt dan instal paket yang cocok di lingkungan virtual 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
    

    Ganti JAX_VERSION dengan versi JAX Anda, seperti 0.12.0.1.

  2. Jika Anda menjalankan klien di luar Pod pathways-head, teruskan port lokal 29000 ke container pathways-proxy di terminal terpisah:

    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
    

    Ganti JOBSET_NAME dengan nilai metadata.name dari JobSet Anda (atau nama WORKLOAD yang Anda teruskan ke perintah gcluster job submit).

  3. Simpan skrip berikut sebagai colocated_example.py. Skrip ini mengalokasikan array NumPy 4 MiB dalam memori host bersama di perangkat CPU yang ditempatkan bersama di setiap worker Cloud TPU dan mentransfernya ke HBM Cloud TPU:

    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. Jalankan skrip terhadap server proxy IFRT:

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

    Outputnya mirip dengan hal berikut ini:

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

    Dalam workload produksi multislice, teruskan argumen jax.Array yang di-sharding yang ditempatkan di perangkat yang ditampilkan oleh panggilan colocated_python.colocated_cpu_devices(mesh) dan tetapkan parameter out_specs_fn dengan metode .specialize(out_specs_fn=...) sehingga Pathways menjalankan satu panggilan paralel di semua sidecar worker tanpa menunggu.

    Jangan jalankan skrip klien di dalam Pod worker dengan variabel lingkungan JAX_PLATFORMS=cpu, karena setelan tersebut menjalankan JAX secara lokal di satu CPU dan mengabaikan Pathways. Anda dapat mengabaikan pesan IFRT proxy server disconnected: CANCELLED apa pun yang dicetak saat keluar.

Untuk pola penggunaan tambahan, lihat referensi berikut:

Memverifikasi deployment sidecar

Jalankan perintah kubectl logs pada JobSet headless sebelum membatalkan atau menghapusnya, atau saat workload batch masih berjalan. Dalam deployment batch JobSet, pengontrol JobSet akan menghapus Pod worker segera setelah Tugas pathways-head selesai. Lihat log batch yang telah selesai di Cloud Logging, seperti yang dijelaskan dalam Memecahkan Masalah Pathways di Cloud.

Untuk memverifikasi deployment yang berjalan dengan alat command line kubectl, selesaikan langkah-langkah berikut:

  1. Periksa log container 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
    

    Ganti JOBSET_NAME dengan nilai metadata.name dari JobSet Anda (atau nama WORKLOAD yang Anda teruskan ke perintah gcluster job submit). Jika Anda membuat manifes dengan builder PathwaysJobSet, tetapkan replicatedjob-name=pathways-worker dalam variabel ROLE_LABEL.

    Outputnya mirip dengan hal berikut ini:

    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
    

    Pastikan output menampilkan pesan startup gRPC dan, setelah panggilan @colocated_python pertama, pesan alokator memori bersama. Manifes yang dibuat dengan builder PathwaysJobSet menggunakan direktori /tmp/shared-memory, dan deployment UDS mencatat unix:/sock/sidecar.sock ke dalam log, bukan localhost:50051.

  2. Periksa log container pathways-worker di Pod yang sama:

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

    Outputnya mirip dengan hal berikut ini:

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

    Pastikan container pathways-worker mengaktifkan memori bersama dan terhubung ke sidecar.

Saat Anda menjalankan perintah kubectl exec untuk memeriksa direktori memori bersama, targetkan container colocated-python-sidecar dengan flag -c colocated-python-sidecar, karena container pathways-worker tidak menyertakan shell.

Memecahkan masalah Python yang ditempatkan bersama

Bagian berikut menjelaskan cara menyelesaikan masalah umum Python yang ditempatkan bersama.

Unable to unpickle error

Jika workload Anda gagal dengan error berikut, versi Python atau paket berbeda antara klien JAX dan container sidecar:

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

Pastikan klien Anda menjalankan Python 3.12 (python --version) dan instal paket klien dengan flag -c constraints.txt yang diekstrak dari image file bantuan. Untuk mengetahui informasi selengkapnya, lihat Menjalankan workload Python yang ditempatkan bersama.

Konflik dependensi selama operasi docker build

Jika perintah uv pip install gagal dengan error No solution found when resolving dependencies, pin dalam file requirements.txt Anda bertentangan dengan file /opt/venv/server_constraints.txt. Hapus paket jax dan jaxlib dari file requirements.txt dan longgarkan pin versi pada paket seperti numpy, ml-dtypes, atau scipy.

Error sidecar tidak diaktifkan

Jika container pathways-proxy keluar dengan error Sidecar create args were set, but sidecar was not enabled, tambahkan flag --sidecar_name=external ke kolom args pada container pathways-proxy.

Sidecar already initialized error

Jika workload Anda gagal dengan error FAILED_PRECONDITION: Sidecar already initialized, pemutusan koneksi klien sebelumnya memulai ulang container pathways-worker, sementara container colocated-python-sidecar tetap diinisialisasi. Hapus dan buat ulang JobSet sebelum memulai sesi klien lain.

Error koneksi sidecar atau memori bersama

Gunakan pemeriksaan berikut untuk mengatasi error pemasangan memori bersama, koneksi gRPC, atau memori host:

  • Failed to stat sidecar_shm_directory: Pasang volume emptyDir memori bersama di jalur yang cocok (/tmp/sidecar atau /tmp/shared-memory) di container pathways-worker dan colocated-python-sidecar.
  • Timed out connecting to sidecar gRPC service atau Failed to connect to external sidecar: Pastikan container colocated-python-sidecar berjalan di kolom initContainers dengan restartPolicy: Always dan ketiga image cloud-pathways menggunakan tag yang cocok. Pastikan setelan TCP (--port=50051) atau UDS (volume /sock dan --unix_domain_socket_path=/sock/sidecar.sock) Anda cocok antara container pathways-proxy dan colocated-python-sidecar.
  • Host worker kehabisan memori setelah burst array besar: Tetapkan flag --pathways_sidecar_shared_memory_idle_release_secs=0 pada container colocated-python-sidecar (bersama dengan flag --port=50051 atau --unix_domain_socket_path) dan flag --cloud_pathways_shared_memory_idle_release_secs=0 pada container pathways-worker. Menetapkan kedua flag ke 0 akan mengosongkan memori bersama yang tidak digunakan dalam waktu sekitar 1 detik. Atau, kurangi jumlah puncak data array host yang disimpan workload Anda di memori sekaligus.

Pembersihan

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan dalam dokumen ini, hapus deployment dan artefak sementara setelah Anda selesai:

  • Manifes JobSet: Menghapus resource JobSet:

    kubectl delete jobset JOBSET_NAME
    

    Ganti JOBSET_NAME dengan nilai metadata.name dari JobSet Anda.

  • Cluster Toolkit: Batalkan tugas yang di-deploy:

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

    Ganti kode berikut:

    • WORKLOAD: nama tugas Pathways Anda.
    • CLUSTER: nama cluster GKE Anda.
    • PROJECT_ID:Google Cloud project ID Anda.
    • LOCATION: region atau zona cluster GKE Anda.

Opsional: Hapus image sidecar kustom di Artifact Registry dan hapus objek sementara di bucket sementara Cloud Storage Anda. Jika Anda tidak lagi memerlukan cluster GKE, hapus cluster tersebut dengan mengikuti langkah-langkah Pembersihan di Membuat cluster GKE dengan Pathways.

Langkah berikutnya