Etichette metadati personalizzate

Puoi aggiungere metadati personalizzati alle chiamate alle API generateContent e streamGenerateContent utilizzando le etichette. Questa pagina spiega che cosa sono le etichette e come usarle 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 associare 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 in base all'etichetta. Con i report di 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.

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

Non è consigliabile creare un numero elevato di etichette univoche, ad esempio per i timestamp o i singoli valori per ogni chiamata API. Il problema con questo approccio è che, quando i valori cambiano di frequente 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:

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 da parte di un pubblico di persone.
    • generateContent: la risposta viene restituita dopo essere stata completamente generata.
  • 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 del modello multimodale che vuoi utilizzare. Ecco alcune opzioni:
    • gemini-1.0-pro-002
    • gemini-1.0-pro-vision-001
    • gemini-1.5-pro-002
    • gemini-1.5-flash
  • ROLE: Il ruolo in una conversazione associato ai contenuti. La specifica di un ruolo è obbligatoria anche nei casi d'uso con un solo turno. I valori accettabili sono:
    • 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 da associare a questa chiamata API.
  • LABEL_VALUE: il valore dell'etichetta.

Per inviare la richiesta, scegli una delle seguenti 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 il seguente 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 il seguente 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 Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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-1.5-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 inviano i dati di utilizzo e di costo alle procedure di fatturazione Cloud a intervalli variabili. Di conseguenza, potresti notare un ritardo tra l'utilizzo dei serviziGoogle Cloud e la visualizzazione dell'utilizzo e dei costi in Fatturazione Cloud. In genere, i costi sono disponibili entro un giorno, ma a volte possono essere necessarie più di 24 ore.