사전 구성된 아키텍처로 GKE에서 오픈 LLM 서빙

이 가이드에서는 vLLM 서빙 프레임워크와 단일 호스트 GPU 노드를 사용해 GKE에서 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 사용자 역할 및 태스크를 참조하세요.

이들 오픈 모델의 모델 서빙 성능 및 비용에 대한 자세한 분석을 위해 GKE Inference Quickstart 도구를 사용할 수도 있습니다. 자세한 내용은 GKE Inference Quickstart 가이드와 함께 제공되는 Colab 노트북을 참조하세요.

시작하기 전에

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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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. person_add 액세스 권한 부여를 클릭합니다.

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

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

  모델 액세스 권한 얻기

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

  아직 토큰이 없다면 새 토큰을 생성하기 위해 다음 단계를 따르세요.

  1. 내 프로필 > 설정 > 액세스 토큰을 클릭합니다.
  2. 새 토큰을 선택합니다.
  3. 원하는 이름을 지정하고 역할은 최소한 읽기로 설정합니다.
  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"
     

     Standard

     "${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. 배포 스크립트는 Hugging Face 토큰을 저장하기 위해 Secret Manager에 보안 비밀을 만듭니다. 클러스터를 배포하기 전에 이 보안 비밀에 토큰을 수동으로 추가해야 합니다. 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 Inference Quickstart 도구를 사용해 모델 추론 성능 및 비용 분석
  • 이 아키텍처를 기반으로 구축된 GitHub의 다른 사용 사례와 패턴 살펴보기