vLLM을 사용하여 RTX 6000 Pro GPU가 있는 Cloud Run에서 Gemma 4 모델의 추론 실행

1. 소개

참고: 이 기능에는 서비스별 약관의 일반 서비스 약관 항에 있는 "GA 이전 제공 서비스 약관"이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요

개요

학습할 내용

• Cloud Run RTX 6000 Pro GPU에 Gemma 4 모델을 배포하는 방법
• 더 빠른 추론과 더 짧은 인스턴스 시작을 위해 vLLM 및 Run:ai Model Streamer를 사용하는 방법

참고: 이 Codelab에서는 Gemma 4 31B Instruction-Tuned 모델을 사용합니다. 이 Codelab에서는 Run:ai Model Streamer 및 직접 VPC 이그레스를 사용하여 컨테이너 시작 중에 Cloud Storage에서 모델을 로드하는 데 걸리는 시간을 최소화하는 방법을 보여줍니다. 자세한 내용은 GPU 권장사항 가이드를 참고하세요.

2. 설정 및 요구사항

이 Codelab 전체에서 사용할 환경 변수를 설정합니다.

# Model name on HuggingFace Hub
export MODEL_NAME="google/gemma-4-31B-it"

# Cloud Run Service name
export SERVICE_NAME=gemma-rtx-vllm-codelab

# Cloud Project and Region for Cloud Run
export GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID> # Change to your Project Id
export GOOGLE_CLOUD_REGION=us-central1 # or europe-west4

# Optional HuggingFace User Access Token for accessing model weights 
# (https://huggingface.co/docs/hub/en/security-tokens),
# if you are loading a private model.
export HF_TOKEN=""

# Service account for Cloud Run service
export SERVICE_ACCOUNT="vllm-service-sa"
export SERVICE_ACCOUNT_EMAIL="${SERVICE_ACCOUNT}@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com"

# GCS Bucket for the model cache.
export MODEL_CACHE_BUCKET="${GOOGLE_CLOUD_PROJECT}-${GOOGLE_CLOUD_REGION}-hf-model-cache"
# Model cache location in GSC bucket
export GCS_MODEL_LOCATION="gs://${MODEL_CACHE_BUCKET}/model-cache/${MODEL_NAME}"

# VPC Network for Direct VPC Egress
export VPC_NETWORK="vllm-${GOOGLE_CLOUD_REGION}-net"
export VPC_SUBNET="vllm-${GOOGLE_CLOUD_REGION}-subnet"
export SUBNET_RANGE="10.8.0.0/26"

# set the project
gcloud config set project $GOOGLE_CLOUD_PROJECT
gcloud config set run/region $GOOGLE_CLOUD_REGION

이 Codelab에 필요한 API 사용 설정

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    iam.googleapis.com \
    compute.googleapis.com \
    vpcaccess.googleapis.com \
    storage.googleapis.com

3. 서비스 계정 만들기

Cloud Run 서비스나 작업을 만들 때 서비스 계정을 지정하지 않으면 Cloud Run에서 Compute Engine 기본 서비스 계정을 사용합니다. 과도한 권한으로 서비스를 실행하지 않도록 Cloud Run 서비스의 별도 서비스 계정을 사용하는 것이 좋습니다.

Cloud Run 서비스의 서비스 계정 만들기

gcloud iam service-accounts create ${SERVICE_ACCOUNT} \
  --project "${GOOGLE_CLOUD_PROJECT}" \
  --display-name "vLLM Service Account"

4. Cloud Storage 설정

모델 가중치를 저장할 Cloud Storage 버킷을 만듭니다. 이렇게 하면 Cloud Run이 서비스 인스턴스를 시작할 때마다 직접 VPC 이그레스를 사용하여 모델 가중치를 더 빠르게 다운로드할 수 있습니다.

vLLM의 Run:ai Model Streamer 기능과 결합하면 모델 로드 시간이 크게 단축됩니다.

버킷 만들기

Cloud Run 서비스와 동일한 위치에 있는 단일 리전 버킷인지 확인합니다.

gcloud storage buckets create "gs://${MODEL_CACHE_BUCKET}" \
    --uniform-bucket-level-access --public-access-prevention \
    --project "${GOOGLE_CLOUD_PROJECT}" --location "${GOOGLE_CLOUD_REGION}"

5. 모델 가중치 검색 및 캐싱

그런 다음 Gemma 4 모델을 Cloud Storage 버킷에 다운로드합니다.

모델 가중치는 수십 기가바이트이며 로컬 머신 또는 Cloud Shell에 다운로드하는 것은 불가능할 수 있습니다.

대신 모델 가중치를 저장할 수 있는 충분한 스토리지가 있는 Cloud Build를 사용합니다.

gcloud builds submit --project="${GOOGLE_CLOUD_PROJECT}" --region="${GOOGLE_CLOUD_REGION}" --no-source \
    --substitutions="_MODEL_NAME=${MODEL_NAME},_HF_TOKEN=${HF_TOKEN},_GCS_MODEL_LOCATION=${GCS_MODEL_LOCATION}" \
    --config=/dev/stdin <<'EOF'
steps:
- name: 'gcr.io/google.com/cloudsdktool/google-cloud-cli:slim'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
    set -e
    pip3 install --root-user-action=ignore --break-system-packages huggingface_hub[cli]
    echo "Downloading the model..."
    if [[ "$_HF_TOKEN" != "" ]]; then
      hf download "$_MODEL_NAME" --token $_HF_TOKEN --local-dir "./model-cache/$_MODEL_NAME"
    else
      hf download "$_MODEL_NAME" --local-dir "./model-cache/$_MODEL_NAME"
    fi
    echo "Uploading the model..."
    gcloud storage cp -r "./model-cache/$_MODEL_NAME" "$_GCS_MODEL_LOCATION"
options:
  machineType: 'E2_HIGHCPU_32'
  diskSizeGb: 500
EOF

6. 직접 VPC 이그레스의 네트워킹 구성

직접 VPC 이그레스 구성을 사용하려면 비공개 Google 액세스가 사용 설정된 네트워크와 서브넷을 만들어야 합니다.

이렇게 하면 Cloud Run 서비스가 Cloud Storage를 비롯한 Google API 및 서비스에서 사용하는 외부 IP 주소 집합에 연결할 수 있습니다.

네트워크 만들기

gcloud compute networks create "$VPC_NETWORK" \
        --subnet-mode=custom \
        --bgp-routing-mode=regional \
        --project "$GOOGLE_CLOUD_PROJECT"

서브넷 만들기

gcloud compute networks subnets create "$VPC_SUBNET" \
        --network="$VPC_NETWORK" \
        --region="$GOOGLE_CLOUD_REGION" \
        --range="$SUBNET_RANGE" \
        --enable-private-ip-google-access \
        --project "$GOOGLE_CLOUD_PROJECT"

7. 서비스 계정 액세스 정책 구성

Cloud Run 서비스 계정에는 만든 스토리지 버킷의 모델 가중치에 액세스할 수 있는 권한이 필요합니다.

gcloud storage buckets add-iam-policy-binding "gs://${MODEL_CACHE_BUCKET}" \
    --member "serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
    --role "roles/storage.admin" \
    --project "${GOOGLE_CLOUD_PROJECT}"

8. 구성 변수 초기화

vLLM 추론 엔진과 Cloud Run 서비스 모두의 변수를 정의합니다.

# vLLM variables
export MAX_MODEL_LEN=32767      # 32767 to improve concurrency. Keep it empty to use model's maximim context length (256K)
export QUANTIZATION_TYPE="fp8"  # Model quantization for faster performance and lower memory usage.
export KV_CACHE_DTYPE="fp8"     # KV-cache quantization to save GPU memory.
export GPU_MEM_UTIL="0.95"      # Fraction of GPU memory to be used by the vLLM engine.
export TENSOR_PARALLEL_SIZE="1" # Partitioning model across GPUs (1 here as we have only 1 GPU).
export MAX_NUM_SEQS=8           # Max concurrent requests vLLM processes in one batch.

# Cloud Run variables
export CLOUD_RUN_CPU_NUM=20
export CLOUD_RUN_MEMORY_GB=80
export CLOUD_RUN_MAX_INSTANCES=3
export CLOUD_RUN_CONCURRENCY=16

성능 조정을 위한 참고사항: 이러한 변수를 조정하는 것은 처리량과 지연 시간 간의 균형입니다.

• MAX_NUM_SEQS vs CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY는 MAX_NUM_SEQS보다 크거나 같아야 합니다. 트래픽 급증 시 최적의 활용을 위해 약간 더 높게 설정합니다 (예: 2배).
• 메모리 압력: MAX_MODEL_LEN과 MAX_NUM_SEQS는 모두 KV 캐시에 GPU 메모리를 사용합니다. 컨텍스트 길이가 긴 경우 메모리 부족 (OOM) 오류가 발생하면 MAX_NUM_SEQS를 줄이는 것이 좋습니다.
• 지연 시간: 동시 실행 (MAX_NUM_SEQS)이 높을수록 총 처리량이 증가하지만 개별 요청 지연 시간이 증가할 수 있습니다.
• 확장: CLOUD_RUN_MAX_INSTANCES를 사용하면 수평으로 확장할 수 있습니다. 단일 인스턴스 지연 시간이 허용되지만 총 용량이 더 필요한 경우 이 값을 늘립니다.

9. Cloud Run에 배포

vLLM 컨테이너 명령줄 준비

vLLM은 대규모 모델을 빠르고 효율적으로 실행하기 위해 많은 매개변수가 필요합니다.

CONTAINER_ARGS=(
    "vllm"
    "serve"
    "${GCS_MODEL_LOCATION}"
    "--served-model-name" "${MODEL_NAME}"
    "--enable-log-requests"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config" "auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser" "gemma4"
    "--reasoning-parser" "gemma4"
    "--dtype" "bfloat16"
    "--quantization" "${QUANTIZATION_TYPE}"
    "--kv-cache-dtype" "${KV_CACHE_DTYPE}"
    "--max-num-seqs" "${MAX_NUM_SEQS}"
    "--limit-mm-per-prompt" '{"image":4,"video":2}'
    "--gpu-memory-utilization" "${GPU_MEM_UTIL}"
    "--tensor-parallel-size" "${TENSOR_PARALLEL_SIZE}"
    "--load-format" "runai_streamer"
    "--port" "8080"
    "--host" "0.0.0.0"
)

if [[ "${MAX_MODEL_LEN}" != "" ]]; then
    CONTAINER_ARGS+=("--max-model-len" "${MAX_MODEL_LEN}")
fi

export CONTAINER_ARGS_STR="${CONTAINER_ARGS[*]}"

Cloud Run 서비스 배포

다음 명령어를 실행하여 Cloud Run 서비스를 배포합니다.

gcloud beta run deploy "${SERVICE_NAME}" \
    --image="us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --region "${GOOGLE_CLOUD_REGION}" \
    --service-account "${SERVICE_ACCOUNT_EMAIL}" \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu="${CLOUD_RUN_CPU_NUM}" \
    --memory="${CLOUD_RUN_MEMORY_GB}Gi" \
    --gpu=1 \
    --gpu-type=nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances ${CLOUD_RUN_MAX_INSTANCES} \
    --concurrency ${CLOUD_RUN_CONCURRENCY} \
    --network ${VPC_NETWORK} \
    --subnet ${VPC_SUBNET} \
    --vpc-egress all-traffic \
    --set-env-vars "MODEL_NAME=${MODEL_NAME}" \
    --set-env-vars "GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}" \
    --set-env-vars "GOOGLE_CLOUD_REGION=${GOOGLE_CLOUD_REGION}" \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=1,timeoutSeconds=240,periodSeconds=240 \
    --command "bash" \
    --args="^;^-c;${CONTAINER_ARGS_STR}"

10. 서비스 테스트

배포되면 vLLM OpenAI 호환 API를 사용하여 Gemma 4 모델과 상호작용할 수 있습니다.

서비스 URL 가져오기

배포된 Cloud Run 서비스의 URL을 검색합니다.

SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --project "${GOOGLE_CLOUD_PROJECT}" --region "${GOOGLE_CLOUD_REGION}" --format 'value(status.url)')
echo "Service URL: $SERVICE_URL"

추론 실행

curl을 사용하여 모델에 프롬프트를 보냅니다.

curl -s "$SERVICE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "'"${MODEL_NAME}"'",
  "messages": [
    {"role": "user", "content": "Why is the sky blue?"}
  ],
  "chat_template_kwargs": {
    "enable_thinking": true
  },
  "skip_special_tokens": false
}' | jq -r '.choices[0].message.content'

11. 축하합니다.

축하합니다. Codelab을 완료했습니다.

Cloud Run 문서를 검토하는 것이 좋습니다.

학습한 내용

• Cloud Run RTX 6000 Pro GPU에 Gemma 4 모델을 배포하는 방법
• 더 빠른 서비스 시작을 위해 Cloud Storage로 직접 VPC 이그레스 및 vLLM 모델 스트리밍을 구성하는 방법

12. 삭제

이 튜토리얼에서 사용된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 프로젝트를 삭제하거나 개별 리소스를 삭제하면 됩니다.

옵션 1: 리소스 삭제

Cloud Run 서비스 삭제

gcloud run services delete $SERVICE_NAME \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}"
      --quiet

서비스 계정 삭제

gcloud iam service-accounts delete \
      ${SERVICE_ACCOUNT_EMAIL} \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --quiet

Cloud Storage 버킷 삭제

gcloud storage rm --recursive gs://$MODEL_CACHE_BUCKET

VPC 네트워크 및 서브넷 삭제

gcloud compute networks subnets delete $VPC_SUBNET \
    --region "${GOOGLE_CLOUD_REGION}" \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --quiet

gcloud compute networks delete $VPC_NETWORK \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --quiet

옵션 2: 프로젝트 삭제

전체 프로젝트를 삭제하려면 리소스 관리로 이동하여 2단계에서 만든 프로젝트를 선택하고 삭제를 선택합니다. 프로젝트를 삭제하면 Cloud SDK에서 프로젝트를 변경해야 합니다. gcloud projects list를 실행하여 사용 가능한 모든 프로젝트의 목록을 볼 수 있습니다.