Etichette metadati personalizzate

Puoi aggiungere metadati personalizzati alle chiamate API come generateContent e rawPredict utilizzando le etichette. Questa pagina spiega cosa sono le etichette e come utilizzarle per suddividere gli addebiti fatturati.

Cosa sono le etichette?

Un'etichetta è una coppia chiave-valore che puoi assegnare alle chiamate API come generateContent e rawPredict. Ti aiutano a organizzare queste chiamate e a gestire i costi su larga scala, con la granularità di cui hai bisogno. Puoi allegare un'etichetta a ogni chiamata, quindi filtrare le chiamate in base alle etichette. Le informazioni relative alle etichette vengono inoltrate al sistema di fatturazione, che ti consente di suddividere gli addebiti fatturati per etichetta. Con i report di fatturazione integrati, puoi filtrare e raggruppare i costi per etichetta. Puoi anche utilizzare le etichette per eseguire query sulle esportazioni dei dati di fatturazione. Per informazioni su come utilizzare le etichette dopo la creazione, consulta un esempio nella panoramica delle etichette.

Requisiti per le etichette

Le etichette applicate a una chiamata API devono soddisfare i seguenti requisiti:

  • Ogni chiamata API può avere fino a 64 etichette per i modelli Google e fino a 32 etichette per i modelli di partner.
  • Ogni etichetta deve essere una coppia chiave/valore.
  • Le chiavi hanno una lunghezza minima di 1 carattere e una lunghezza massima di 63 caratteri e non possono essere vuote. I valori possono essere vuoti e avere una lunghezza massima di 63 caratteri.
  • Chiavi e valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8; sono consentiti i caratteri internazionali. Le chiavi devono iniziare con una lettera minuscola o un carattere internazionale.
  • La parte della chiave di un'etichetta deve essere univoca all'interno di una singola chiamata API. Tuttavia, puoi utilizzare la stessa chiave con più chiamate.

Questi limiti si applicano alla chiave e al valore di ogni etichetta e alla singola chiamata API che contiene le etichette. Non esiste un limite al numero di chiavi di etichetta che puoi creare in tutte le chiamate API all'interno di un progetto. Ogni chiave di etichetta può avere fino a 1000 valori univoci in tutte le richieste durante la durata dell'account di fatturazione associato. La chiave di etichetta potrebbe essere eliminata senza preavviso se sono associati più di 1000 valori univoci.

Utilizzi comuni delle etichette

Ecco alcuni casi d'uso comuni per le etichette:

  • Etichette di team o centro di costo: aggiungi etichette basate su team o centro di costo per distinguere le chiamate API di proprietà di team diversi (ad esempio, team:research e team:analytics). Le etichette di questo tipo sono utili per la contabilità dei costi o la definizione del budget.

  • Etichette dei componenti: ad esempio, component:redis, component:frontend, component:ingest, e component:dashboard.

  • Etichette di ambiente o fase: ad esempio, environment:production e environment:test.

  • Etichette di proprietà: utilizzate per identificare i team responsabili delle operazioni, ad esempio: team:shopping-cart.

Sconsigliamo di creare un numero elevato di etichette univoche, ad esempio per timestamp o valori individuali per ogni chiamata API. Il problema di questo approccio è che le chiavi ingombrano il catalogo, aumentano notevolmente i tempi di caricamento durante le query e rendono difficile filtrare e generare report sulle chiamate API in modo efficace.

Modelli supportati

La possibilità di aggiungere etichette a una richiesta è supportata per i modelli Google e un sottoinsieme di modelli di partner. Se aggiungi etichette a una richiesta per un modello non supportato, la richiesta genera un errore.

Modelli Google

I modelli Google supportano le etichette nei seguenti metodi API.

  • generateContent
  • streamGenerateContent

Modelli di partner

I modelli di partner supportano le etichette nei seguenti metodi API.

  • rawPredict
  • streamRawPredict

I seguenti modelli di partner supportano le etichette.

Le etichette vengono inoltrate alla fatturazione Cloud solo quando la richiesta utilizza l' PayGo. Le richieste che utilizzano l' opzione di consumo Throughput riservato ignoreranno silenziosamente le etichette inviate nella richiesta.

Aggiungere un'etichetta a una chiamata API del modello Google

Per aggiungere un'etichetta a una chiamata API generateContent o streamGenerateContent:

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • GENERATE_RESPONSE_METHOD: il tipo di risposta che vuoi che il modello generi. Scegli un metodo che generi la modalità di restituzione della risposta del modello:
    • streamGenerateContent: la risposta viene trasmessa in streaming durante la generazione per ridurre la percezione della latenza per un pubblico umano.
    • generateContent: la risposta viene restituita dopo essere stata generata completamente.
  • LOCATION: la regione in cui elaborare la richiesta. Le opzioni disponibili includono le seguenti:

    Fai clic per espandere un elenco parziale delle regioni disponibili

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: il tuo [ID progetto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL_ID: l'ID modello del modello che vuoi utilizzare.
  • ROLE: Il ruolo in una conversazione associata ai contenuti. La specifica di un ruolo è obbligatoria anche nei casi d'uso a turno singolo. I valori accettabili includono i seguenti:
    • USER: specifica i contenuti inviati da te.
    • MODEL: specifica la risposta del modello.
  • PROMPT_TEXT
     Le istruzioni di testo da includere nel prompt. JSON
  • LABEL_KEY: i metadati dell'etichetta che vuoi associare a questa chiamata API.
  • LABEL_VALUE: il valore dell'etichetta.

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui il comando seguente nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

Quindi esegui il comando seguente per inviare la richiesta 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

Salva il corpo della richiesta in un file denominato request.json. Esegui il comando seguente nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

Quindi esegui il comando seguente per inviare la richiesta 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

Dovresti ricevere una risposta JSON simile alla seguente.

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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 I prodotti segnalano i dati di costo e utilizzo ai processi di fatturazione Cloud a intervalli variabili. Di conseguenza, potresti riscontrare un ritardo tra l'utilizzo dei Google Cloud servizi e la visualizzazione dell'utilizzo e dei costi relativi nella fatturazione Cloud. In genere, i costi sono disponibili entro un giorno, ma a volte possono essere necessarie più di 24 ore.

Aggiungere un'etichetta a una chiamata API del modello di partner

Per aggiungere un'etichetta a una chiamata API rawPredict o streamRawPredict:

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • MODEL_ID: l'ID modello del modello che vuoi utilizzare. Ad esempio, claude-opus-4-6.

Salva il corpo della richiesta in un file denominato request.json. Esegui il comando seguente nel terminale per creare o sovrascrivere questo file nella directory corrente:

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

Quindi esegui il comando seguente per inviare la richiesta REST:

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

Prima di provare questo esempio, segui le istruzioni di configurazione Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • MODEL_ID: l'ID modello del modello che vuoi utilizzare. Ad esempio, 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"))