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) 역할을 부여합니다.
- 사용자 계정:
- Google Cloud 프로젝트에 대한 Artifact Registry 작성자(
roles/artifactregistry.writer) - 커스텀 사이드카 이미지를 Artifact Registry에 푸시합니다. - Google Cloud 프로젝트의 Kubernetes Engine 개발자(
roles/container.developer) - GKE에서JobSet리소스를 배포하고, 포트를 전달하고, 포드 로그를 읽습니다.
- Google Cloud 프로젝트에 대한 Artifact Registry 작성자(
- GKE 노드 풀 서비스 계정: Pathways 포드는 Pathways를 사용하여 GKE 클러스터 만들기에 구성된 대로 노드 풀에서
--workload-metadata=GCE_METADATA플래그를 사용할 때 이 서비스 계정을 사용합니다.- 커스텀 사이드카 이미지를 가져오기 위해 비공개 저장소를 호스팅하는 Google Cloud 프로젝트에 대한 Artifact Registry 리더(
roles/artifactregistry.reader) - 컴파일 캐시 및 기타 임시 파일에 대한 Cloud Storage 스크래치 버킷의 스토리지 객체 관리자(
roles/storage.objectAdmin)
- 커스텀 사이드카 이미지를 가져오기 위해 비공개 저장소를 호스팅하는 Google Cloud 프로젝트에 대한 Artifact Registry 리더(
선택사항: Pathways 리소스 관리자(pathways-rm) 컨테이너가 이전 컴파일 캐시 항목을 만료하는 버킷 수명 주기 규칙을 추가하도록 허용하려면 스크래치 버킷에 대한 스토리지 관리자 역할(roles/storage.admin)도 부여합니다. 이 역할이 없으면 pathways-rm 컨테이너가 경고를 로깅하고 캐시를 계속 사용합니다. 수명 주기 업데이트를 건너뛰려면 --enable_gcs_olm=false 플래그를 pathways-rm 컨테이너에 전달합니다.
노드 풀에서 GKE용 워크로드 아이덴티티 제휴를 대신 사용하는 경우 Pathways 포드에서 사용하는 Kubernetes 서비스 계정 또는 바인딩된 IAM 서비스 계정에 스크래치 버킷 역할을 부여합니다. 기본적으로 Pathways 포드는 JobSet 매니페스트가 serviceAccountName 필드를 설정하지 않는 한 default 서비스 계정을 사용합니다. 노드 풀 서비스 계정에 Artifact Registry 리더 역할을 유지합니다.
코로케이션된 Python이 Pathways와 작동하는 방식
Pathways에서 JAX 컨트롤러 스크립트는 단일 CPU 호스트에서 실행되고 Cloud TPU 워커 포드는 C++ pathways-worker 컨테이너를 실행합니다. 워커 호스트에서 @colocated_python 함수와 @colocated_python_class 메서드를 실행하기 위해 코로케이션 Python은 다음 구성요소를 사용합니다.
- JAX 컨트롤러:
jax.experimental.colocated_python모듈을 사용하여 각 Cloud TPU 칩을 호스트 CPU 기기와 페어링하고cloudpickle라이브러리를 사용하여 Python 함수 및 유형 메타데이터를 직렬화합니다. pathways-proxy컨테이너(pathways-head포드): gRPC를 통해 직렬화된 함수를 수신하고 호출의 입력 CPU 기기를 소유한 작업자 VM의pathways-worker컨테이너로 라우팅합니다.--sidecar_name=external플래그를 전달하면colocated-python-sidecar컨테이너를 타겟팅하도록pathways-proxy컨테이너가 구성됩니다.pathways-worker컨테이너(각 작업자 포드): 직렬화된 함수를 로컬 사이드카 컨테이너에 로드하고, 로컬 gRPC를 통해 실행을 트리거하고, 공유 인메모리emptyDir볼륨(medium: Memory)을 통해 배열 버퍼를 교환합니다.colocated-python-sidecar컨테이너(각 워커 포드): 격리된 Python 3.12 런타임에서 VM당 한 번씩 VM의 로컬 샤드에서 함수를 압축 해제하고 실행하여 출력 배열을 공유 호스트 메모리에 직접 작성합니다.
Pathways 아키텍처에 대한 자세한 내용은 Pathways 구성요소를 참조하세요.
실행 흐름
데코레이팅된 함수를 호출하면 Pathways는 클러스터 전체에서 두 단계로 실행합니다.
- 함수 라우팅:
jax.experimental.colocated_python모듈은 함수를 임시 프레임워크 런타임(IFRT) 프로그램으로 패킹하고pathways-proxy컨테이너로 전송합니다. 프록시는 입력 샤드를 보유한 작업자 VM에만 프로그램을 전달하며, 모든 로컬 샤드에서 VM당 한 번씩 실행됩니다. - 공유 메모리 실행:
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상태 다시 만들기: 스테이트풀(Stateful) 사이드카 객체는 메모리의 단계 간에 유지되지만 탄력적 학습 중에 워커 포드가 다시 시작되거나 슬라이스 수가 변경되면 자동으로 저장되지 않습니다. 재확장 또는 다시 시작 후 체크포인트에서 스테이트풀(Stateful) 객체를 다시 만듭니다.
사전 빌드된 이미지 및 태그
Google Cloud 는 공개 Artifact Registry 저장소에 사전 빌드된 Pathways 이미지를 게시합니다.
- 같은 위치에 있는 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파일을 만듭니다./opt/venv/server_constraints.txt파일에 이미 설치되고 고정된jax및jaxlib패키지는 생략합니다.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에서 패키지를 설치하는 경우 슬림 기본 이미지에서git도구를 생략하므로uv pip installRUN명령어 앞에 다음RUN명령어를 추가합니다.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)로 바꿉니다.커스텀 사이드카 이미지를 빌드하고 푸시합니다.
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 배포
이 섹션의 kubectl 명령줄 도구를 사용하여 JobSet 매니페스트를 적용하거나 Cluster Toolkit으로 배포에서 gcluster CLI를 사용하여 작업을 직접 제출하여 사이드카로 Pathways를 배포할 수 있습니다.
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로 바꿉니다.두 생성기 모두 매니페스트를 구성하여 다음을 실행합니다.
- 각 워커 포드에서
restartPolicy: Always를 사용하여initContainers필드 아래에서colocated-python-sidecar컨테이너를 실행합니다.gclusterCLI는 작업자 복제 작업의 이름을worker로 지정하는 반면PathwaysJobSet빌더는pathways-worker로 지정합니다. --sidecar_name=external플래그를pathways-proxy컨테이너에 전달하고pathways-worker컨테이너를localhost:50051의 루프백 TCP를 통해 사이드카에 연결합니다.pathways-proxy컨테이너가initContainers필드에서 실행되면restartPolicy: Always도 사용합니다.- 두 워커 포드 컨테이너에서
medium: Memory를 사용하여 인메모리emptyDir볼륨을 마운트합니다.gcluster매니페스트의/tmp/sidecar또는PathwaysJobSet매니페스트의/tmp/shared-memory에서 마운트합니다. 두 생성기 모두 사이드카에서CLOUD_PATHWAYS_SIDECAR_SHM_DIRECTORY환경 변수를 설정하고pathways-worker컨테이너에서--cloud_pathways_sidecar_shm_directory플래그를 설정합니다.
JobSet매니페스트를 적용하고 포드가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 배포당 JAX 클라이언트 세션 하나를 실행합니다. 클라이언트 연결이 끊긴 후 다시 시작된 pathways-worker 컨테이너는 실행 중인 사이드카를 재사용할 수 없습니다. 다른 세션을 시작하기 전에 JobSet를 삭제하고 다시 만듭니다.
인메모리 emptyDir 볼륨의 파일은 포드 메모리 사용량에 반영됩니다. 공유 메모리 볼륨에서 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를 설정하는 워커 포드에서 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)를 설정합니다.--cloud_pathways_external_sidecar_unix_domain_socket_path=/sock/sidecar.sock플래그를pathways-proxy컨테이너의args필드에 추가합니다.
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 플래그를 명시적으로 전달하여 세 이미지 모두 일치하는 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포드 내에서 컨테이너화된 일괄 작업을 실행하려면--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-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:29000JOBSET_NAME를JobSet의metadata.name값(또는gcluster job submit명령어에 전달한WORKLOAD이름)으로 바꿉니다.다음 스크립트를
colocated_example.py로 저장합니다. 이 스크립트는 각 Cloud TPU 워커의 공동 배치된 CPU 기기에 있는 공유 호스트 메모리에 4MiB 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가 대기 없이 모든 워커 사이드카에서 하나의 병렬 호출을 실행하도록 합니다.JAX_PLATFORMS=cpu환경 변수를 사용하여worker포드 내에서 클라이언트 스크립트를 실행하지 마세요. 이 설정은 하나의 CPU에서 로컬로 JAX를 실행하고 Pathways를 우회하기 때문입니다. 종료 시 출력되는IFRT proxy server disconnected: CANCELLED메시지는 무시해도 됩니다.
추가 사용 패턴은 다음 리소스를 참고하세요.
- JAX 공동 배치 Python 노트북: 함수 특수화 및 스테이트풀(Stateful)
@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 배포에서 JobSet 컨트롤러는 pathways-head 작업이 완료되는 즉시 worker 포드를 삭제합니다. 대신 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를 로깅합니다.동일한 포드에서
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 명령어를 실행하여 공유 메모리 디렉터리를 검사할 때 pathways-worker 컨테이너에 셸이 포함되지 않으므로 -c colocated-python-sidecar 플래그를 사용하여 colocated-python-sidecar 컨테이너를 타겟팅합니다.
공동 배치된 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 오류와 함께 실패하면 이전 클라이언트 연결 해제로 인해 pathways-worker 컨테이너가 다시 시작되고 colocated-python-sidecar 컨테이너는 초기화된 상태로 유지됩니다. 다른 클라이언트 세션을 시작하기 전에 JobSet를 삭제하고 다시 만듭니다.
공유 메모리 또는 사이드카 연결 오류
다음 검사를 사용하여 공유 메모리 마운트, gRPC 연결 또는 호스트 메모리 오류를 해결합니다.
Failed to stat sidecar_shm_directory:pathways-worker및colocated-python-sidecar컨테이너 모두에서 일치하는 경로(/tmp/sidecar또는/tmp/shared-memory)에 공유 메모리emptyDir볼륨을 마운트합니다.Timed out connecting to sidecar gRPC service또는Failed to connect to external sidecar:colocated-python-sidecar컨테이너가restartPolicy: Always를 사용하여initContainers필드에서 실행되고 세 개의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로 워크로드 실행