사전 구성된 아키텍처로 GKE에서 TPU를 사용하여 오픈 LLM 서빙

Autopilot Standard

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

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

• Google Gemma 3 1B-it
• Google Gemma 3 4B-it
• Google Gemma 3 27B-it

참고: Gemma와 같은 게이트된 모델을 사용하려면 해당 Hugging Face 모델 페이지에서 라이선스 조건을 반드시 수락해야 합니다.

이 가이드는 추론용 오픈 모델 서빙을 위해 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.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

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

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

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

  모델 액세스 권한 얻기

  Gemma와 같은 게이트된 모델을 사용하려면 해당 Hugging Face 모델 페이지에서 라이선스 조건을 수락해야 합니다.

  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-vllm-tpu-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 버전을 업데이트하려면 다음 스크립트를 실행할 수 있습니다. 이 스크립트는 tfswitch 도구를 설치하고 홈 디렉터리에 Terraform v1.8.0을 설치합니다. 스크립트의 안내에 따라 필요한 환경 변수를 설정하거나 --modify-rc-file 플래그를 스크립트에 전달합니다.

     "${ACP_REPO_DIR}/tools/bin/install_terraform.sh" && \
     export PATH=${HOME}/bin:${HOME}/.local/bin:${PATH}
     

  4. 다음 배포 스크립트를 실행합니다. 이 배포 스크립트는 필요한 Google Cloud API를 사용 설정하고 이 가이드에 필요한 인프라를 프로비저닝합니다. 여기에는 새 VPC 네트워크, 비공개 노드가 포함된 GKE 클러스터, 기타 보조 리소스가 포함됩니다. 스크립트 실행이 완료되기까지 몇 분 정도 걸릴 수 있습니다.

     GKE Autopilot 클러스터 또는 Standard 클러스터에서 TPU를 사용해 모델을 서빙할 수 있습니다. Autopilot 클러스터는 완전 관리형 Kubernetes 환경을 제공합니다. 워크로드에 가장 적합한 GKE 작업 모드를 선택하는 방법에 대한 자세한 내용은 GKE 작업 모드 정보를 참조하세요.

     Autopilot

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-tpu-model/deploy-ap.sh"
     

     Standard

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-tpu-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 1B-it

     export ACCELERATOR_TYPE="v5e"
     export HF_MODEL_ID="google/gemma-3-1b-it"
     

     Gemma 3 4B-it

     export ACCELERATOR_TYPE="v5e"
     export HF_MODEL_ID="google/gemma-3-4b-it"
     

     Gemma 3 27B-it

     export ACCELERATOR_TYPE="v5e"
     export HF_MODEL_ID="google/gemma-3-27b-it"
     

     다른 모델 버전이나 TPU 유형을 포함한 추가 구성은 accelerated-platforms GitHub 저장소에 있는 매니페스트를 참고하세요.

  모델 다운로드

  1. 배포 구성에서 환경 변수를 불러옵니다. 이러한 환경 변수에는 프로비저닝한 인프라의 필수 구성 세부정보가 포함되어 있습니다.

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

  2. 모델을 Cloud Storage에 다운로드하는 Hugging Face 모델 다운로드 리소스를 구성하려면 다음 스크립트를 실행합니다.

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

  3. Hugging Face 모델 다운로드 리소스를 적용합니다.

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

  4. Hugging Face 모델 다운로드 작업이 완료될 때까지 모니터링합니다.

     until kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} wait job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --for=condition=complete --timeout=10s >/dev/null; do
         clear
         kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
         echo -e "\nhf-model-to-gcs logs(last 10 lines):"
         kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} logs job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --container=hf-model-to-gcs --tail 10
     done
     

  5. Hugging Face 모델 다운로드 작업이 완료되었는지 확인합니다.

     kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
     

  6. Hugging Face 모델 다운로드 리소스를 삭제합니다.

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

  모델 배포

  1. 배포 구성에서 환경 변수를 불러옵니다.

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

  2. Hugging Face 모델 이름이 설정되어 있는지 확인합니다.

     echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
     

  3. vLLM 리소스를 구성합니다.

     "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-tpu/vllm/configure_vllm.sh"
     

  4. GKE 클러스터에 추론 워크로드를 배포합니다.

     kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-tpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
     

  배포 테스트

  1. 추론 워크로드가 제공될 때까지 배포를 모니터링합니다.

     until kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} wait deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --for=condition=available --timeout=10s >/dev/null; do
         clear
         kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
         echo -e "\nfetch-safetensors logs(last 10 lines):"
         kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
         echo -e "\ninference-server logs(last 10 lines):"
         kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
     done
     

  2. 추론 워크로드 배포가 사용 가능한지 확인합니다.

     kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
     echo -e "\nfetch-safetensors logs(last 10 lines):"
     kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
     echo -e "\ninference-server logs(last 10 lines):"
     kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
     

  3. 다음 스크립트를 실행하여 포트 전달을 설정하고 모델에 샘플 요청을 보냅니다.

     kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
     PF_PID=$!
     while ! echo -e '\x1dclose\x0d' | telnet localhost 8000 >/dev/null 2>&1; do
         sleep 0.1
     done
     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-tpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
     

  2. 리소스를 정리합니다.

     Autopilot

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-tpu-model/teardown-ap.sh"
     

     Standard

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-tpu-model/teardown-standard.sh"
     

  다음 단계

  • GKE에서 AI/ML 모델 추론 자세히 알아보기
  • GKE Inference Quickstart 도구를 사용해 모델 추론 성능 및 비용 분석
  • 이 아키텍처를 빌드하는 데 사용된 accelerated-platforms GitHub 저장소를 살펴봅니다.