Étiquettes de métadonnées personnalisées

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

Qu'est-ce qu'une étiquette ?

Une étiquette est une paire clé-valeur que vous pouvez attribuer aux appels d'API tels que generateContent et rawPredict. 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 leurs étiquettes. 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. 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 pour les modèles Google et jusqu'à 32 étiquettes pour les modèles de 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 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 créer autant de clés d'étiquette 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 y 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:research et team:analytics). Vous pouvez utiliser ce type d'étiquette pour la comptabilité 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).

Nous vous déconseillons de créer un grand nombre 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 les clés encombrent le catalogue, augmentent considérablement les temps de chargement lors des requêtes et rendent difficile le filtrage et la création de rapports efficaces sur les appels d'API.

Modèles compatibles

La possibilité d'ajouter des étiquettes à une requête est disponible pour les modèles Google et un sous-ensemble de modèles de partenaires. Si vous ajoutez des étiquettes à une requête pour un modèle non compatible, la requête génère une erreur.

Ajouter une étiquette à un appel d'API de modèle Google

Pour ajouter une étiquette à un appel d'API generateContent ou streamGenerateContent, procédez comme suit :

cat > request.json << 'EOF'
{
  "contents": {
    "role": "ROLE",
    "parts": { "text": "PROMPT_TEXT" }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
}
EOF

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"

@'
{
  "contents": {
    "role": "ROLE",
    "parts": { "text": "PROMPT_TEXT" }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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

{
  "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
  }
}

import os

from google import genai

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("LOCATION_ID")
GEMINI_MODEL = os.getenv("GEMINI_MODEL_ID", "gemini-2.5-flash")


def generate_content() -> genai.types.GenerateContentResponse:

    genai_client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

    labels = {
        "environment": "testing",
        "feature": "genai",
        "model": "gemini",
    }

    config = genai.types.GenerateContentConfig(temperature=0.4, labels=labels)

    response = genai_client.models.generate_content(
        model=GEMINI_MODEL, contents="What is Generative AI?", config=config
    )

    print(response.text)
    return response

Cloud de Confiance by S3NS Les produits 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 servicesCloud de Confiance by S3NS 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 à un appel d'API de modèle de partenaire

Pour ajouter une étiquette à un appel d'API rawPredict ou streamRawPredict, procédez comme suit :

cat > request.json << 'EOF'
{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "user",
      "content": "What is Generative AI?"
    }
  ],
  "max_tokens": 1024,
  "stream": false
}
EOF

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"

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"))