データの読み込みやチェックポイントなどのホストバインド作業を Google Kubernetes Engine(GKE)の単一の Pathways コントローラを介してルーティングしないようにするには、JAX コロケーション Python API を使用して、Cloud TPU ワーカー VM でこれらの関数を実行します。
このドキュメントは、機械学習エンジニアを対象としており、コロケーションされた Python が Pathways とどのように連携するかについて説明します。JobSet マニフェストまたは Cluster Toolkit を使用してサイドカー コンテナをビルド、デプロイ、検証する方法について説明します。
始める前に
次の前提条件を満たしていることを確認してください。
- Pathways を使用して GKE クラスタを作成する。
kubectlコマンドライン ツールとgke-gcloud-auth-pluginプラグインをインストールします。- Google Cloud CLI をインストールします。
- Docker をインストールする。
- Kubernetes Engine API と Artifact Registry API を有効にします。
- Pathways の一時ファイル用の Cloud Storage スクラッチ バケットを作成します。
- カスタム サイドカー イメージをビルドする場合は、Artifact Registry Docker リポジトリを作成します。
- JAX ワークロードを実行するクライアント環境に Python 3.12 をインストールします。
- 省略可: Cluster Toolkit を使用してデプロイするには、
gclusterCLI のバージョン 1.108.0 以降をインストールします。
必要なロール
次の 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 ログの読み取りを行います。
- カスタム サイドカー イメージを Artifact Registry に push するための、 Google Cloud プロジェクトに対する Artifact Registry 書き込み(
- GKE ノードプール サービス アカウント: Pathways を使用して GKE クラスタを作成するで構成されているように、ノードプールで
--workload-metadata=GCE_METADATAフラグが使用されている場合、Pathways Pod はこのサービス アカウントを使用します。- カスタム サイドカー イメージを pull する限定公開リポジトリをホストする Google Cloud プロジェクトに対する Artifact Registry 読み取り(
roles/artifactregistry.reader)。 - コンパイル キャッシュとその他の一時ファイル用の Cloud Storage スクラッチ バケットに対する Storage オブジェクト管理者(
roles/storage.objectAdmin)。
- カスタム サイドカー イメージを pull する限定公開リポジトリをホストする Google Cloud プロジェクトに対する Artifact Registry 読み取り(
省略可: 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-headPod 内): 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 つのステージで実行します。
- 関数ルーティング:
jax.experimental.colocated_pythonモジュールは、関数を Interim Framework Runtime(IFRT)プログラムにパッケージ化し、pathways-proxyコンテナに送信します。プロキシは、入力シャードを保持するワーカー VM にのみプログラムを転送し、すべてのローカル シャードで VM ごとに 1 回実行します。 - 共有メモリ実行:
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 バージョンに一致するビルド済みイメージにレイヤ化します。
空のビルド ディレクトリに、追加パッケージ用の
requirements.txtファイルを作成します。jaxパッケージとjaxlibパッケージは、すでにインストールされ、/opt/venv/server_constraints.txtファイルに固定されているため、省略します。grain/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 installRUN命令の前に次のRUN命令を追加します。これは、スリムなベースイメージではgitツールが省略されているためです。RUN apt-get update && \ apt-get install -y --no-install-recommends git && \ rm -rf /var/lib/apt/lists/*gcloud auth configure-dockerコマンドを使用して、Artifact Registry リージョンに対して Docker を認証します。gcloud auth configure-docker REGISTRY_LOCATION-docker.pkg.devREGISTRY_LOCATIONは、Artifact Registry のロケーション(us、us-central1など)に置き換えます。カスタム サイドカー イメージをビルドして 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 マニフェストを生成して適用する手順は次のとおりです。
次のいずれかのツールを使用して、
JobSetマニフェスト(pathways-colocated-jobset.yaml)を生成します。pathways-utilsPython ビルダー:.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コンテナを実行します。gclusterCLI では、ワーカーのレプリケートされたジョブに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フラグを設定します。
JobSetマニフェストを適用し、Pod がRunningステータスになるまで待ちます。kubectl apply -f pathways-colocated-jobset.yaml kubectl get pods -l jobset.sigs.k8s.io/jobset-name=JOBSET_NAMEJOBSET_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"]とexecstartupProbe(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-headPod 内でコンテナ化されたバッチジョブを実行するには、--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 クライアント スクリプトを実行します。
シリアル化の依存関係をサイドカー イメージに合わせるには、
/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 pathwaysutilsJAX_VERSIONは、JAX のバージョン(0.12.0.1など)に置き換えます。pathways-headPod の外部でクライアントを実行する場合は、別のターミナルでローカルポート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:29000JOBSET_NAMEは、JobSetのmetadata.name値(またはgcluster job submitコマンドに渡したWORKLOAD名)に置き換えます。次のスクリプトを
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}" )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環境変数を使用してworkerPod 内でクライアント スクリプトを実行しないでください。この設定では、JAX が 1 つの CPU でローカルに実行され、Pathways がバイパスされます。終了時に出力されるIFRT proxy server disconnected: CANCELLEDメッセージは無視してかまいません。
その他の使用パターンについては、次のリソースをご覧ください。
- JAX コロケーション Python ノートブック: 関数特殊化とステートフル
@colocated_python_classオブジェクト - MaxText
multihost_dataloading.pyモジュール: コロケーションされた Python を使用するRemoteIteratorマルチホスト入力パイプライン - Orbax Pathways チェックポイント処理と Pathways を使用した多層チェックポイント処理:
orbax.checkpoint.pathways.register_type_handlers(checkpointing_impl=CheckpointingImpl.COLOCATED_PYTHON)呼び出し(または MaxText のcolocated_python_checkpointing=True設定)と多層チェックポイントのuse_colocated_python=Trueオプションを使用した、ワーカー サイドカーでの分散チェックポイント処理
サイドカーのデプロイを確認する
ヘッドレス をキャンセルまたは
削除する前、またはバッチ ワークロードの実行中に、ヘッドレス JobSet で kubectl logs コマンドを実行します。バッチ JobSet デプロイでは、pathways-head Job が完了するとすぐに、JobSet コントローラが worker Pod を削除します。代わりに、Cloud での Pathways のトラブルシューティングの説明に沿って、完了したバッチログを Cloud Logging で表示します。
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-sidecarJOBSET_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をログに記録します。同じ 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:50051pathways-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_NAMEJOBSET_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 クラスタを作成するのクリーンアップ手順に沿って削除します。
次のステップ
- JAX ワークロードを Pathways に移植する
- Pathways を使用した復元力のあるトレーニング
- Pathways を使用してバッチ ワークロードを実行する
- Pathways を使用してインタラクティブなワークロードを実行する
- Cloud での Pathways のトラブルシューティング
- Cluster Toolkit で Pathways を使用してワークロードを実行する