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 mostra 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 l'utilizzo e i costi su larga scala, con la granularità di cui hai bisogno. Puoi allegare un'etichetta a ogni chiamata e poi filtrare le chiamate in base alle etichette. Le informazioni sulle etichette vengono inoltrate al sistema di logging e fatturazione, che ti consente di suddividere l'utilizzo e gli addebiti fatturati per etichetta. Con i report sulla fatturazione integrati, puoi filtrare e raggruppare i costi in base alle etichette. 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.

Agent Platform supporta due tipi di etichette: le etichette del corpo della richiesta, che raggiungono la fatturazione Cloud, e le etichette dell'intestazione, che vengono visualizzate nei log dei metadati delle richieste di inferenza. La sezione successiva li mette a confronto.

Scegli un'etichetta in base al tuo caso d'uso

Agent Platform offre due meccanismi di etichettatura. Vengono impostati in modo diverso, raggiungono destinazioni diverse e vengono visualizzati in campi diversi del log dei metadati della richiesta di inferenza. Puoi utilizzare uno o entrambi i metodi nella stessa richiesta, se supportati.

Le etichette del corpo della richiesta funzionano come segue:

  • Puoi impostarli nel campo labels del corpo della richiesta.
  • Raggiungono i log dei metadati delle richieste di inferenza e di fatturazione Cloud.
  • Vengono visualizzati nel campo labels della voce di log.
  • Supportato per il traffico con pagamento a consumo.
  • Per i modelli partner come Claude, le etichette delle richieste vengono inviate nell'intestazione X-Vertex-AI-Labels anziché nel corpo della richiesta. Raggiungono la fatturazione Cloud, ma non vengono scritti nel log dei metadati della richiesta di inferenza.

Le etichette di intestazione funzionano nel seguente modo:

  • Puoi impostarle nell'intestazione della richiesta x-goog-agent-platform-observability-label-KEY.
  • Raggiungono solo i log dei metadati delle richieste di inferenza.
  • Vengono visualizzati nel campo jsonPayload.httpHeaders della voce di log.
  • Metodi API supportati: generateContent e streamGenerateContent per i modelli Gemini e rawPredict e streamRawPredict per i modelli Claude. Opzioni di consumo supportate: throughput riservato e ogni opzione con pagamento a consumo offerta dal modello.

Trova ogni etichetta nella voce di log

Una singola richiesta può contenere entrambi. La seguente richiesta imposta un valore per ciascuno:

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

Le due etichette vengono inserite in campi diversi della stessa voce di log:

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

I due tipi di etichette occupano campi diversi, quindi vengono interrogati in modo diverso. In Esplora log:

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

Come funzionano le etichette di intestazione

Le etichette delle intestazioni fanno parte del logging dei metadati delle richieste di inferenza. Per acquisirli, attiva i log dei metadati delle richieste di inferenza per il progetto.

Invia un'intestazione per etichetta, utilizzando il prefisso riservato. Il prefisso non fa distinzione tra maiuscole e minuscole:

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

Ad esempio:

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

Ogni intestazione viene visualizzata nella voce di log in jsonPayload.httpHeaders, con il nome dell'intestazione in minuscolo come chiave e il valore in un array values, come mostrato in Trova ogni etichetta nella voce di log.

Agent Platform acquisisce anche un piccolo insieme di intestazioni proprie: x-vertex-ai-llm-request-type e x-vertex-ai-llm-shared-request-type. Non vengono acquisite altre intestazioni.

Le etichette delle intestazioni funzionano allo stesso modo per Gemini e Claude e sono il modo in cui etichetti le richieste di Claude nel log dei metadati delle richieste di inferenza.

Limiti per le etichette delle intestazioni

  • Una singola richiesta scrive al massimo 32 intestazioni. Se sono idonei più agenti, la piattaforma degli agenti li mantiene in ordine alfabetico crescente ed elimina il resto. La caduta è silenziosa.
  • Un valore dell'intestazione più lungo di 1024 byte viene troncato e il troncamento viene contrassegnato nel valore archiviato.
  • Le intestazioni ripetute con lo stesso nome vengono combinate in una singola voce con più valori.

Per eseguire query sulle etichette delle intestazioni, consulta Utilizzo per etichetta di intestazione personalizzata.

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 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 con etichette. Non esiste un limite al numero di chiavi di etichetta che puoi creare per tutte le chiamate API all'interno di un progetto. Ogni chiave di etichetta può avere fino a 1000 valori univoci in tutte le richieste per tutta la durata dell'account di fatturazione associato. La chiave dell'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 per team o centro di costo: aggiungi etichette in base al team o al centro di costo per distinguere le chiamate API di proprietà di team diversi (ad esempio, team:research e team:analytics). Puoi utilizzare questo tipo di etichetta 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 i timestamp o i singoli valori 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 in modo efficace sulle chiamate API.

Modelli supportati per le etichette delle richieste

Le etichette di richiesta e le etichette di intestazione sono supportate su modelli diversi. La possibilità di aggiungere etichette di richiesta di annuncio a una richiesta è supportata per i modelli Google e un sottoinsieme di modelli partner. Se aggiungi etichette di richiesta a una richiesta per un modello non supportato, la richiesta genera un errore. I modelli Google accettano le etichette di richiesta nel campo labels del corpo della richiesta. I modelli dei partner li accettano nell'intestazione X-Vertex-AI-Labels.

Modelli Google

I modelli Google supportano le etichette sui seguenti metodi API.

  • generateContent
  • streamGenerateContent

Modelli di partner

I modelli dei partner supportano le etichette sui seguenti metodi API.

  • rawPredict
  • streamRawPredict

I seguenti modelli dei partner supportano le etichette.

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

Modelli supportati per le etichette di intestazione

Le etichette delle intestazioni vengono scritte solo nel log dei metadati della richiesta di inferenza, quindi funzionano sui modelli e sui metodi registrati dal log.

  • Modelli Gemini: generateContent e streamGenerateContent.
  • Modelli Claude: rawPredict e streamRawPredict.
  • Opzioni di consumo: throughput riservato e tutte le opzioni con pagamento a consumo offerte dal modello.
  • Altri modelli partner, tra cui Mistral AI, non sono supportati. Una richiesta con etichette di intestazione viene comunque eseguita, ma non viene scritta alcuna voce di log, quindi le etichette non vengono registrate da nessuna parte.
  • Le etichette di intestazione non raggiungono mai la fatturazione Cloud. Per suddividere gli addebiti fatturati, utilizza le etichette delle richieste.

Aggiungi un'etichetta di richiesta a una chiamata API di un modello Google

Per aggiungere un'etichetta a una chiamata API generateContent o streamGenerateContent, segui questi passaggi:

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 risposta del modello nel modo che preferisci:
    • streamGenerateContent: la risposta viene trasmessa in streaming man mano che viene generata 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.
  • PROJECT_ID: il tuo ID progetto. .
  • MODEL_ID: l'ID 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 single-turn. I valori accettabili includono:
    • 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 questo comando 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 questo comando 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 questo comando 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 questo comando 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 di 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 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

I prodottiGoogle Cloud 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 serviziGoogle Cloud 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.

Aggiungi un'etichetta di richiesta a una chiamata API di un modello partner

Per aggiungere un'etichetta a una chiamata API rawPredict o streamRawPredict, segui questi passaggi:

REST

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

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

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando 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 questo comando 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 di 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 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"))

Aggiungi etichette di intestazione alle chiamate API

Le etichette di intestazione non richiedono modifiche al corpo della richiesta. Aggiungi un'intestazione x-goog-agent-platform-observability-label-KEY per etichetta a qualsiasi richiesta supportata. I seguenti esempi mostrano la richiesta e i campi risultanti della voce di log dei metadati della richiesta di inferenza, dalle richieste di test del 14/10/2026.

Aggiungi etichette di intestazione a una chiamata API del modello Gemini

Invia le etichette di intestazione con generateContent o streamGenerateContent. Sostituisci PROJECT_ID con l'ID progetto.

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

La voce di log registra ogni etichetta in jsonPayload.httpHeaders. Le etichette di intestazione vengono registrate anche sul traffico del throughput riservato, cosa che non è supportata dalle etichette di richiesta:

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

Aggiungi etichette di intestazione a una chiamata API del modello Claude

Invia le etichette di intestazione con rawPredict o streamRawPredict. Sostituisci PROJECT_ID e MODEL_ID, ad esempio 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}'

La voce di log registra l'etichetta in jsonPayload.httpHeaders, accanto ai conteggi dei token di Claude:

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

Una richiesta Claude può anche contenere etichette di richiesta nell'intestazione X-Vertex-AI-Labels, come mostrato in Aggiungi un'etichetta di richiesta a una chiamata API di un modello partner. Questi raggiungono la fatturazione Cloud, ma non vengono scritti nella voce di log.

Etichette delle intestazioni delle query

In Esplora log, filtra in base a un valore dell'etichetta dell'intestazione:

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

In Observability Analytics, raggruppa per un'etichetta di intestazione con la query Utilizzo per etichetta di intestazione personalizzata nella pagina Registra i metadati della richiesta di inferenza.