이 튜토리얼에서는 Llama 4 Scout (17Bx16E), 17B 대규모 언어 모델 (LLM)을 배포하고 vLLM 프레임워크를 사용하여 서빙하는 방법을 보여줍니다. Google Kubernetes Engine (GKE)의 단일 A4 가상 머신 (VM) 인스턴스에 이 모델을 배포합니다.
이 튜토리얼은 추론 워크로드를 처리하기 위해 Kubernetes 컨테이너 조정 기능을 사용하는 데 관심이 있는 머신러닝 (ML) 엔지니어, 플랫폼 관리자 및 운영자, 데이터 및 AI 전문가를 대상으로 합니다.
목표
Hugging Face를 사용하여 Llama 4에 액세스합니다.
개발 환경을 준비합니다.
Autopilot 모드로 GKE 클러스터를 만듭니다.
Hugging Face 사용자 인증 정보용 Kubernetes 보안 비밀을 만듭니다.
GKE 클러스터에 vLLM 컨테이너를 배포합니다.
curl을 사용하여 Llama 4와 상호작용합니다.
삭제
비용
이 가이드에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.
프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용합니다.
시작하기 전에
- 계정에 로그인합니다. Google Cloud 를 처음 사용하는 경우 Google Cloud 계정을 만들어 실제 시나리오에서 제품이 어떻게 작동하는지 평가하세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $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 프로젝트 이름으로 바꿉니다.
필요한 API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 역할 (
roles/serviceusage.serviceUsageAdmin)이 포함된 서비스 사용량 관리자 IAMserviceusage.services.enable권한이 필요합니다. 역할 부여 방법 알아보기.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 프로젝트 이름으로 바꿉니다.
필요한 API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 역할 (
roles/serviceusage.serviceUsageAdmin)이 포함된 서비스 사용량 관리자 IAMserviceusage.services.enable권한이 필요합니다. 역할 부여 방법 알아보기.gcloud services enable container.googleapis.com
-
사용자 계정에 역할을 부여합니다. 다음 IAM 역할마다 다음 명령어를 1회 실행합니다.
roles/container.admingcloud 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를 사용하여 Llama 4에 액세스
Hugging Face를 사용하여 Llama 4에 액세스하려면 다음 단계를 따르세요.
- Llama 4를 사용하려면 동의 계약에 서명합니다.
- Hugging Face
read액세스 토큰을 만듭니다. read액세스 토큰 값을 복사하여 저장합니다. 이 튜토리얼의 뒷부분에서 사용합니다.
개발 환경 준비
개발 환경을 준비하려면 다음 변수를 설정하세요.
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를 지정합니다.
리소스 만들기 및 구성 Google Cloud
이 섹션의 안내에 따라 필요한 리소스를 만듭니다.
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 콘솔에서 Kubernetes 클러스터로 이동하세요. Google Cloud
Hugging Face 사용자 인증 정보를 저장할 Kubernetes 보안 비밀 만들기
Hugging Face 사용자 인증 정보를 저장할 Kubernetes 보안 비밀을 만들려면 다음 단계를 따르세요.
GKE 클러스터와 통신하도록
kubectl을 구성합니다.gcloud container clusters get-credentials $CLUSTER_NAME \ --location=$REGION이전 단계에서 만든 Hugging Face
read access토큰이 포함된 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 컨테이너 배포
Llama-4-Scout-17B-16E-Instruct 모델을 서빙하기 위해 vLLM 컨테이너를 배포하려면 다음 단계를 따르세요.
선택한 vLLM 배포로
vllm-l4-17b.yaml파일을 만듭니다.apiVersion: apps/v1 kind: Deployment metadata: name: vllm-llama4-deployment spec: replicas: 1 selector: matchLabels: app: llama4-server template: metadata: labels: app: llama4-server ai.gke.io/model: llama-4-scout-17b 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:20250722_0916_RC01 resources: requests: cpu: "10" memory: "128Gi" ephemeral-storage: "240Gi" nvidia.com/gpu: "8" limits: cpu: "10" memory: "128Gi" ephemeral-storage: "240Gi" 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: meta-llama/Llama-4-Scout-17B-16E-Instruct - 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: 1800 periodSeconds: 10 readinessProbe: httpGet: path: /health port: 8000 initialDelaySeconds: 1800 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: llama4-server type: ClusterIP ports: - protocol: TCP port: 8000 targetPort: 8000 --- apiVersion: monitoring.googleapis.com/v1 kind: PodMonitoring metadata: name: vllm-llama4-monitoring spec: selector: matchLabels: app: llama4-server endpoints: - port: 8000 path: /metrics interval: 30sGKE 클러스터에
vllm-l4-17b.yaml파일을 적용합니다.kubectl apply -f vllm-l4-17b.yaml배포 프로세스 중에 컨테이너는 Hugging Face에서
Llama-4-Scout-17B-16E-Instruct모델을 다운로드해야 합니다. 따라서 컨테이너 배포가 완료되는 데 최대 30분이 걸릴 수 있습니다.완료 상태를 보려면 다음 명령어를 실행합니다.
kubectl wait \ --for=condition=Available \ --timeout=1800s deployment/vllm-llama4-deployment--timeout=1800s플래그를 사용하면 명령어가 최대 30분 동안 배포를 모니터링할 수 있습니다.
curl을 사용하여 Llama 4와 상호작용
배포한 Llama 4 Scout 모델을 확인하려면 다음 단계를 따르세요.
Llama 4 Scout에 대한 포트 전달을 설정합니다.
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": "meta-llama/Llama-4-Scout-17B-16E-Instruct", "messages": [ { "role": "user", "content": "Describe a sailboat in one short sentence?" } ] }'표시되는 출력은 다음과 유사합니다.
{ "id": "chatcmpl-ec0ad6310c494a889b17600881c06e3d", "object": "chat.completion", "created": 1754073279, "model": "meta-llama/Llama-4-Scout-17B-16E-Instruct", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "A sailboat is a type of watercraft that uses the wind for propulsion, typically featuring a hull, mast, and one or more sails.", "refusal": null, "annotations": null, "audio": null, "function_call": null, "tool_calls": [], "reasoning_content": null }, "logprobs": null, "finish_reason": "stop", "stop_reason": null } ], "service_tier": null, "system_fingerprint": null, "usage": { "prompt_tokens": 19, "total_tokens": 49, "completion_tokens": 30, "prompt_tokens_details": null }, "prompt_logprobs": null, "kv_transfer_params": null }
모델 성능 관찰
모델의 성능을 관찰하려면 Cloud Monitoring에 통합된 vLLM 대시보드를 사용할 수 있습니다. 이 대시보드를 사용하여 토큰 처리량, 요청 지연 시간, 오류율 등의 주요 성능 측정항목을 확인할 수 있습니다.
Managed Service for Prometheus를 사용하여 모델에서 측정항목을 수집하는 방법은 Cloud Monitoring 문서의 vLLM 모니터링 가능성 가이드를 참조하세요. Google Cloud
삭제
이 튜토리얼에서 사용된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 리소스가 포함된 프로젝트를 삭제하거나 프로젝트를 유지하고 개별 리소스를 삭제하세요.
프로젝트 삭제
프로젝트 삭제: Google Cloud
gcloud projects delete PROJECT_ID
리소스 삭제
vllm-l4-17b.yaml파일의 배포 및 서비스와 GKE 클러스터의 Kubernetes 보안 비밀을 삭제하려면 다음 명령어를 실행합니다.kubectl delete -f vllm-l4-17b.yaml kubectl delete secret hf-secretGKE 클러스터를 삭제하려면 다음 명령어를 실행합니다.
gcloud container clusters delete $CLUSTER_NAME \ --region=$REGION