Pathways로 같은 위치에 배치된 Python 실행

Google Kubernetes Engine(GKE)에서 단일 Pathways 컨트롤러를 통해 데이터 로드 및 체크포인트와 같은 호스트 바인딩 작업을 라우팅하지 않으려면 JAX 코로케이션 Python API를 사용하여 Cloud TPU 워커 VM에서 이러한 함수를 실행합니다.

머신러닝 엔지니어를 대상으로 하는 이 문서에서는 공동 배치된 Python이 Pathways와 함께 작동하는 방식을 설명합니다. JobSet 매니페스트 또는 Cluster Toolkit을 사용하여 사이드카 컨테이너를 빌드, 배포, 확인하는 방법을 알아봅니다.

시작하기 전에

다음 기본 요건을 완료합니다.

필요한 역할

다음 Identity and Access Management(IAM) 역할을 부여합니다.

  • 사용자 계정:
    • Google Cloud 프로젝트에 대한 Artifact Registry 작성자(roles/artifactregistry.writer) - 커스텀 사이드카 이미지를 Artifact Registry에 푸시합니다.
    • Google Cloud 프로젝트의 Kubernetes Engine 개발자(roles/container.developer) - GKE에서 JobSet 리소스를 배포하고, 포트를 전달하고, 포드 로그를 읽습니다.
  • GKE 노드 풀 서비스 계정: Pathways 포드는 Pathways를 사용하여 GKE 클러스터 만들기에 구성된 대로 노드 풀에서 --workload-metadata=GCE_METADATA 플래그를 사용할 때 이 서비스 계정을 사용합니다.
    • 커스텀 사이드카 이미지를 가져오기 위해 비공개 저장소를 호스팅하는 Google Cloud 프로젝트에 대한 Artifact Registry 리더(roles/artifactregistry.reader)
    • 컴파일 캐시 및 기타 임시 파일에 대한 Cloud Storage 스크래치 버킷의 스토리지 객체 관리자(roles/storage.objectAdmin)

선택사항: 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는 클러스터 전체에서 두 단계로 실행합니다.

  1. 함수 라우팅: jax.experimental.colocated_python 모듈은 함수를 임시 프레임워크 런타임(IFRT) 프로그램으로 패킹하고 pathways-proxy 컨테이너로 전송합니다. 프록시는 입력 샤드를 보유한 작업자 VM에만 프로그램을 전달하며, 모든 로컬 샤드에서 VM당 한 번씩 실행됩니다.
  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 상태 다시 만들기: 스테이트풀(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 버전과 일치하는 사전 빌드된 이미지에 레이어링합니다.

  1. 빈 빌드 디렉터리에서 추가 패키지의 requirements.txt 파일을 만듭니다. /opt/venv/server_constraints.txt 파일에 이미 설치되고 고정된 jax 및 jaxlib 패키지는 생략합니다.

    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에서 패키지를 설치하는 경우 슬림 기본 이미지에서 git 도구를 생략하므로 uv pip install RUN 명령어 앞에 다음 RUN 명령어를 추가합니다.

    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. 커스텀 사이드카 이미지를 빌드하고 푸시합니다.

    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 매니페스트를 생성하고 적용하려면 다음 단계를 완료하세요.

  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로 바꿉니다.

    두 생성기 모두 매니페스트를 구성하여 다음을 실행합니다.

    • 각 워커 포드에서 restartPolicy: Always를 사용하여 initContainers 필드 아래에서 colocated-python-sidecar 컨테이너를 실행합니다. gcluster CLI는 작업자 복제 작업의 이름을 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 플래그를 설정합니다.
  2. JobSet 매니페스트를 적용하고 포드가 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 배포당 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"] 및 exec startupProbe(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 클라이언트 스크립트를 실행합니다.

  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 포드 외부에서 클라이언트를 실행하는 경우 별도의 터미널에서 로컬 포트 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 기기에 있는 공유 호스트 메모리에 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}"
    )
    
  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가 대기 없이 모든 워커 사이드카에서 하나의 병렬 호출을 실행하도록 합니다.

    JAX_PLATFORMS=cpu 환경 변수를 사용하여 worker 포드 내에서 클라이언트 스크립트를 실행하지 마세요. 이 설정은 하나의 CPU에서 로컬로 JAX를 실행하고 Pathways를 우회하기 때문입니다. 종료 시 출력되는 IFRT proxy server disconnected: CANCELLED 메시지는 무시해도 됩니다.

추가 사용 패턴은 다음 리소스를 참고하세요.

사이드카 배포 확인

헤드리스 를 취소하거나 삭제하기 전 또는 일괄 워크로드가 아직 실행 중인 동안 헤드리스 JobSet에서 kubectl logs 명령어를 실행합니다. 일괄 JobSet 배포에서 JobSet 컨트롤러는 pathways-head 작업이 완료되는 즉시 worker 포드를 삭제합니다. 대신 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. 동일한 포드에서 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 명령어를 실행하여 공유 메모리 디렉터리를 검사할 때 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_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 클러스터 만들기의 정리 단계에 따라 클러스터를 삭제합니다.

다음 단계