Diffuser des LLM ouverts sur GKE à l'aide de TPU avec une architecture préconfigurée

Autopilot Standard

Cette page vous explique comment déployer et diffuser rapidement des grands modèles de langage (LLM) ouverts populaires sur GKE avec des TPU pour l'inférence à l'aide d'une architecture de référence pour l'inférence GKE préconfigurée et prête pour la production. Cette approche utilise l'infrastructure en tant que code (IaC), avec Terraform encapsulé dans des scripts CLI, pour créer un environnement GKE standardisé, sécurisé et évolutif conçu pour les charges de travail d'inférence d'IA.

Dans ce guide, vous allez déployer et diffuser des LLM à l'aide de nœuds TPU à hôte unique sur GKE avec le framework de diffusion vLLM. Ce guide fournit des instructions et des configurations pour déployer les modèles ouverts suivants :

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

Remarque : Vous devez accepter les conditions de licence pour tous les modèles fermés que vous souhaitez utiliser (comme Gemma) sur la page Hugging Face correspondante.

Ce guide est destiné aux ingénieurs en machine learning (ML) et aux spécialistes des données et de l'IA qui souhaitent explorer les fonctionnalités d'orchestration de conteneurs Kubernetes pour diffuser des modèles ouverts pour l'inférence. Pour en savoir plus sur les rôles courants et les exemples de tâches cités dans le contenu Google Cloud , consultez Rôles utilisateur et tâches courantes de GKE.

Avant de commencer

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.

     Accéder à IAM
  2. Sélectionnez le projet.
  3. Cliquez sur  Accorder l'accès.

  4. Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail d'un compte Google.

  5. Dans la liste Sélectionner un rôle, sélectionnez un rôle.
  6. Pour attribuer des rôles supplémentaires, cliquez sur  Ajouter un autre rôle et ajoutez tous les rôles supplémentaires.
  7. Cliquez sur Enregistrer.
  • Créez un compte Hugging Face.
  • Assurez-vous que votre projet dispose d'un quota TPU suffisant (GKE Standard) ou d'un quota TPU suffisant (GKE Autopilot). Pour en savoir plus, consultez Planifier des TPU dans GKE.

  Accéder au modèle

  Acceptez les conditions de licence pour tous les modèles avec accès restreint que vous souhaitez utiliser (comme Gemma) sur leur page de modèle Hugging Face respective.

  Pour accéder au modèle via Hugging Face, vous avez besoin d'un jeton Hugging Face.

  Pour générer un nouveau jeton si vous n'en possédez pas, procédez comme suit:

  1. Cliquez sur Votre profil > Paramètres > Jetons d'accès.
  2. Sélectionnez New Token (Nouveau jeton).
  3. Spécifiez le nom de votre choix et un rôle d'au moins Lecteur.
  4. Sélectionnez Générer un jeton.
  5. Copiez le jeton dans votre presse-papiers.

  Provisionner l'environnement d'inférence GKE

  Dans cette section, vous allez déployer l'infrastructure nécessaire pour diffuser votre modèle.

  Lancer Cloud Shell

  Ce guide utilise Cloud Shell pour exécuter les commandes. Cloud Shell est préinstallé avec les outils nécessaires, y compris gcloud, kubectl et git.

  Dans la console Google Cloud , démarrez une instance Cloud Shell :

  Ouvrir Cloud Shell

  Une session s'ouvre dans le volet inférieur de la console Google Cloud .

  Déployer l'architecture de base

  Pour provisionner le cluster GKE et les ressources nécessaires pour accéder aux modèles de Hugging Face, procédez comme suit :

  1. Dans Cloud Shell, clonez le dépôt suivant :

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

  2. Définissez vos variables d'environnement :

     export TF_VAR_platform_default_project_id=PROJECT_ID
     export HF_TOKEN_READ=HF_TOKEN
     

     Remplacez les valeurs suivantes :

     • PROJECT_ID : ID de votre projet Google Cloud.
     • HF_TOKEN : jeton Hugging Face que vous avez généré précédemment.

  3. Ce guide nécessite Terraform version 1.8.0 ou ultérieure. Cloud Shell est installé par défaut avec Terraform v1.5.7.

     Pour mettre à jour la version de Terraform dans Cloud Shell, vous pouvez exécuter le script suivant. Ce script installe l'outil tfswitch et Terraform v1.8.0 dans votre répertoire d'accueil. Suivez les instructions du script pour définir la variable d'environnement nécessaire ou transmettez l'indicateur --modify-rc-file au script.

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

  4. Exécutez le script de déploiement suivant. Le script de déploiement active les API Google Cloud requises et provisionne l'infrastructure nécessaire pour ce guide. Cela inclut un nouveau réseau VPC, un cluster GKE avec des nœuds privés et d'autres ressources d'assistance. L'exécution du script peut prendre plusieurs minutes.

     Vous pouvez diffuser des modèles à l'aide de TPU dans un cluster GKE Autopilot ou Standard. Un cluster Autopilot offre une expérience Kubernetes entièrement gérée. Pour en savoir plus sur le choix du mode de fonctionnement GKE le mieux adapté à vos charges de travail, consultez À propos des modes de fonctionnement 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"
     

     Une fois ce script terminé, vous disposerez d'un cluster GKE prêt pour les charges de travail d'inférence.

  5. Exécutez la commande suivante pour définir les variables d'environnement à partir de la configuration partagée :

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

  6. Le script de déploiement crée un secret dans Secret Manager pour stocker votre jeton Hugging Face. Vous devez ajouter manuellement votre jeton à ce secret avant de déployer le cluster. Dans Cloud Shell, exécutez cette commande pour ajouter le jeton à 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}
     

  Déployer un modèle ouvert

  Vous êtes maintenant prêt à télécharger et à déployer le modèle.

  Sélectionnez un modèle

  1. Définissez les variables d'environnement pour le modèle que vous souhaitez déployer :

     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"
     

     Pour d'autres configurations, y compris d'autres variantes de modèles et types de TPU, consultez les fichiers manifestes disponibles dans le dépôt GitHub accelerated-platforms.

  Télécharger le modèle

  1. Importez les variables d'environnement à partir de votre déploiement. Ces variables d'environnement contiennent les informations de configuration nécessaires à partir de l'infrastructure que vous avez provisionnée.

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

  2. Exécutez le script suivant pour configurer les ressources de téléchargement du modèle Hugging Face qui téléchargent le modèle dans Cloud Storage :

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

  3. Appliquez les ressources de téléchargement de modèle Hugging Face :

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

  4. Surveillez le job de téléchargement du modèle Hugging Face jusqu'à ce qu'il soit terminé.

     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. Vérifiez que le job de téléchargement du modèle Hugging Face est terminé.

     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. Supprimez les ressources de téléchargement du modèle Hugging Face.

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

  Déployer le modèle

  1. Importez les variables d'environnement à partir de votre déploiement.

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

  2. Vérifiez que le nom du modèle Hugging Face est défini.

     echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
     

  3. Configurez les ressources vLLM.

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

  4. Déployez la charge de travail d'inférence sur votre cluster 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}"
     

  Tester votre déploiement

  1. Surveillez le déploiement de la charge de travail d'inférence jusqu'à ce qu'elle soit disponible.

     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. Vérifiez que le déploiement de la charge de travail d'inférence est disponible.

     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. Exécutez le script suivant pour configurer le transfert de port et envoyer un exemple de requête au modèle.

     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}
     

     Vous devriez obtenir une réponse JSON du modèle répondant à la question.

  Effectuer un nettoyage

  Pour éviter que des frais ne vous soient facturés, supprimez toutes les ressources que vous avez créées.

  1. Supprimez la charge de travail d'inférence :

     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. Nettoyez les ressources :

     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"
     

  Étapes suivantes

  • En savoir plus sur l'inférence de modèles d'IA et de ML sur GKE
  • Analysez les performances et les coûts d'inférence des modèles avec l'outil de démarrage rapide de l'inférence GKE.
  • Explorez le dépôt GitHub accelerated-platforms utilisé pour créer cette architecture.