사전 구성된 아키텍처를 사용하여 GKE에서 개방형 LLM 제공

Autopilot Standard

---

이 페이지에서는 사전 구성된 프로덕션 지원 참조 아키텍처를 사용하여 추론을 위해 GKE에 인기 있는 개방형 대규모 언어 모델 (LLM)을 빠르게 배포하고 제공하는 방법을 보여줍니다. 이 접근 방식에서는 코드형 인프라 (IaC)를 사용하며, Terraform은 CLI 스크립트로 래핑되어 AI 추론 워크로드용으로 설계된 표준화되고 안전하며 확장 가능한 GKE 환경을 만듭니다.

이 가이드에서는 vLLM 서빙 프레임워크를 사용하여 GKE에서 단일 호스트 GPU 노드를 사용하여 LLM을 배포하고 서빙합니다. 이 가이드에서는 다음 공개 모델을 배포하기 위한 안내와 구성을 제공합니다.

• Google Gemma 3 27B-it
• Meta Llama 4 Scout 17B-16E-Instruct
• Qwen3 32-B
• OpenAI gpt-oss-20b

이 가이드는 추론을 위해 개방형 모델을 서빙하기 위해 Kubernetes 컨테이너 조정 기능을 살펴보는 데 관심이 있는 머신러닝 (ML) 엔지니어와 데이터 및 AI 전문가를 대상으로 합니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참고하세요.

시작하기 전에

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Enable the APIs

• Make sure that you have the following role or roles on the project: roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin, and roles/serviceusage.serviceUsageAdmin

  Check for the roles

  1. In the Google Cloud console, go to the IAM page.

     Go to IAM
  2. Select the project.

  3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

  4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

  Grant the roles

  1. In the Google Cloud console, go to the IAM page.

     IAM으로 이동
  2. 프로젝트를 선택합니다.
  3. 액세스 권한 부여를 클릭합니다.

  4. 새 주 구성원 필드에 사용자 식별자를 입력합니다. 일반적으로 Google 계정의 이메일 주소입니다.

  5. 역할 선택 목록에서 역할을 선택합니다.
  6. 역할을 추가로 부여하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.
  7. 저장을 클릭합니다.
  • Hugging Face 계정을 만듭니다.
  • 프로젝트에 충분한 GPU 할당량이 있는지 확인합니다. 자세한 내용은 배정 할당량을 참고하세요.

  모델 액세스 권한 얻기

  참고: 사용하려는 게이트 모델(예: Gemma 또는 Llama)의 라이선스 약관을 해당 Hugging Face 모델 페이지에서 수락해야 합니다.

  Hugging Face를 통해 모델에 액세스하려면 Hugging Face 토큰이 필요합니다.

  아직 토큰이 없으면 다음 단계에 따라 새 토큰을 생성합니다.

  1. 내 프로필 > 설정 > 액세스 토큰을 클릭합니다.
  2. 새 토큰을 선택합니다.
  3. 원하는 이름과 Read 이상의 역할을 지정합니다.
  4. 토큰 생성을 선택합니다.
  5. 클립보드에 생성된 토큰을 복사합니다.

  GKE 추론 환경 프로비저닝

  이 섹션에서는 모델을 제공하는 데 필요한 인프라를 배포합니다.

  Cloud Shell 실행

  이 가이드에서는 Cloud Shell을 사용하여 명령어를 실행합니다. Cloud Shell에는 gcloud, kubectl, git 등 필요한 도구가 사전 설치되어 있습니다.

  Google Cloud 콘솔에서 Cloud Shell 인스턴스를 시작합니다.

  Cloud Shell 열기

  그러면 Google Cloud 콘솔 하단 창에서 세션이 실행됩니다.

  기본 아키텍처 배포

  Hugging Face에서 모델에 액세스하는 데 필요한 GKE 클러스터와 리소스를 프로비저닝하려면 다음 단계를 따르세요.

  1. Cloud Shell에서 다음 저장소를 클론합니다.

     git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-tutorial && \
     cd accelerated-platforms && \
     export ACP_REPO_DIR="$(pwd)"
     

  2. 환경 변수를 설정합니다.

     export TF_VAR_platform_default_project_id=PROJECT_ID
     export HF_TOKEN_READ=HF_TOKEN
     

     다음 값을 바꿉니다.

     • PROJECT_ID: Google Cloud프로젝트 ID
     • HF_TOKEN: 앞에서 생성한 Hugging Face 토큰입니다.

  3. 이 가이드에는 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
     

  4. 다음 배포 스크립트를 실행합니다. 배포 스크립트는 필수 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 클러스터가 생성됩니다.

  5. 다음 명령어를 실행하여 공유 구성에서 환경 변수를 설정합니다.

     source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
     

  6. 배포 스크립트는 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}
     

  개방형 모델 배포

  이제 모델을 다운로드하고 배포할 준비가 되었습니다.

  1. 배포할 모델의 환경 변수를 설정합니다.

     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-platforms GitHub 저장소에서 제공되는 매니페스트를 참고하세요.

  2. 배포에서 환경 변수를 소싱합니다. 이러한 환경 변수에는 프로비저닝한 인프라의 필수 구성 세부정보가 포함됩니다.

     source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
     

  3. 다음 스크립트를 실행하여 모델을 Cloud Storage에 다운로드하는 Kubernetes 작업을 구성합니다.

     "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/configure_huggingface.sh"
     

  4. 모델 다운로드 작업을 배포합니다.

     kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/huggingface"
     

  5. 다운로드가 완료될 때까지 기다립니다. 작업 상태를 모니터링하고 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
     

  6. 추론 워크로드를 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}"
     

  배포 테스트

  1. 추론 서버 포드가 준비될 때까지 기다립니다. 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}"
     

  2. 다음 스크립트를 실행하여 포트 전달을 설정하고 모델에 샘플 요청을 보냅니다. 이 예시에서는 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 응답이 표시됩니다.

  삭제

  요금이 청구되지 않도록 하려면 만든 리소스를 모두 삭제하세요.

  1. 추론 워크로드를 삭제합니다.

     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}"
     

  2. 기본 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의 다른 사용 사례와 패턴을 살펴봅니다.