Benutzerdefinierte Metadatenlabels

Mithilfe von Labels können Sie generateContent- und streamGenerateContent-API-Aufrufen 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 generateContent- und streamGenerateContent-API-Aufrufen 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 ihren 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.

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 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 innerhalb eines einzelnen API-Aufrufs 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 Labels Sie auf alle API-Aufrufe in einem Projekt anwenden können.

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 es schwierig ist, API-Aufrufe effektiv zu filtern und Berichte über sie zu erstellen, wenn sich die Werte häufig ändern oder wenn Schlüssel verwendet werden, die den Katalog überlasten.

API-Aufruf ein Label 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: Die Art 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.
MODEL_ID: die Modell-ID des multimodalen Modells, das Sie verwenden möchten. Beispiele:
- gemini-1.0-pro-002
- gemini-1.0-pro-vision-001
- gemini-1.5-pro-002
- gemini-1.5-flash
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 mit diesem API-Aufruf verknüpft werden sollen.
LABEL_VALUE: Der Wert des Labels.

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

curl

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch bei der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

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

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud CLI angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

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:

Antwort

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

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