GKE에서 vLLM을 사용하여 Gemma 3 27B 추론 제공

이 튜토리얼에서는 vLLM 서빙 프레임워크를 사용하여 Gemma 3 27B 대규모 언어 모델 (LLM)을 배포하고 서빙하는 방법을 보여줍니다. Google Kubernetes Engine (GKE)의 단일 A4 가상 머신(VM) 인스턴스에 Gemma 3를 배포합니다.

이 튜토리얼은 추론 워크로드를 처리하기 위해 Kubernetes 컨테이너 조정 기능을 사용하는 데 관심이 있는 머신러닝 (ML) 엔지니어, 플랫폼 관리자 및 운영자, 데이터 및 AI 전문가를 대상으로 합니다.

목표

Hugging Face를 사용하여 Gemma 3에 액세스합니다.
환경을 준비합니다.
Autopilot 모드로 GKE 클러스터를 만듭니다.
Hugging Face 사용자 인증 정보용 Kubernetes 보안 비밀을 만듭니다.
GKE 클러스터에 vLLM 컨테이너를 배포합니다.
curl을 사용하여 Gemma 3와 상호작용합니다.
삭제

비용

이 가이드에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.

프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용합니다.

시작하기 전에

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

Google Cloud CLI를 설치합니다.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

Google Cloud 프로젝트를 만듭니다.
```
gcloud projects create PROJECT_ID
```
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.
생성한 Google Cloud 프로젝트를 선택합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

필요한 API를 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할 (roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

gcloud services enable container.googleapis.com

Google Cloud CLI를 설치합니다.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

Google Cloud 프로젝트를 만듭니다.
```
gcloud projects create PROJECT_ID
```
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.
생성한 Google Cloud 프로젝트를 선택합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

필요한 API를 사용 설정합니다.

API 사용 설정에 필요한 역할

gcloud services enable container.googleapis.com

사용자 계정에 역할을 부여합니다. 다음 IAM 역할마다 다음 명령어를 1회 실행합니다. roles/container.admin
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
```
다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID입니다.
- USER_IDENTIFIER: 사용자 계정의 식별자입니다. 예를 들면 myemail@example.com입니다.
- ROLE: 사용자 계정에 부여하는 IAM 역할입니다.
Hugging Face 계정에 로그인하거나 계정을 만듭니다.

Hugging Face를 사용하여 Gemma 3에 액세스

Hugging Face를 사용하여 Gemma 3에 액세스하려면 다음 단계를 따르세요.

Hugging Face에 로그인
Hugging Face read 액세스 토큰을 만듭니다. 내 프로필 > 설정 > 액세스 토큰 > +새 토큰 만들기를 클릭합니다.
read access 토큰 값을 복사하여 저장합니다. 이 주소는 이 튜토리얼의 뒷부분에서 사용됩니다.

개발 환경 준비

환경을 준비하려면 기본 환경 변수를 설정하세요.

gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export RESERVATION_URL=RESERVATION_URL
export REGION=REGION
export CLUSTER_NAME=CLUSTER_NAME
export HUGGING_FACE_TOKEN=HUGGING_FACE_TOKEN
export NETWORK=NETWORK_NAME
export SUBNETWORK=SUBNETWORK_NAME

다음을 바꿉니다.

PROJECT_ID: GKE 클러스터를 만들려는 Google Cloud 프로젝트의 ID입니다.
RESERVATION_URL: GKE 클러스터를 만드는 데 사용할 예약의 URL입니다. 예약이 있는 프로젝트에 따라 다음 값 중 하나를 지정합니다.
- 예약이 프로젝트에 있는 경우: RESERVATION_NAME
- 예약이 다른 프로젝트에 있고 내 프로젝트에서 예약을 사용할 수 있는 경우: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
REGION: GKE 클러스터를 만들 리전입니다. 예약이 있는 리전에서만 클러스터를 만들 수 있습니다.
CLUSTER_NAME: 만들려는 GKE 클러스터의 이름입니다.
HUGGING_FACE_TOKEN: 이전 섹션에서 만든 Hugging Face 액세스 토큰입니다.
NETWORK_NAME: GKE 클러스터가 사용하는 네트워크입니다. 다음 값 중 하나를 지정합니다.
- 커스텀 네트워크를 만든 경우 네트워크 이름을 지정합니다.
- 그렇지 않은 경우 default을 지정합니다.
SUBNETWORK_NAME: GKE 클러스터가 사용하는 서브네트워크입니다. 다음 값 중 하나를 지정합니다.
- 커스텀 하위 네트워크를 만든 경우 하위 네트워크의 이름을 지정합니다. 예약과 동일한 리전에 있는 서브네트워크만 지정할 수 있습니다.
- 그렇지 않은 경우 default을 지정합니다.

Autopilot 모드로 GKE 클러스터 만들기

Autopilot 모드로 GKE 클러스터를 만들려면 다음 명령어를 실행합니다.

gcloud container clusters create-auto $CLUSTER_NAME \
    --project=$PROJECT_ID \
    --region=$REGION \
    --release-channel=rapid \
    --network=$NETWORK \
    --subnetwork=$SUBNETWORK

GKE 클러스터를 만드는 데 다소 시간이 걸릴 수 있습니다. Google Cloud 에서 클러스터 생성을 완료했는지 확인하려면 Google Cloud 콘솔에서 Kubernetes 클러스터로 이동합니다.

Hugging Face 사용자 인증 정보용 Kubernetes 보안 비밀 만들기

Hugging Face 사용자 인증 정보용 Kubernetes 보안 비밀을 만들려면 다음 단계를 따르세요.

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

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

Hugging Face 토큰을 저장할 Kubernetes 보안 비밀을 만듭니다.

kubectl create secret generic hf-secret \
    --from-literal=hf_api_token=${HUGGING_FACE_TOKEN} \
    --dry-run=client -o yaml | kubectl apply -f -

GKE 클러스터에 vLLM 컨테이너 배포

Kubernetes 배포를 사용하여 Gemma 3 27B 모델을 제공하는 vLLM 컨테이너를 배포하려면 다음 단계를 따르세요.

선택한 vLLM 배포를 사용하여 vllm-3-27b-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-3-27b-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:20250801_0916_RC01
        resources:
          requests:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "120Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "120Gi"
            nvidia.com/gpu: "8"
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=$(MODEL_ID)
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=4096
        - --max-num-seqs=4
        env:
        - name: MODEL_ID
          value: google/gemma-3-27b-it
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 600
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 600
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: RESERVATION_URL
        cloud.google.com/reservation-affinity: "specific"
        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

GKE 클러스터에 vllm-3-27b-it.yaml 파일을 적용합니다.
```
kubectl apply -f vllm-3-27b-it.yaml
```
배포 프로세스 중에 컨테이너는 Hugging Face에서 Gemma 3를 다운로드해야 합니다. 따라서 컨테이너 배포를 완료하는 데 최대 30분이 걸릴 수 있습니다.

배포가 완료될 때까지 기다립니다.

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

curl을 사용하여 Gemma 3와 상호작용

배포된 Gemma 3 27B 명령 조정 모델을 확인하려면 다음 단계를 따르세요.

Gemma 3로의 포트 전달을 설정합니다.

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

새 터미널 창을 엽니다. 그런 다음 curl을 사용하여 모델과 채팅할 수 있습니다.

curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "google/gemma-3-27b-it",
  "messages": [
    {
      "role": "user",
      "content": "Why is the sky blue?"
    }
  ]
}'

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

{
  "id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
  "object": "chat.completion",
  "created": 1741763029,
  "model": "google/gemma-3-27b-it",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning_content": null,
        "content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
        "tool_calls": []
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": 106
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "total_tokens": 668,
    "completion_tokens": 653,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null
}

모델의 성능을 모니터링하려면 Cloud Monitoring의 vLLM 대시보드 통합을 사용하면 됩니다. 이 대시보드를 사용하면 토큰 처리량, 네트워크 지연 시간, 오류율과 같은 모델의 주요 성능 측정항목을 확인할 수 있습니다. 자세한 내용은 Monitoring 문서의 vLLM을 참고하세요.

삭제

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

프로젝트 삭제

주의: 프로젝트를 삭제하면 다음과 같은 효과가 발생합니다.

프로젝트의 모든 항목이 삭제됩니다. 이 문서의 태스크에 기존 프로젝트를 사용한 경우 프로젝트를 삭제하면 프로젝트에서 수행한 다른 작업도 삭제됩니다.
커스텀 프로젝트 ID가 손실됩니다. 이 프로젝트를 만들 때 앞으로 사용할 커스텀 프로젝트 ID를 만들었을 수 있습니다. appspot.com URL과 같이 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트를 삭제하는 대신 프로젝트 내에서 선택한 리소스만 삭제합니다.

여러 아키텍처, 튜토리얼 또는 빠른 시작을 살펴보려는 경우 프로젝트를 재사용하면 프로젝트 할당량 한도 초과를 방지할 수 있습니다.

Google Cloud 프로젝트를 삭제합니다.

gcloud projects delete PROJECT_ID

GKE 클러스터 삭제

GKE 클러스터를 삭제하려면 다음 명령어를 실행합니다.

gcloud container clusters delete $CLUSTER_NAME \
    --region=$REGION

yaml 파일 및 Kubernetes 보안 비밀 삭제

GKE 클러스터에서 vllm-3-27b-it.yaml 파일과 Kubernetes 보안 비밀을 삭제하려면 다음 명령어를 실행합니다.

kubectl delete -f vllm-3-27b-it.yaml
kubectl delete secret hf-secret

다음 단계

AI에 최적화된 GKE 클러스터 관리