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
eteam: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
ecomponent:dashboard
.Etichette di ambiente o fase: ad esempio,
environment:production
eenvironment: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.
Le istruzioni di testo da includere nel prompt. JSONPROMPT_TEXT
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.
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.