이 가이드에서는 vLLM 서빙 프레임워크를 사용하여 GKE에서 단일 호스트 GPU 노드를 사용하여 LLM을 배포하고 서빙합니다. 이 가이드에서는 다음 공개 모델을 배포하기 위한 안내와 구성을 제공합니다.
이 가이드는 추론을 위해 개방형 모델을 서빙하기 위해 Kubernetes 컨테이너 조정 기능을 살펴보는 데 관심이 있는 머신러닝 (ML) 엔지니어와 데이터 및 AI 전문가를 대상으로 합니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참고하세요.
이러한 오픈 모델의 모델 서빙 성능과 비용을 자세히 분석하려면 GKE Inference Quickstart 도구를 사용해도 됩니다. 자세한 내용은 GKE 추론 빠른 시작 가이드 및 관련 Colab 노트북을 참고하세요.
모델 액세스 권한 얻기
Hugging Face를 통해 모델에 액세스하려면 Hugging Face 토큰이 필요합니다.
아직 토큰이 없으면 다음 단계에 따라 새 토큰을 생성합니다.
- 내 프로필 > 설정 > 액세스 토큰을 클릭합니다.
- 새 토큰을 선택합니다.
- 원하는 이름과 Read 이상의 역할을 지정합니다.
- 토큰 생성을 선택합니다.
- 클립보드에 생성된 토큰을 복사합니다.
GKE 추론 환경 프로비저닝
이 섹션에서는 모델을 제공하는 데 필요한 인프라를 배포합니다.
Cloud Shell 실행
이 가이드에서는 Cloud Shell을 사용하여 명령어를 실행합니다. Cloud Shell에는 gcloud, kubectl, git 등 필요한 도구가 사전 설치되어 있습니다.
Google Cloud 콘솔에서 Cloud Shell 인스턴스를 시작합니다.
그러면 Google Cloud 콘솔 하단 창에서 세션이 실행됩니다.
기본 아키텍처 배포
Hugging Face에서 모델에 액세스하는 데 필요한 GKE 클러스터와 리소스를 프로비저닝하려면 다음 단계를 따르세요.
Cloud Shell에서 다음 저장소를 클론합니다.
git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-tutorial && \ cd accelerated-platforms && \ export ACP_REPO_DIR="$(pwd)"환경 변수를 설정합니다.
export TF_VAR_platform_default_project_id=PROJECT_ID export HF_TOKEN_READ=HF_TOKEN다음 값을 바꿉니다.
PROJECT_ID: Google Cloud프로젝트 IDHF_TOKEN: 앞에서 생성한 Hugging Face 토큰입니다.
이 가이드에는 Terraform 버전 1.8.0 이상이 필요합니다. Cloud Shell에는 Terraform v1.5.7이 기본적으로 설치되어 있습니다.
Cloud Shell에서 Terraform 버전을 업데이트하려면 다음 스크립트를 실행하면 됩니다. 이 스크립트는
terraform-switcher도구를 설치하고 셸 환경을 변경합니다."${ACP_REPO_DIR}/tools/bin/install_terraform.sh" source ~/.bashrc다음 배포 스크립트를 실행합니다. 배포 스크립트는 필수 Google Cloud API를 사용 설정하고 이 가이드에 필요한 인프라를 프로비저닝합니다. 여기에는 새 VPC 네트워크, 비공개 노드가 있는 GKE 클러스터, 기타 지원 리소스가 포함됩니다. 스크립트를 완료하는 데 몇 분 정도 걸릴 수 있습니다.
GKE Autopilot 또는 Standard 클러스터에서 GPU를 사용하여 모델을 서빙할 수 있습니다. Autopilot 클러스터는 완전 관리형 Kubernetes 환경을 제공합니다. 워크로드에 가장 적합한 GKE 작업 모드를 선택하는 방법에 관한 자세한 내용은 GKE 작업 모드 정보를 참고하세요.
Autopilot
"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-ap.sh"표준
"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-standard.sh"이 스크립트가 완료되면 추론 워크로드에 사용할 수 있는 GKE 클러스터가 생성됩니다.
다음 명령어를 실행하여 공유 구성에서 환경 변수를 설정합니다.
source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"배포 스크립트는 Secret Manager에 보안 비밀을 만들어 Hugging Face 토큰을 저장합니다. 클러스터를 배포하기 전에 이 보안 비밀에 토큰을 수동으로 추가해야 합니다. Cloud Shell에서 다음 명령어를 실행하여 Secret Manager에 토큰을 추가합니다.
echo ${HF_TOKEN_READ} | gcloud secrets versions add ${huggingface_hub_access_token_read_secret_manager_secret_name} \ --data-file=- \ --project=${huggingface_secret_manager_project_id}
개방형 모델 배포
이제 모델을 다운로드하고 배포할 준비가 되었습니다.
배포할 모델의 환경 변수를 설정합니다.
Gemma 3 27B-it
export ACCELERATOR_TYPE="h100" export HF_MODEL_ID="google/gemma-3-27b-it"Llama 4 Scout 17B-16E-Instruct
export ACCELERATOR_TYPE="h100" export HF_MODEL_ID="meta-llama/llama-4-scout-17b-16e-instruct"Qwen3 32B
export ACCELERATOR_TYPE="h100" export HF_MODEL_ID="qwen/qwen3-32b"gpt-oss 20B
export ACCELERATOR_TYPE="h100" export HF_MODEL_ID="openai/gpt-oss-20b"다른 모델 변형 및 GPU 유형을 포함한 추가 구성은
accelerated-platformsGitHub 저장소에서 제공되는 매니페스트를 참고하세요.배포에서 환경 변수를 소싱합니다. 이러한 환경 변수에는 프로비저닝한 인프라의 필수 구성 세부정보가 포함됩니다.
source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"다음 스크립트를 실행하여 모델을 Cloud Storage에 다운로드하는 Kubernetes 작업을 구성합니다.
"${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/configure_huggingface.sh"모델 다운로드 작업을 배포합니다.
kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/huggingface"다운로드가 완료될 때까지 기다립니다. 작업 상태를 모니터링하고
COMPLETIONS이1/1이면Ctrl+C을 눌러 종료합니다.watch --color --interval 5 --no-title "kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs추론 워크로드를 GKE 클러스터에 배포합니다.
"${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/configure_deployment.sh" kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
배포 테스트
추론 서버 포드가 준비될 때까지 기다립니다.
READY열이1/1인 경우Ctrl+C를 눌러 종료합니다.watch --color --interval 5 --no-title "kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"다음 스크립트를 실행하여 포트 전달을 설정하고 모델에 샘플 요청을 보냅니다. 이 예시에서는 Gemma 3 27b-it 모델의 페이로드 형식을 사용합니다.
kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null & PF_PID=$! curl http://127.0.0.1:8000/v1/chat/completions \ --data '{ "model": "/gcs/'${HF_MODEL_ID}'", "messages": [ { "role": "user", "content": "What is GKE?" } ] }' \ --header "Content-Type: application/json" \ --request POST \ --show-error \ --silent | jq kill -9 ${PF_PID}질문에 답하는 모델의 JSON 응답이 표시됩니다.
삭제
요금이 청구되지 않도록 하려면 만든 리소스를 모두 삭제하세요.
추론 워크로드를 삭제합니다.
kubectl delete --ignore-not-found --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"기본 GKE 클러스터를 삭제합니다.
Autopilot
"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-ap.sh"Standard
"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-standard.sh"
다음 단계
- GKE의 AI/ML 모델 추론에 대해 자세히 알아보세요.
- GKE 추론 빠른 시작 도구로 모델 추론 성능과 비용을 분석합니다.
- 이 아키텍처를 기반으로 구축된 GitHub의 다른 사용 사례와 패턴을 살펴봅니다.