Ray LLM을 사용해서 GKE에서 TPU를 사용하는 Gemma 개방형 모델 제공

이 튜토리얼에서는 Ray Serve LLM을 사용하여 멀티 호스트 TPU 추론 서비스를 배포하는 방법을 안내합니다. Ray의 기본 TPU 지원을 활용하여 복잡한 가속기 토폴로지 전반에서 분산 엔진 작업자를 원자적으로 공동 예약하면 추론을 위해 멀티 호스트 TPU 슬라이스에 대규모 모델을 배포할 수 있습니다.

이 튜토리얼은 분산된 멀티 호스트 TPU 슬라이스에서 AI/ML 워크로드를 서빙하기 위해 Kubernetes 컨테이너 조정 기능을 사용하는 데 관심이 있는 머신러닝 (ML) 엔지니어, 플랫폼 관리자 및 운영자, 데이터 및 AI 전문가를 대상으로 합니다. Google Cloud 콘텐츠에서 언급된 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참조하세요.

이 페이지를 읽기 전 다음 내용을 숙지해야 합니다.

배경

이 섹션에서는 이 가이드에서 사용되는 주요 기술을 설명합니다.

TPU

Tensor Processing Unit (TPU)을 사용하면 머신러닝 및 데이터 처리와 같이 노드에서 실행되는 특정 워크로드를 가속화할 수 있습니다. TPU의 주요 장점은 대규모 성능입니다. 이 튜토리얼에서는 6세대 Cloud TPU인 TPU Trillium을 사용합니다. 멀티 호스트 TPU 슬라이스는 고속 칩 간 상호 연결 (ICI)을 사용하여 통신하는 여러 물리적 노드로 구성되며, 높은 처리량과 짧은 지연 시간의 서비스에 적합합니다.

Ray의 vLLM

vLLM은 처리량이 많고 메모리 효율적인 LLM 서빙 엔진입니다. Ray Serve와 통합하면 vLLM이 여러 호스트에서 확장되고 물리적 하드웨어 토폴로지에 기본적으로 액세스할 수 있습니다. 이 튜토리얼에서는 Ray Serve의 LLMConfig 및 LLMServer 배포를 사용하여 멀티 호스트 슬라이스에서 vLLM 추론을 오케스트레이션하여 프레임워크가 토폴로지 배포 및 게재위치 그룹 확산을 자동으로 처리하도록 하는 방법을 보여줍니다.

목표

이 튜토리얼은 멀티 호스트 TPU를 사용하는 관리형 Kubernetes 환경에서 LLM을 추론 용도로 실제로 배포하는 방식을 이해하고 탐색하는 데 필요한 기초를 제공합니다.

  1. Autopilot 또는 Standard 모드의 GKE 클러스터로 환경을 준비합니다.
  2. 종속 항목이 내장된 커스텀 컨테이너 이미지를 빌드합니다.
  3. TPU 슬라이스에서 vLLM 추론을 오케스트레이션하기 위해 Ray LLM Python 스크립트를 클러스터에 배포합니다.
  4. Ray LLM을 사용하여 curl 및 선택적 웹 채팅 인터페이스를 통해 Gemma 4 모델을 제공합니다.

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

  • Google Kubernetes Engine API를 사용 설정합니다.
    • Google Kubernetes Engine API 사용 설정
  • 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치했으면 gcloud components update 명령어를 실행하여 최신 버전을 가져옵니다. 이전 gcloud CLI 버전에서는 이 문서의 명령어를 실행하지 못할 수 있습니다.
  • 선택한 리전에서 TPU Trillium (v6e) 용량에 대한 프로젝트 할당량이 충분한지 확인합니다. 자세한 내용은 Cloud TPU 할당량을 참고하세요.
  • GKE 클러스터가 GKE Dataplane V2를 사용하고 Standard 및 Autopilot 모두에 대해 1.35.2-gke.1842000 이상의 DRANET 버전 요구사항을 충족하는지 확인합니다.
  • 다음 IAM 역할이 있는지 확인합니다.
    • roles/container.admin
    • roles/iam.serviceAccountAdmin

개발 환경 준비

이 튜토리얼에서는 Cloud Shell을 사용하여 Google Cloud에서 호스팅되는 리소스를 관리합니다. Cloud Shell에는 kubectl 및 gcloud CLI를 비롯해 이 튜토리얼에 필요한 소프트웨어가 사전 설치되어 있습니다.

Cloud Shell로 환경을 설정하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 Cloud Shell 활성화 셸 활성화 버튼를 클릭하여 Cloud Shell 세션을 시작합니다. 그러면 Google Cloud 콘솔 하단 창에서 세션이 실행됩니다.

  2. Python 가상 환경을 만들고 활성화합니다.

    python3 -m venv ray-env
source ray-env/bin/activate

  3. Ray CLI를 설치합니다.

    pip install "ray"

  4. 기본 환경 변수를 설정합니다.

    export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME=ray-llm-cluster
export REGION=REGION
export ZONE=ZONE
export NAMESPACE=default
export KSA_NAME=ray-ksa
export GSA_NAME=tpu-reader-sa
export NETWORK_NAME=${CLUSTER_NAME}-net
export GS_BUCKET=BUCKET_NAME
export REPO_NAME=ray-repo
export CUSTOM_IMAGE_URI=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/vllm-tpu-ray:vllm-tpu

    다음을 바꿉니다.

    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • CLUSTER_NAME: 클러스터 이름입니다.
    • REGION: TPU Trillium 용량을 사용할 수 있는 리전입니다.
    • ZONE: TPU Trillium 용량을 사용할 수 있는 영역입니다. 자세한 내용은 GKE의 TPU 가용성을 참조하세요.
    • REPOSITORY: Artifact Registry 저장소의 이름입니다.
    • BUCKET_NAME: 스토리지 버킷 이름

Google Cloud 리소스 만들기 및 구성

다음 안내에 따라 필요한 리소스를 만듭니다.

GKE 클러스터 및 노드 풀 만들기

TPU를 활용하여 GKE Autopilot 또는 Standard 클러스터에서 Gemma를 제공할 수 있습니다. GKE 관리 DRANET은 분산 포드의 고성능 네트워킹 리소스를 동적으로 요청하고 관리하므로 GKE는 수동 VPC 설정 없이 가속기 상호 통신을 위한 보조 고속 네트워크를 자동으로 프로비저닝할 수 있습니다.

Autopilot

  1. Cloud Shell에서 Autopilot 클러스터를 만듭니다.

    gcloud container clusters create-auto ${CLUSTER_NAME} \
    --project=${PROJECT_ID} \
    --enable-ray-operator \
    --location=${REGION}

  2. 클러스터와 통신하도록 kubectl을 구성합니다.

    gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${REGION}

  3. Autopilot 모드에서 GKE 관리 DRANET을 사용하려면 저장소에 제공된 커스텀 ComputeClass 리소스를 배포하여 동적 네트워킹을 선택하세요.

    apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: dranet-compute-class
spec:
  nodePoolAutoCreation:
    enabled: true
  nodePoolConfig:
    dra:
      networking:
        enabled: true
  priorities:
  - machineType: ct6e-standard-4t
    acceleratorNetworkProfile: auto

  4. 매니페스트를 클러스터에 적용합니다.

    kubectl apply -f ai-ml/gke-ray/rayserve/llm/tpu/networking/dranet-compute-class.yaml

표준

  1. Cloud Shell에서 Ray 연산자를 사용 설정하고 GKE Dataplane V2를 사용하는 Standard 클러스터를 만듭니다.

    gcloud container clusters create ${CLUSTER_NAME} \
    --project=${PROJECT_ID} \
    --addons=RayOperator,GcsFuseCsiDriver \
    --machine-type=n2-standard-8 \
    --enable-dataplane-v2 \
    --workload-pool=${PROJECT_ID}.svc.id.goog \
    --location=${ZONE}

  2. DRANET 드라이버를 사용 설정하여 멀티 호스트 TPU 슬라이스 노드 풀을 만듭니다.

    gcloud container node-pools create v6e-16 \
    --location=${ZONE} \
    --cluster=${CLUSTER_NAME} \
    --machine-type=ct6e-standard-4t \
    --tpu-topology=4x4 \
    --num-nodes=4 \
    --enable-gvnic \
    --scopes=https://www.googleapis.com/auth/cloud-platform \
    --accelerator-network-profile=auto \
    --node-labels=cloud.google.com/gke-networking-dra-driver=true

스토리지 및 인증 구성

Cloud Storage 버킷을 만들고 모델 로딩을 가속화하도록 Rapid Cache 인스턴스를 초기화한 후 Hugging Face의 인증을 구성합니다.

  1. TPU 영역에서 스토리지 버킷을 만들고 Rapid Cache 인스턴스를 초기화합니다.

    gcloud storage buckets create gs://${GS_BUCKET} --project=${PROJECT_ID} --default-storage-class=STANDARD --location=${REGION}

gcloud storage buckets anywhere-caches create gs://${GS_BUCKET} ${ZONE} \
    --ttl=1d \
    --admission-policy=ADMIT_ON_FIRST_MISS

  2. 가중치 버킷을 GKE 포드에 안전하게 마운트할 수 있도록 ID 링크를 구성합니다. 먼저 전용 IAM 서비스 계정을 만들고 버킷 읽기 권한을 부여합니다.

    gcloud iam service-accounts create ${GSA_NAME}

gcloud storage buckets add-iam-policy-binding gs://${GS_BUCKET} \
    --member="serviceAccount:${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/storage.objectAdmin"

  3. GKE용 워크로드 아이덴티티 제휴 바인딩을 만들고 Kubernetes ServiceAccount 객체에 주석을 추가합니다.

    gcloud iam service-accounts add-iam-policy-binding ${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com \
    --role="roles/iam.workloadIdentityUser" \
    --member="serviceAccount:${PROJECT_ID}.svc.id.goog[${NAMESPACE}/${KSA_NAME}]"

kubectl create serviceaccount ${KSA_NAME} --namespace ${NAMESPACE}
kubectl annotate serviceaccount ${KSA_NAME} --namespace ${NAMESPACE} iam.gke.io/gcp-service-account=${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

  4. Gemma 4 모델 가중치를 다운로드하려면 Hugging Face에서 Google의 라이선스 계약을 확인해야 합니다. Hugging Face의 Gemma 4 모델 페이지로 이동합니다.

  5. 동의 및 저장소 액세스를 클릭하여 라이선스 약관에 동의하고 로그인합니다.

  6. Hugging Face 계정 설정으로 이동하여 Read 역할이 있는 액세스 토큰을 생성합니다.

  7. Hugging Face 토큰을 내보내고 Ray가 모델 가중치를 가져올 수 있도록 Kubernetes 보안 비밀을 만듭니다.

    export HF_TOKEN=YOUR_HUGGING_FACE_TOKEN

kubectl create secret generic hf-secret \
  --from-literal=hf_api_token=${HF_TOKEN}

커스텀 컨테이너 이미지 빌드

멀티 호스트 환경에 필요한 종속 항목이 모두 있는지 확인하려면 vLLM의 TPU 이미지를 기반으로 커스텀 이미지를 빌드하고 서빙 스크립트를 여기에 복사하세요.

  1. Artifact Registry 저장소를 만듭니다.

    gcloud artifacts repositories create ${REPO_NAME} \
    --repository-format=docker \
    --location=${REGION}

  2. 프로젝트에 Docker를 인증합니다.

    gcloud auth configure-docker ${REGION}-docker.pkg.dev

  3. 샘플 저장소에서 Dockerfile를 검사합니다.

    FROM vllm/vllm-tpu:v0.21.0

ENV VLLM_TARGET_DEVICE=tpu
ENV VLLM_XLA_CACHE_PATH=/data

USER root

RUN pip install --no-cache-dir -U \
    "https://s3-us-west-2.amazonaws.com/ray-wheels/master/75b85027a859439fae5634e49aa6443f6fbecfeb/ray-3.0.0.dev0-cp312-cp312-manylinux2014_x86_64.whl" && \
    pip install --no-cache-dir --no-deps "ray[llm]"

COPY serve_tpu_multihost.py /home/ray/serve_tpu_multihost.py

  4. 이미지를 빌드하고 Artifact Registry에 푸시합니다.

    docker build -t ${CUSTOM_IMAGE_URI} .
docker push ${CUSTOM_IMAGE_URI}

Cloud Storage에 모델 가중치 사전 스테이징

RayCluster를 배포하기 전에 독립형 Kubernetes 작업을 사용하여 Cloud Storage 버킷에 직접 모델 가중치를 사전 스테이징하여 모델 로드 성능을 최적화하고 분산 TPU 슬라이스 전반에서 고가용성을 보장하세요. 이 분리된 접근 방식을 사용하면 조정된 병렬 스트리밍이 가능하여 클러스터 시작 시간이 단축됩니다.

  1. 다운로더 작업의 매니페스트는 저장소에서 확인할 수 있습니다. 매니페스트 구성을 검토합니다.

    apiVersion: batch/v1
kind: Job
metadata:
  name: model-downloader
spec:
  ttlSecondsAfterFinished: 60
  template:
    metadata:
      annotations:
        gke-gcsfuse/volumes: "true"
        gke-gcsfuse/memory-limit: "0"
    spec:
      serviceAccountName: ${KSA_NAME}
      restartPolicy: OnFailure
      containers:
      - name: downloader
        image: python:3.10-slim
        command: ["/bin/sh", "-c"]
        args:
        - |
          pip install -U huggingface_hub filelock

          python -c '
          import filelock

          class DummyLock:
              def __init__(self, *args, **kwargs): pass
              def __enter__(self): return self
              def __exit__(self, *args): pass
              def acquire(self, *args, **kwargs): pass
              def release(self, *args, **kwargs): pass

          filelock.FileLock = DummyLock

          from huggingface_hub import snapshot_download
          snapshot_download(
              repo_id="google/gemma-4-31B-it", 
              local_dir="/data/google/gemma-4-31B-it"
          )
          '
        env:
        - name: HF_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: ${GS_BUCKET}
            mountOptions: "implicit-dirs"

  2. 저장소의 파일을 적용하여 다운로더 작업을 만듭니다.

    envsubst < ai-ml/gke-ray/rayserve/llm/tpu/components/model-downloader-job.yaml | kubectl apply -f -

  3. 다운로드 스트림이 성공을 보고할 때까지 작업을 모니터링합니다.

    kubectl logs -f job/model-downloader

추론 스크립트 만들기

다음 Python 스크립트는 Ray Serve의 상위 수준 LLMConfig 래퍼로 구동되는 Ray Serve 애플리케이션을 정의합니다.

  1. 샘플 저장소에서 serve_tpu_multihost.py 스크립트를 검사합니다.

    import os
import ray
from ray import serve
from ray.serve.llm import LLMConfig, ModelLoadingConfig, LLMServingArgs, build_openai_app

# Read configurations from environment variables
MODEL_ID = os.environ.get("MODEL_ID", "google/gemma-4-31B-it")
MODEL_SOURCE = os.environ.get("MODEL_SOURCE", "/data/google/gemma-4-31B-it")

# TPU hardware options (i.e. TPU-V6E, TPU-V7X etc.)
ACCELERATOR_TYPE = os.environ.get("ACCELERATOR_TYPE", "TPU-V6E")
TPU_TOPOLOGY = os.environ.get("TPU_TOPOLOGY", "4x4")

# vLLM engine parameters
TENSOR_PARALLEL_SIZE = int(os.environ.get("TENSOR_PARALLEL_SIZE", "16"))
MAX_MODEL_LEN = int(os.environ.get("MAX_MODEL_LEN", "8192"))
MAX_NUM_BATCHED_TOKENS = int(os.environ.get("MAX_NUM_BATCHED_TOKENS", "4096"))

# Define the multi-host TPU LLM config
llm_config = LLMConfig(
    model_loading_config=dict(
        model_id=MODEL_ID,
        model_source=MODEL_SOURCE
    ),
    accelerator_type=ACCELERATOR_TYPE,
    accelerator_config={"kind": "tpu", "topology": TPU_TOPOLOGY},
    engine_kwargs={
        "tensor_parallel_size": TENSOR_PARALLEL_SIZE,
        "max_model_len": MAX_MODEL_LEN,
        "max_num_batched_tokens": MAX_NUM_BATCHED_TOKENS,
        "distributed_executor_backend": "ray",
    }
)

deployment = build_openai_app(
    LLMServingArgs(
        llm_configs=[llm_config]
    )
)

Ray LLM API 이해

이 스크립트는 Ray Serve의 기본 ray.serve.llm 라이브러리를 활용하여 멀티 호스트 TPU 오케스트레이션의 복잡성을 추상화합니다. vLLM 엔진을 래핑하여 Ray Serve LLM은 프로덕션에서 고도로 분산된 추론 워크로드를 위해 특별히 설계된 확장 가능한 고성능 프레임워크를 제공합니다.

Ray LLM API를 사용하면 다음과 같은 몇 가지 주요 이점이 있습니다.

  • 다중 노드 배포: Ray Serve LLM을 사용하면 사용자가 TPU 멀티 호스트 슬라이스와 같은 여러 분산 호스트에 걸쳐 있는 대규모 모델을 자동 배치, 조정, 토폴로지 분산을 통해 기본적으로 제공할 수 있습니다.
  • vLLM 호환성: Ray Serve LLM은 vLLM 서버와 호환되는 OpenAI 호환 API를 제공합니다. Kubernetes 클러스터에서 워크로드를 확장하는 동안 vLLM의 고급 기능 세트 (예: 구조화된 출력, 멀티모달 기능, 추론 모델)에 액세스할 수도 있습니다.
  • 프로덕션 준비 기능: Ray Serve LLM에는 내장 자동 확장, 캐시 적중률을 극대화하는 맞춤 요청 라우팅, 측정항목 및 모니터링 가능성을 위한 내장 통합과 같은 엔터프라이즈급 기능이 포함되어 있습니다.

제공된 추론 스크립트에서 배포는 두 가지 주요 구성요소로 정의됩니다.

  • LLMConfig: 이 객체는 서빙 구성을 정의합니다. 모델 소스, vLLM의 엔진 매개변수, accelerator_config을 지정합니다. {"kind": "tpu", "topology": "4x4"}를 설정하면 Ray Serve LLM이 실제 16칩 TPU v6e 슬라이스에 정확하게 매핑되는 분산 게재위치 그룹을 자동으로 프로비저닝합니다.
  • build_openai_app: 이 API는 구성된 vLLM 엔진을 OpenAI 호환 FastAPI 서버에 자동으로 래핑하여 맞춤 서버 코드를 작성하지 않고도 즉시 업계 표준 REST API (예: /v1/chat/completions)를 제공합니다.

RayService 배포

동적 리소스 할당 (DRA) 네트워킹 구성과 RayService 서빙 매니페스트를 배포합니다.

  1. 저장소에 제공된 ResourceClaimTemplate를 배포하여 각 노드에서 사용 가능한 모든 NetDevice 인터페이스를 요청합니다.

    apiVersion: resource.k8s.io/v1
kind: ResourceClaimTemplate
metadata:
  name: all-netdev
spec:
  spec:
    devices:
      requests:
      - name: req-netdev
        exactly:
          deviceClassName: netdev.google.com
          allocationMode: All

  2. 템플릿 매니페스트를 클러스터에 적용합니다.

    kubectl apply -f ai-ml/gke-ray/rayserve/llm/tpu/networking/all-netdev-template.yaml

  3. RayService 제공 매니페스트는 저장소에서 사용할 수 있습니다. 매니페스트 구성을 검토합니다.

    apiVersion: ray.io/v1
kind: RayService
metadata:
  name: vllm-tpu-multihost
  labels:
    ai.gke.io/model: "gemma-4-31B-it"
    ai.gke.io/inference-server: "vllm"
spec:
  serveConfigV2: |
    http_options:
      host: 0.0.0.0
      port: 8000
    applications:
      - name: llm
        import_path: ai-ml.gke-ray.rayserve.llm.tpu.serve_tpu_multihost:deployment
        runtime_env:
          working_dir: "https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/archive/main.zip"
          env_vars:
            # Use local disk to prevent multi-host GCSFuse race conditions
            VLLM_XLA_CACHE_PATH: "/tmp/vllm_xla_cache"
  rayClusterConfig:
    headGroupSpec:
      rayStartParams: {}
      template:
        metadata:
          annotations:
            gke-gcsfuse/volumes: "true"
            gke-gcsfuse/cpu-limit: "0"
            gke-gcsfuse/memory-limit: "0"
            gke-gcsfuse/ephemeral-storage-limit: "0"
        spec:
          serviceAccountName: $KSA_NAME
          containers:
          - name: ray-head
            image: $CUSTOM_IMAGE_URI
            imagePullPolicy: Always
            ports:
            - containerPort: 6379
              name: gcs
            - containerPort: 8265
              name: dashboard
            - containerPort: 10001
              name: client
            - containerPort: 8000
              name: serve
            resources:
              limits:
                cpu: "2"
                memory: 16Gi
              requests:
                cpu: "2"
                memory: 16Gi
            volumeMounts:
            - name: dshm
              mountPath: /dev/shm
            - name: gcs-fuse-csi-ephemeral
              mountPath: /data
          volumes:
          - name: dshm
            emptyDir:
              medium: Memory
          - name: gke-gcsfuse-cache
            emptyDir:
              medium: Memory
          - name: gcs-fuse-csi-ephemeral
            csi:
              driver: gcsfuse.csi.storage.gke.io
              volumeAttributes:
                bucketName: $GS_BUCKET
                mountOptions: "implicit-dirs"
    workerGroupSpecs:
    - groupName: tpu-group
      replicas: 1
      minReplicas: 1
      maxReplicas: 1
      numOfHosts: 4
      rayStartParams: {}
      template:
        metadata:
          annotations:
            gke-gcsfuse/volumes: "true"
            gke-gcsfuse/cpu-limit: "0"
            gke-gcsfuse/memory-limit: "0"
            gke-gcsfuse/ephemeral-storage-limit: "0"
        spec:
          serviceAccountName: $KSA_NAME
          containers:
            - name: ray-worker
              image: $CUSTOM_IMAGE_URI
              imagePullPolicy: Always
              resources:
                limits:
                  cpu: "20"
                  google.com/tpu: "4"
                  memory: 200Gi
                requests:
                  cpu: "20"
                  google.com/tpu: "4"
                  memory: 200Gi
                claims:
                - name: netdev
              env:
                - name: HF_HOME
                  value: "/data/huggingface"
                - name: HF_TOKEN
                  valueFrom:
                    secretKeyRef:
                      name: hf-secret
                      key: hf_api_token
                - name: JAX_PLATFORMS
                  value: "tpu,cpu"
                - name: NODE_IP
                  valueFrom:
                    fieldRef:
                      fieldPath: status.hostIP
                - name: VBAR_CONTROL_SERVICE_URL
                  value: $(NODE_IP):8353
                - name: TPU_MULTIHOST_BACKEND
                  value: "ray"
                - name: TPU_BACKEND_TYPE
                  value: "jax"
                - name: ENABLE_PJRT_COMPATIBILITY
                  value: "true"
              volumeMounts:
              - name: dshm
                mountPath: /dev/shm
              - name: gcs-fuse-csi-ephemeral
                mountPath: /data
          volumes:
          - name: dshm
            emptyDir:
              medium: Memory
          - name: gke-gcsfuse-cache
            emptyDir:
              medium: Memory
          - name: gcs-fuse-csi-ephemeral
            csi:
              driver: gcsfuse.csi.storage.gke.io
              volumeAttributes:
                bucketName: $GS_BUCKET
                mountOptions: "implicit-dirs"
          resourceClaims:
            - name: netdev
              resourceClaimTemplateName: all-netdev
          nodeSelector:
            cloud.google.com/gke-tpu-accelerator: tpu-v6e-slice
            cloud.google.com/gke-tpu-topology: 4x4

  4. 매니페스트를 사용하여 서비스를 배포합니다.

    Autopilot

    1. Autopilot 클러스터에 서비스를 배포하려면 먼저 매니페스트를 다운로드하고 로컬로 수정하여 Autopilot에서 DRANET 네트워킹에 필요한 선택 ComputeClass nodeSelector를 추가해야 합니다.

      curl -O https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes-engine-samples/main/ai-ml/gke-ray/rayserve/llm/tpu/ray-service.tpu-v6e-multihost.yaml

    2. 다음과 같이 nodeSelector 필드 아래에 라벨을 추가합니다.

      nodeSelector:
  cloud.google.com/gke-tpu-accelerator: tpu-v6e-slice
  cloud.google.com/gke-tpu-topology: 4x4
  cloud.google.com/compute-class: dranet-compute-class

    3. 그런 다음 수정된 로컬 매니페스트를 사용하여 서비스를 배포합니다.

      envsubst < ray-service.tpu-v6e-multihost.yaml | kubectl apply -f -

    표준

    표준 클러스터에 서비스를 배포하려면 저장소에서 직접 매니페스트를 배포하세요.

    envsubst < ai-ml/gke-ray/rayserve/llm/tpu/ray-service.tpu-v6e-multihost.yaml | kubectl apply -f -

인증

  1. RayService를 사용할 수 있을 때까지 기다립니다.

    kubectl wait --for=condition=Ready --timeout=1800s rayservice/vllm-tpu-multihost

  2. 모델이 성공적으로 로드되었는지 확인하려면 Ray 헤드 포드의 로그를 확인하세요.

    kubectl logs -f -l ray.io/node-type=head -c ray-head

모델 제공

이 섹션에서는 모델과 상호작용합니다. 계속 진행하기 전에 모델이 완전히 다운로드되었는지 확인합니다.

포트 전달 설정

다음 명령어를 실행하여 모델에 대한 포트 전달을 설정합니다.

kubectl port-forward svc/vllm-tpu-multihost-head-svc 8000:8000 2>&1 >/dev/null &

curl을 사용하여 모델과 상호작용

이 섹션에서는 기본 스모크 테스트를 수행하여 배포된 Gemma 4 모델을 확인하는 방법을 보여줍니다.

새 터미널 세션에서 curl을 사용해서 모델과 채팅합니다.

curl -X POST http://127.0.0.1:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "google/gemma-4-31B-it",
        "messages": [
            {
              "role": "user",
              "content": "Why is GKE managed DRANET preferred for multi-host TPU networking?"
            }
        ],
        "max_tokens": 256
    }'

결과는 다음과 유사합니다.

{
  "id": "chatcmpl-392692d3-5325-4832-a3a3-0b084c1045b0",
  "object": "chat.completion",
  "created": 1779883255,
  "model": "google/gemma-4-31B-it",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "To understand why GKE-managed **DRANET** (Distributed RANET) is preferred for multi-host TPU networking, it is first necessary to understand the fundamental challenge of TPU pods: **the need for massive, low-latency, all-to-all communication.**\n\nWhen you scale a model across multiple TPU hosts (multi-host), the hosts must synchronize gradients and weights constantly. Standard TCP/IP networking introduces too much overhead (latency and CPU jitter) for these operations.\n\nHere is the detailed breakdown of why GKE-managed DRANET is the preferred architecture:\n\n### 1. Bypassing the Kernel (Zero-Copy Networking)\nStandard networking requires the operating system kernel to handle packets, moving data from the network card to kernel space and then to user space.\n*   **The DRANET Advantage:** DRANET implements a specialized networking stack that allows for **Kernel Bypass**. It enables the TPU hardware/drivers to write data directly into the memory of the destination host. This reduces latency and eliminates the CPU overhead associated with processing network interrupts.\n\n### 2. High-Bandwidth, Low-Latency Interconnect\nMulti-host TPU training relies on a specialized topology (like a 2D or 3D"
      },
      "finish_reason": "length"
    }
  ]
}

(선택사항) GRadio 채팅 인터페이스를 통해 모델과 상호작용

이 섹션에서는 명령 조정 모델과 상호작용할 수 있는 웹 채팅 애플리케이션을 빌드합니다.

Gradio는 챗봇용 사용자 인터페이스를 만드는 ChatInterface 래퍼가 있는 Python 라이브러리입니다.

채팅 인터페이스 배포

채팅 인터페이스의 매니페스트는 저장소에서 확인할 수 있습니다. 매니페스트 구성을 검토합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gradio
  labels:
    app: gradio
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gradio
  template:
    metadata:
      labels:
        app: gradio
    spec:
      containers:
      - name: gradio
        image: us-docker.pkg.dev/google-samples/containers/gke/gradio-app:v1.0.7
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"
        env:
        - name: CONTEXT_PATH
          value: "/v1/chat/completions"
        - name: HOST
          value: "http://vllm-tpu-multihost-serve-svc:8000"
        - name: LLM_ENGINE
          value: "openai-chat"
        - name: MODEL_ID
          value: "google/gemma-4-31B-it"
        - name: DISABLE_SYSTEM_MESSAGE
          value: "true"
        ports:
        - containerPort: 7860
---
apiVersion: v1
kind: Service
metadata:
  name: gradio
spec:
  selector:
    app: gradio
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 7860
  type: ClusterIP

매니페스트를 적용합니다.

kubectl apply -f ai-ml/gke-ray/rayserve/llm/tpu/components/gradio.yaml

배포를 사용할 수 있을 때까지 기다립니다.

kubectl wait --for=condition=Available --timeout=900s deployment/gradio

채팅 인터페이스 사용

Cloud Shell에서 다음 명령어를 실행합니다.

kubectl port-forward service/gradio 8080:8080

이렇게 하면 Cloud Shell에서 Gradio 서비스로의 포트 전달이 생성됩니다.

Cloud Shell 작업 표시줄의 오른쪽 상단에 있는 웹 미리보기 아이콘 웹 미리보기 버튼을 클릭합니다. 포트 8080에서 미리보기를 클릭합니다. 브라우저에 새 탭이 열립니다.

GRadio 채팅 인터페이스를 사용하여 Gemma와 상호작용합니다. 프롬프트를 추가하고 제출을 클릭합니다.

모델 성능 관찰

KubeRay에서 실행되는 모델의 관측 가능성 측정항목 대시보드를 보려면 전용 GKE 기반 Ray 대시보드를 사용하면 됩니다.

클러스터를 구성하고 관측 가능성 대시보드에 액세스하는 방법에 관한 자세한 안내는 Google Kubernetes Engine (GKE)의 RayCluster에 대한 로그 및 측정항목 수집 및 보기를 참고하세요.

Ray 대시보드 액세스

Ray 행위자의 상태를 검사하고, 자세한 애플리케이션 로그를 확인하고, Ray에서 기본적으로 노드 수준 사용률을 모니터링하려면 Ray 대시보드에 액세스하면 됩니다.

  1. Ray 헤드 노드 서비스를 로컬 머신으로 포트 전달합니다.

    kubectl port-forward svc/vllm-tpu-multihost-head-svc 8265:8265

  2. 브라우저를 열고 http://localhost:8265로 이동합니다. Cloud Shell을 사용하는 경우 웹 미리보기 버튼을 클릭하고 포트 8265에서 미리보기를 선택합니다.

  3. vLLM 배포, 모델 복제본 상태, 쿼리 지연 시간을 보려면 제공 탭을 클릭합니다.

삭제

이 튜토리얼에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 리소스를 삭제하세요.

  1. RayService를 삭제합니다.

    kubectl delete rayservice vllm-tpu-multihost

  2. GKE 클러스터를 삭제합니다.

    gcloud container clusters delete ${CLUSTER_NAME} --zone=${ZONE}

다음 단계