vLLM과 함께 GKE에서 GPU를 사용하여 Gemma 개방형 모델 제공

Autopilot Standard

GPU를 사용하여 vLLM 프레임워크와 함께 Google Kubernetes Engine (GKE)에서 Gemma 4 대규모 언어 모델 (LLM)을 제공하려면 NVIDIA B200, H100, RTX Pro 6000 또는 L4 GPU와 같은 지원되는 가속기로 GKE 클러스터를 프로비저닝해야 합니다.

Gemma 4 모델 가중치를 가져오려면 사전 빌드된 vLLM 컨테이너가 Hugging Face 저장소에서 다운로드하도록 구성하면 됩니다. 또는 컨테이너가 Google Cloud Managed Lustre 인스턴스에 Cloud Storage 모델 버킷을 캐싱하는 등 기존 영구 스토리지에서 모델 가중치를 로드할 수 있습니다.

가중치가 로드되면 vLLM 컨테이너는 처리량이 높은 추론을 위해 OpenAI 호환 API 엔드포인트를 노출합니다.

이 튜토리얼은 H200, H100, A100, L4 GPU 하드웨어에서 AI/ML 워크로드를 서빙하기 위해 Kubernetes의 컨테이너 조정 기능을 활용하고자 하는 머신러닝(ML) 엔지니어, 플랫폼 관리자 및 운영자, 데이터 및 AI 전문가를 대상으로 합니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참조하세요.

ML 모델을 비용 효율적으로 빠르게 빌드하고 서빙할 수 있도록 설계된 통합 관리형 AI 플랫폼이 필요한 경우 Vertex AI 솔루션을 사용하는 것이 좋습니다.

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

배경

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

GPU

GPU를 사용하면 머신러닝 및 데이터 처리와 같이 노드에서 실행되는 특정 워크로드를 가속화할 수 있습니다. GKE는 NVIDIA H200, H100, L4, A100 GPU가 있는 머신 유형을 포함하여 노드 구성에 사용되는 다양한 머신 유형 옵션을 제공합니다.

vLLM

vLLM은 GPU의 서빙 처리량을 늘릴 수 있는 고도로 최적화된 오픈소스 LLM 서빙 프레임워크로, 다음과 같은 기능을 제공합니다.

PagedAttention으로 최적화된 Transformer구현
전체 서빙 처리량을 개선하기 위한 연속적인 작업 일괄 처리
여러 GPU에서 텐서 동시 로드 및 분산 서빙

자세한 내용은 vLLM 문서를 참조하세요.

목표

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

Autopilot 또는 Standard 모드의 GKE 클러스터로 환경을 준비합니다.
클러스터에 vLLM 컨테이너를 배포합니다.
vLLM을 사용하여 curl 및 웹 채팅 인터페이스를 통해 Gemma 4 모델을 제공합니다.

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

프로젝트에 다음 역할이 있는지 확인합니다. roles/container.admin, roles/iam.serviceAccountAdmin
역할 확인
1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
  IAM으로 이동
2. 프로젝트를 선택합니다.
3. 주 구성원 열에서 나 또는 내가 속한 그룹을 식별하는 모든 행을 찾습니다. 내가 속한 그룹을 알아보려면 관리자에게 문의하세요.
4. 나를 지정하거나 포함하는 모든 행의 역할 열을 확인하여 역할 목록에 필요한 역할이 포함되어 있는지 확인합니다.
역할 부여
1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
  IAM으로 이동
2. 프로젝트를 선택합니다.
3. 액세스 권한 부여를 클릭합니다.
4. 새 주 구성원 필드에 사용자 식별자를 입력합니다. 일반적으로 Google 계정의 이메일 주소입니다.
5. 역할 선택을 클릭한 후 역할을 검색합니다.
6. 역할을 추가로 부여하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.
7. 저장을 클릭합니다.

프로젝트에 L4 GPU 할당량이 충분한지 확인합니다. 자세한 내용은 GPU 정보 및 배정 할당량을 참조하세요.

개발 환경 준비

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

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

Google Cloud 콘솔의 경우 Google Cloud 콘솔에서 Cloud Shell 활성화를 클릭하여 Cloud Shell 세션을 시작합니다. 그러면 Google Cloud 콘솔 하단 창에서 세션이 실행됩니다.
기본 환경 변수를 설정합니다.
```
gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export REGION=REGION
export ZONE=ZONE
export CLUSTER_NAME=CLUSTER_NAME
```
다음 값을 바꿉니다.
- PROJECT_ID: Google Cloud프로젝트 ID
- REGION: 사용하려는 가속기 유형을 지원하는 리전(예: L4 GPU의 경우 us-central1) 어떤 리전에서 어떤 GPU를 사용할 수 있는지 확인할 수 있습니다.
- ZONE: 사용하려는 가속기 유형을 지원하는 영역(예: RTX PRO 6000 GPU의 경우 us-central1-b 및 us-central1-f) 어떤 영역에서 어떤 GPU를 사용할 수 있는지 확인할 수 있습니다.
- CLUSTER_NAME: 클러스터 이름입니다.

Google Cloud 리소스 만들기 및 구성

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

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

GPU를 활용하여 GKE Autopilot 또는 Standard 클러스터에서 Gemma를 제공할 수 있습니다. 완전 관리형 Kubernetes 환경을 위해서는 Autopilot을 사용하는 것이 좋습니다. 워크로드에 가장 적합한 GKE 작업 모드를 선택하려면 GKE 작업 모드 선택을 참조하세요.

Autopilot

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

gcloud container clusters create-auto CLUSTER_NAME \
    --project=PROJECT_ID \
    --location=CONTROL_PLANE_LOCATION \
    --release-channel=rapid

다음 값을 바꿉니다.

PROJECT_ID: Google Cloud프로젝트 ID
CONTROL_PLANE_LOCATION: 클러스터의 컨트롤 플레인에 대한 Compute Engine 리전입니다. 사용하려는 가속기 유형을 지원하는 리전을 제공합니다(예: L4 GPU의 경우 us-central1).
CLUSTER_NAME: 클러스터 이름입니다.

GKE는 배포된 워크로드의 요청에 따라 CPU 및 GPU 노드를 사용하여 Autopilot 클러스터를 만듭니다.

Standard

Cloud Shell에서 다음 명령어를 실행하여 Standard 클러스터를 만듭니다.
```
gcloud container clusters create CLUSTER_NAME \
    --project=PROJECT_ID \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --release-channel=rapid \
    --num-nodes=1
```
다음 값을 바꿉니다.
- PROJECT_ID: Google Cloud프로젝트 ID
- CONTROL_PLANE_LOCATION: 클러스터의 컨트롤 플레인에 대한 Compute Engine 리전입니다. 사용하려는 가속기 유형을 지원하는 리전을 제공합니다(예: L4 GPU의 경우 us-central1).
- CLUSTER_NAME: 클러스터 이름입니다.
클러스터 만들기는 몇 분 정도 걸릴 수 있습니다.

적절한 디스크 크기로 클러스터에 노드 풀을 생성하려면 다음 명령어를 실행합니다.

  gcloud container node-pools create gpupool \
      --accelerator type=nvidia-rtx-pro-6000,count=1,gpu-driver-version=latest \
      --project=PROJECT_ID \
      --location=REGION \
      --node-locations=ZONE \
      --cluster=CLUSTER_NAME \
      --machine-type=g4-standard-48 \
      --num-nodes=1

GKE는 RTX PRO가 포함된 단일 노드 풀을 만듭니다. 각 노드에 6,000개의 GPU

Hugging Face 가중치를 사용하여 vLLM에 Gemma 4 모델 배포

Hugging Face 가중치를 사용하여 Gemma 4 모델을 배포하려면 선택한 모델 크기에 맞는 Kubernetes 배포 매니페스트를 적용하세요. 배포는 클러스터에서 노드 간에 배포되는 여러 포드 복제본을 실행할 수 있는 Kubernetes API 객체입니다.

절차

이 매니페스트를 적용하면 vLLM 컨테이너 이미지가 풀링되고, NVIDIA GPU가 요청되며, Hugging Face에서 가중치가 자동으로 다운로드되어 vLLM 추론 엔진이 시작됩니다.

Gemma 4 E2B-it

다음 안내에 따라 Gemma 4 E2B 명령 조정 모델을 배포합니다 (텍스트 전용 입력).

다음 vllm-4-e2b-it.yaml 매니페스트를 만듭니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gemma-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-4-e2b-it
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4
        resources:
          requests:
            cpu: "2"
            memory: "10Gi"
            ephemeral-storage: "10Gi"
            nvidia.com/gpu: "1"
          limits:
            cpu: "2"
            memory: "10Gi"
            ephemeral-storage: "10Gi"
            nvidia.com/gpu: "1"
        command: ["python3", "-m", "vllm.entrypoints.api_server"]
        args:
          - --model=$(MODEL_ID)
          - --host=0.0.0.0
          - --port=8000
          - --tensor-parallel-size=1
          - --enable-log-requests
          - --enable-chunked-prefill
          - --enable-prefix-caching
          - --enable-auto-tool-choice
          - --generation-config=auto
          - --tool-call-parser=gemma4
          - --dtype=bfloat16
          - --max-num-seqs=16
          - --max-model-len=32768
          - --gpu-memory-utilization=0.95
          - --reasoning-parser=gemma4
          - --trust-remote-code
        env:
        - name: LD_LIBRARY_PATH
          value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
        - name: MODEL_ID
          value: google/gemma-4-E2B-it
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-rtx-pro-6000
        cloud.google.com/gke-gpu-driver-version: latest
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000

매니페스트를 적용합니다.
```
kubectl apply -f vllm-4-e2b-it.yaml
```

Gemma 4 E4B-it

다음 안내에 따라 Gemma 4 E4B 명령 조정 모델을 배포합니다.

다음 vllm-4-e4b-it.yaml 매니페스트를 만듭니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gemma-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-4-e4b-it
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4
        resources:
          requests:
            cpu: "4"
            memory: "20Gi"
            ephemeral-storage: "20Gi"
            nvidia.com/gpu: "1"
          limits:
            cpu: "4"
            memory: "20Gi"
            ephemeral-storage: "20Gi"
            nvidia.com/gpu: "1"
        command: ["python3", "-m", "vllm.entrypoints.api_server"]
        args:
          - --model=$(MODEL_ID)
          - --host=0.0.0.0
          - --port=8000
          - --tensor-parallel-size=1
          - --enable-log-requests
          - --enable-chunked-prefill
          - --enable-prefix-caching
          - --enable-auto-tool-choice
          - --generation-config=auto
          - --tool-call-parser=gemma4
          - --dtype=bfloat16
          - --max-num-seqs=16
          - --max-model-len=32768
          - --gpu-memory-utilization=0.95
          - --reasoning-parser=gemma4
          - --trust-remote-code
        env:
        - name: LD_LIBRARY_PATH
          value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
        - name: MODEL_ID
          value: google/gemma-4-E4b-it
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-rtx-pro-6000
        cloud.google.com/gke-gpu-driver-version: latest
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000

매니페스트를 적용합니다.
```
kubectl apply -f vllm-4-E4b-it.yaml
```
이 예시에서는 --max-model-len=32768 vLLM 옵션을 사용하여 컨텍스트 윈도우를 32K로 제한합니다. 더 큰 컨텍스트 윈도우 크기(최대 128K)를 원하는 경우 GPU 용량이 더 큰 매니페스트와 노드 풀 구성을 조정하세요.

Gemma 4 26B-A4B-it

다음 안내에 따라 Gemma 4 26B-A4B 명령 조정 모델을 배포합니다.

다음 vllm-4-26b-a4b-it.yaml 매니페스트를 만듭니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gemma-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-4-26b-a4b-it
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4
        resources:
          requests:
            cpu: "20"
            memory: "80Gi"
            ephemeral-storage: "80Gi"
            nvidia.com/gpu: "1"
          limits:
            cpu: "20"
            memory: "80Gi"
            ephemeral-storage: "80Gi"
            nvidia.com/gpu: "1"
        command: ["python3", "-m", "vllm.entrypoints.api_server"]
        args:
          - --model=$(MODEL_ID)
          - --host=0.0.0.0
          - --port=8000
          - --tensor-parallel-size=1
          - --enable-log-requests
          - --enable-chunked-prefill
          - --enable-prefix-caching
          - --enable-auto-tool-choice
          - --generation-config=auto
          - --tool-call-parser=gemma4
          - --dtype=bfloat16
          - --max-num-seqs=16
          - --max-model-len=16384
          - --gpu-memory-utilization=0.95
          - --reasoning-parser=gemma4
          - --trust-remote-code
        env:
        - name: LD_LIBRARY_PATH
          value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
        - name: MODEL_ID
          value: google/gemma-4-26B-A4B-it
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-rtx-pro-6000
        cloud.google.com/gke-gpu-driver-version: latest
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000

매니페스트를 적용합니다.
```
kubectl apply -f vllm-4-26b-a4b-it.yaml
```
이 예시에서는 --max-model-len=16384 vLLM 옵션을 사용하여 컨텍스트 윈도우 크기를 16K로 제한합니다. 더 큰 컨텍스트 윈도우 크기(최대 128K)를 원하는 경우 GPU 용량이 더 큰 매니페스트와 노드 풀 구성을 조정하세요.

Gemma 4 31B-it

다음 안내에 따라 Gemma 4 31B 명령 조정 모델을 배포합니다.

다음 vllm-4-31b-it.yaml 매니페스트를 만듭니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gemma-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-4-31b-it
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4
        resources:
          requests:
            cpu: "22"
            memory: "100Gi"
            ephemeral-storage: "80Gi"
            nvidia.com/gpu: "1"
          limits:
            cpu: "22"
            memory: "100Gi"
            ephemeral-storage: "80Gi"
            nvidia.com/gpu: "1"
        command: ["python3", "-m", "vllm.entrypoints.api_server"]
        args:
          - --model=$(MODEL_ID)
          - --host=0.0.0.0
          - --port=8000
          - --tensor-parallel-size=1
          - --enable-log-requests
          - --enable-chunked-prefill
          - --enable-prefix-caching
          - --enable-auto-tool-choice
          - --generation-config=auto
          - --tool-call-parser=gemma4
          - --dtype=bfloat16
          - --max-num-seqs=16
          - --max-model-len=16384
          - --gpu-memory-utilization=0.95
          - --reasoning-parser=gemma4
          - --trust-remote-code
        env:
        - name: LD_LIBRARY_PATH
          value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
        - name: MODEL_ID
          value: google/gemma-4-31B-it
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-rtx-pro-6000
        cloud.google.com/gke-gpu-driver-version: latest
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000

매니페스트를 적용합니다.
```
kubectl apply -f vllm-4-31b-it.yaml
```
이 예시에서는 --max-model-len=16384 vLLM 옵션을 사용하여 컨텍스트 윈도우 크기를 16K로 제한합니다. 더 큰 컨텍스트 윈도우 크기(최대 128K)를 원하는 경우 GPU 용량이 더 큰 매니페스트와 노드 풀 구성을 조정하세요.

인증

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

kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deployment

실행 중인 배포의 로그를 봅니다.

kubectl logs -f -l app=gemma-server

배포 리소스는 Gemma 모델 데이터를 다운로드합니다. 이 프로세스는 몇 분 정도 걸릴 수 있습니다. 출력은 다음과 비슷합니다.

  ...
  ...
  (APIServer pid=1) INFO:     Started server process [1]
  (APIServer pid=1) INFO:     Waiting for application startup.
  (APIServer pid=1) INFO:     Application startup complete.

Hugging Face 배포를 사용할 수 있게 되면 포트 전달을 설정하여 모델과 상호작용합니다.

Managed Lustre에서 미세 조정된 Gemma 배포

Google Cloud Managed Lustre 인스턴스에 이미 저장된 미세 조정된 Gemma 모델 (예: Gemma 3 27B)을 제공하려면 해당 PersistentVolumeClaim (PVC)를 vLLM 컨테이너에 마운트해야 합니다.

기본 요건

Lustre 인스턴스에 연결되는 기존 PVC가 GKE 클러스터에 있는지 확인합니다. 이 예시에서 PVC 이름은 gemma-lustre-pvc입니다.

기존 인스턴스에 대한 PVC 및 PersistentVolume (PV)을 만드는 방법을 알아보려면 기존 Managed Lustre 인스턴스 액세스를 참고하세요.

절차

다음 YAML 매니페스트를 vllm-lustre-gemma.yaml로 저장합니다. 이 예시에서 배포는 Lustre PVC를 /data에 마운트하고 vLLM에 해당 로컬 경로에서 모델 가중치를 로드하도록 지시합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gemma-lustre
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=/data/gemma-3-27b
        - --tensor-parallel-size=1
        resources:
          limits:
            nvidia.com/gpu: "1"
        volumeMounts:
        - name: model-weights
          mountPath: /data
      volumes:
      - name: model-weights
        persistentVolumeClaim:
          claimName: gemma-lustre-pvc
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-l4
        cloud.google.com/gke-gpu-driver-version: latest

매니페스트를 GKE 클러스터에 적용합니다.
```
kubectl apply -f vllm-lustre-gemma.yaml
```

인증

Lustre 볼륨에서 모델이 성공적으로 로드되었는지 확인하려면 vLLM 시작 시퀀스의 포드 로그를 확인하세요.

kubectl logs -l app=gemma-server

모델 제공

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

포트 전달 설정

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

kubectl port-forward service/llm-service 8000:8000

출력은 다음과 비슷합니다.

Forwarding from 127.0.0.1:8000 -> 8000

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

이 섹션에서는 기본 스모크 테스트를 수행하여 배포된 Gemma 4 명령 조정 모델을 확인하는 방법을 보여줍니다. 다른 모델의 경우 gemma-4-e4b-it를 해당 모델의 이름으로 바꿉니다.

이 예시에서는 Gemma 4 E4B 명령 조정 모델을 텍스트 전용 입력으로 테스트하는 방법을 보여줍니다.

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

curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
    "model": "google/gemma-4-26B-A4B-it",
    "messages": [
        {
          "role": "user",
          "content": "Why is the sky blue?"
        }
    ],
    "chat_template_kwargs": {
         "enable_thinking": true
    },
    "skip_special_tokens": false
}'

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

{
  "id": "chatcmpl-be75ccfcbdf753d1",
  "object": "chat.completion",
  "created": 1775006187,
  "model": "google/gemma-4-26B-A4B-it",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The short answer is a phenomenon called **Rayleigh scattering**.\n\nTo understand how it works, you have to look at three things: sunlight, the Earth's atmosphere, and how light travels.\n\n### 1. Sunlight is a Rainbow\nAlthough sunlight looks white to us, it is actually made up of all the colors of the rainbow (red, orange, yellow, green, blue, indigo, and violet). Light travels as **waves**, and each color has a different wavelength:\n*   **Red light** travels in long, lazy, wide waves.\n*   **Blue and violet light** travel in short, choppy, tight waves.\n\n### 2. The Atmosphere is an Obstacle Course\nEarth's atmosphere is filled with gases (mostly nitrogen and oxygen). As sunlight travels through the atmosphere, it strikes the molecules of these gases. \n\nBecause the gas molecules are very small, they affect the colors differently based on their wavelength:\n*   The **long waves** (reds and yellows) pass through the atmosphere mostly straight, without hitting much. They are like large ocean waves that roll right over small pebbles.\n*   The **short waves** (blues and violets) strike the gas molecules and get scattered in every direction. They are like small ripples that hit a pebble and splash everywhere.\n\nBecause this blue light is being scattered in every direction by the air, when you look up, your eyes are catching that scattered blue light coming from every part of the sky.\n\n### 3. Why isn't the sky violet?\nIf violet light has an even shorter wavelength than blue light, you might wonder why the sky doesn't look purple. There are two main reasons:\n1.  **The Sun's output:** The Sun emits much more blue light than violet light.\n2.  **Human Biology:** Human eyes are much more sensitive to blue than to violet. Our eyes interpret the scatter of mixed blue and violet light simply as pale blue.\n\n---\n\n### Bonus: Why are sunsets red?\nWhen the sun is setting, it is much lower on the horizon. This means the sunlight has to travel through a much **thicker** layer of the atmosphere to reach your eyes. \n\nBy the time the light gets to you, the blue light has been scattered away completely로. Only the long-wavelength colors—the reds, oranges, and pinks—are able to make it through that thick layer of air without being scattered away, creating the beautiful colors of a sunset.",
        "refusal": null,
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": [],
        "reasoning": "\"Why is the sky blue?\"\nScience/Physics (Atmospheric scattering).\nExplain the phenomenon clearly, accurately, and engagingly.\n\n    *   Sunlight (white light) is made of a spectrum of colors (ROYGBIV).\n    *   Earth's atmosphere is filled with gases (nitrogen, oxygen) and particles.\n    *   Rayleigh Scattering: Shorter wavelengths (blue/violet) scatter more easily than longer wavelengths (red/yellow) when hitting small gas molecules.\n    *   The human eye's sensitivity: Why isn't it violet?\n\n    A good scientific explanation should follow a logical flow:\n    *   *Direct Answer:* The core mechanism (Rayleigh Scattering).\n    *   *The Components:* Sunlight and the Atmosphere.\n    *   *The Mechanism:* How light interacts with gas molecules.\n    *   *The Wavelength Factor:* Comparing colors.\n    *   *The \"Wait, why not violet?\" question:* Addressing human perception.\n    *   *Bonus/Related concept:* Why sunsets are red.\n\n        *   Use the term **Rayleigh Scattering**.\n        *   Summarize: Its how sunlight interacts with the Earth's atmosphere.\n\n        *   Sunlight looks white, but it's actually a mix of all colors (the rainbow).\n        *   Each color travels as a different wavelength. Red = long/lazy waves; Blue/Violet = short/choppy waves.\n\n        *   The atmosphere is mostly Nitrogen and Oxygen.\n        *   When sunlight hits these tiny gas molecules, the light gets scattered in all directions.\n\n        *   Blue light travels in shorter, smaller waves.\n        *   Because these waves are small, they strike the gas molecules more frequently and get scattered more easily than the longer red/yellow waves.\n        *   Result: When you look up, your eyes are catching this \"scattered\" blue light coming from every direction.\n\n        *   *Technically*, violet light has an even shorter wavelength than blue, so it scatters *even more*. Why isn't the sky violet?\n        *   Two reasons: 1. The Sun emits more blue light than violet light. 2. Human eyes are much more sensitive to blue than violet.\n\n        *   Briefly mention sunsets to provide a complete picture.\n        *   At sunset, light travels through *more* atmosphere. The blue is scattered away completely, leaving only the long red/orange waves to reach your eyes.\n\n    *   *Tone Check:* Is it too academic? Use analogies (like waves in water or skipping stones) if needed, but keep it concise.\n    *   *Clarity:* Ensure the distinction between wavelength and scattering is clear."
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": 106,
      "token_ids": null
    }
  ],
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 21,
    "total_tokens": 1122,
    "completion_tokens": 1101,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null,
  "prompt_token_ids": null,
  "kv_transfer_params": null
}

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

이 섹션에서는 명령 조정 모델과 상호작용할 수 있는 웹 채팅 애플리케이션을 빌드합니다. 편의를 위해 이 섹션에서는 4B-it 모델을 사용한 테스트 접근 방식만 설명합니다.

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

채팅 인터페이스 배포

Cloud Shell에서 다음 매니페스트를 gradio.yaml로 저장합니다. google/gemma-4-E4B-it을 배포에 사용한 Gemma 4 모델 이름으로 변경합니다.

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://llm-service:8000"
        - name: LLM_ENGINE
          value: "openai-chat"
        - name: MODEL_ID
          value: "google/gemma-4-E4B-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 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와 상호작용합니다. 프롬프트를 추가하고 제출을 클릭합니다.

문제해결

Empty reply from server 메시지가 표시되면 컨테이너에서 모델 데이터 다운로드가 완료되지 않았을 수 있습니다. 모델을 제공할 준비가 되었음을 나타내는 Connected 메시지가 있는지 포드의 로그를 다시 확인합니다.
Connection refused가 표시되면 포트 전달이 활성 상태인지 확인합니다.

모델 성능 관찰

모델의 관측 가능성 측정항목 대시보드를 보려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 배포된 모델 페이지로 이동합니다.

배포된 모델로 이동
측정항목, 로그, 대시보드 등 특정 배포에 관한 세부정보를 보려면 목록에서 모델 이름을 클릭합니다.
모델 세부정보 페이지에서 관측 가능성 탭을 클릭하여 다음 대시보드를 확인합니다. 메시지가 표시되면 사용 설정을 클릭하여 클러스터의 측정항목 수집을 사용 설정합니다.
- 인프라 사용량 대시보드에는 사용률 측정항목이 표시됩니다.
- DCGM 대시보드에는 DCGM 측정항목이 표시됩니다.
- vLLM을 사용하는 경우 모델 성능 대시보드를 사용할 수 있으며 vLLM 모델 성능 측정항목이 표시됩니다.

Cloud Monitoring에 통합된 vLLM 대시보드에서 측정항목을 볼 수도 있습니다. 이러한 측정항목은 사전 설정된 필터 없이 모든 vLLM 배포에 대해 집계됩니다.

Cloud Monitoring에서 대시보드를 사용하려면 GKE 클러스터에서 Google Cloud Managed Service for Prometheus를 사용 설정해야 합니다. 이 서비스는 GKE 클러스터의 vLLM에서 측정항목을 수집합니다. vLLM은 기본적으로 Prometheus 형식으로 측정항목을 노출하므로, 별도의 내보내기 도구를 설치할 필요가 없습니다. Google Cloud Managed Service for Prometheus를 사용하여 모델에서 측정항목을 수집하는 방법은 Cloud Monitoring 문서의 vLLM 모니터링 가능성 가이드를 참고하세요.

삭제

이 튜토리얼에서 사용된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 리소스가 포함된 프로젝트를 삭제하거나 프로젝트를 유지하고 개별 리소스를 삭제하세요.

배포된 리소스 삭제

이 가이드에서 만든 리소스에 대해 Google Cloud 계정에 비용이 청구되지 않도록 하려면 다음 명령어를 실행합니다.

gcloud container clusters delete CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION