1. Introduction
Les grands modèles de langage (LLM) modifient la façon dont nous créons des applications intelligentes. Mais il peut être difficile de préparer ces modèles puissants pour une utilisation dans le monde réel. Ils ont besoin de beaucoup de puissance de calcul, en particulier de cartes graphiques (GPU), et de moyens intelligents pour gérer de nombreuses requêtes à la fois. De plus, vous souhaitez limiter les coûts et assurer le bon fonctionnement de votre application sans délai.
Cet atelier de programmation vous montrera comment relever ces défis. Nous utiliserons deux outils clés :
- vLLM : il s'agit d'un moteur ultrarapide pour les LLM. Il permet à vos modèles de s'exécuter beaucoup plus efficacement, en traitant plus de requêtes à la fois et en réduisant l'utilisation de la mémoire.
- Google Cloud Run : plate-forme sans serveur de Google. Il est idéal pour déployer des applications, car il gère toute la mise à l'échelle pour vous, de zéro à des milliers d'utilisateurs, et inversement. Mieux encore, Cloud Run est désormais compatible avec les GPU, qui sont essentiels pour héberger des LLM.
Ensemble, vLLM et Cloud Run offrent un moyen puissant, flexible et économique de diffuser vos LLM. Dans ce guide, vous allez déployer un modèle ouvert et le rendre disponible en tant qu'API Web standard.
Points abordés :
- Comment choisir la taille et la variante de modèle appropriées pour la diffusion.
- Configurer vLLM pour diffuser des points de terminaison d'API compatibles avec OpenAI
- Découvrez comment conteneuriser le serveur vLLM avec Docker.
- Transférer votre image de conteneur vers Google Artifact Registry
- Découvrez comment déployer le conteneur sur Cloud Run avec l'accélération du GPU.
- Comment tester votre modèle déployé.
Ce dont vous avez besoin** :
- Un navigateur, tel que Chrome, pour accéder à la console Google Cloud
- Une connexion Internet fiable
- Un projet Google Cloud avec facturation activée
- Un jeton d'accès Hugging Face (cliquez ici pour en créer un si vous n'en avez pas encore)
- Connaissances de base de Python, Docker et de l'interface de ligne de commande
- Un esprit curieux et une soif d'apprendre
2. Avant de commencer
Configurer un projet Google Cloud
Cet atelier de programmation nécessite un projet Google Cloud associé à un compte de facturation actif.
- Pour les sessions animées par un instructeur : si vous êtes en classe, votre instructeur vous fournira les informations nécessaires sur le projet et la facturation. Suivez les instructions de votre instructeur pour terminer la configuration.
- Pour les apprenants indépendants : si vous effectuez cette opération seul, vous devrez configurer un nouveau projet et activer un compte de facturation d'essai. Pour commencer, suivez les étapes ci-dessous.
- Ouvrez une fenêtre de navigation privée en appuyant sur Ctrl+Maj+N ou Cmd+Maj+N.
- Accédez à ce portail d'échange depuis la fenêtre de navigation privée.
- Connectez-vous et obtenez un compte de facturation d'essai avec votre compte Gmail personnel.
- Suivez les instructions de cette présentation pour terminer la configuration.
Configurer Cloud Shell
Nous allons maintenant configurer Cloud Shell, une interface de ligne de commande pratique directement dans la console Google Cloud.
Lancer Cloud Shell
En haut à droite de la console Google Cloud, vous verrez une icône en forme de terminal (>_). Cliquez dessus pour activer Cloud Shell.
Autoriser l'accès
Si vous y êtes invité, cliquez sur Autoriser pour accorder à Cloud Shell les autorisations nécessaires pour interagir avec votre projet Google Cloud.
Vérifier l'ID du projet
Examinez le Project ID dans votre terminal. Il sera écrit en jaune, comme illustré sur l'image ci-dessous. Assurez-vous qu'il s'agit du même ID que celui que vous avez enregistré lorsque vous avez créé le projet.
Si Project ID s'affiche correctement dans le terminal, passez à l'étape Activer les API nécessaires.
ID de projet correct (si nécessaire)
Si le Project ID est incorrect ou ne s'affiche pas du tout, utilisez cette commande pour le corriger. Veillez à remplacer le texte your-project-id par votre Project ID correct avant d'exécuter la commande.
gcloud config set project your-project-id
Activer les API nécessaires
Pour utiliser les services Google Cloud tels que Cloud Run, vous devez d'abord activer leurs API respectives pour votre projet. Exécutez les commandes suivantes dans Cloud Shell pour activer les services nécessaires à cet atelier de programmation :
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com
3. Choisir le bon modèle
Vous trouverez de nombreux modèles ouverts sur des sites Web tels que Hugging Face Hub et Kaggle. Lorsque vous souhaitez utiliser l'un de ces modèles sur un service tel que Google Cloud Run, vous devez en choisir un qui correspond aux ressources dont vous disposez (c'est-à-dire un GPU NVIDIA L4).
Au-delà de la taille, n'oubliez pas de tenir compte de ce que le modèle peut réellement faire. Les modèles ne sont pas tous identiques : chacun a ses propres avantages et inconvénients. Par exemple, certains modèles peuvent gérer différents types d'entrées (comme des images et du texte, ce qu'on appelle des capacités multimodales), tandis que d'autres peuvent mémoriser et traiter plus d'informations à la fois (ce qui signifie qu'ils disposent de fenêtres de contexte plus grandes). Les modèles plus volumineux disposent souvent de fonctionnalités plus avancées, comme l'appel de fonction et la réflexion.
Il est également important de vérifier si le modèle souhaité est compatible avec l'outil de diffusion (vLLM dans ce cas). Vous pouvez consulter tous les modèles compatibles avec vLLM ici.
Explorons maintenant Gemma 3, la toute nouvelle famille de grands modèles de langage (LLM) de Google, disponible publiquement. Gemma 3 est disponible en quatre échelles différentes en fonction de leur complexité, mesurée en paramètres : 1 milliard, 4 milliards, 12 milliards et 27 milliards.
Pour chacune de ces tailles, vous trouverez deux types principaux :
- Version de base (pré-entraînée) : il s'agit du modèle de fondation qui a appris à partir d'une quantité massive de données.
- Version optimisée pour les instructions : cette version a été affinée pour mieux comprendre et suivre des instructions ou des commandes spécifiques.
Les modèles plus grands (4, 12 et 27 milliards de paramètres) sont multimodaux, ce qui signifie qu'ils peuvent comprendre et traiter à la fois des images et du texte. La plus petite variante de 1 milliard de paramètres se concentre toutefois uniquement sur le texte.
Pour cet atelier de programmation, nous utiliserons 1 milliard de variantes de Gemma 3 : gemma-3-1b-it. L'utilisation d'un modèle plus petit vous aide également à apprendre à travailler avec des ressources limitées, ce qui est important pour réduire les coûts et vous assurer que votre application s'exécute correctement dans le cloud.
4. Variables d'environnement et secrets
Créer un fichier d'environnement
Avant de continuer, il est judicieux de regrouper toutes les configurations que vous utiliserez tout au long de cet atelier de programmation. Pour commencer, ouvrez votre terminal et procédez comme suit :
- Créez un dossier pour ce projet.
- Accédez au dossier que vous venez de créer.
- Créez un fichier .env vide dans ce dossier (ce fichier contiendra ultérieurement vos variables d'environnement).
Voici la commande à exécuter pour effectuer ces étapes :
mkdir vllm-gemma3
cd vllm-gemma3
touch .env
Ensuite, copiez les variables listées ci-dessous et collez-les dans le fichier.env que vous venez de créer. N'oubliez pas de remplacer les valeurs des espaces réservés (your_project_id et your_region) par les informations spécifiques à votre projet. Par exemple, PROJECT_ID=unique-ai-project et REGION=us-central1
PROJECT_ID=your_project_id
REGION=your_region
MODEL_PROVIDER=google
MODEL_VARIANT=gemma-3-1b-it
MODEL_NAME=${MODEL_PROVIDER}/${MODEL_VARIANT}
AR_REPO_NAME=vllm-gemma3-repo
SERVICE_NAME=${MODEL_VARIANT}-service
IMAGE_NAME=${REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/${SERVICE_NAME}
SERVICE_ACC_NAME=${SERVICE_NAME}-sa
SERVICE_ACC_EMAIL=${SERVICE_ACC_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
Une fois le fichier.env modifié et enregistré, saisissez cette commande pour charger ces variables d'environnement dans la session de terminal :
source .env
Vous pouvez vérifier si les variables sont chargées ou non en affichant l'une d'elles. Exemple :
echo $SERVICE_NAME
Si vous obtenez la même valeur que celle que vous avez attribuée dans le fichier.env, cela signifie que les variables ont été chargées correctement.
Stocker un secret dans Secret Manager
Pour toutes les données sensibles, y compris les codes d'accès, les identifiants et les mots de passe, nous vous recommandons d'utiliser un gestionnaire de secrets.
Avant d'utiliser les modèles Gemma 3, vous devez d'abord prendre connaissance des conditions d'utilisation et les accepter, car l'accès est limité. Accédez à la fiche du modèle Gamma3 sur Hugging Face Hub et acceptez les conditions d'utilisation.
Une fois que vous avez obtenu le jeton d'accès Hugging Face, accédez à la page Secret Manager et créez un secret en suivant ces instructions.
- Accédez à la console Google Cloud.
- Sélectionnez le projet dans la barre de menu déroulant en haut à gauche.
- Recherchez Secret Manager dans la barre de recherche, puis cliquez sur cette option lorsqu'elle s'affiche.
Lorsque vous êtes sur la page Secret Manager :
- Cliquez sur le bouton + Créer un secret.
- Renseignez les informations suivantes :
- Name (Nom) : HF_TOKEN
- Valeur du secret : <your_hf_access_token>
- Lorsque vous avez terminé, cliquez sur le bouton Créer un secret.
Vous devriez maintenant disposer du jeton d'accès Hugging Face en tant que secret dans Google Cloud Secret Manager.
Vous pouvez tester votre accès au secret en exécutant la commande ci-dessous dans le terminal. Cette commande le récupérera depuis Secret Manager :
gcloud secrets versions access latest --secret=HF_TOKEN
Votre jeton d'accès devrait être récupéré et affiché dans la fenêtre du terminal.
5. Créer un compte de service
Pour renforcer la sécurité et gérer efficacement l'accès en production, les services doivent fonctionner avec des comptes de service dédiés, strictement limités aux autorisations nécessaires à leurs tâches spécifiques.
Exécutez cette commande pour créer un compte de service.
gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'
La commande suivante associe l'autorisation nécessaire.
gcloud secrets add-iam-policy-binding HF_TOKEN \
--member="serviceAccount:${SERVICE_ACC_EMAIL}" \
--role="roles/secretmanager.secretAccessor"
6. Créer une image sur Artifact Registry
Cette étape consiste à créer une image Docker qui inclut les pondérations du modèle et vLLM préinstallé.
1. Créez un dépôt Docker dans Artifact Registry.
Créons un dépôt Docker dans Artifact Registry pour transférer vos images compilées. Exécutez la commande suivante dans le terminal :
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. Stocker le modèle
En vous basant sur la documentation sur les bonnes pratiques concernant les GPU, vous pouvez stocker les modèles de ML dans des images de conteneur ou optimiser leur chargement à partir de Cloud Storage. Bien sûr, chaque approche a ses avantages et ses inconvénients. Pour en savoir plus, consultez la documentation. Par souci de simplicité, nous allons simplement stocker le modèle dans l'image de conteneur.
3. Créer un fichier Docker
Créez un fichier nommé Dockerfile et copiez-y le contenu ci-dessous :
FROM vllm/vllm-openai:v0.9.0
ARG MODEL_NAME
ARG HF_TOKEN
ENV HF_HOME=/model-cache
ENV MODEL_NAME=${MODEL_NAME}
# Use the HF_TOKEN argument to log in and download the model
RUN huggingface-cli login --token ${HF_TOKEN} && \
huggingface-cli download ${MODEL_NAME}
ENV HF_HUB_OFFLINE=1
EXPOSE 8080
ENTRYPOINT python3 -m vllm.entrypoints.openai.api_server \
--port ${PORT:-8080} \
--model ${MODEL_NAME} \
--gpu-memory-utilization 0.90 \
${MAX_MODEL_LEN:+--max-model-len "$MAX_MODEL_LEN"}
4. Créez un fichier cloudbuild.yaml.
Ensuite, créez un fichier nommé cloudbuild.yaml dans le même répertoire. Ce fichier définit les étapes à suivre pour Cloud Build. Copiez et collez le contenu suivant dans cloudbuild.yaml :
steps:
- name: 'gcr.io/cloud-builders/docker'
entrypoint: 'bash'
args:
- '-c'
- |
docker build \
--build-arg MODEL_NAME=${_MODEL_NAME} \
--build-arg HF_TOKEN=$$HF_TOKEN_SECRET \
-t ${_IMAGE_NAME} .
secretEnv: ['HF_TOKEN_SECRET']
images:
- '${_IMAGE_NAME}'
availableSecrets:
secretManager:
- versionName: projects/${PROJECT_ID}/secrets/HF_TOKEN/versions/latest
env: 'HF_TOKEN_SECRET'
5. Envoyez le build à Cloud Build.
Copiez et collez le code suivant, puis exécutez-le dans le terminal :
gcloud builds submit . \
--config=cloudbuild.yaml \
--region=${REGION} \
--substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}
Cette commande importe votre code (Dockerfile et cloudbuild.yaml), transmet vos variables shell en tant que substitutions (_MODEL_NAME et _IMAGE_NAME) et lance la compilation.
Cloud Build va maintenant exécuter les étapes définies dans cloudbuild.yaml. Vous pouvez suivre les journaux dans votre terminal ou en cliquant sur le lien vers les détails de la compilation dans la console Cloud. Une fois l'opération terminée, l'image de conteneur sera disponible dans votre dépôt Artifact Registry et prête à être déployée.
7. Tester le service
Exécutez la commande suivante dans le terminal pour créer un proxy, afin de pouvoir accéder au service tel qu'il s'exécute dans localhost :
gcloud run services proxy ${SERVICE_NAME} --region ${REGION}
Dans une nouvelle fenêtre de terminal, exécutez la commande curl dans le terminal pour tester la connexion.
curl -X POST http://localhost:8080/v1/completions \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-1b-it",
"prompt": "Cloud Run is a ",
"max_tokens": 128,
"temperature": 0.90
}'
Si un résultat semblable à celui ci-dessous s'affiche :
{"id":"cmpl-e96d05d2893d42939c1780d44233defa","object":"text_completion","created":1746870778,"model":"google/gemma-3-1b-it","choices":[{"index":0,"text":"100% managed Kubernetes service. It's a great option for many use cases.\n\nHere's a breakdown of key features and considerations:\n\n* **Managed Kubernetes:** This means Google handles the underlying infrastructure, including scaling, patching, and maintenance. You don't need to worry about managing Kubernetes clusters.\n* **Serverless:** You only pay for the compute time your application actually uses. No charges when your code isn't running.\n* **Scalability:** Cloud Run automatically scales your application based on demand. You can easily scale up or down to handle fluctuating traffic.\n*","logprobs":null,"finish_reason":"length","stop_reason":null,"prompt_logprobs":null}],"usage":{"prompt_tokens":6,"total_tokens":134,"completion_tokens":128,"prompt_tokens_details":null}}
8. Conclusion
Félicitations ! Vous avez terminé cet atelier de programmation. Vous avez appris à :
- Choisissez une taille de modèle appropriée pour un déploiement cible.
- Configurez vLLM pour qu'il diffuse une API compatible avec OpenAI.
- Intégrez en conteneur de manière sécurisée le serveur vLLM et les pondérations du modèle avec Docker.
- Transférez une image de conteneur vers Google Artifact Registry.
- Déployez un service accéléré par GPU sur Cloud Run.
- Tester un modèle déployé et authentifié
N'hésitez pas à déployer d'autres modèles intéressants comme Llama, Mistral ou Qwen pour poursuivre votre apprentissage.
9. Effectuer un nettoyage
Pour éviter que des frais ne vous soient facturés à l'avenir, il est important de supprimer les ressources que vous avez créées. Exécutez les commandes suivantes pour nettoyer votre projet.
1. Supprimez le service Cloud Run :
gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet
2. Supprimez le dépôt Artifact Registry :
gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet
3. Supprimez le compte de service :
gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet
4. Supprimez le secret de Secret Manager :
gcloud secrets delete HF_TOKEN --quiet