Offene LLMs in GKE mit TPUs und einer vorkonfigurierten Architektur bereitstellen

Autopilot Standard

Auf dieser Seite wird beschrieben, wie Sie beliebte offene Large Language Models (LLMs) in GKE mit TPUs für die Inferenz mithilfe einer vorkonfigurierten, produktionsbereiten GKE-Inferenzreferenzarchitektur schnell bereitstellen und bereitstellen. Bei diesem Ansatz wird Infrastructure as Code (IaC) verwendet, wobei Terraform in CLI-Skripts eingebunden ist, um eine standardisierte, sichere und skalierbare GKE-Umgebung für KI-Inferenz-Arbeitslasten zu erstellen.

In diesem Leitfaden stellen Sie LLMs mit TPU-Knoten mit einem einzelnen Host in GKE mit dem vLLM-Bereitstellungs-Framework bereit. In diesem Leitfaden finden Sie Anleitungen und Konfigurationen für die Bereitstellung der folgenden offenen Modelle:

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

Hinweis :Sie müssen die Lizenzbedingungen für alle Modelle mit eingeschränktem Zugriff, die Sie verwenden möchten (z. B. Gemma), auf der jeweiligen Hugging Face-Modellseite akzeptieren.

Dieser Leitfaden richtet sich an ML-Entwickler (Machine Learning) und Daten- und KI-Spezialisten, die daran interessiert sind, Funktionen zur Kubernetes-Containerorchestrierung für die Bereitstellung offener Modelle für die Inferenz zu nutzen. Weitere Informationen zu gängigen Rollen und Beispielaufgaben, auf die in Google Cloud Inhalten verwiesen wird, finden Sie unter Häufig verwendete GKE-Nutzerrollen und -Aufgaben.

Hinweise

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 aufrufen
  2. Wählen Sie das Projekt aus.
  3. Klicken Sie auf Zugriffsrechte erteilen.

  4. Geben Sie im Feld Neue Hauptkonten Ihre Nutzer-ID ein. Das ist in der Regel die E‑Mail-Adresse eines Google-Kontos.

  5. Wählen Sie in der Liste Rolle auswählen eine Rolle aus.
  6. Klicken Sie auf Weitere Rolle hinzufügen, wenn Sie weitere Rollen zuweisen möchten.
  7. Klicken Sie auf Speichern.
  • Erstellen Sie ein Hugging Face-Konto.
  • Prüfen Sie, ob Ihr Projekt ein ausreichendes TPU-Kontingent (GKE Standard) oder TPU-Kontingent (GKE Autopilot) hat. Weitere Informationen finden Sie unter TPUs in GKE planen.

  Zugriff auf das Modell erhalten

  Akzeptieren Sie die Lizenzbedingungen für alle Modelle mit Zugriffsbeschränkung, die Sie verwenden möchten (z. B. Gemma), auf der jeweiligen Hugging Face-Modellseite.

  Für den Zugriff auf das Modell über Hugging Face benötigen Sie ein Hugging Face-Token.

  Führen Sie die folgenden Schritte aus, um ein neues Token zu generieren, falls Sie noch keines haben:

  1. Klicken Sie auf Mein Profil > Einstellungen > Zugriffstokens.
  2. Wählen Sie Neues Token aus.
  3. Geben Sie einen Namen Ihrer Wahl und eine Rolle von mindestens Lesen an.
  4. Wählen Sie Token generieren aus.
  5. Kopieren Sie das Token in die Zwischenablage.

  GKE-Inferenzumgebung bereitstellen

  In diesem Abschnitt stellen Sie die erforderliche Infrastruktur zum Bereitstellen Ihres Modells bereit.

  Cloud Shell starten

  In dieser Anleitung wird Cloud Shell zum Ausführen von Befehlen verwendet. In Cloud Shell sind die erforderlichen Tools vorinstalliert, einschließlich gcloud, kubectl und git.

  Starten Sie in der Google Cloud Console eine Cloud Shell-Instanz:

  Cloud Shell öffnen

  Dadurch wird im unteren Bereich der Google Cloud console eine Sitzung gestartet.

  Basisarchitektur bereitstellen

  So stellen Sie den GKE-Cluster und die erforderlichen Ressourcen für den Zugriff auf Modelle von Hugging Face bereit:

  1. Klonen Sie in Cloud Shell das folgende Repository:

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

  2. Legen Sie die Umgebungsvariablen fest:

     export TF_VAR_platform_default_project_id=PROJECT_ID
     export HF_TOKEN_READ=HF_TOKEN
     

     Ersetzen Sie die folgenden Werte:

     • PROJECT_ID: Ihre Google Cloud Projekt-ID.
     • HF_TOKEN: das Hugging Face-Token, das Sie zuvor generiert haben.

  3. Für diese Anleitung ist Terraform-Version 1.8.0 oder höher erforderlich. In Cloud Shell ist standardmäßig Terraform v1.5.7 installiert.

     Wenn Sie die Terraform-Version in Cloud Shell aktualisieren möchten, können Sie das folgende Skript ausführen. Dieses Skript installiert das Tool tfswitch und Terraform v1.8.0 in Ihrem Basisverzeichnis. Folgen Sie der Anleitung im Skript, um die erforderliche Umgebungsvariable festzulegen oder das Flag --modify-rc-file an das Skript zu übergeben.

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

  4. Führen Sie das folgende Bereitstellungsskript aus. Das Bereitstellungsskript aktiviert die erforderlichen Google Cloud APIs und stellt die erforderliche Infrastruktur für diese Anleitung bereit. Dazu gehören ein neues VPC-Netzwerk, ein GKE-Cluster mit privaten Knoten und andere unterstützende Ressourcen. Die Ausführung des Skripts kann mehrere Minuten dauern.

     Sie können Modelle mit TPUs in einem GKE-Cluster im Autopilot- oder Standardmodus bereitstellen. Ein Autopilot-Cluster bietet eine vollständig verwaltete Kubernetes-Umgebung. Weitere Informationen zum Auswählen des GKE-Betriebsmodus, der für Ihre Arbeitslasten am besten geeignet ist, finden Sie unter GKE-Betriebsmodi.

     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"
     

     Nach Abschluss dieses Skripts haben Sie einen GKE-Cluster, der für Inferenzarbeitslasten bereit ist.

  5. Führen Sie den folgenden Befehl aus, um Umgebungsvariablen aus der freigegebenen Konfiguration festzulegen:

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

  6. Das Bereitstellungsskript erstellt ein Secret in Secret Manager, um Ihr Hugging Face-Token zu speichern. Sie müssen Ihr Token diesem Secret manuell hinzufügen, bevor Sie den Cluster bereitstellen. Führen Sie in Cloud Shell diesen Befehl aus, um das Token in Secret Manager hinzuzufügen.

     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}
     

  Offenes Modell bereitstellen

  Sie können das Modell jetzt herunterladen und bereitstellen.

  Modell auswählen

  1. Legen Sie die Umgebungsvariablen für das Modell fest, das Sie bereitstellen möchten:

     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"
     

     Weitere Konfigurationen, einschließlich anderer Modellvarianten und TPU-Typen, finden Sie in den Manifesten im GitHub-Repository accelerated-platforms.

  Modell herunterladen

  1. Rufen Sie die Umgebungsvariablen aus Ihrer Bereitstellung ab. Diese Umgebungsvariablen enthalten die erforderlichen Konfigurationsdetails aus der von Ihnen bereitgestellten Infrastruktur.

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

  2. Führen Sie das folgende Skript aus, um die Ressourcen für den Hugging Face-Modelldownload zu konfigurieren, mit denen das Modell in Cloud Storage heruntergeladen wird:

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

  3. Wenden Sie die Ressourcen für den Download von Hugging Face-Modellen an:

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

  4. Überwachen Sie den Downloadjob für das Hugging Face-Modell, bis er abgeschlossen ist.

     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. Prüfen Sie, ob der Download des Hugging Face-Modells abgeschlossen ist.

     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. Löschen Sie die Downloadressourcen für das Hugging Face-Modell.

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

  Modell bereitstellen

  1. Rufen Sie die Umgebungsvariablen aus Ihrer Bereitstellung ab.

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

  2. Prüfen Sie, ob der Name des Hugging Face-Modells festgelegt ist.

     echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
     

  3. Konfigurieren Sie die vLLM-Ressourcen.

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

  4. Stellen Sie die Inferenzarbeitslast in Ihrem GKE-Cluster bereit.

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

  Bereitstellung testen

  1. Überwachen Sie die Bereitstellung der Inferenzarbeitslast, bis sie verfügbar ist.

     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. Prüfen Sie, ob das Deployment der Inferenzarbeitslast verfügbar ist.

     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. Führen Sie das folgende Skript aus, um die Portweiterleitung einzurichten und eine Beispielanfrage an das Modell zu senden.

     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}
     

     Sie sollten eine JSON-Antwort vom Modell sehen, in der die Frage beantwortet wird.

  Bereinigen

  Löschen Sie alle erstellten Ressourcen, um Gebühren zu vermeiden.

  1. Löschen Sie die Inferenzarbeitslast:

     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. Ressourcen bereinigen:

     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"
     

  Nächste Schritte

  • Weitere Informationen zur KI-/ML-Modellinferenz in GKE
  • Mit dem GKE Inference Quickstart-Tool können Sie die Leistung und Kosten der Modellinferenz analysieren.
  • GitHub-Repository für beschleunigte Plattformen, das zum Erstellen dieser Architektur verwendet wurde