Benutzerdefinierte Metadatenlabels

Sie können API-Aufrufen wie generateContent und rawPredict benutzerdefinierte Metadaten hinzufügen, indem Sie Labels verwenden. Auf dieser Seite wird erläutert, was Labels sind und wie Sie damit Ihre abgerechneten Gebühren 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 Kosten in großem Umfang mit der erforderlichen Detailgenauigkeit zu verwalten. Sie können jedem Anruf ein Label zuweisen und dann die Anrufe nach Labels filtern. Informationen zu Labels werden an das Abrechnungssystem weitergeleitet, sodass Sie 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 dem Erstellen finden Sie in diesem Beispiel.

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 die einzelnen API-Aufrufe, die Labels haben. Es gibt keine Beschränkung, wie viele Label-Schlüssel Sie für alle API-Aufrufe in einem Projekt erstellen können. Jeder Label-Schlüssel kann über die gesamte Lebensdauer des zugehörigen Abrechnungskontos hinweg bis zu 1.000 eindeutige Werte in allen Anfragen haben. Der Labelschlüssel wird möglicherweise ohne Vorankündigung entfernt, wenn mehr als 1.000 Einzelwerte damit verknüpft 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 jeden 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 ist, API-Aufrufe effektiv zu filtern und Berichte über sie zu erstellen.

Unterstützte Modelle

Die Möglichkeit, einer Anfrage Labels hinzuzufügen, wird für Google-Modelle und eine Teilmenge von Partnermodellen unterstützt. Wenn Sie einer Anfrage für ein nicht unterstütztes Modell Labels hinzufügen, führt die Anfrage zu einem Fehler.

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 dann an Cloud Billing weitergeleitet, wenn für die Anfrage die Nutzungsoption PayGo verwendet wird. Bei Anfragen mit der Verbrauchsoption Bereitgestellter Durchsatz werden im Antrag gesendete Labels stillschweigend ignoriert.

Label einem Google-Modell-API-Aufruf 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. Folgende Optionen sind verfügbar:

    Klicken Sie, um eine unvollständige Liste der verfügbaren Regionen einzublenden

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: Ihre [Projekt-ID](/resource-manager/docs/creating-managing-projects#identifiers). .
  • 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 diesem API-Aufruf zuordnen 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

Folgen Sie der Einrichtungsanleitung für Python in der Kurzanleitung zur Agent Platform mit Clientbibliotheken, bevor Sie dieses Beispiel anwenden.

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 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.

Google Cloud -Produkte melden Nutzungs- und Kostendaten in unterschiedlichen Intervallen an Cloud Billing-Vorgänge. 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.

Label 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 den 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

Folgen Sie der Einrichtungsanleitung für Python in der Kurzanleitung zur Agent Platform mit Clientbibliotheken, bevor Sie dieses Beispiel anwenden.

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