A Vertex AI para Pesquisa no varejo vai substituir a plataforma Retail. Estamos atualizando o conteúdo para refletir o novo branding.

Esta página foi traduzida pela API Cloud Translation.

Monitoramento e solução de problemas

Esta página descreve como receber informações sobre erros que ocorreram em importações de eventos do catálogo e do usuário e em outras operações da API no Vertex AI Search for Retail.

Se precisar de ajuda para configurar alertas, consulte Configurar alertas do Cloud Monitoring.

Introdução

É importante fornecer informações precisas do catálogo e eventos do usuário para a API. Assim, é importante conseguir os melhores resultados. Monitorar e entender a origem dos erros ajuda você a encontrar e corrigir erros no seu site.

Conferir erros de integração agregados

Para conferir os erros agregados gerados pelos processos de upload de dados e solicitações de previsão ou pesquisa, use a página Monitoramento.

Nesta página, você vai encontrar todos os erros da API Vertex AI Search for Retail. É possível conferir erros relacionados ao catálogo de produtos, eventos do usuário, previsões de recomendações, resultados da pesquisa e modelos. O sistema também registra erros de importações, como uma linha malformada no arquivo do Cloud Storage. O sistema registra até 100 erros por arquivo de importação. Você pode definir o período em que os erros são exibidos e filtrar com base no tipo de erro.

É possível clicar em um erro individual para ver os registros desse erro no Cloud Logging.

É possível abrir registros de erro individuais expandindo esse registro. Os registros de erros fornecem mais detalhes sobre a solicitação, incluindo payloads de solicitações e respostas e detalhes dos erros. Essas informações podem ajudar você a determinar onde a chamada de método incorreto está localizada no seu site.

Para erros de JSON inválidos, é possível ver mais informações sobre o problema expandindo o campo status.

Conferir o status de uma operação de integração específica

É possível conferir o status de uma operação de integração específica na janela Status da atividade:

Acesse a página Dados> no console da Pesquisa para varejo.

Acessar a página "Dados"
Clique em Status da atividade.

A janela Status da atividade mostra o status das operações de longa duração no catálogo de produtos, nos eventos do usuário e nos controles.

É possível inspecionar erros para operações específicas de integração nessa janela.
Clique em Ver registros na coluna "Detalhes" de qualquer operação com um erro para inspecionar os arquivos de registros no Cloud Logging.

Ver registros no Cloud Logging

Para abrir os arquivos de registro diretamente no Cloud Logging, use o seguinte procedimento. Você precisa ter o papel de Visualizador de registros (roles/logging.viewer) para conferir os registros.

Acesse o Explorador de registros no console do Google Cloud. Acessar o Explorador de registros
Selecione seu projeto da Vertex AI para Pesquisa para varejo no seletor de projetos.
Clique no menu suspenso Recurso e selecione API consumida > Cloud Retail.

Para mais informações sobre o Explorador de registros, consulte Conferir registros usando o Explorador de registros.

Por exemplo, este link abre registros de todos os erros da Vertex AI para Pesquisa para varejo na última hora:

Abrir os registros da Vertex AI para Pesquisa no varejo

Para configurar quais registros de API são gravados, consulte Configurar a geração de registros.

Configurar a geração de registros

É possível configurar quais registros de serviço são gravados no Logging. A configuração de registro oferece uma maneira de definir os níveis de gravidade em que registrar logs, ativar ou desativar o registro e substituir as configurações padrão de registro para serviços específicos.

Cada solicitação de API feita por um usuário final pode gerar uma entrada de registro. Uma entrada contém informações como o método da API, quando ele foi invocado, o código de resposta e os corpos de solicitação e resposta. A configuração de geração de registros de um projeto especifica quais tipos de registros gerados pela API são gravados no Logging, com a opção de especificar de forma granular as configurações de geração de registros para serviços específicos da API.

Para atualizar as configurações de registro, você precisa da função de editor da Vertex AI para Pesquisa para varejo.

Você pode usar o console ou a API LoggingConfig para configurar o Logging.

Console

Para atualizar as configurações de geração de registros no console, siga estas etapas:

Acesse a página Monitoramento no console da Pesquisa para varejo.

Acessar a página "Monitoramento"
Clique em Configuração de registro.
Para definir uma configuração de geração de registros global, selecione um nível de geração de registros. Se você selecionar LOG_ALL, também insira uma taxa de amostragem para registros com êxito.
Para definir uma configuração no nível do serviço, selecione um serviço para atualizar e escolha o nível de registro dele. Essa configuração substitui a configuração global de registro.

curl

Para atualizar as configurações de geração de registros usando a API, use o recurso LoggingConfig. Consulte a referência da API LoggingConfig.

Para conferir a configuração atual de geração de registros, use loggingConfig.Get.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig"

PROJECT_ID: o ID do seu projeto.

Para atualizar a configuração de geração de registros, use o método loggingConfig.Patch. Para saber mais, consulte a referência da API LoggingConfig.

Este exemplo usa loggingConfig.Patch para definir a configuração de geração de registros global como LOG_WARNINGS_AND_ABOVE. Ele também define duas configurações no nível do serviço: CatalogService é definido como LOG_WARNINGS_AND_ABOVE e ControlService é definido como LOG_ALL.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig" \
  --data '{
    "name": "projects/PROJECT_ID/loggingConfig",
    "default_log_generation_rule": {"logging_level": "LOG_ERRORS_AND_ABOVE"},
    "service_log_generation_rules": [
      {
        "service_name": "CatalogService",
        "log_generation_rule": {
          "logging_level": "LOG_WARNINGS_AND_ABOVE"
          }
      },
      {
        "service_name": "ControlService",
        "log_generation_rule": {
            "logging_level": "LOG_ALL", "info_log_sample_rate": "0.1"
            }
        }
      ]
    }'

Níveis de registro

Apenas registros de alguns níveis de gravidade são gravados no Logging. As configurações de nível de registro determinam quais registros gerados por um método de API são gravados no registro.

Quando nenhuma configuração de registro no nível do serviço está definida para um método da API, a configuração global de nível de registro é usada.

A configuração padrão do nível de registro é LOG_WARNINGS_AND_ABOVE.

O campo logging_level aceita os seguintes valores:

LOGGING_DISABLED: nenhum registro foi gravado.
LOG_ERRORS_AND_ABOVE: registra apenas erros.
LOG_WARNINGS_AND_ABOVE: registra apenas erros e avisos.
LOG_ALL: registra tudo, incluindo registros bem-sucedidos, como INFO.

Taxa de amostragem para registros bem-sucedidos

Se você definir o nível de registro como LOG_ALL, mas não quiser registrar todos os registros bem-sucedidos, especifique uma taxa de amostragem. Por exemplo, você pode decidir monitorar periodicamente os registros para confirmar o status ou conferir uma porcentagem de registros bem-sucedidos. Especificar uma taxa de amostragem pode ajudar você a fazer isso sem gravar um grande volume de entradas de registro INFO no Logging, o que pode gerar custos mais altos.

Para especificar uma taxa de amostragem, defina info_log_sample_rate como um valor float válido maior que 0 e menor ou igual a 1. A taxa de amostragem determina a probabilidade de um registro INFO ser gravado no registro. O valor padrão é 1 (todos os registros INFO são gravados).

Configurações no nível do serviço

É possível definir configurações de registro para serviços específicos. Isso substitui a configuração global de geração de registros para esse serviço. Por exemplo, talvez o nível de geração de registros global esteja definido como LOG_WARNINGS_AND_ABOVE, mas o nível de geração de registros do serviço UserEventService esteja definido como LOG_ALL para que você possa verificar integrações de eventos do usuário bem-sucedidas.

Use o objeto ServiceLoggingLevel para definir níveis de geração de registros granulares.

O campo service_name aceita os seguintes valores:

CompletionService
ControlService
MerchantCenterStreaming
ModelService
PredictionService
ProductService
ServingConfigService
UserEventService

Tipos de erro

Esta seção fornece definições dos tipos de erro que podem aparecer nos registros:

MISSING_FIELD: um valor de campo obrigatório não foi definido. por exemplo, um item de catálogo não tem o título.
INVALID_TIMESTAMP: o carimbo de data/hora é inválido, por exemplo, estar muito distante no futuro ou formatado incorretamente.
FIELD_VALUE_TOO_SMALL: o valor no campo é menor que o mínimo necessário; por exemplo, um preço negativo.
INCORRECT_JSON_FORMAT: o JSON na solicitação está formatado incorretamente, como um colchete { ausente.
INVALID_LANGUAGE_CODE: o código do idioma está formatado incorretamente.
FIELD_VALUE_EXCEEDED: o valor no campo é maior que o máximo permitido.
INVALID_RESOURCE_ID: o ID do recurso é inválido; por exemplo, um catalog_id inexistente no nome do recurso.
FIELD_SIZE_EXCEEDED: o número de entradas no campo excede o limite máximo.
UNEXPECTED_FIELD: um campo que deveria estar vazio foi preenchido. Por exemplo, a transação para um evento de visualização da página de detalhes.
INVALID_FORMAT: o campo não está formatado corretamente, como uma string malformada.
RESOURCE_ALREADY_EXISTS: você tentou criar um recurso que já existe, como um item de catálogo criado anteriormente.
INVALID_API_KEY: a chave de API não corresponde ao projeto na sua solicitação.
INSUFFICIENT_PERMISSIONS: você não tem permissão para executar a solicitação. Esse erro geralmente está relacionado à falta de permissão do IAM necessária.
UNJOINED_WITH_CATALOG: a solicitação inclui um código de item de catálogo que não existe no catálogo. Verifique se o seu catálogo está atualizado.
BATCH_ERROR: a solicitação tem vários erros. Por exemplo, uma importação in-line com 10 itens que falharam na validação por motivos diferentes.
INACTIVE_RECOMMENDATION_MODEL: você consultou um modelo que não está ativo para exibição.
ABUSIVE_ENTITY: o ID do visitante ou do usuário associado à solicitação enviou um número anormal de eventos em um curto período.
FILTER_TOO_STRICT: o filtro de solicitação de previsão bloqueou todos os resultados da previsão. Os itens genéricos (não personalizados) conhecidos são retornados, a menos que a chamada especifique strictFiltering como falso. Nesse caso, nenhum item é retornado. Veja alguns motivos comuns que podem causar esse problema:
- Você está especificando uma tag de filtro que não existe no seu catálogo. Pode levar até um dia para que uma atualização de tag de filtro entre em vigor.
- Seu filtro é muito limitado.

Conferir métricas de carregamento de dados

Para monitorar a ingestão de dados de eventos do usuário e do catálogo no console do Google Cloud, siga estas etapas:

Confira as métricas de erro da ingestão de dados de eventos de catálogo e do usuário na página Monitoramento.

Acessar a página "Monitoramento"
Depois que o sistema de upload de dados estiver em execução, use as guias Catálogo e Evento na página Dados para conferir informações agregadas sobre seu catálogo, visualizar os produtos enviados e conferir visualizações das métricas de integração de eventos do usuário.

Acessar a página "Dados"
Para criar alertas que informam se algo der errado com seus uploads de dados, siga os procedimentos em Configurar alertas do Cloud Monitoring.

Resumo dos dados do catálogo

Use a guia Catálogo na página Dados para ver estatísticas de dados de alto nível para cada ramificação de catálogo. Nesta página, você verá quantos produtos foram importados, quantos estão em estoque e quando foi a última importação de cada ramificação de catálogo de produtos.

Também é possível visualizar os itens do catálogo que você enviou e filtrar com base nos campos dos produtos.

É possível importar dados para diferentes ramificações como uma forma de organizar e visualizar recomendações ou resultados de pesquisa. Por exemplo, para se preparar para um período de festas de fim de ano, faça o upload de novos dados de catálogo para uma ramificação não padrão e verifique se os resultados da Vertex AI para Pesquisa de varejo são gerados corretamente antes de publicar no site.

Estatísticas de gravação de eventos do usuário

Para cada tipo de evento do usuário, é possível ver na guia Evento quantos você gravou, quantos não foram associados a um produto (eventos não incluídos) e as diferenças entre os números e os períodos anteriores. É possível selecionar um período predefinido ou inserir um intervalo personalizado.

O gráfico de métricas exibe os eventos do usuário ingeridos ao longo do tempo, que podem ser filtrados por tipo de evento.

Métricas de qualidade de dados

Na página Qualidade dos dados, você encontra métricas que mostram as porcentagens de produtos e eventos do usuário que atendem aos padrões recomendados de qualidade de dados para pesquisa. Use esta página para avaliar quais dados você precisa importar ou atualizar para melhorar a qualidade dos resultados da pesquisa e desbloquear níveis de desempenho da pesquisa.

Para mais informações sobre os níveis de desempenho da pesquisa e como verificar a qualidade dos seus dados, consulte Desbloquear níveis de desempenho da pesquisa.

Para conferir uma lista de todas as métricas de qualidade de dados do catálogo, consulte Métricas de qualidade de dados do catálogo.

Para todos os requisitos e recomendações de eventos do usuário para recomendações e pesquisa, consulte Requisitos e práticas recomendadas para eventos do usuário.

Eventos cancelados

Quando um evento de usuário ou uma solicitação de API se refere a um produto que não foi enviado para a Vertex AI para Pesquisa no varejo, ele é um evento não associado. Os eventos de usuários não associados ainda são registrados, e as solicitações separadas são processadas, mas nenhum deles pode ser usado para melhorar ainda mais o modelo para previsões futuras. Por esse motivo, verifique se a porcentagem de evento não registrado é muito baixa para eventos de usuário e solicitações de previsão.

Veja a porcentagem de evento de usuário desconectado na guia Evento da página Dados.

Erros da API

Para conferir um gráfico de erros da API ao longo do tempo, exibido pelo nome do método, clique em Visualizar métricas da API na barra de botões da página Monitoramento.

Monitorar a atividade do método da API

Para visualizar o tráfego, os erros e a latência por método de API, acesse a página Monitoramento. Você pode selecionar um período predefinido ou inserir um intervalo personalizado.

Para ver mais detalhes sobre cada gráfico:

Abaixo de um gráfico, clique no nome de um método para isolá-lo.
Passe o cursor sobre um gráfico para ver uma chamada com cada método e os valores deles nesse momento.
Clique e arraste sobre qualquer seção do gráfico para aumentar o zoom nesse período.

A seguir

Saiba como definir alertas de erros para seus feeds de dados.
Saiba mais sobre o Error Reporting.
Saiba mais sobre como visualizar registros no Logging.