Registrar solicitações e respostas

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

Métodos de API com suporte 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 base

É 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 registro 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 conferir instruções sobre como ativar registros de solicitação-resposta para um modelo de base.

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

SDK do Python

Esse método pode ser usado para criar ou atualizar um PublisherModelConfig.

publisher_model = GenerativeModel('gemini-2.0-pro-001')

# 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. O registro de solicitação-resposta é aceito em todas as regiões com suporte ao modelo.
  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região do recurso do modelo. Se você estiver usando o endpoint global, insira global.
  • PUBLISHER: o nome do editor. Por exemplo, google.
  • MODEL: o nome do modelo de base. Por exemplo, gemini-2.0-flash-001.
  • SAMPLING_RATE: para reduzir os custos de armazenamento, é possível definir um número entre 0 ou 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% das solicitações.
  • 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 a seguir: 

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 a seguir: 

$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ê receberá uma resposta JSON semelhante a esta:

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

Receba a configuração de geração de registros de solicitação-resposta para o modelo de base usando a API REST.

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: o local do recurso do modelo.
  • PUBLISHER: o nome do editor. Por exemplo, google.
  • MODEL: o nome do modelo de 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 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 o registro de solicitação-resposta para o modelo de base usando a API REST ou o SDK do Python.

SDK do Python

publisher_model.set_request_response_logging_config(
  enabled=False,
  sampling_rate=0,
  bigquery_destination=''
  )

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: o local do recurso do modelo.
  • PUBLISHER: o nome do editor. Por exemplo, google.
  • MODEL: o nome do modelo de 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 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 a seguir: 

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 a seguir: 

$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ê receberá uma resposta JSON semelhante a esta:

Registros de solicitação-resposta para modelos ajustados

É possível configurar logs 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 conferir instruções sobre como ativar registros de solicitação-resposta para um modelo ajustado.

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.

tuned_model = GenerativeModel("projects/PROJECT_ID/locations/REGION/endpoints/ENDPOINT_ID")

# Set logging configuration
tuned_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

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, então as solicitações enviadas para todos os modelos implantados 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) em adição à geração de registros de solicitação-resposta padrão.

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

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 a configuração de geração de registros

Receba a configuração de geração de registros de solicitação-resposta para o modelo ajustado usando a API REST.

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 base. 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

tuned_model = GenerativeModel("projects/PROJECT_ID/locations/REGION/endpoints/ENDPOINT_ID")

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

API REST

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

Esquema da tabela de registro

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 é o tempo aproximado em que a resposta é retornada.
request_id NUMERIC O ID de 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 o registro de solicitações e respostas de endpoint da Vertex AI.
response_payload STRING Incluído para geração de registros de modelos de parceiros e compatibilidade com o registro de solicitações e respostas de endpoint da Vertex AI.
modelo STRING Nome do recurso do modelo.
model_version STRING A versão do modelo. Esse é o padrão para modelos 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 Write do BigQuery não são registrados.

A seguir