Etichette metadati personalizzate

Puoi aggiungere metadati personalizzati all'API generateContent e streamGenerateContent tramite le etichette. Questa pagina spiega cosa sono le etichette e mostra come utilizzale 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 report sulla fatturazione, puoi filtrare e raggruppare i costi per etichette. Puoi utilizzare le etichette anche query 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 i caratteri internazionali. Le chiavi devono iniziare con una lettera minuscola o 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. Là 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 del team o del centro di costo: aggiungi etichette in base al team o centro di costo per distinguere le chiamate API di proprietà team (ad es. team:research e team:analytics). Puoi utilizzare questo tipo di etichetta per la contabilizzazione dei costi o la definizione del budget.

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

• Etichette dell'ambiente o della fase: ad esempio, environment:production e environment:test.

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

Nota: non includere informazioni sensibili nelle etichette, incluse informazioni che consentono l'identificazione personale, come il nome o il titolo di una persona. Le etichette non sono progettate per gestire informazioni sensibili.

Sconsigliamo di creare un numero elevato di etichette univoche, ad esempio timestamp o 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, procedi nel seguente modo: le seguenti:

REST

Prima di utilizzare i dati della richiesta, effettua 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 riprodotta in streaming durante la generazione per ridurre la percezione della latenza per un pubblico umano.
  • generateContent: la risposta viene restituita dopo che è 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 in e i casi d'uso a turno singolo. 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 che vuoi associare a questa chiamata API.
• LABEL_VALUE: il valore dell'etichetta.

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: Il comando seguente presuppone che tu abbia eseguito l'accesso a l'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud di Google. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list

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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list

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.

Risposta

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": Generative AI is a type of artificial intelligence (AI) that can **create new
            content**, like text, images, audio, video, and even code.
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.037841797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.06347656
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.053466797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.08496094
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08154297,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.033203125
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.071777344,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.083984375
        }
      ],
      "avgLogprobs": -0.40486351219383448
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 555,
    "totalTokenCount": 560
  }
}

I prodotti Google Cloud registrano i dati di utilizzo e di costo per le procedure di fatturazione Cloud a intervalli variabili. Di conseguenza, potresti notare un ritardo tra l'utilizzo dei servizi Google Cloud e la visualizzazione dell'utilizzo e dei costi in Fatturazione Cloud. In genere, i costi sono disponibili entro un giorno, ma a volte richiedono più di 24 ore.