Registrar solicitações e respostas

A Vertex AI pode registrar amostras de solicitações e respostas para o Gemini e modelos de parceiros compatíveis. Os registros são salvos em uma tabela do BigQuery para visualização e análise. Nesta página, descrevemos como configurar registros de solicitação-resposta para modelos de base e modelos ajustados.

Métodos de API compatíveis para geração de registros

Os registros de solicitação-resposta são compatíveis com todos os modelos do Gemini que usam generateContent ou streamGenerateContent.

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

  • Claude antrópico

Registros de solicitação-resposta para modelos de fundação básicos

É possível configurar registros de solicitação-resposta para modelos de base usando a API REST ou o SDK do Python. As configurações de geração de registros podem levar alguns minutos para entrar em vigor.

Ativar a geração de registros de solicitação/resposta

Selecione uma das guias a seguir para instruções sobre como ativar registros de solicitação-resposta para um modelo de base.

Para modelos da Anthropic, apenas REST é compatível com a configuração de geração de registros. Ative a configuração de geração de registros pela API REST definindo o editor como anthropic e o nome do modelo como um dos modelos do Claude compatíveis.

SDK do Python

Esse 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 usando setPublisherModelConfig:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • ENDPOINT_PREFIX: a região do recurso do modelo seguida por -. Por exemplo, us-central1-. Se você estiver usando o endpoint global, deixe em branco. A geração de registros de solicitação-resposta é compatível com todas as regiões aceitas pelo modelo.
  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região do recurso de modelo. Se você estiver usando o endpoint global, insira global.
  • PUBLISHER: o nome do editor. Por exemplo, google.
  • MODEL: o nome do modelo de fundação. Por exemplo, gemini-2.0-flash-001.
  • SAMPLING_RATE: para reduzir os custos de armazenamento, defina um número entre 0 e 1 para definir a fração de solicitações a serem registradas. Por exemplo, um valor de 1 registra todas as solicitações, e um valor de 0,1 registra 10% delas.
  • BQ_URI: a tabela do BigQuery a ser usada para geração de registros. Se você especificar apenas um nome de projeto, um novo conjunto de dados será criado com o nome logging_ENDPOINT_DISPLAY_NAME\_ENDPOINT_ID, em que ENDPOINT_DISPLAY_NAME segue as regras de nomenclatura do BigQuery. Se você não especificar um nome de tabela, será 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 da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$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

Você vai receber uma resposta JSON semelhante a esta:

Acessar configuração de geração de registros

Use a API REST para receber a configuração de geração de registros de solicitação-resposta do modelo de base.

API REST

Receba a configuração de geração de registros de solicitação/resposta usando fetchPublisherModelConfig:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a localização do recurso do modelo.
  • PUBLISHER: o nome do editor. Por exemplo, google.
  • MODEL: o nome do modelo de fundação. 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 a solicitação, 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

Você receberá uma resposta JSON semelhante a esta:

Desative a geração de registros

Desative a geração de registros de solicitação-resposta para o modelo de base usando a API REST ou o SDK do Python.

SDK do 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 a geração de registros:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a localização do recurso do modelo.
  • PUBLISHER: o nome do editor. Por exemplo, google.
  • MODEL: o nome do modelo de fundação. 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 da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$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

Você vai receber uma resposta JSON semelhante a esta:

Registros de solicitação-resposta para modelos ajustados

É possível configurar registros de solicitação-resposta para modelos ajustados usando a API REST ou o SDK do Python.

Ativar registros de solicitação/resposta

Selecione uma das guias a seguir para instruções sobre como ativar registros de solicitação-resposta para um modelo refinado.

SDK do Python

Esse método pode ser usado para atualizar a configuração de geração de registros de solicitação-resposta de um 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

Só é possível ativar a geração de registros de solicitação/resposta ao criar um endpoint usando projects.locations.endpoints.create ou corrigir um endpoint existente usando projects.locations.endpoints.patch.

As solicitações e respostas são registradas no nível do endpoint. Portanto, as solicitações enviadas a qualquer modelo implantado no mesmo endpoint são registradas.

Ao criar ou corrigir um endpoint, preencha o campo predictRequestResponseLoggingConfig do recurso de endpoint com as seguintes entradas:

  • enabled: definido como True para ativar a geração de registros de solicitação-resposta.

  • samplingRate: para reduzir os custos de armazenamento, defina um número entre 0 e 1 para definir a fração de solicitações a serem registradas. Por exemplo, um valor de 1 registra todas as solicitações, e um valor de 0,1 registra 10% delas.

  • BigQueryDestination: a tabela do BigQuery a ser usada para geração de registros. Se você especificar apenas um nome de projeto, um novo conjunto de dados será criado com o nome logging_ENDPOINT_DISPLAY_NAME_ENDPOINT_ID, em que ENDPOINT_DISPLAY_NAME segue as regras de nomenclatura do BigQuery. Se você não especificar um nome de tabela, será criada uma nova tabela com o nome request_response_logging.

  • enableOtelLogging: definido como true para ativar a geração de registros do OpenTelemetry (OTEL) além da geração de registros padrão de solicitação-resposta.

Para conferir o esquema da tabela do BigQuery, consulte Esquema da tabela de registros.

Veja a seguir um exemplo de configuração:

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

Acessar configuração de geração de registros

Use a API REST para receber a configuração de geração de registros de solicitação-resposta do modelo refinado.

API REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: o local do recurso de endpoint.
  • MODEL: o nome do modelo de fundação. Por exemplo, gemini-2.0-flash-001.
  • ENDPOINT_ID: o ID do endpoint.

Método HTTP e URL: 

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

Para enviar a solicitação, 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

Você receberá uma resposta JSON semelhante a esta:

Desativar a configuração de geração de registros

Desative a configuração de geração de registros de solicitação-resposta para o endpoint.

SDK do 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 geração de registros

No BigQuery, os registros são gravados usando o seguinte esquema:

Nome do campo Tipo Observações
endpoint STRING Nome do recurso do endpoint em que o modelo ajustado é implantado.
deployed_model_id STRING ID do modelo implantado para um modelo ajustado implantado em um endpoint.
logging_time TIMESTAMP O horário em que o registro é realizado. Esse é aproximadamente o tempo em que a resposta é retornada.
request_id NUMERIC O ID da solicitação de número inteiro gerado automaticamente com base na solicitação da API.
request_payload STRING Incluído para geração de registros de modelos de parceiros e compatibilidade com versões anteriores com o registro de solicitação-resposta de endpoint da Vertex AI.
response_payload STRING Incluído para geração de registros de modelos de parceiros e compatibilidade com versões anteriores com o registro de solicitação-resposta de endpoint da Vertex AI.
modelo STRING Nome do recurso do modelo.
model_version STRING A versão do modelo. Geralmente, é "padrão" para modelos do Gemini.
api_method STRING generateContent, streamGenerateContent, rawPredict, streamRawPredict
full_request JSON O GenerateContentRequest completo.
full_response JSON O GenerateContentResponse completo.
metadados JSON Qualquer metadado da chamada. Contém a latência da solicitação.
otel_log JSON Registros no formato de esquema do OpenTelemetry. Disponível apenas se otel_logging estiver ativado na configuração de geração de registros.

Os pares de solicitação-resposta maiores que o limite de 10 MB por linha da API de gravação do BigQuery não são registrados.

A seguir