Registra richieste e risposte

Vertex AI può registrare campioni di richieste e risposte per Gemini e i modelli partner supportati. I log vengono salvati in una tabella BigQuery per la visualizzazione e l'analisi. Questa pagina descrive come configurare i log di richiesta-risposta per i modelli di base e quelli sottoposti a fine tuning.

Metodi API supportati per la registrazione

I log di richiesta/risposta sono supportati per tutti i modelli Gemini che utilizzano generateContent o streamGenerateContent.

Sono supportati anche i seguenti modelli di partner che utilizzano rawPredict o streamrawPredict:

  • Anthropic Claude

Log di richiesta-risposta per i foundation model di base

Puoi configurare i log di richiesta-risposta per i modelli di base utilizzando l'API REST o l'SDK Python. L'applicazione delle configurazioni di logging può richiedere alcuni minuti.

Abilita la registrazione di richieste e risposte

Seleziona una delle seguenti schede per istruzioni su come attivare i log di richiesta-risposta per un modello di base.

Per i modelli Anthropic, per la configurazione della registrazione è supportato solo REST. Attiva la configurazione della registrazione tramite l'API REST impostando l'editore su anthropic e impostando il nome del modello su uno dei modelli Claude supportati.

SDK Python

Questo metodo può essere utilizzato per creare o aggiornare un PublisherModelConfig.

# Specify the preview version of GenerativeModel
import vertexai
from vertexai.preview.generative_models import(
    GenerativeModel,
    )

PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

vertexai.init(project=PROJECT_ID, location=LOCATION)

publisher_model = GenerativeModel("gemini-2.5-flash")

# Set logging configuration
publisher_model.set_request_response_logging_config(
    enabled=True,
    sampling_rate=1.0,
    bigquery_destination="bq://PROJECT_ID.DATASET_NAME.TABLE_NAME",
    enable_otel_logging=True
    )

API REST

Crea o aggiorna un PublisherModelConfig utilizzando setPublisherModelConfig:

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

  • ENDPOINT_PREFIX: la regione della risorsa modello seguita da -. Ad esempio: us-central1-. Se utilizzi l'endpoint globale, lascia vuoto il campo. La registrazione di richieste e risposte è supportata per tutte le regioni supportate dal modello.
  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la regione della risorsa del modello. Se utilizzi l'endpoint globale, inserisci global.
  • PUBLISHER: il nome dell'editore. Ad esempio, google.
  • MODEL: Il nome del modello di base. Ad esempio, gemini-2.0-flash-001.
  • SAMPLING_RATE: Per ridurre i costi di archiviazione, puoi impostare un numero compreso tra 0 e 1 per definire la frazione di richieste da registrare. Ad esempio, un valore di 1 registra tutte le richieste, mentre un valore di 0,1 registra il 10% delle richieste.
  • BQ_URI: la tabella BigQuery da utilizzare per la registrazione. Se specifichi solo un nome di progetto, viene creato un nuovo set di dati con il nome logging_ENDPOINT_DISPLAY_NAME\_ENDPOINT_ID, dove ENDPOINT_DISPLAY_NAME segue le regole di denominazione di BigQuery. Se non specifichi un nome della tabella, viene creata una nuova tabella con il nome request_response_logging.

Metodo HTTP e URL: 

POST https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig

Corpo JSON della richiesta: 

{
  "publisherModelConfig": {
     "loggingConfig": {
       "enabled": true,
       "samplingRate": SAMPLING_RATE,
       "bigqueryDestination": {
         "outputUri": "BQ_URI"
       },
       "enableOtelLogging": true
     }
   }
 }

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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://ENDPOINT_PREFIXaiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

Recuperare la configurazione di logging

Recupera la configurazione della registrazione delle richieste e delle risposte per il modello di base utilizzando l'API REST.

API REST

Recupera la configurazione del logging di richiesta-risposta utilizzando fetchPublisherModelConfig:

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

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la posizione della risorsa modello.
  • PUBLISHER: il nome dell'editore. Ad esempio, google.
  • MODEL: Il nome del modello di base. Ad esempio, gemini-2.0-flash-001.

Metodo HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:fetchPublisherModelConfig

Per inviare la richiesta, scegli una di queste opzioni:

curl

Esegui questo comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:fetchPublisherModelConfig"

PowerShell

Esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:fetchPublisherModelConfig" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

Disattivare la registrazione

Disattiva la registrazione di richieste e risposte per il modello di base utilizzando l'API REST o l'SDK Python.

SDK Python

# Specify the preview version of GenerativeModel
import vertexai
from vertexai.preview.generative_models import(
    GenerativeModel,
    )

PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

vertexai.init(project=PROJECT_ID, location=LOCATION)

publisher_model = GenerativeModel("gemini-2.5-flash")

# Disable logging
publisher_model.set_request_response_logging_config(
    enabled=False,
    )

API REST

Utilizza setPublisherModelConfig per disattivare la registrazione:

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

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la posizione della risorsa modello.
  • PUBLISHER: il nome dell'editore. Ad esempio, google.
  • MODEL: Il nome del modello di base. Ad esempio, gemini-2.0-flash-001.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig

Corpo JSON della richiesta: 

{
  "publisherModelConfig": {
     "loggingConfig": {
       "enabled": false
     }
  }
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo comando: 

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

Log di richiesta-risposta per i modelli ottimizzati

Puoi configurare i log di richiesta-risposta per i modelli ottimizzati utilizzando l'API REST o l'SDK Python.

Attiva i log di richiesta-risposta

Seleziona una delle seguenti schede per istruzioni su come attivare i log richiesta-risposta per un modello sottoposto a fine tuning.

SDK Python

Questo metodo può essere utilizzato per aggiornare la configurazione della registrazione di richieste e risposte per un endpoint.

# Specify the preview version of GenerativeModel
import vertexai
from vertexai.preview.generative_models import(
    GenerativeModel,
    )

PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

vertexai.init(project=PROJECT_ID, location=LOCATION)

tuned_model = GenerativeModel(f"projects/{PROJECT_ID}/locations/{LOCATION}/endpoints/ENDPOINT_ID")

# Set logging configuration
publisher_model.set_request_response_logging_config(
    enabled=True,
    sampling_rate=1.0,
    bigquery_destination=f"bq://{PROJECT_ID}.DATASET_NAME.TABLE_NAME",
    enable_otel_logging=True,
    )

API REST

Puoi attivare la registrazione delle richieste e delle risposte solo quando crei un endpoint utilizzando projects.locations.endpoints.create o quando modifichi un endpoint esistente utilizzando projects.locations.endpoints.patch.

Le richieste e le risposte vengono registrate a livello di endpoint, quindi vengono registrate le richieste inviate a tutti i modelli di cui è stato eseguito il deployment nello stesso endpoint.

Quando crei o applichi una patch a un endpoint, inserisci dati nel campo predictRequestResponseLoggingConfig della risorsa Endpoint con le seguenti voci:

  • enabled: impostato su True per abilitare la registrazione di richieste e risposte.

  • samplingRate: per ridurre i costi di archiviazione, puoi impostare un numero compreso tra 0 e 1 per definire la frazione di richieste da registrare. Ad esempio, un valore pari a 1 registra tutte le richieste, mentre un valore pari a 0,1 registra il 10% delle richieste.

  • BigQueryDestination: la tabella BigQuery da utilizzare per la registrazione. Se specifichi solo un nome di progetto, viene creato un nuovo set di dati con il nome logging_ENDPOINT_DISPLAY_NAME_ENDPOINT_ID, dove ENDPOINT_DISPLAY_NAME segue le regole di denominazione di BigQuery. Se non specifichi un nome tabella, ne viene creata una nuova con il nome request_response_logging.

  • enableOtelLogging: impostato su true per attivare il logging OpenTelemetry (OTEL) oltre al logging predefinito di richiesta-risposta.

Per visualizzare lo schema della tabella BigQuery, vedi Schema della tabella di logging.

Di seguito è riportata una configurazione di esempio:

{
  "predictRequestResponseLoggingConfig": {
    "enabled": true,
    "samplingRate": 0.5,
    "bigqueryDestination": {
      "outputUri": "bq://PROJECT_ID.DATASET_NAME.TABLE_NAME"
    },
    "enableOtelLogging": true
  }
}

Recuperare la configurazione di logging

Recupera la configurazione della registrazione delle richieste e delle risposte per il modello sottoposto a fine tuning utilizzando l'API REST.

API REST

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

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la posizione della risorsa endpoint.
  • MODEL: Il nome del modello di base. Ad esempio, gemini-2.0-flash-001.
  • ENDPOINT_ID: l'ID dell'endpoint.

Metodo HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID

Per inviare la richiesta, scegli una di queste opzioni:

curl

Esegui questo comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID"

PowerShell

Esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

Disabilita la configurazione del logging

Disattiva la configurazione del logging delle richieste e delle risposte per l'endpoint.

SDK Python

# Specify the preview version of GenerativeModel
import vertexai
from vertexai.preview.generative_models import(
    GenerativeModel,
    )

PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

vertexai.init(project=PROJECT_ID, location=LOCATION)

tuned_model = GenerativeModel(f"projects/{PROJECT_ID}/locations/{LOCATION}/endpoints/ENDPOINT_ID")

# Disable logging
tuned_model.set_request_response_logging_config(
    enabled=False,
    )

API REST

{
"predictRequestResponseLoggingConfig": {
  "enabled": false
}
}

Schema della tabella di logging

In BigQuery, i log vengono registrati utilizzando il seguente schema:

Nome campo Tipo Note
endpoint STRING Nome della risorsa dell'endpoint su cui viene eseguito il deployment del modello ottimizzato.
deployed_model_id STRING ID modello di cui è stato eseguito il deployment per un modello ottimizzato di cui è stato eseguito il deployment su un endpoint.
logging_time TIMESTAMP L'ora in cui viene eseguito il logging. Questo è approssimativamente il momento in cui viene restituita la risposta.
request_id NUMERIC ID richiesta intero generato automaticamente in base alla richiesta API.
request_payload STRING Incluso per il logging dei modelli partner e la compatibilità con le versioni precedenti con il log di richiesta/risposta dell'endpoint Vertex AI.
response_payload STRING Incluso per il logging dei modelli partner e la compatibilità con le versioni precedenti con il log di richiesta/risposta dell'endpoint Vertex AI.
modello STRING Nome della risorsa del modello.
model_version STRING La versione del modello. Spesso è "default" per i modelli Gemini.
api_method STRING generateContent, streamGenerateContent, rawPredict, streamRawPredict
full_request JSON L'intero GenerateContentRequest.
full_response JSON L'intero GenerateContentResponse.
metadati JSON Qualsiasi metadato della chiamata; contiene la latenza della richiesta.
otel_log JSON Log nel formato dello schema OpenTelemetry. Disponibile solo se otel_logging è abilitato nella configurazione della registrazione.

Tieni presente che le coppie richiesta-risposta più grandi del limite di 10 MB per le righe dell'API BigQuery Write non vengono registrate.

Passaggi successivi