Pathways でコロケーションされた Python を実行する

データの読み込みやチェックポイントなどのホストバインド作業を Google Kubernetes Engine(GKE)の単一の Pathways コントローラを介してルーティングしないようにするには、JAX コロケーション Python API を使用して、Cloud TPU ワーカー VM でこれらの関数を実行します。

このドキュメントは、機械学習エンジニアを対象としており、コロケーションされた Python が Pathways とどのように連携するかについて説明します。JobSet マニフェストまたは Cluster Toolkit を使用してサイドカー コンテナをビルド、デプロイ、検証する方法について説明します。

始める前に

次の前提条件を満たしていることを確認してください。

必要なロール

次の Identity and Access Management(IAM)ロールを付与します。

  • ユーザー アカウント:
    • カスタム サイドカー イメージを Artifact Registry に push するための、 Google Cloud プロジェクトに対する Artifact Registry 書き込み(roles/artifactregistry.writer)。
    • Google Cloud プロジェクトの Kubernetes Engine デベロッパー(roles/container.developer)。JobSet リソースのデプロイ、ポートの転送、GKE での Pod ログの読み取りを行います。
  • GKE ノードプール サービス アカウント: Pathways を使用して GKE クラスタを作成するで構成されているように、ノードプールで --workload-metadata=GCE_METADATA フラグが使用されている場合、Pathways Pod はこのサービス アカウントを使用します。
    • カスタム サイドカー イメージを pull する限定公開リポジトリをホストする Google Cloud プロジェクトに対する Artifact Registry 読み取り(roles/artifactregistry.reader)。
    • コンパイル キャッシュとその他の一時ファイル用の Cloud Storage スクラッチ バケットに対する Storage オブジェクト管理者(roles/storage.objectAdmin)。

省略可: Pathways リソース マネージャー(pathways-rm)コンテナが、古いコンパイル キャッシュ エントリを期限切れにするバケット ライフサイクル ルールを追加できるようにするには、スクラッチ バケットに対するストレージ管理者ロール(roles/storage.admin)も付与します。このロールがないと、pathways-rm コンテナは警告をログに記録し、キャッシュの使用を継続します。ライフサイクルの更新をスキップするには、--enable_gcs_olm=false フラグを pathways-rm コンテナに渡します。

ノードプールで Workload Identity Federation for GKE を使用している場合は、Pathways Pod が使用する Kubernetes サービス アカウントまたはバインドされた IAM サービス アカウントにスクラッチ バケットのロールを付与します。デフォルトでは、JobSet マニフェストで serviceAccountName フィールドが設定されていない限り、Pathways Pod は default サービス アカウントを使用します。ノードプールのサービス アカウントに Artifact Registry 読み取りロールを保持します。

コロケーションされた Python と Pathways の連携

Pathways では、JAX コントローラ スクリプトは単一の CPU ホストで実行され、Cloud TPU ワーカー Pod は C++ pathways-worker コンテナを実行します。ワーカーホストで @colocated_python 関数と @colocated_python_class メソッドを実行するために、コロケーション Python は次のコンポーネントを使用します。

  • JAX コントローラ: jax.experimental.colocated_python モジュールを使用して、各 Cloud TPU チップをホスト CPU デバイスとペアリングし、cloudpickle ライブラリを使用して Python 関数と型メタデータをシリアル化します。
  • pathways-proxy コンテナ(pathways-head Pod 内): gRPC 経由でシリアル化された関数を受け取り、呼び出しの入力 CPU デバイスを所有するワーカー VM の pathways-worker コンテナにルーティングします。--sidecar_name=external フラグを渡すと、colocated-python-sidecar コンテナをターゲットとするように pathways-proxy コンテナが構成されます。
  • pathways-worker コンテナ(各ワーカー Pod): シリアル化された関数をローカル サイドカー コンテナに読み込み、ローカル gRPC を介して実行をトリガーし、共有インメモリ emptyDir ボリューム(medium: Memory)を介して配列バッファを交換します。
  • colocated-python-sidecar コンテナ(各ワーカー Pod): VM のローカル シャード全体で VM ごとに 1 回、分離された Python 3.12 ランタイムで関数を解凍して実行し、出力配列を共有ホストメモリに直接書き込みます。

Pathways アーキテクチャの詳細については、Pathways コンポーネントをご覧ください。

実行フロー

デコレートされた関数を呼び出すと、Pathways はクラスタ全体で次の 2 つのステージで実行します。

  1. 関数ルーティング: jax.experimental.colocated_python モジュールは、関数を Interim Framework Runtime(IFRT)プログラムにパッケージ化し、pathways-proxy コンテナに送信します。プロキシは、入力シャードを保持するワーカー VM にのみプログラムを転送し、すべてのローカル シャードで VM ごとに 1 回実行します。
  2. 共有メモリ実行: pathways-worker コンテナは、入力シャードをインメモリ共有ボリューム(/tmp/sidecar または /tmp/shared-memory)に書き込み、ループバック TCP(localhost:50051)または Unix ドメイン ソケット(/sock/sidecar.sock)を介して colocated-python-sidecar コンテナを呼び出します。出力配列は、gRPC コピーなしで共有メモリを介して返され、Cloud TPU デバイスに配置されると、Cloud TPU 高帯域幅メモリ(HBM)に直接移動します。

コロケーションされた CPU デバイスの検出や非同期ディスパッチの出力仕様の宣言など、JAX API の使用方法については、JAX コロケーション Python ガイドをご覧ください。

設計ガイドライン

コロケーションされた Python 関数を作成する場合は、次のガイドラインに従ってください。

  • キャプチャされる変数を最小限に抑える: クロージャで大きな配列やシリアル化できないオブジェクト(開いているファイルやネットワーク クライアントなど)をキャプチャするのではなく、配列データをシャーディングされた jax.Array 引数として渡します。ワーカーの @colocated_python_class インスタンス内でファイルまたはクライアントを開きます。
  • 再起動後に @colocated_python_class 状態を再作成する: ステートフル サイドカー オブジェクトはメモリ内のステップ間で保持されますが、エラスティック トレーニング中にワーカー Pod が再起動したり、スライス数が変更されたりしても、自動的に保存されません。再スケーリングまたは再起動後に、チェックポイントからステートフル オブジェクトを再作成します。

事前ビルドされたイメージとタグ

Google Cloud は、ビルド済みの Pathways イメージを公開 Artifact Registry リポジトリに公開します。

  • コロケーションされた Python サイドカー: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/colocated_python_sidecar:TAG
  • Pathways リソース マネージャーとワーカー: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/server:TAG
  • IFRT プロキシ サーバー: us-docker.pkg.dev/cloud-tpu-v2-images/cloud-pathways/proxy_server:TAG

server、proxy_server、colocated_python_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: 日付スタンプ付きのビルドタグ(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 など)に置き換えます。

カスタム サイドカー イメージをビルドする

ビルド済みのサイドカー イメージには、jax、jaxlib、numpy、scipy、ml-dtypes、opt-einsum、cloudpickle、absl-py のパッケージが含まれています。コロケーションされた Python 関数がこれらのパッケージのみを使用している場合は、サイドカーを使用して Pathways JobSet をデプロイするまたは Cluster Toolkit を使用してデプロイするに進みます。

カスタム Python 依存関係を追加するには、JAX バージョンに一致するビルド済みイメージにレイヤ化します。

  1. 空のビルド ディレクトリに、追加パッケージ用の requirements.txt ファイルを作成します。jax パッケージと jaxlib パッケージは、すでにインストールされ、/opt/venv/server_constraints.txt ファイルに固定されているため、省略します。

    grain
    
  2. /opt/venv/server_constraints.txt ファイルによって制限された requirements.txt ファイルにパッケージをインストールする Dockerfile を作成します。

    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 ファイルが Git URL からパッケージをインストールする場合は、uv pip install RUN 命令の前に次の RUN 命令を追加します。これは、スリムなベースイメージでは git ツールが省略されているためです。

    RUN apt-get update && \
        apt-get install -y --no-install-recommends git && \
        rm -rf /var/lib/apt/lists/*
    
  3. gcloud auth configure-docker コマンドを使用して、Artifact Registry リージョンに対して Docker を認証します。

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

    REGISTRY_LOCATION は、Artifact Registry のロケーション(us、us-central1 など)に置き換えます。

  4. カスタム サイドカー イメージをビルドして push します。

    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 プロジェクト ID。
    • REPOSITORY: Artifact Registry Docker リポジトリの名前。

サイドカーを使用して Pathways JobSet をデプロイする

サイドカーを使用して Pathways をデプロイするには、このセクションの kubectl コマンドライン ツールで JobSet マニフェストを適用するか、Cluster Toolkit を使用してデプロイするで gcluster CLI を使用してジョブを直接送信します。

JobSet マニフェストを生成して適用する手順は次のとおりです。

  1. 次のいずれかのツールを使用して、JobSet マニフェスト(pathways-colocated-jobset.yaml)を生成します。

    • pathways-utils Python ビルダー: .add_colocated_python("SIDECAR_IMAGE") メソッドと .export_yaml("pathways-colocated-jobset.yaml") メソッドを呼び出して、PathwaysJobSet ビルダーで JobSet を構成します。pathwaysutils パッケージ(PyPI のバージョン 0.1.14 以前)を使用する場合は、proxy_container_kwargs={"args": ["--sidecar_name=external"]} 引数を PathwaysJobSet コンストラクタに渡すか、main ブランチから pathways-utils パッケージをインストールします。
    • Cluster Toolkit(gcluster): --pathways-colocated-python-sidecar-image フラグを指定して gcluster job submit コマンドを実行し、--dry-run-out=pathways-colocated-jobset.yaml フラグを追加して、ジョブを送信せずにマニフェストをローカルでレンダリングします。

    SIDECAR_IMAGE は、カスタム サイドカー イメージの URI またはビルド済みの colocated_python_sidecar イメージの URI に置き換えます。

    どちらのジェネレータも、次の処理を行うようにマニフェストを構成します。

    • 各ワーカー Pod で restartPolicy: Always を使用して、initContainers フィールドの下で colocated-python-sidecar コンテナを実行します。gcluster CLI では、ワーカーのレプリケートされたジョブに worker という名前が付けられますが、PathwaysJobSet ビルダーでは pathways-worker という名前が付けられます。
    • --sidecar_name=external フラグを pathways-proxy コンテナに渡し、localhost:50051 のループバック TCP を介して pathways-worker コンテナをサイドカーに接続します。pathways-proxy コンテナが initContainers フィールドで実行されると、restartPolicy: Always も使用されます。
    • 両方のワーカー Pod コンテナに medium: Memory を含むインメモリ emptyDir ボリュームをマウントします。gcluster マニフェストの /tmp/sidecar、または PathwaysJobSet マニフェストの /tmp/shared-memory。どちらのジェネレータも、サイドカーに CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY 環境変数を設定し、pathways-worker コンテナに --cloud_pathways_sidecar_shm_directory フラグを設定します。
  2. JobSet マニフェストを適用し、Pod が Running ステータスになるまで待ちます。

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

    JOBSET_NAME は、JobSet の metadata.name 値に置き換えます。

JobSet デプロイごとに 1 つの JAX クライアント セッションを実行します。クライアントが切断されると、再起動された pathways-worker コンテナは実行中のサイドカーを再利用できません。別のセッションを開始する前に、JobSet を削除して再作成します。

インメモリ emptyDir ボリューム内のファイルは、Pod のメモリ使用量にカウントされます。共有メモリ ボリュームの emptyDir.sizeLimit フィールド(175Gi など)を設定して、ノードあたりの使用量に上限を設定します。デフォルトでは、両方のコンテナは、解放された共有メモリを 30 秒間のアイドル時間保持して再利用します。このウィンドウを変更するには、colocated-python-sidecar コンテナの args フィールドの --pathways_sidecar_shared_memory_idle_release_secs=SECONDS フラグ(--port=50051 フラグまたは --unix_domain_socket_path フラグとともに)と、pathways-worker コンテナの args フィールドの --cloud_pathways_shared_memory_idle_release_secs=SECONDS フラグの両方を設定します。SECONDS は、アイドル タイムアウト(秒単位)に置き換えます。両方のフラグを 0 に設定すると、解放されたページが約 1 秒以内に解放されます。これにより、追加の割り当てオーバーヘッドを犠牲にしてメモリ使用量が削減されます。

省略可: Unix ドメイン ソケットを使用する

hostNetwork: true を設定するワーカー Pod で TCP ポートを開く代わりに、/sock/sidecar.sock で Unix ドメイン ソケット(UDS)を使用するには、kubectl apply コマンドを実行する前に、JobSet マニフェストに次のオーバーライドを適用します。

  • pathways-worker コンテナと colocated-python-sidecar コンテナの両方の /sock に、sidecar-socket という名前の emptyDir: {} ボリュームをマウントします。
  • colocated-python-sidecar コンテナに args: ["--unix_domain_socket_path=/sock/sidecar.sock"] と exec startupProbe(test -S /sock/sidecar.sock)を設定します。
  • pathways-proxy コンテナの args フィールドに --cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock フラグを追加します。

Cluster Toolkit を使用してデプロイする

Cluster Toolkit(gcluster バージョン 1.108.0 以降)で、--pathways-colocated-python-sidecar-image フラグを gcluster job submit コマンドに渡すと、ループバック TCP(localhost:50051)を介して colocated-python-sidecar コンテナが構成され、/tmp/sidecar にインメモリ ボリュームがマウントされ、--sidecar_name=external フラグが設定されます。--pathways-server-image フラグと --pathways-proxy-server-image フラグを明示的に渡して、3 つのイメージすべてで一致する cloud-pathways タグが使用されるようにします。

サイドカー イメージを使用してヘッドレス Pathways デプロイを送信し、それに対してインタラクティブなクライアント スクリプトを実行できるようにします。

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: Cloud Storage スクラッチ バケット。
  • JAX_VERSION: JAX のバージョン(0.12.0.1 など)。
  • SIDECAR_IMAGE: カスタムまたはビルド済みのサイドカー イメージの URI。
  • WORKLOAD: 一意の JobSet 名(22 文字以下)。
  • CLUSTER: GKE クラスタ名。
  • PROJECT_ID: 実際のGoogle Cloud プロジェクト ID。
  • 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 コマンドでジョブを実行またはエクスポートする方法をカスタマイズすることもできます。

  • バッチ ワークロード: ヘッドレス デプロイではなく、pathways-head Pod 内でコンテナ化されたバッチジョブを実行するには、--pathways-headless フラグを --image="CLIENT_IMAGE" フラグと --command="COMMAND" フラグに置き換えます。server_constraints.txt ピンでビルドされた Python 3.12 JAX クライアント イメージを使用し、エントリ コマンド(python colocated_example.py など)を渡します。
  • ローカル マニフェストのレンダリング: --dry-run-out=pathways-colocated-jobset.yaml フラグを追加して、JobSet マニフェストを送信せずにローカルでレンダリングします。
  • 後続のヘッドレス セッション: 別のクライアント セッションを開始する前に、gcluster job cancel コマンドを実行してジョブを再送信します。

コロケーションされた Python ワークロードを実行する

pathways-head ワークロード コンテナ内またはポート転送を介して、pathways-proxy コンテナに対して JAX_PLATFORMS=proxy 環境変数を使用して JAX クライアント スクリプトを実行します。

  1. シリアル化の依存関係をサイドカー イメージに合わせるには、/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. pathways-head Pod の外部でクライアントを実行する場合は、別のターミナルでローカルポート 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 は、JobSet の metadata.name 値(または gcluster job submit コマンドに渡した WORKLOAD 名)に置き換えます。

  3. 次のスクリプトを colocated_example.py として保存します。このスクリプトは、各 Cloud TPU ワーカーのコロケーション CPU デバイスの共有ホストメモリに 4 MiB の NumPy 配列を割り当て、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. 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
    

    マルチスライス本番環境ワークロードでは、colocated_python.colocated_cpu_devices(mesh) 呼び出しによって返されたデバイスに配置されたシャーディングされた jax.Array 引数を渡し、.specialize(out_specs_fn=...) メソッドで out_specs_fn パラメータを設定します。これにより、Pathways は待機することなく、すべてのワーカー サイドカーで 1 つの並列呼び出しを実行します。

    JAX_PLATFORMS=cpu 環境変数を使用して worker Pod 内でクライアント スクリプトを実行しないでください。この設定では、JAX が 1 つの CPU でローカルに実行され、Pathways がバイパスされます。終了時に出力される IFRT proxy server disconnected: CANCELLED メッセージは無視してかまいません。

その他の使用パターンについては、次のリソースをご覧ください。

サイドカーのデプロイを確認する

ヘッドレス をキャンセルまたは 削除する前、またはバッチ ワークロードの実行中に、ヘッドレス JobSet で kubectl logs コマンドを実行します。バッチ JobSet デプロイでは、pathways-head Job が完了するとすぐに、JobSet コントローラが worker Pod を削除します。代わりに、Cloud での Pathways のトラブルシューティングの説明に沿って、完了したバッチログを Cloud Logging で表示します。

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 は、JobSet の metadata.name 値(または gcluster job submit コマンドに渡した WORKLOAD 名)に置き換えます。PathwaysJobSet ビルダーでマニフェストを生成した場合は、ROLE_LABEL 変数に replicatedjob-name=pathways-worker を設定します。

    出力は次のようになります。

    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 呼び出しの後に共有メモリ割り当てメッセージが表示されることを確認します。PathwaysJobSet ビルダーで生成されたマニフェストは /tmp/shared-memory ディレクトリを使用し、UDS デプロイは localhost:50051 ではなく unix:/sock/sidecar.sock をログに記録します。

  2. 同じ Pod の pathways-worker コンテナログを調べます。

    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 コンテナで共有メモリが有効になり、サイドカーに接続されていることを確認します。

kubectl exec コマンドを実行して共有メモリ ディレクトリを検査する場合は、-c colocated-python-sidecar フラグを使用して colocated-python-sidecar コンテナをターゲットにします。pathways-worker コンテナにはシェルが含まれていないためです。

コロケーション Python のトラブルシューティング

以降のセクションでは、一般的な Python のコロケーションの問題を解決する方法について説明します。

エラー Unable to unpickle 件

ワークロードが次のエラーで失敗した場合、JAX クライアントとサイドカー コンテナの間で Python またはパッケージのバージョンが異なります。

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

クライアントが Python 3.12(python --version)を実行していることを確認し、サイドカー イメージから抽出された -c constraints.txt フラグを使用してクライアント パッケージをインストールします。詳細については、コロケーションされた Python ワークロードを実行するをご覧ください。

docker build の実行中の依存関係の競合

uv pip install コマンドが No solution found when resolving dependencies エラーで失敗した場合、requirements.txt ファイルのピンが /opt/venv/server_constraints.txt ファイルと競合しています。requirements.txt ファイルから jax パッケージと jaxlib パッケージを削除し、numpy、ml-dtypes、scipy などのパッケージのバージョン固定を緩和します。

サイドカーが有効になっていないエラー

pathways-proxy コンテナが Sidecar create args were set, but sidecar was not enabled エラーで終了した場合は、pathways-proxy コンテナの args フィールドに --sidecar_name=external フラグを追加します。

エラー Sidecar already initialized 件

ワークロードが FAILED_PRECONDITION: Sidecar already initialized エラーで失敗した場合、以前のクライアントの切断により、colocated-python-sidecar コンテナが初期化されたまま pathways-worker コンテナが再起動されています。別のクライアント セッションを開始する前に、JobSet を削除して再作成します。

共有メモリまたはサイドカー接続エラー

共有メモリのマウント、gRPC 接続、ホストメモリのエラーを解決するには、次のチェックを行います。

  • Failed to stat sidecar_shm_directory: 共有メモリ emptyDir ボリュームを、pathways-worker コンテナと colocated-python-sidecar コンテナの両方の一致するパス(/tmp/sidecar または /tmp/shared-memory)にマウントします。
  • Timed out connecting to sidecar gRPC service または Failed to connect to external sidecar: colocated-python-sidecar コンテナが initContainers フィールドで restartPolicy: Always を使用して実行されていること、および 3 つの cloud-pathways イメージすべてが一致するタグを使用していることを確認します。TCP(--port=50051)または UDS(/sock ボリュームと --unix_domain_socket_path=/sock/sidecar.sock)の設定が pathways-proxy コンテナと colocated-python-sidecar コンテナの間で一致していることを確認します。
  • 大規模な配列バースト後のワーカーホストのメモリ不足: colocated-python-sidecar コンテナに --pathways_sidecar_shared_memory_idle_release_secs=0 フラグ(--port=50051 フラグまたは --unix_domain_socket_path フラグとともに)を設定し、pathways-worker コンテナに --cloud_pathways_shared_memory_idle_release_secs=0 フラグを設定します。両方のフラグを 0 に設定すると、未使用の共有メモリが約 1 秒以内に解放されます。または、ワークロードがメモリに一度に保持するホスト配列データのピーク量を減らします。

クリーンアップ

このドキュメントで使用したリソースについて Google Cloud アカウントに課金されないようにするには、完了時にデプロイと一時アーティファクトを削除します。

  • JobSet マニフェスト: JobSet リソースを削除します。

    kubectl delete jobset JOBSET_NAME
    

    JOBSET_NAME は、JobSet の metadata.name 値に置き換えます。

  • Cluster Toolkit: デプロイされたジョブをキャンセルします。

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

    次のように置き換えます。

    • WORKLOAD: Pathways ジョブの名前。
    • CLUSTER: GKE クラスタ名。
    • PROJECT_ID: 実際のGoogle Cloud プロジェクト ID。
    • LOCATION: GKE クラスタのリージョンまたはゾーン。

省略可: Artifact Registry のカスタム サイドカー イメージを削除し、Cloud Storage スクラッチ バケットの一時オブジェクトを削除します。GKE クラスタが不要になったら、Pathways を使用して GKE クラスタを作成するのクリーンアップ手順に沿って削除します。

次のステップ