Registe pedidos e respostas

O Vertex AI pode registar exemplos de pedidos e respostas para o Gemini e modelos de parceiros suportados. Os registos são guardados numa tabela do BigQuery para visualização e análise. Esta página descreve como configurar registos de pedido-resposta para modelos de base e modelos com ajuste fino.

Métodos da API suportados para registo

Os registos de pedido-resposta são suportados para todos os modelos Gemini que usam generateContent ou streamGenerateContent.

Os seguintes modelos de parceiros que usam rawPredict ou streamrawPredict também são suportados:

  • Anthropic Claude

Registos de pedido-resposta para modelos de base

Pode configurar registos de pedidos e respostas para modelos de base usando a API REST ou o SDK Python. As configurações de registo podem demorar alguns minutos a entrar em vigor.

Ative o registo de pedidos-respostas

Selecione um dos seguintes separadores para ver instruções sobre como ativar os registos de pedido-resposta para um modelo base fundamental.

Para os modelos da Anthropic, apenas o REST é suportado para a configuração do registo. Ative a configuração de registo através da API REST definindo o publicador como anthropic e definindo o nome do modelo como um dos modelos Claude suportados.

SDK Python

Este método pode ser usado para criar ou atualizar um 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

Crie ou atualize um PublisherModelConfig através do setPublisherModelConfig:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • ENDPOINT_PREFIX: a região do recurso do modelo seguida de -. Por exemplo, us-central1-. Se usar o ponto final global, deixe em branco. O registo de pedidos e respostas é suportado para todas as regiões suportadas pelo modelo.
  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região do recurso do modelo. Se usar o ponto final global, introduza global.
  • PUBLISHER: o nome do publicador. Por exemplo, google.
  • MODEL: o nome do modelo base. Por exemplo, gemini-2.0-flash-001.
  • SAMPLING_RATE: para reduzir os custos de armazenamento, pode definir um número entre 0 e 1 para definir a fração de pedidos a registar. Por exemplo, um valor de 1 regista todos os pedidos e um valor de 0, 1 regista 10% dos pedidos.
  • BQ_URI: a tabela do BigQuery a usar para o registo. Se especificar apenas um nome de projeto, é criado um novo conjunto de dados com o nome logging_ENDPOINT_DISPLAY_NAME\_ENDPOINT_ID, em que ENDPOINT_DISPLAY_NAME segue as regras de nomenclatura do BigQuery. Se não especificar um nome de tabela, é criada uma nova tabela com o nome request_response_logging.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Deve receber uma resposta JSON semelhante à seguinte:

Obtenha a configuração de registo

Obtenha a configuração do registo de pedidos e respostas para o modelo base através da API REST.

API REST

Obtenha a configuração do registo de pedidos e respostas através de fetchPublisherModelConfig:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a localização do recurso do modelo.
  • PUBLISHER: o nome do publicador. Por exemplo, google.
  • MODEL: o nome do modelo base. Por exemplo, gemini-2.0-flash-001.

Método HTTP e URL: 

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Execute o seguinte 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

Execute o seguinte 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

Deve receber uma resposta JSON semelhante à seguinte:

Desative o registo

Desative o registo de pedidos-respostas para o modelo base através da API REST ou do 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

Use setPublisherModelConfig para desativar o registo:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a localização do recurso do modelo.
  • PUBLISHER: o nome do publicador. Por exemplo, google.
  • MODEL: o nome do modelo base. Por exemplo, gemini-2.0-flash-001.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Deve receber uma resposta JSON semelhante à seguinte:

Registos de pedido-resposta para modelos com ajuste fino

Pode configurar registos de pedido-resposta para modelos otimizados usando a API REST ou o SDK Python.

Ative os registos de pedido-resposta

Selecione um dos seguintes separadores para ver instruções sobre como ativar os registos de pedido-resposta para um modelo com ajuste fino.

SDK Python

Este método pode ser usado para atualizar a configuração do registo de pedidos e respostas para um ponto final.

# 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

Só pode ativar o registo de pedidos/respostas quando cria um ponto final através de projects.locations.endpoints.create ou aplica um patch a um ponto final existente através de projects.locations.endpoints.patch.

Os pedidos e as respostas são registados ao nível do ponto final, pelo que os pedidos enviados para quaisquer modelos implementados no mesmo ponto final são registados.

Quando criar ou corrigir um ponto final, preencha o campo predictRequestResponseLoggingConfig do recurso Endpoint com as seguintes entradas:

  • enabled: definido como True para ativar o registo de pedidos/respostas.

  • samplingRate: para reduzir os custos de armazenamento, pode definir um número entre 0 e 1 para definir a fração de pedidos a registar. Por exemplo, um valor de 1 regista todos os pedidos e um valor de 0, 1 regista 10% dos pedidos.

  • BigQueryDestination: a tabela do BigQuery a usar para o registo. Se especificar apenas um nome do projeto, é criado um novo conjunto de dados com o nome logging_ENDPOINT_DISPLAY_NAME_ENDPOINT_ID, em que ENDPOINT_DISPLAY_NAME segue as regras de nomenclatura do BigQuery. Se não especificar um nome da tabela, é criada uma nova tabela com o nome request_response_logging.

  • enableOtelLogging: defina como true para ativar o registo do OpenTelemetry (OTEL) além do registo predefinido de pedido-resposta.

Para ver o esquema da tabela do BigQuery, consulte o artigo Esquema da tabela de registo.

Segue-se um exemplo de configuração:

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

Obtenha a configuração de registo

Obtenha a configuração do registo de pedidos-respostas para o modelo otimizado através da API REST.

API REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a localização do recurso do ponto final.
  • MODEL: o nome do modelo base. Por exemplo, gemini-2.0-flash-001.
  • ENDPOINT_ID: o ID do ponto final.

Método HTTP e URL: 

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Execute o seguinte 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

Execute o seguinte 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

Deve receber uma resposta JSON semelhante à seguinte:

Desative a configuração de registo

Desative a configuração do registo de pedidos e respostas para o ponto final.

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
}
}

Esquema da tabela de registo

No BigQuery, os registos são gravados com o seguinte esquema:

Nome do campo Tipo Notas
ponto final STRING Nome do recurso do ponto final no qual o modelo otimizado está implementado.
deployed_model_id STRING ID do modelo implementado para um modelo otimizado implementado num ponto final.
logging_time TIMESTAMP A hora em que o registo é feito. Este é aproximadamente o tempo que a resposta demora a ser devolvida.
request_id NUMERIC O ID do pedido de número inteiro gerado automaticamente com base no pedido da API.
request_payload STRING Incluído para o registo de modelos de parceiros e a retrocompatibilidade com o registo de pedidos-respostas do ponto final da Vertex AI.
response_payload STRING Incluído para o registo de modelos de parceiros e a retrocompatibilidade com o registo de pedidos-respostas do ponto final da Vertex AI.
modelo STRING Nome do recurso do modelo.
model_version STRING A versão do modelo. Esta é frequentemente a predefinição para os modelos Gemini.
api_method STRING generateContent, streamGenerateContent, rawPredict, streamRawPredict
full_request JSON O GenerateContentRequest completo.
full_response JSON O GenerateContentResponse completo.
metadados JSON Quaisquer metadados da chamada; contém a latência do pedido.
otel_log JSON Registos no formato de esquema OpenTelemetry. Apenas disponível se otel_logging estiver ativado na configuração de registo.

Tenha em atenção que os pares de pedido-resposta superiores ao limite de linhas de 10 MB da API Write do BigQuery não são registados.

O que se segue?