vLLM을 사용하여 Cloud Run GPU에서 LLM 추론을 실행하는 방법

1. 소개

개요

Cloud Run은 Google Cloud의 컨테이너 플랫폼으로, 클러스터를 관리하지 않고도 컨테이너에서 코드를 간단하게 실행할 수 있습니다.

Cloud Run은 L4 또는 NVIDIA RTX PRO 6000 Blackwell GPU를 제공합니다. Cloud Run 인스턴스당 GPU가 하나 있으며 요청이 없을 때 인스턴스를 0으로 축소하는 것을 포함하여 Cloud Run 자동 확장 기능이 계속 적용됩니다.

GPU의 한 가지 사용 사례는 자체 개방형 대규모 언어 모델 (LLM)을 실행하는 것입니다. 이 튜토리얼에서는 LLM을 실행하는 서비스를 배포하는 방법을 안내합니다.

이 Codelab에서는 vLLM 추론 라이브러리가 포함된 사전 빌드된 컨테이너를 사용하여 Cloud Run에 Gemma 4 개방형 모델을 배포하는 방법을 설명합니다.

학습할 내용

• Cloud Run에서 GPU를 사용하는 방법
• vLLM을 추론 엔진으로 사용하여 Cloud Run에 Google의 Gemma 4 2B 명령어 조정 모델을 배포하는 방법

2. 설정 및 요구사항

기본 요건

• Cloud Console에 로그인되어 있습니다.
• 이전에 Cloud Run 서비스를 배포했습니다. 예를 들어 소스 코드에서 웹 서비스 배포 빠른 시작에 따라 시작할 수 있습니다.

3. API 사용 설정 및 환경 변수 설정

API 사용 설정

이 Codelab을 사용하기 전에 사용 설정해야 하는 API가 여러 개 있습니다. 이 Codelab에서는 다음 API를 사용해야 합니다. 다음 명령어를 실행하여 이러한 API를 사용 설정할 수 있습니다.

gcloud services enable run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com

환경 변수 설정

아래에서 프로젝트 ID를 구성합니다.

export PROJECT_ID=<YOUR_PROJECT_ID>

export REGION=europe-west4
export SERVICE_NAME=gemma4-cr-codelab
export SERVICE_ACCOUNT_NAME=gemma4-cr-sa
export SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

4. 서비스 계정 만들기

이 서비스 계정은 Cloud Run 서비스 ID로 사용됩니다.

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Cloud Run gemma 4 SA"

5. 서비스 배포

Cloud Run에 Gemma 모델을 배포하려면 권장 설정으로 다음 gcloud CLI 명령어를 사용하세요.

CONTAINER_ARGS=(
    "serve"
    "google/gemma-4-E2B-it"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config=auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser=gemma4"
    "--reasoning-parser=gemma4"
    "--dtype=bfloat16"
    "--max-num-seqs=64"
    "--gpu-memory-utilization=0.95"
    "--tensor-parallel-size=1"
    "--port=8080"
    "--host=0.0.0.0"
)
gcloud beta run deploy $SERVICE_NAME \
    --image "us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project $PROJECT_ID \
    --region $REGION \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu 20 \
    --memory 80Gi \
    --gpu 1 \
    --gpu-type nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances 3 \
    --concurrency 64 \
    --timeout 600 \
    --service-account $SERVICE_ACCOUNT_ADDRESS \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=1,timeoutSeconds=240,periodSeconds=240 \
    --command "vllm" \
    --args=$(IFS=','; echo "${CONTAINER_ARGS[*]}")

6. 서비스 테스트

배포되면 자동으로 ID 토큰을 추가하는 Cloud Run 개발 프록시 서비스를 사용하거나 서비스 URL을 직접 컬링할 수 있습니다.

Cloud Run 개발 프록시 서비스 사용

먼저 프록시를 시작합니다.

gcloud run services proxy $SERVICE_NAME \
  --project $PROJECT \
  --region $REGION \
  --port=9090

프록시를 실행 상태로 두고 별도의 터미널 탭에서 요청을 보내려면 다음 명령어를 실행합니다. 프록시는 localhost:9090에서 실행됩니다.

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

다음과 비슷한 출력이 표시됩니다.

{
 "id": "chatcmpl-9cf1ab1450487047",
 "object": "chat.completion",
 "created": 1774904187,
 "model": "google/gemma-4-E2B-it",
 "choices": [
   {
     "index": 0,
     "message": {
       "role": "assistant",
       "content": "The short answer is a phenomenon called **Rayleigh scattering**...",
       "function_call": null,
       "tool_calls": [],
       "reasoning": "*   Question: \"Why is the sky blue?\"\n..."
     },
     "finish_reason": "stop",
     "stop_reason": 106
   }
 ],
 "usage": {
   "prompt_tokens": 21,
   "total_tokens": 877,
   "completion_tokens": 856
 }
}

서비스 URL을 직접 사용

먼저 배포된 서비스의 URL을 가져옵니다.

SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --region $REGION --format 'value(status.url)')

서비스 컬링

curl $SERVICE_URL/v1/chat/completions \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E2B-it",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}],
    "chat_template_kwargs": {
         "enable_thinking": true
     },
     "skip_special_tokens": false
  }'

7. 축하합니다.

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

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

학습한 내용

• Cloud Run에서 GPU를 사용하는 방법
• vLLM을 추론 엔진으로 사용하여 Cloud Run에 Google의 Gemma 4 (2B) 모델을 배포하는 방법

8. 정리

의도치 않은 요금이 청구되지 않도록 하려면(예: Cloud Run 서비스가 무료 등급의 월별 Cloud Run 호출 할당량보다 더 많이 호출되는 경우) Cloud Run을 삭제하거나 2단계에서 만든 프로젝트를 삭제하면 됩니다.

Cloud Run 서비스를 삭제하려면 https://console.cloud.google.com/run에서 Cloud Run Cloud Console로 이동하여 gemma4-cr-codelab 서비스를 삭제합니다. gemma4-cr-codelab-sa 서비스 계정을 삭제할 수도 있습니다.

전체 프로젝트를 삭제하려면 https://console.cloud.google.com/cloud-resource-manager로 이동하여 2단계에서 만든 프로젝트를 선택하고 삭제를 선택합니다. 프로젝트를 삭제하면 Cloud SDK에서 프로젝트를 변경해야 합니다. gcloud projects list를 실행하여 사용 가능한 모든 프로젝트의 목록을 볼 수 있습니다.