Étiquettes de métadonnées personnalisées

Vous pouvez ajouter des métadonnées personnalisées aux appels d'API generateContent et streamGenerateContent à 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.

Qu'est-ce qu'une étiquette ?

Une étiquette est une paire clé-valeur que vous pouvez attribuer aux appels d'API generateContent et streamGenerateContent. Les étiquettes vous aident à organiser ces appels et à gérer 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 facturation afin que vous puissiez analyser vos frais en fonction des étiquettes. 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.

Exigences relatives aux étiquettes

Les étiquettes appliquées à un appel d'API doivent répondre aux exigences suivantes :

  • Vous pouvez appliquer jusqu'à 64 étiquettes à chaque appel d'API.
  • 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 appliquer autant d'étiquettes que vous le souhaitez à tous les appels d'API d'un projet.

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:research et team: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:ingest et component:dashboard.

  • Étiquettes d'environnement ou d'étape : par exemple, environment:production et environment:test.

  • Étiquettes de propriété : permettent d'identifier les équipes responsables des opérations (par exemple, team:shopping-cart).

Nous vous déconseillons de créer de nombreuses étiquettes uniques (par exemple, pour les codes temporels ou les valeurs individuelles de chaque appel d'API). Le problème avec cette approche est que lorsque les valeurs changent fréquemment ou que des clés encombrent le catalogue, il est difficile de filtrer efficacement les appels d'API et de créer des rapports.

Ajouter une étiquette à un appel d'API

Pour ajouter une étiquette à un appel d'API generateContent ou streamGenerateContent, 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. Les options disponibles incluent les suivantes :

    Cliquer pour développer la liste partielle des régions disponibles

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • 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.
  • PROMPT_TEXT
     Instructions textuelles à inclure dans la requête. JSON
  • 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"
  },
}
EOF

Exé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 utf8

Exé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 de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI pour Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

import vertexai

from vertexai.generative_models import GenerativeModel

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel("gemini-2.0-flash-001")

prompt = "What is Generative AI?"
response = model.generate_content(
    prompt,
    # Example Labels
    labels={
        "team": "research",
        "component": "frontend",
        "environment": "production",
    },
)

print(response.text)
# Example response:
# Generative AI is a type of Artificial Intelligence focused on **creating new content** based on existing data.

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.