Vous pouvez ajouter des métadonnées personnalisées aux appels d'API tels que generateContent, interactions.create et rawPredict à l'aide d'étiquettes. Cette page explique ce que sont les étiquettes et vous montre comment les utiliser pour décomposer les frais qui vous sont facturés.
À propos des libellés
Une étiquette est une paire clé-valeur que vous pouvez attribuer aux appels d'API tels que generateContent, interactions.create et rawPredict. Elles vous aident à organiser ces appels et à gérer votre utilisation et vos coûts à grande échelle, avec la précision dont vous avez besoin. Vous pouvez associer une étiquette à chaque appel, puis filtrer les appels en fonction de leur étiquette. Les informations sur les étiquettes sont transmises au système de journalisation et de facturation. Ainsi, vous pouvez trier votre utilisation et vos frais facturés par étiquette. Grâce aux rapports de facturation intégrés, vous pouvez filtrer et regrouper les coûts par étiquette. Vous pouvez également utiliser des étiquettes pour interroger les exportations de données de facturation.
Pour découvrir comment utiliser des étiquettes, consultez un exemple sur la page de présentation des étiquettes.
Agent Platform accepte deux types d'étiquettes : les étiquettes de corps de requête, qui atteignent Cloud Billing, et les étiquettes d'en-tête, qui apparaissent dans les journaux de métadonnées des requêtes d'inférence. La section suivante les compare.
Choisissez une étiquette en fonction de votre cas d'utilisation
Agent Platform propose deux mécanismes d'étiquetage. Vous les définissez différemment, ils atteignent des destinations différentes et ils apparaissent dans différents champs du journal des métadonnées de la requête d'inférence. Vous pouvez utiliser l'un ou l'autre, ou les deux dans la même requête, si possible.
Les libellés du corps de la requête fonctionnent comme suit :
- Vous les définissez dans le champ
labelsdu corps de la requête. - Elles atteignent les journaux de métadonnées des requêtes d'inférence et Cloud Billing.
- Elles apparaissent dans le champ
labelsde l'entrée de journal. - Compatible avec le trafic de paiement à l'usage.
- Pour les modèles partenaires tels que Claude, les étiquettes de requête sont envoyées dans l'en-tête
X-Vertex-AI-Labelsau lieu du corps de la requête. Elles atteignent Cloud Billing, mais ne sont pas écrites dans le journal des métadonnées de la requête d'inférence.
Les libellés d'en-tête fonctionnent comme suit :
- Vous les définissez dans l'en-tête de requête
x-goog-agent-platform-observability-label-KEY. - Ils n'atteignent que les journaux de métadonnées des requêtes d'inférence.
- Elles apparaissent dans le champ
jsonPayload.httpHeadersde l'entrée de journal. - Méthodes d'API compatibles :
generateContentetstreamGenerateContentpour les modèles Gemini, etrawPredictetstreamRawPredictpour les modèles Claude. Options de consommation compatibles : débit provisionné et toutes les options de paiement à l'usage proposées par le modèle.
Rechercher chaque étiquette dans l'entrée de journal
Une même requête peut contenir les deux. La requête suivante définit un élément de chaque type :
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-pro:generateContent
x-goog-agent-platform-observability-label-team: payments
{
"labels": {"cost_center": "cc-1234"},
"contents": [{"role": "user", "parts": [{"text": "..."}]}]
}
Les deux étiquettes se trouvent dans des champs différents de la même entrée de journal :
{
"labels": {
"gen_ai.operation.name": "generate_content",
"cost_center": "cc-1234"
},
"jsonPayload": {
"httpHeaders": {
"x-goog-agent-platform-observability-label-team": {
"values": ["payments"]
}
}
}
}
Les deux types d'étiquettes occupent des champs différents. Vous les interrogez donc différemment. Dans l'explorateur de journaux :
labels.cost_center="cc-1234"
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"
Dans Analyse de l'observabilité :
JSON_VALUE(labels.cost_center) AS cost_center,
JSON_VALUE(json_payload.httpHeaders
["x-goog-agent-platform-observability-label-team"].values[0]) AS team
Fonctionnement des libellés d'en-tête
Les étiquettes d'en-tête font partie de la journalisation des métadonnées des requêtes d'inférence. Pour les capturer, activez les journaux de métadonnées des requêtes d'inférence pour le projet.
Envoyez un en-tête par étiquette, en utilisant le préfixe réservé. Le préfixe n'est pas sensible à la casse :
x-goog-agent-platform-observability-label-KEY: VALUE
Exemple :
x-goog-agent-platform-observability-label-team: payments
x-goog-agent-platform-observability-label-application: invoice-ocr
Chaque en-tête apparaît dans l'entrée de journal sous jsonPayload.httpHeaders, avec pour clé le nom de l'en-tête en minuscules, et la valeur dans un tableau values, comme indiqué dans Rechercher chaque étiquette dans l'entrée de journal.
Agent Platform capture également un petit ensemble de ses propres en-têtes : x-vertex-ai-llm-request-type et x-vertex-ai-llm-shared-request-type. Aucun autre en-tête n'est capturé.
Les libellés d'en-tête fonctionnent de la même manière pour Gemini et Claude. Ils vous permettent d'étiqueter les requêtes Claude dans le journal des métadonnées des requêtes d'inférence.
Limites pour les libellés d'en-tête
- Une seule requête écrit au maximum 32 en-têtes. Si d'autres sont éligibles, Agent Platform les conserve par ordre alphabétique croissant et supprime les autres. La suppression est silencieuse.
- Une valeur d'en-tête de plus de 1 024 octets est tronquée, et la troncature est marquée dans la valeur stockée.
- Les en-têtes répétés portant le même nom sont combinés en une seule entrée avec plusieurs valeurs.
Pour interroger les étiquettes d'en-tête, consultez Utilisation par étiquette d'en-tête personnalisée.
Exigences relatives aux étiquettes
Les étiquettes appliquées à un appel d'API doivent répondre aux exigences suivantes :
- Chaque appel d'API peut comporter jusqu'à 64 étiquettes pour les modèles Google et jusqu'à 32 étiquettes pour les modèles partenaires.
- Chaque étiquette doit correspondre à une paire clé/valeur.
- Les clés doivent comporter un (1) caractère au minimum et 63 au maximum, et ne peuvent pas être vides. Les valeurs peuvent être vides et comporter 63 caractères au maximum.
- Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets. Tous les caractères doivent être au format d'encodage UTF-8. Les caractères internationaux sont autorisés. Les clés doivent commencer par une lettre minuscule ou un caractère international.
- La partie clé d'une étiquette doit être unique dans un appel d'API. Cependant, vous pouvez utiliser la même clés avec plusieurs appels.
Ces limites s'appliquent à la clé et à la valeur de chaque étiquette, ainsi qu'à l'appel d'API individuel associé à des étiquettes. Vous pouvez créer autant de clés d'étiquettes que vous le souhaitez pour tous les appels d'API d'un projet. Chaque clé d'étiquette peut comporter jusqu'à 1 000 valeurs uniques pour toutes les requêtes pendant la durée de vie du compte de facturation associé. La clé d'étiquette peut être supprimée sans préavis si plus de 1 000 valeurs uniques lui sont associées.
Cas d'utilisation courants des étiquettes
Voici quelques cas d'utilisation courants des étiquettes :
Étiquettes d'équipe ou de centre de coûts : ajoutez des étiquettes basées sur des équipes ou des centres de coûts pour distinguer les appels d'API appartenant à différentes équipes (par exemple,
team:researchetteam:analytics). Vous pouvez utiliser ce type d'étiquette pour la comptabilité ou la budgétisation.Étiquettes de composant : par exemple,
component:redis,component:frontend,component:ingestetcomponent:dashboard.Étiquettes d'environnement ou d'étape : par exemple,
environment:productionetenvironment:test.Étiquettes de propriété : permettent d'identifier les équipes responsables des opérations (par exemple,
team:shopping-cart).Attribution des abus des utilisateurs finaux (
safety_identifier) : associez un ID utilisateur anonymisé par utilisateur (par exemple,safety_identifier:user_session_001) aux appels Gemini et Veo afin que les commentaires sur les règles ciblent des utilisateurs finaux spécifiques plutôt que l'ensemble de votre projet. Pour connaître les règles de mise en forme et obtenir des exemples, consultez Transmettre un identifiant de sécurité de l'utilisateur final dans les appels d'API.
Évitez de créer de nombreuses étiquettes uniques (par exemple, pour les codes temporels ou les valeurs individuelles de chaque appel d'API). La création d'un grand nombre de clés uniques encombre le catalogue, augmente considérablement les temps de chargement lors des requêtes et complique le filtrage et la création de rapports sur les appels d'API.
Modèles compatibles pour les étiquettes de requête
Les étiquettes de requête et d'en-tête sont compatibles avec différents modèles. La possibilité d'ajouter des étiquettes de requête à une requête est compatible avec les modèles Google et un sous-ensemble de modèles partenaires. Si vous ajoutez des étiquettes de requête à une requête pour un modèle non compatible, la requête génère une erreur. Les modèles Google acceptent les étiquettes de requête dans le champ labels du corps de la requête. Les modèles partenaires les acceptent dans l'en-tête X-Vertex-AI-Labels.
Modèles Google
Les modèles Google sont compatibles avec les étiquettes sur les méthodes d'API suivantes :
generateContentstreamGenerateContentpredictLongRunning(génération de vidéos Veo)interactions.create
Modèles de partenaires
Les modèles partenaires sont compatibles avec les étiquettes sur les méthodes d'API suivantes :
rawPredictstreamRawPredict
Les modèles partenaires suivants sont compatibles avec les étiquettes :
Les étiquettes ne sont transmises à Cloud Billing que lorsque la requête utilise l'option de consommation PayGo. Les requêtes utilisant l'option de consommation Débit provisionné ignorent silencieusement les étiquettes envoyées dans la requête.
Modèles compatibles pour les étiquettes d'en-tête
Les étiquettes d'en-tête ne sont écrites que dans le journal des métadonnées de la requête d'inférence. Elles fonctionnent donc sur les modèles et les méthodes enregistrés par le journal.
- Modèles Gemini :
generateContentetstreamGenerateContent. - Modèles Claude :
rawPredictetstreamRawPredict. - Options de consommation : débit provisionné et toutes les options de paiement à l'usage proposées par le modèle.
- Les autres modèles partenaires, y compris Mistral AI, ne sont pas compatibles. Une requête envoyée avec des étiquettes d'en-tête aboutit, mais aucune entrée de journal n'est écrite. Les étiquettes ne sont donc enregistrées nulle part.
- Les libellés d'en-tête ne parviennent jamais à Cloud Billing. Pour ventiler les frais facturés, utilisez des étiquettes de requête.
Ajouter une étiquette de requête à un appel d'API de modèle Google
Pour ajouter une étiquette à un appel d'API generateContent, streamGenerateContent ou interactions.create, procédez comme suit :
REST
Avant d'utiliser les données de requête, remplacez les éléments suivants :
GENERATE_RESPONSE_METHOD: type de réponse que le modèle doit générer. Choisissez la méthode de renvoi de la réponse du modèle :streamGenerateContent: la réponse s'affiche progressivement à mesure qu'elle est générée afin que les utilisateurs ressentent moins la latence.generateContent: la réponse est renvoyée une fois qu'elle a été entièrement générée.
LOCATION: région dans laquelle traiter la requête.PROJECT_ID: ID de votre projet. .MODEL_ID: ID du modèle que vous souhaitez utiliser.ROLE: rôle dans une conversation associée au contenu. La spécification d'un rôle est requise, même dans les cas d'utilisation à un seul tour. Les valeurs acceptées incluent les suivantes :USER: spécifie le contenu que vous envoyez.MODEL: spécifie la réponse du modèle.
Instructions textuelles à inclure dans le prompt. JSONPROMPT_TEXT
LABEL_KEY: métadonnées de l'étiquette que vous souhaitez associer à cet appel d'API.LABEL_VALUE: valeur de l'étiquette.
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json.
Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :
cat > request.json << 'EOF'
{
"contents": {
"role": "ROLE",
"parts": { "text": "PROMPT_TEXT" }
},
"labels": {
"LABEL_KEY": "LABEL_VALUE"
},
}
EOFExécutez ensuite la commande suivante pour envoyer votre requête REST :
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"
PowerShell
Enregistrez le corps de la requête dans un fichier nommé request.json.
Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :
@'
{
"contents": {
"role": "ROLE",
"parts": { "text": "PROMPT_TEXT" }
},
"labels": {
"LABEL_KEY": "LABEL_VALUE"
},
}
'@ | Out-File -FilePath request.json -Encoding utf8Exécutez ensuite la commande suivante pour envoyer votre requête REST :
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON semblable à la suivante.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.
Pour vous authentifier auprès d'Agent Platform, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Les produitsGoogle Cloud transmettent à des intervalles variables les données d'utilisation et de coût aux processus Cloud Billing. Par conséquent, vous pouvez constater un décalage entre votre utilisation des servicesGoogle Cloud et la disponibilité des données d'utilisation et de coût dans Cloud Billing. Généralement, vos coûts sont affichés dans la journée, mais cela peut parfois prendre plus de 24 heures.
Ajouter une étiquette de requête à un appel d'API de modèle partenaire
Pour ajouter une étiquette à un appel d'API rawPredict ou streamRawPredict, procédez comme suit :
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
PROJECT_ID: ID du projet.MODEL_ID: ID du modèle que vous souhaitez utiliser. Exemple :claude-opus-4-6.
Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :
cat > request.json << 'EOF'
{
"anthropic_version": "vertex-2023-10-16",
"messages": [
{
"role": "user",
"content": "What is Generative AI?"
}
],
"max_tokens": 1024,
"stream": false
}
EOF
Exécutez ensuite la commande suivante pour envoyer votre requête REST :
REQUEST_LABELS=$(echo -n '{"team": "research", "component": "frontend"}' | base64 --wrap 0)
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "X-Vertex-AI-Labels: ${REQUEST_LABELS}" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL_ID:rawPredict"
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.
Pour vous authentifier auprès d'Agent Platform, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
PROJECT_ID: ID du projet.MODEL_ID: ID du modèle que vous souhaitez utiliser. Exemple :claude-opus-4-6.
import base64 import json from google.cloud.aiplatform import aiplatform_v1 from google.api import httpbody_pb2 project_id = "PROJECT_ID" model_id = "MODEL_ID" request_body = { "anthropic_version": "vertex-2023-10-16", "messages": [{ "role": "user", "content": [{"type": "text", "text": "What is Generative AI?"}] }], "max_tokens": 256, "stream": True, } # Encode labels to base64 for the X-Vertex-AI-Labels header labels = { "team": "research", "component": "frontend", "environment": "production", } labels_json = json.dumps(labels).encode("utf-8") vertex_header_value = base64.b64encode(labels_json) endpoint_id=f"projects/{project_id}/locations/global/publishers/anthropic/models/{model_id}" client = aiplatform_v1.PredictionServiceClient() responses = client.stream_raw_predict( request=aiplatform_v1.StreamRawPredictRequest( endpoint=endpoint_id, http_body=httpbody_pb2.HttpBody( data=json.dumps(request_body).encode("utf-8"), content_type="application/json", ), ), metadata=[("x-vertex-ai-labels", vertex_header_value)], ) for response in responses: print(response.data.decode("utf-8"))
Ajouter des étiquettes d'en-tête aux appels d'API
Les libellés d'en-tête ne nécessitent aucune modification du corps de la requête. Ajoutez un en-tête x-goog-agent-platform-observability-label-KEY par étiquette à toute requête compatible. Les exemples suivants montrent la requête et les champs résultants de l'entrée de journal des métadonnées de la requête d'inférence, à partir de requêtes de test effectuées le 14/10/2026.
Ajouter des étiquettes d'en-tête à un appel d'API de modèle Gemini
Envoyez les libellés d'en-tête avec generateContent ou streamGenerateContent. Remplacez PROJECT_ID par l'ID de votre projet.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-agent-platform-observability-label-team: payments" \
-H "x-goog-agent-platform-observability-label-application: invoice-ocr" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" \
-d '{"contents": [{"role": "user", "parts": [{"text": "What is Generative AI?"}]}]}'
L'entrée de journal enregistre chaque étiquette sous jsonPayload.httpHeaders. Les libellés d'en-tête sont également enregistrés sur le trafic de débit provisionné, ce que les libellés de requête ne permettent pas :
{
"method": "GENERATE_CONTENT",
"trafficType": "PROVISIONED_THROUGHPUT",
"httpHeaders": {
"x-goog-agent-platform-observability-label-application": {"values": ["invoice-ocr"]},
"x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
},
"generateContentDetails": {"usageMetadata": {"promptTokenCount": 6, "candidatesTokenCount": 1, "totalTokenCount": 7}},
"provisionedThroughput": {"accountingResource": "projects/PROJECT_NUMBER", "ptChargedInputTokenCount": "6", "ptChargedOutputTokenCount": "9"}
}
Ajouter des étiquettes d'en-tête à un appel d'API de modèle Claude
Envoyez les libellés d'en-tête avec rawPredict ou streamRawPredict. Remplacez PROJECT_ID et MODEL_ID, par exemple claude-opus-4-6.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-agent-platform-observability-label-team: payments" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL_ID:rawPredict" \
-d '{"anthropic_version": "vertex-2023-10-16", "messages": [{"role": "user", "content": "What is Generative AI?"}], "max_tokens": 256}'
L'entrée de journal enregistre l'étiquette sous jsonPayload.httpHeaders, à côté du nombre de jetons de Claude :
{
"method": "RAW_PREDICT",
"trafficType": "ON_DEMAND",
"httpHeaders": {
"x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
},
"rawPredictDetails": {"usageMetadata": {"input_tokens": 17, "output_tokens": 16, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}
}
Une requête Claude peut également comporter des étiquettes de requête dans l'en-tête X-Vertex-AI-Labels, comme indiqué dans Ajouter une étiquette de requête à un appel d'API de modèle partenaire.
Elles atteignent Cloud Billing, mais ne sont pas écrites dans l'entrée de journal.
Libellés d'en-tête de requête
Dans l'explorateur de journaux, filtrez sur une valeur d'étiquette d'en-tête :
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"
Dans l'Analyse de l'observabilité, regroupez les données par étiquette d'en-tête à l'aide de la requête Utilisation par étiquette d'en-tête personnalisée sur la page Consigner les métadonnées de requête d'inférence.