Menyajikan LLM terbuka di GKE menggunakan TPU dengan arsitektur yang telah dikonfigurasi sebelumnya

Halaman ini menunjukkan cara men-deploy dan menyajikan model bahasa besar (LLM) open source populer dengan cepat di GKE dengan TPU untuk inferensi menggunakan arsitektur referensi inferensi GKE yang telah dikonfigurasi sebelumnya dan siap produksi. Pendekatan ini menggunakan Infrastructure as Code (IaC), dengan Terraform yang di-wrap dalam skrip CLI, untuk membuat lingkungan GKE yang standar, aman, dan skalabel yang dirancang untuk beban kerja inferensi AI.

Dalam panduan ini, Anda akan men-deploy dan menyajikan LLM menggunakan node TPU host tunggal di GKE dengan framework penyajian vLLM. Panduan ini memberikan petunjuk dan konfigurasi untuk men-deploy model terbuka berikut:

Panduan ini ditujukan untuk engineer Machine Learning (ML) serta spesialis Data dan AI yang tertarik untuk mempelajari kemampuan orkestrasi container Kubernetes dalam menyajikan model terbuka untuk inferensi. Untuk mempelajari lebih lanjut peran umum dan contoh tugas yang dirujuk dalam konten Google Cloud , lihat Peran dan tugas pengguna GKE umum.

Sebelum memulai

  • 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.

    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.

    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.

      Buka IAM
    2. Pilih project.
    3. Klik Grant access.

    4. Di kolom New principals, masukkan ID pengguna Anda. ID pengguna biasanya adalah alamat email untuk Akun Google.

    5. Di daftar Select a role, pilih peran.
    6. Untuk memberikan peran tambahan, klik Add another role, lalu tambahkan setiap peran tambahan.
    7. Klik Simpan.

      8. Mendapatkan akses ke model

      Setujui persyaratan lisensi untuk model tertutup apa pun yang ingin Anda gunakan (seperti Gemma) di halaman model Hugging Face masing-masing.

      Untuk mengakses model melalui Hugging Face, Anda memerlukan token Hugging Face.

      Ikuti langkah-langkah berikut untuk membuat token baru jika Anda belum memilikinya:

      1. Klik Profil Anda > Setelan > Token Akses.
      2. Pilih New Token.
      3. Tentukan Nama pilihan Anda dan Peran minimal Baca.
      4. Pilih Generate a token.
      5. Salin token yang dihasilkan ke papan klip Anda.

      Menyediakan lingkungan inferensi GKE

      Di bagian ini, Anda akan men-deploy infrastruktur yang diperlukan untuk menayangkan model Anda.

      Meluncurkan Cloud Shell

      Panduan ini menggunakan Cloud Shell untuk menjalankan perintah. Cloud Shell telah diinstal sebelumnya dengan alat yang diperlukan, termasuk gcloud, kubectl, dan git.

      Di konsol Google Cloud , mulai instance Cloud Shell:

      Buka Cloud Shell

      Tindakan ini akan meluncurkan sesi di panel bawah konsol Google Cloud .

      Men-deploy arsitektur dasar

      Untuk menyediakan cluster GKE dan resource yang diperlukan untuk mengakses model dari Hugging Face, ikuti langkah-langkah berikut:

      1. Di Cloud Shell, clone repositori berikut:

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

      2. Tetapkan variabel lingkungan Anda:

        export TF_VAR_platform_default_project_id=PROJECT_ID
export HF_TOKEN_READ=HF_TOKEN

        Ganti nilai berikut:

        • PROJECT_ID: Project ID Google CloudAnda.
        • HF_TOKEN: token Hugging Face yang Anda buat sebelumnya.

      3. Panduan ini memerlukan Terraform versi 1.8.0 atau yang lebih baru. Cloud Shell telah menginstal Terraform v1.5.7 secara default.

        Untuk mengupdate versi Terraform di Cloud Shell, Anda dapat menjalankan skrip berikut. Skrip ini akan menginstal alat tfswitch dan menginstal Terraform v1.8.0 di direktori beranda Anda. Ikuti petunjuk dari skrip untuk menetapkan variabel lingkungan yang diperlukan atau teruskan flag --modify-rc-file ke skrip.

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

      4. Jalankan skrip deployment berikut. Skrip deployment mengaktifkan API yang diperlukan dan menyediakan infrastruktur yang diperlukan untuk panduan ini. Google Cloud Hal ini mencakup jaringan VPC baru, cluster GKE dengan node pribadi, dan resource pendukung lainnya. Skrip dapat memerlukan waktu beberapa menit untuk menyelesaikan prosesnya.

        Anda dapat menayangkan model menggunakan TPU di cluster GKE Autopilot atau Standard. Cluster Autopilot memberikan pengalaman Kubernetes yang terkelola sepenuhnya. Untuk mengetahui informasi selengkapnya tentang memilih mode operasi GKE yang paling sesuai untuk workload Anda, lihat Tentang mode operasi GKE.

        Autopilot

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

        Standar

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

        Setelah skrip ini selesai, Anda akan memiliki cluster GKE yang siap untuk beban kerja inferensi.

      5. Jalankan perintah berikut untuk menetapkan variabel lingkungan dari konfigurasi bersama:

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

      6. Skrip deployment membuat secret di Secret Manager untuk menyimpan token Hugging Face Anda. Anda harus menambahkan token secara manual ke secret ini sebelum men-deploy cluster. Di Cloud Shell, jalankan perintah ini untuk menambahkan token ke 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}

      Men-deploy model terbuka

      Sekarang Anda siap mendownload dan men-deploy model.

      Pilih model

      1. Tetapkan variabel lingkungan untuk model yang ingin Anda deploy:

        Gemma 3 1B-it

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

        Gemma 3 4B-bit

        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"

        Untuk konfigurasi tambahan, termasuk varian model dan jenis TPU lainnya, lihat manifes yang tersedia di repositori GitHub accelerated-platforms.

      Download model

      1. Dapatkan variabel lingkungan dari deployment Anda. Variabel lingkungan ini berisi detail konfigurasi yang diperlukan dari infrastruktur yang Anda sediakan.

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

      2. Jalankan skrip berikut untuk mengonfigurasi resource download model Hugging Face yang mendownload model ke Cloud Storage:

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

      3. Terapkan resource download model Hugging Face:

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

      4. Pantau tugas download model Hugging Face hingga selesai.

        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. Verifikasi bahwa tugas download model Hugging Face telah selesai.

        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. Hapus resource download model Hugging Face.

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

      Men-deploy model

      1. Dapatkan variabel lingkungan dari deployment Anda.

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

      2. Pastikan nama model Hugging Face telah ditetapkan.

        echo "HF_MODEL_NAME=${HF_MODEL_NAME}"

      3. Konfigurasi resource vLLM.

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

      4. Deploy workload inferensi ke cluster GKE Anda.

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

      Menguji deployment Anda

      1. Pantau deployment workload inferensi hingga tersedia. 

        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. Pastikan deployment workload inferensi tersedia.

        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. Jalankan skrip berikut untuk menyiapkan penerusan port dan mengirim permintaan contoh ke model.

        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}

        Anda akan melihat respons JSON dari model yang menjawab pertanyaan.

      Pembersihan

      Untuk menghindari timbulnya tagihan, hapus semua resource yang Anda buat.

      1. Hapus workload inferensi:

        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. Bersihkan resource:

        Autopilot

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

        Standar

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

      Langkah berikutnya