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

Autopilot Standard

Cette page explique comment déployer et diffuser rapidement des grands modèles de langage ouverts populaires (LLM) sur GKE avec des TPU pour l'inférence à l'aide d'une architecture de référence d'inférence GKE préconfigurée et prête pour la production GKE inference reference architecture. 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 à accès restreint que vous souhaitez utiliser (tels que Gemma) sur leur page de modèle Hugging Face respective.

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 que nous citons dans Google Cloud le contenu, consultez Rôles utilisateur et tâches courantes de GKE.

Avant de commencer

Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

• Assurez-vous de disposer des rôles suivants sur le projet : roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.roleAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin, roles/serviceusage.serviceUsageAdmin et roles/secretmanager.secretVersionManager.

  Vérifier les rôles

  1. Dans la Google Cloud console, accédez à la page IAM.

     Accéder à IAM
  2. Sélectionnez le projet.

  3. Dans la colonne Compte principal, recherchez toutes les lignes qui vous identifient ou identifient un groupe dont vous faites partie. Pour savoir à quels groupes vous appartenez, contactez votre administrateur.

  4. Pour toutes les lignes qui vous spécifient ou vous incluent, consultez la colonne Rôle pour vous assurer que la liste inclut les rôles requis.

  Attribuer les rôles

  1. Dans la Google Cloud console, accédez à la page IAM.

     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. Cliquez sur Sélectionner un rôle, puis recherchez le 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 quota TPU (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 à accès restreint que vous souhaitez utiliser (tels que Gemma) sur leur page de modèle Hugging Face respective.

Pour accéder au modèle depuis 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 Your Profile > Settings > Access Tokens (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 Read (Lecture).
4. Sélectionnez Generate a token (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 des commandes. Cloud Shell est préinstallé avec les outils nécessaires, y compris gcloud, kubectl et git.

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

Ouvrir Cloud Shell

Cette action lance une session dans le volet inférieur de la Google Cloud console.

Déployer l'architecture de base

Pour provisionner le cluster GKE et les ressources nécessaires pour accéder aux modèles depuis 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 : votre Google Cloud ID de projet.
   • HF_TOKEN: le jeton Hugging Face que vous avez généré précédemment.

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

   Pour mettre à jour la version de Terraform dans Cloud Shell, vous pouvez exécuter le script suivant. Ce script installe l'tfswitch outil et Terraform v1.8.0 dans votre répertoire personnel. Suivez les instructions du script pour définir la variable d'environnement nécessaire ou transmettre 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 requises Google Cloud 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 GKE 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 de 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 obtenir des configurations supplémentaires, y compris d'autres variantes de modèle et types de TPU, consultez les fichiers manifestes disponibles dans le accelerated-platforms dépôt GitHub.

Télécharger le modèle

1. Récupérez les variables d'environnement à partir de votre déploiement. Ces variables d'environnement contiennent les détails 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écharge 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 du 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 la tâche de téléchargement du modèle Hugging Face jusqu'à ce qu'elle soit terminée.

   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 la tâche de téléchargement du modèle Hugging Face est terminée.

   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. Récupérez 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 voir 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"
   

Étape suivante

• 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 GKE Inference Quickstart.
• Explorez le dépôt GitHub accelerated-platforms utilisé pour créer cette architecture.