Benutzerdefinierte Metadatenlabels

Sie können API-Aufrufen wie generateContent und rawPredict mithilfe von Labels benutzerdefinierte Metadaten hinzufügen. Auf dieser Seite wird erläutert, was Labels sind und wie Sie damit Ihre in Rechnung gestellten Kosten aufschlüsseln können.

Was sind Labels?

Ein Label ist ein Schlüssel/Wert-Paar, das Sie API-Aufrufen wie generateContent und rawPredict zuweisen können. Clusterlabels helfen Ihnen dabei, diese Aufrufe zu organisieren und Ihre Nutzung und Kosten in großem Umfang mit der erforderlichen Detailgenauigkeit zu verwalten. Sie können jedem Aufruf ein Label zuweisen und dann die Aufrufe nach ihren Labels filtern. Informationen zu Labels werden an das Logging- und Abrechnungssystem weitergeleitet, sodass Sie die Nutzung und die abgerechneten Gebühren nach Label aufschlüsseln können. Dank integrierter Abrechnungsberichte können Sie Kosten nach Labels filtern und gruppieren. Sie können Labels auch verwenden, um Abrechnungsdatenexporte abzufragen. Informationen zur Verwendung von Labels nach der Erstellung finden Sie in einem Beispiel in der Labelübersicht.

Die Agent Platform unterstützt zwei Arten von Labels: Anfrage-Body-Labels, die Cloud Billing erreichen, und Header-Labels, die in Metadatenlogs für Inferenzanfragen angezeigt werden. Im nächsten Abschnitt werden sie verglichen.

Label für Ihren Anwendungsfall auswählen

Die Agent Platform bietet zwei Labelmechanismen. Sie werden unterschiedlich festgelegt, erreichen unterschiedliche Ziele und werden in verschiedenen Feldern des Metadatenlogs der Inferenzanfrage angezeigt. Sie können beide oder nur einen der beiden Ansätze für dieselbe Anfrage verwenden, sofern dies unterstützt wird.

Labels im Anfragetext funktionieren so:

  • Sie legen sie im Feld labels des Anfragetexts fest.
  • Sie erreichen Cloud Billing- und Inferenzanfrage-Metadatenlogs.
  • Sie werden im Feld labels des Logeintrags angezeigt.
  • Wird für „Pay as you go“-Traffic unterstützt.
  • Bei Partnermodellen wie Claude werden Anfragelabels im Header X-Vertex-AI-Labels anstelle des Anfragetexts gesendet. Sie erreichen Cloud Billing, werden aber nicht in das Metadatenlog für Inferenzanfragen geschrieben.

Header-Labels funktionieren so:

  • Sie legen sie im Anfrageheader x-goog-agent-platform-observability-label-KEY fest.
  • Sie erreichen nur Metadatenlogs für Inferenzanfragen.
  • Sie werden im Feld jsonPayload.httpHeaders des Logeintrags angezeigt.
  • Unterstützte API-Methoden: generateContent und streamGenerateContent für Gemini-Modelle sowie rawPredict und streamRawPredict für Claude-Modelle. Unterstützte Verbrauchsoptionen: Bereitgestellter Durchsatz und alle Pay-as-you-go-Optionen, die das Modell bietet.

Jedes Label im Logeintrag finden

Eine einzelne Anfrage kann beides enthalten. Mit der folgenden Anfrage wird jeweils eine Option festgelegt:

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": "..."}]}]
}

Die beiden Labels werden in verschiedenen Feldern desselben Logeintrags angezeigt:

{
  "labels": {
    "gen_ai.operation.name": "generate_content",
    "cost_center": "cc-1234"
  },
  "jsonPayload": {
    "httpHeaders": {
      "x-goog-agent-platform-observability-label-team": {
        "values": ["payments"]
      }
    }
  }
}

Die beiden Labeltypen belegen unterschiedliche Felder, sodass Sie sie unterschiedlich abfragen. Im Log-Explorer:

labels.cost_center="cc-1234"
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"

In Observability Analytics:

JSON_VALUE(labels.cost_center) AS cost_center,
JSON_VALUE(json_payload.httpHeaders
  ["x-goog-agent-platform-observability-label-team"].values[0]) AS team

Funktionsweise von Header-Labels

Header-Labels sind Teil des Metadaten-Loggings von Inferenzanfragen. Wenn Sie sie erfassen möchten, aktivieren Sie Metadatenlogs für Inferenzanfragen für das Projekt.

Senden Sie einen Header pro Label mit dem reservierten Präfix. Bei dem Präfix wird die Groß-/Kleinschreibung nicht berücksichtigt:

x-goog-agent-platform-observability-label-KEY: VALUE

Beispiel:

x-goog-agent-platform-observability-label-team: payments
x-goog-agent-platform-observability-label-application: invoice-ocr

Jeder Header wird im Logeintrag unter jsonPayload.httpHeaders angezeigt, wobei der Headername in Kleinbuchstaben angegeben ist und der Wert in einem values-Array enthalten ist, wie unter Jedes Label im Logeintrag finden gezeigt.

Die Agent Platform erfasst auch eine kleine Anzahl eigener Header: x-vertex-ai-llm-request-type und x-vertex-ai-llm-shared-request-type. Andere Header werden nicht erfasst.

Header-Labels funktionieren für Gemini und Claude auf dieselbe Weise. Sie werden verwendet, um Claude-Anfragen im Metadatenprotokoll für Inferenzanfragen zu kennzeichnen.

Limits für Header-Labels

  • In einer einzelnen Anfrage werden maximal 32 Header geschrieben. Wenn mehr Agenten infrage kommen, behält die Agentenplattform sie in aufsteigender alphabetischer Reihenfolge und verwirft den Rest. Der Tropfen ist stumm.
  • Ein Headerwert,der länger als 1.024 Byte ist, wird abgeschnitten. Die Kürzung wird im gespeicherten Wert markiert.
  • Wiederkehrende Header mit demselben Namen werden zu einem einzigen Eintrag mit mehreren Werten kombiniert.

Informationen zum Abfragen von Header-Labels finden Sie unter Nutzung nach benutzerdefiniertem Header-Label.

Anforderungen an Labels

Die Labels, die auf einen API-Aufruf angewendet werden, müssen die folgenden Anforderungen erfüllen:

  • Jeder API-Aufruf kann bis zu 64 Labels für Google-Modelle und bis zu 32 Labels für Partnermodelle haben.
  • Jedes Label muss ein Schlüssel/Wert-Paar sein.
  • Schlüssel haben eine Mindestlänge von 1 Zeichen und eine maximale Länge von 63 Zeichen und dürfen nicht leer sein. Werte dürfen leer sein und haben eine maximale Länge von 63 Zeichen.
  • Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Alle Zeichen müssen UTF-8-codiert sein. Internationale Zeichen sind zulässig. Schlüssel müssen mit einem Kleinbuchstaben oder einem internationalen Zeichen beginnen.
  • Der Schlüsselabschnitt eines Labels darf in einem einzelnen API-Aufruf nur einmal vorkommen. Sie können jedoch denselben Schlüssel für mehrere Aufrufe verwenden.

Die Limits gelten für den Schlüssel und den Wert für jedes Label und für den einzelnen API-Aufruf, der Labels hat. Es gibt keine Beschränkung, wie viele Labelschlüssel Sie für alle API-Aufrufe in einem Projekt erstellen können. Jeder Labelschlüssel kann bis zu 1.000 eindeutige Werte für alle Anfragen während der Lebensdauer des zugehörigen Rechnungskontos haben. Der Labelschlüssel wird möglicherweise ohne Vorankündigung gelöscht, wenn ihm mehr als 1.000 eindeutige Werte zugeordnet sind.

Einsatzmöglichkeiten von Labels

Labels kommen u. a. in folgenden Situationen zum Einsatz:

  • Labels für Teams oder Kostenstellen: Fügen Sie Labels basierend auf einem Team oder einer Kostenstelle hinzu, um zwischen den API-Aufrufen verschiedener Teams zu unterscheiden (z. B. team:research und team:analytics). Sie können diese Art von Label für die Kostenabrechnung oder Budgetplanung nutzen.

  • Labels für Komponenten: z. B. component:redis, component:frontend, component:ingest und component:dashboard.

  • Labels für Umgebungen oder Phasen: z. B. environment:production und environment:test.

  • Labels für Eigentumsrechte: Wird verwendet, um die Teams zu identifizieren, die für den Betrieb verantwortlich sind, z. B. team:shopping-cart.

Es wird empfohlen, nicht zu viele eindeutige Labels zu erstellen, etwa für Zeitstempel oder einzelne Werte für einzelne API-Aufruf. Das Problem bei diesem Ansatz besteht darin, dass die Schlüssel den Katalog überlasten, die Ladezeiten bei Abfragen erheblich verlängern und es schwierig machen, API-Aufrufe effektiv zu filtern und Berichte über sie zu erstellen.

Unterstützte Modelle für Anfragelabels

Anfragelabels und Headerlabels werden von verschiedenen Modellen unterstützt. Das Hinzufügen von Anfragelabels zu einer Anfrage wird für Google-Modelle und eine Teilmenge von Partnermodellen unterstützt. Wenn Sie einer Anfrage für ein nicht unterstütztes Modell Anfrage-Labels hinzufügen, führt die Anfrage zu einem Fehler. Google-Modelle akzeptieren Anfragelabels im Feld labels des Anfragetexts. Partnermodelle akzeptieren sie im Header X-Vertex-AI-Labels.

Google-Modelle

Google-Modelle unterstützen Labels für die folgenden API-Methoden.

  • generateContent
  • streamGenerateContent

Partnermodelle

Partnermodelle unterstützen Labels für die folgenden API-Methoden.

  • rawPredict
  • streamRawPredict

Die folgenden Partnermodelle unterstützen Labels.

Labels werden nur an Cloud Billing weitergeleitet, wenn für die Anfrage die Nutzungsoption PayGo verwendet wird. Bei Anfragen mit der Verbrauchsoption Bereitgestellter Durchsatz werden in der Anfrage gesendete Labels ignoriert.

Unterstützte Modelle für Header-Labels

Header-Labels werden nur in das Metadatenprotokoll der Inferenzanfrage geschrieben. Sie funktionieren also für die Modelle und Methoden, die im Protokoll erfasst werden.

  • Gemini-Modelle: generateContent und streamGenerateContent.
  • Claude-Modelle: rawPredict und streamRawPredict.
  • Verbrauchsoptionen: Bereitgestellter Durchsatz und alle Pay-as-you-go-Optionen, die das Modell bietet.
  • Andere Partnermodelle, einschließlich Mistral AI, werden nicht unterstützt. Eine Anfrage an sie mit Header-Labels ist weiterhin erfolgreich, es wird jedoch kein Logeintrag geschrieben, sodass die Labels nirgendwo aufgezeichnet werden.
  • Header-Labels erreichen Cloud Billing nie. Verwenden Sie Anfrage-Labels, um in Rechnung gestellte Gebühren aufzuschlüsseln.

Anfragelabel zu einem API-Aufruf für ein Google-Modell hinzufügen

So fügen Sie einem generateContent- oder streamGenerateContent-API-Aufruf ein Label hinzu:

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • GENERATE_RESPONSE_METHOD: Der Typ der Antwort, die das Modell generieren soll. Wählen Sie eine Methode aus, mit der generiert wird, wie die Antwort des Modells zurückgegeben werden soll:
    • streamGenerateContent: Die Antwort wird während der Generierung gestreamt, um die Wahrnehmung der Latenz für menschliche Zielgruppen zu reduzieren.
    • generateContent: Die Antwort wird zurückgegeben, nachdem sie vollständig generiert wurde.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • PROJECT_ID: Ihre Projekt-ID. .
  • MODEL_ID: Die Modell-ID des Modells, das Sie verwenden möchten.
  • ROLE: Die Rolle in einer Unterhaltung, die mit dem Inhalt verknüpft ist. Die Angabe einer Rolle ist auch bei Anwendungsfällen mit nur einem Schritt erforderlich. Unter anderem sind folgende Werte zulässig:
    • USER: Gibt Inhalte an, die von Ihnen gesendet werden
    • MODEL: Gibt die Antwort des Modells an.
  • PROMPT_TEXT
    : Die Textanleitung, die in den Prompt eingefügt werden soll. JSON
  • LABEL_KEY: Die Labelmetadaten, die Sie mit diesem API-Aufruf verknüpfen möchten.
  • LABEL_VALUE: Der Wert des Labels.

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben: 

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

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden: 

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben: 

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

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden: 

$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

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

Python

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Python in der Agent Platform-Kurzanleitung zur Verwendung von Clientbibliotheken.

Richten Sie zur Authentifizierung bei der Agent Platform Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 


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

Google Cloud -Produkte melden Nutzungs- und Kostendaten in unterschiedlichen Intervallen an Cloud Billing-Prozesse. Deshalb kann es zu einer Verzögerung zwischen der Nutzung vonGoogle Cloud -Diensten und der Nutzung und Kosten kommen, die in Cloud Billing angezeigt werden. In der Regel sind Ihre Kosten innerhalb eines Tages verfügbar, manchmal kann es aber auch mehr als 24 Stunden dauern.

Anfragelabel zu einem API-Aufruf für ein Partnermodell hinzufügen

So fügen Sie einem rawPredict- oder streamRawPredict-API-Aufruf ein Label hinzu:

REST

Ersetzen Sie folgende Werte in den Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • MODEL_ID: Die Modell-ID des Modells, das Sie verwenden möchten. Beispiel: claude-opus-4-6

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben:

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

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden:

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

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Python in der Agent Platform-Kurzanleitung zur Verwendung von Clientbibliotheken.

Richten Sie zur Authentifizierung bei der Agent Platform Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Ersetzen Sie folgende Werte in den Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • MODEL_ID: Die Modell-ID des Modells, das Sie verwenden möchten. Beispiel: 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"))

Headerlabels zu API-Aufrufen hinzufügen

Für Headerlabels sind keine Änderungen am Anfragetext erforderlich. Fügen Sie jeder unterstützten Anfrage einen x-goog-agent-platform-observability-label-KEY-Header pro Label hinzu. Die folgenden Beispiele zeigen die Anfrage und die resultierenden Felder des Logeintrags für die Metadaten der Inferenzanfrage aus Testanfragen vom 14.10.2026.

Header-Labels zu einem API-Aufruf für ein Gemini-Modell hinzufügen

Header-Labels mit generateContent oder streamGenerateContent senden. Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

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?"}]}]}'

Im Logeintrag wird jedes Label unter jsonPayload.httpHeaders aufgezeichnet. Header-Labels werden auch für Traffic mit bereitgestelltem Durchsatz aufgezeichnet, was von Anfrage-Labels nicht unterstützt wird:

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

Headerlabels zu einem Claude-Modell-API-Aufruf hinzufügen

Header-Labels mit rawPredict oder streamRawPredict senden. Ersetzen Sie PROJECT_ID und MODEL_ID, z. B. durch 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}'

Im Logeintrag wird das Label unter jsonPayload.httpHeaders neben den Tokenzahlen von Claude aufgezeichnet:

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

Eine Claude-Anfrage kann auch Anfrage-Labels im Header X-Vertex-AI-Labels enthalten, wie unter Anfrage-Label zu einem API-Aufruf für ein Partnermodell hinzufügen beschrieben. Diese erreichen Cloud Billing, werden aber nicht in den Logeintrag geschrieben.

Abfrageheader-Labels

Filtern Sie im Log-Explorer nach einem Header-Labelwert:

jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"

In Observability Analytics können Sie auf der Seite Metadaten von Inferenzanfragen protokollieren mit der Abfrage Nutzung nach benutzerdefiniertem Headerlabel nach einem Headerlabel gruppieren.