É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 répartir les frais facturés.

Qu'est-ce qu'un libellé ?

Une étiquette est une paire clé-valeur que vous pouvez attribuer aux appels d'API generateContent et streamGenerateContent. Elle vous aide à 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. Ainsi, vous pouvez trier 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.

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.
• Chaque libellé 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 au sein d'un seul appel d'API. Cependant, vous pouvez utiliser la même clé 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 l'équipe ou le centre 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é analytique ou la budgétisation.

• Libellés de composant : par exemple, component:redis, component:frontend, component:ingest et component:dashboard.

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

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

Remarque : Ne faites pas figurer des informations sensibles dans les étiquettes, y compris des informations permettant d'identifier personnellement l'utilisateur telles que le nom ou le titre d'une personne. Les étiquettes ne sont pas conçues pour gérer des informations sensibles.

Nous vous déconseillons de créer beaucoup d'é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 associés.

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 ci-dessous, effectuez les remplacements suivants :

• GENERATE_RESPONSE_METHOD : type de réponse que le modèle doit générer. Choisissez une méthode qui génère le mode de renvoi de la réponse du modèle :
  • streamGenerateContent : la réponse est affichée progressivement à mesure qu'elle est générée afin de réduire la perception de la latence auprès d'un public humain.
  • 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 sont les suivantes :

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

  • us-central1
  • us-west4
  • northamerica-northeast1
  • us-east4
  • us-west1
  • asia-northeast3
  • asia-southeast1
  • asia-northeast1
• PROJECT_ID : l'ID de votre projet.
• MODEL_ID : ID du modèle multimodal que vous souhaitez utiliser. Voici quelques options possibles :
  • gemini-1.0-pro-002
  • gemini-1.0-pro-vision-001
  • gemini-1.5-pro-002
  • gemini-1.5-flash
• 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 envoyé par vous.
  • 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

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

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

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

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.

Réponse

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": Generative AI is a type of artificial intelligence (AI) that can **create new
            content**, like text, images, audio, video, and even code.
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.037841797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.06347656
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.053466797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.08496094
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08154297,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.033203125
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.071777344,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.083984375
        }
      ],
      "avgLogprobs": -0.40486351219383448
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 555,
    "totalTokenCount": 560
  }
}

Les produits Google Cloud transmettent les données d'utilisation et de coût aux processus Cloud Billing à des intervalles variables. Par conséquent, vous pouvez constater un délai entre votre utilisation des services Google Cloud, et la disponibilité des données d'utilisation et de coût pour l'affichage dans Cloud Billing. Généralement, vos coûts sont disponibles dans la journée, mais ils peuvent parfois prendre plus de 24 heures.