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

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

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

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 seu 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 com precisão através da API REST ou do 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.

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ó 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 aplicar uma correção a 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: definido como true para ativar o registo de OpenTelemetry (OTEL) além do registo de pedido-resposta predefinido.

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 seu 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 de registo de pedidos e respostas para o ponto final.

SDK 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 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. Só está 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?