Etichette metadati personalizzate

Puoi aggiungere metadati personalizzati alle chiamate API generateContent e streamGenerateContent 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 generateContent e streamGenerateContent. 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 sulle etichette vengono inoltrate al sistema di fatturazione, che ti consente di suddividere gli addebiti fatturati in base all'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.

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.
  • 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.
  • Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8 e 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 etichette. Non esiste un limite al numero di etichette che puoi applicare a tutte le chiamate API all'interno di un progetto.

Utilizzi comuni delle etichette

Ecco alcuni casi d'uso comuni per le etichette:

  • Etichette per 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). 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.

Non è consigliabile creare un numero elevato di etichette uniche, ad esempio per timestamp o valori individuali per ogni chiamata API. Il problema di questo approccio è che quando i valori cambiano frequentemente o con chiavi che ingombrano il catalogo, è difficile filtrare e generare report in modo efficace sulle chiamate API.

Aggiungere un'etichetta a una chiamata API

Per aggiungere un'etichetta a una chiamata API generateContent o streamGenerateContent, procedi nel seguente modo:

REST

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

  • 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 il pubblico umano.
    • generateContent: la risposta viene restituita dopo essere stata generata completamente.
  • LOCATION: la regione in cui elaborare la richiesta. Le opzioni disponibili includono:

    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
  • 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 singolo turno. 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 Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Python.

Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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.

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 nel fatturazione Cloud. In genere, i costi sono disponibili entro un giorno, ma a volte possono essere necessarie più di 24 ore.