Sobre os atributos do produto

A Vertex AI para Pesquisa no comércio pode usar atributos de produtos para indexação, reconhecimento dinâmico, capacidade de pesquisa, filtragem e qualidade do modelo. Nesta página, você verá como definir configurações de atributos de produtos e como elas são tratadas dependendo do método e da configuração usados.

Tipos de atributo

Os atributos de produto podem ter diferentes configurações padrão e opções permitidas, dependendo do tipo.

  • Atributos do sistema: os atributos predefinidos são campos Product que fornecem mais informações sobre o produto. Isso inclui atributos de produto como marca, disponibilidade, cor e tamanho. Para conferir todos os atributos de sistema disponíveis para produtos, consulte a documentação de referência de Product.

  • Atributos personalizados: são atributos extras que você define usando o campo Product.attributes. Por exemplo, isso pode incluir nomes de lojas, fornecedores ou estilo. Para exemplos e limites de atributos personalizados, consulte a documentação de referência de Product.attributes.

    Alguns exemplos de atributos personalizados entre os 20 principais:

    • Linha de produtos a que este item pertence
    • Volume de vendas na loja para este produto
    • Ocasião para roupas
    • Ofertas e cupons aplicáveis a este produto
    • Popularidade do produto em todo o site

  • Atributos no nível do inventário: atributos do sistema ou personalizados que fornecem informações no nível da loja sobre o produto. Você pode usar atributos no nível do inventário para produtos cujas propriedades variam significativamente entre lojas e regiões, como itens de supermercado, ou para produtos que têm promoções específicas da loja.

    inventories.price e inventories.originalPrice são atributos numéricos do sistema predefinidos pela Vertex AI para Pesquisa para Commerce. É possível criar atributos personalizados no nível do inventário, que podem ser textuais ou numéricos. Por padrão, os atributos no nível do inventário são indexáveis. Não é possível definir atributos pesquisáveis e de refinamento dinâmico no nível do inventário.

Configurações disponíveis

As configurações de configuração de atributos afetam o comportamento de pesquisa e recomendações em todo o site.

A Pesquisa usa as seguintes configurações de atributo:

  • Indexável: a pesquisa pode filtrar e usar facetas com esse atributo.
  • Atributos dinâmicos: a pesquisa pode usar automaticamente esse atributo como um atributo dinâmico com base no comportamento anterior do usuário, como cliques e visualizações de atributos. Para ativar o atributo dinâmico para um atributo, Indexable precisa ser definido como verdadeiro para esse atributo.
  • Pesquisável: esse atributo pode ser pesquisado por consultas de pesquisa, o que aumenta o recall dele. Esse controle é aplicável apenas a atributos de texto.
  • Recuperável: se definido como "true", a pesquisa vai retornar esse atributo nas respostas às consultas de pesquisa. Se todos os atributos tiverem "Recuperável" definido como "false", os resultados da pesquisa vão conter apenas o nome do produto ou (para variantes) o nome do produto e as informações de cor. O campo REST "RetrievableFields" foi descontinuado para produtos. Em vez disso, use o controle recuperável em todo o site.

As recomendações usam as seguintes configurações de atributo:

  • Filtrável (pré-lançamento público): esse atributo pode ser usado em expressões de filtro de recomendações. Esse controle é aplicável apenas a atributos de texto.

Indexável

Se um atributo for definido como indexável, a pesquisa poderá filtrar e criar atributos usando o atributo.

  • Atributos do sistema: a indexabilidade está sempre ativada para atributos predefinidos do sistema. Essa configuração não pode ser desativada para atributos do sistema.
  • Atributos personalizados: ativados por padrão. É possível desativar a indexabilidade de qualquer atributo personalizado. Se você planeja tornar um índice de atributos personalizados indexável, ele precisa seguir o padrão de expressão regular [a-zA-Z0-9][a-zA-Z0-9_]*. Por exemplo, key0LikeThis ou KEY_1_LIKE_THIS.
  • Atributos no nível do inventário: sempre ativados para atributos do sistema no nível do inventário. Essa configuração não pode ser alterada. Ativada por padrão para atributos personalizados no nível do inventário. Essa configuração pode ser desativada.
  • Dependências: N/A

As mudanças na configuração do índice entram em vigor imediatamente após a importação dos dados do catálogo. Caso contrário, pode levar até 12 horas ou mais para que as mudanças entrem em vigor. É possível testar se as mudanças foram aplicadas na página Avaliar.

Atributos dinâmicos

Quando um atributo é configurado como dinâmico, a pesquisa pode usá-lo como um atributo dinâmico. Os atributos dinâmicos podem ser adicionados automaticamente a uma pesquisa com base no comportamento anterior do usuário, como cliques e visualizações.

  • Atributos do sistema: ativados por padrão se a capacidade de indexação estiver definida como "true". É possível desativar o atributo dinâmico para qualquer atributo do sistema.
  • Atributos personalizados: ativados por padrão se a capacidade de indexação estiver definida como "true". É possível desativar o atributo dinâmico para qualquer atributo personalizado.
  • Atributos no nível do inventário: não são aceitos.
  • Dependências: para ativar o atributo dinâmico para um atributo, primeiro ative a capacidade de indexação dele.

A definição do atributo dinâmico para um atributo sempre global. A configuração de atributos dinâmicos aplicada a esse atributo é usada por produtos no catálogo que o utilizam.

As mudanças na configuração do atributo dinâmico levam até dois dias. Para testar se as mudanças foram aplicadas, acesse a página Avaliar.

Para atributos personalizados numéricos, os buckets precisam ser especificados na solicitação. Os valores numéricos não são agrupados automaticamente.

Pesquisável

Se um atributo for definido como pesquisável, o recall dele nas consultas de pesquisa será melhorado.

Somente valores de atributos textuais podem ter a capacidade de pesquisa ativada. Não se aplica a atributos numéricos.

  • Atributos do sistema: os atributos predefinidos do sistema textual para Product têm as configurações de capacidade de pesquisa configuradas pela Vertex AI para Pesquisa no comércio. Não é possível mudar essa configuração.
  • Atributos personalizados: desativados por padrão. É possível ativar essa configuração para qualquer atributo personalizado textual.
  • Atributos no nível do inventário: não são aceitos.
  • Dependências: N/A
  • Pesquisa exata: a pesquisa segmentada retorna consultas que correspondem a qualquer produto no seu catálogo. Essa opção funciona bem para números de série. Saiba mais sobre a opção de pesquisa exata.

Embora os produtos com um atributo pesquisável tenham mais chances de aparecer nos resultados da pesquisa para esse atributo, não há garantia de que eles vão aparecer.

Filtragem de recomendações

Se um atributo tiver a filtragem de recomendações ativada, ele poderá ser usado em expressões de filtro de recomendações para filtrar produtos em previsões.

  • Atributos do sistema: desativados por padrão. É possível ativar essa configuração para qualquer atributo textual predefinido do sistema para Product, exceto FulfillmentInfo e title. Não é compatível com atributos numéricos.
  • Atributos personalizados: desativados por padrão. É possível ativar essa configuração para qualquer atributo textual personalizado em Product. Não é compatível com atributos numéricos.
  • Atributos no nível do inventário: aceitos apenas para o valor availability IN_STOCK.
  • Dependências: N/A

Opção de pesquisa exata

Você pode atribuir um valor específico para consultas de string específicas à opção exact-searchable, um campo de atributo do catálogo. Se uma consulta corresponder a um produto no catálogo em que o valor desse campo é a string fornecida na consulta, ela vai retornar exatamente esse produto na consulta de pesquisa. Essa opção funciona bem para números de série, em que os clientes esperam uma experiência de pesquisa segmentada.

Normalmente, para atributos personalizados, o campo ExactSearchableOption é útil para atributos de produto com um valor exato (como ModelId ou ManufacturerId). Atributos como product_id são campos de índice primário, ou seja, pesquisáveis por correspondência exata por padrão. O campo item_id está sempre ativado para correspondência exata e não pode ser desativado.

  • Para evitar que itens não relacionados sejam retornados nas pesquisas, nunca defina a opção de pesquisa como um valor genérico, como battery.
  • Para evitar a veiculação insuficiente de consultas de pesquisa, não defina campos especiais como tag (que pode ter "iphone" como um dos valores de string) como de pesquisa exata. Isso pode fazer com que essas consultas limitem os resultados para todos os iPhones no catálogo de produtos.

Para mais informações, consulte Sobre os atributos de produto.

Comportamento do atributo

Ao estruturar seu catálogo de produtos usando designações de produtos principais e variantes, saiba como os atributos de produto são processados para filtragem. O comportamento delas depende de você estar usando a pesquisa ou as recomendações e de como você configura a taxonomia do catálogo.

Para garantir um comportamento de filtragem previsível e preciso, mantenha a consistência e a integridade nas definições de atributos filtráveis em produtos principais e variantes. Essa abordagem ajuda na filtragem precisa, o que melhora a descoberta de produtos e a relevância da pesquisa.

Comportamento da variante principal na pesquisa x recomendações

Embora apenas os itens principais sejam retornados nos resultados de pesquisa e recomendação, a Vertex AI para Pesquisa no comércio otimiza a qualidade da pesquisa e da recomendação.

  • Para modelos de pesquisa, os atributos da variante são usados para o produto principal no índice de pesquisa. Os resultados da pesquisa mostram várias opções para o produto principal com base nos atributos das variantes.

  • Para modelos de recomendação, os detalhes e atributos do produto não são herdados do principal para a variante. Para uma qualidade ideal de recomendação, é fundamental que os produtos principais e variantes tenham detalhes completos e precisos para atributos importantes, como product.categories, product.title, product.attributes e product.prices.

Processar atributos durante a indexação e a filtragem

Se o mesmo atributo for definido em Primária e Variante, o atributo na variante fará parte da filtragem. Por exemplo, digamos que um atributo seja definido para um produto principal e suas variantes (cor ou tamanho). Os valores de atributos de variantes são usados principalmente para filtragem, em que o sistema verifica se alguma das variantes do item principal corresponde ao valor do atributo. Por exemplo, um produto principal pode ser marcado como out-of-stock, mas se pelo menos uma das variantes estiver in-stock, o produto principal vai aparecer nos resultados da pesquisa se um filtro in-stock for aplicado.

Por estes motivos, defina os mesmos atributos filtráveis em Principal e Variante:

  • Os atributos de variante têm precedência para filtragem. Se um atributo for definido em um produto principal e nas variantes dele, o atributo da variante será usado na filtragem. Por exemplo, se um produto principal tiver uma cor de marcador de posição, mas as variantes tiverem cores reais, a cor da variante será preenchida e usada para filtragem.

  • Para atributos relacionados ao inventário, como disponibilidade, se um produto principal tiver variantes, a disponibilidade dele precisa ser definida como OUT_OF_STOCK, enquanto a disponibilidade real (como IN_STOCK) precisa ser definida no nível da variante. Assim, o produto principal é considerado em estoque desde que pelo menos uma variante esteja disponível. Nesse caso, filtros como availability: ANY("IN_STOCK") retornam o produto principal corretamente.

  • Quando uma expressão de filtro é usada, a resposta de previsão retorna produtos principais que têm pelo menos um produto principal ou variante correspondente ao valor do atributo do filtro.

Atributos opcionais para filtragem

Mantenha o campo categories limpo e otimizado para taxonomia. Se for necessário mais filtragem, implemente-a com base em categorias amplas usando atributos personalizados separados, não no campo categories. Isso também evita um impacto negativo no treinamento do preenchimento automático para sugestões de categorias.

Por exemplo, digamos que você normalmente defina categorias como [lvl1, lvl1>lvl2, lvl1>lvl2>lvl3] para filtragem. O preenchimento automático conta as categorias mais frequentes para uma determinada consulta. Assim, lvl1 e lvl2 (todos os seus produtos) aparecem como categorias sugeridas.

Práticas recomendadas

Se o catálogo consistir em produtos principais e variantes e o mesmo atributo for definido em ambos, o atributo na variante será considerado durante a filtragem.

  • Preencha os atributos com precisão: verifique se os produtos principais e variantes têm detalhes completos e precisos nos atributos, principalmente aqueles usados para filtragem, para maximizar a eficácia.

  • Use campos integrados: não dependa apenas de atributos personalizados. Mapeie as informações do produto para os campos Product integrados (brands, colors, sizes e os campos obrigatórios). Os campos integrados têm um impacto maior na capacidade de pesquisa, indexação e otimizações de relevância. Os atributos personalizados (Product.attributes) são usados para dados de produtos que não se encaixam nos atributos predefinidos do sistema.

  • Definir o controle de campos recuperáveis em todo o site: a API é compatível com variantRollupKeys para variantes, permitindo que você recupere detalhes nas respostas de pesquisa.

  • Idioma consistente do catálogo: o catálogo de produtos precisa estar em um só idioma, e as consultas de pesquisa precisam ser enviadas no mesmo idioma. Ter vários idiomas no catálogo pode prejudicar o desempenho do modelo. Não definir o código de idioma pode afetar recursos como a correção ortográfica.

  • Informações de preço: preencha com precisão as informações de preço dos produtos principais e das variantes para garantir recomendações e filtragem precisas. Se um produto não tiver preços no nível do produto e depender apenas dos preços do inventário local, preencha o preço do produto principal com a mediana dos preços no nível do inventário.

Modos de configuração

O modo de configuração determina como as configurações de atributo são tratadas e quais configurações de atributo você pode definir.

  • Modo de configuração no nível do catálogo (padrão): nesse modo, as configurações de atributo no nível do catálogo são usadas como fonte da verdade.
  • Modo de configuração no nível do produto (descontinuado): nesse modo, as configurações de atributo no nível do produto são usadas como fonte da verdade.

Antes, a configuração no nível do produto era o modo padrão. Se você ainda está no modo de configuração no nível do produto e precisa alternar para o modo de configuração no nível do catálogo, entre em contato com o suporte. Após fazer a troca, a pesquisa não é compatível com o modo de configuração no nível do produto.

Para verificar o modo de configuração, acesse a página Controles do console de pesquisa para e-commerce. Se a opção Indexável estiver disponível como uma coluna na guia Controles em todo o site, o modelo de configuração será no nível do catálogo. Se a coluna Indexável não estiver disponível na guia Controles em todo o site, o modelo de configuração será no nível do produto.

Métodos de configuração

É possível definir configurações de atributos das seguintes maneiras:

  • Console de pesquisa para comércio: defina configurações de atributo no nível do catálogo usando o console de pesquisa para comércio. Isso configura atributos globalmente em todos os produtos. Quais dessas configurações estão disponíveis no console depende do modo de configuração. Consulte a próxima seção para mais detalhes sobre como configurar atributos no console.

  • Método de API AttributeConfig: defina as configurações de atributo no nível do catálogo usando a API. Isso configura atributos em todos os produtos.

  • Método de API Product (descontinuado): defina atributos personalizados no nível do produto usando o método de API Product. Definir atributos com esse método não está disponível para novos usuários e não é recomendado.

Configurar atributos no console

É possível definir globalmente as opções de atributo em todos os produtos na página Controles do console Pesquisa para e-commerce, na guia Controles em todo o site. Para mais detalhes sobre como definir isso no console, consulte Gerenciar controles de atributos para todo o site.

Para usar esse recurso, o modo de configuração precisa ser no nível do catálogo.

As alterações nas configurações de atributos para indexação e pesquisa entram em vigor imediatamente após a ingestão do catálogo. Caso contrário, pode levar até 12 horas ou mais para que as mudanças entrem em vigor. É possível testar se as mudanças foram aplicadas na página Avaliar.

Configurar atributos com AttributesConfig

Com o recurso de API AttributesConfig, é possível gerenciar configurações de atributos no nível do catálogo.

Os campos a seguir definem opções de atributo no nível do catálogo:

Para recuperar todas as configurações de atributo, use o método GetAttributesConfig.

Atualizar vários atributos

Use o método updateAttributesConfig para atualizar vários atributos no nível do catálogo.

Os atributos do catálogo incluídos na solicitação são atualizados ou inseridos no catálogo, caso não existam. Se não houver um valor para um campo de atributo do catálogo, ele vai receber um valor padrão.

O número máximo de atributos de catálogo permitidos em uma solicitação é 1.000.

Atualizar um atributo individual

Os seguintes métodos são usados para atualizar atributos individuais do catálogo:

  • AddCatalogAttribute: adiciona uma configuração de atributo individual a um atributo do catálogo.

    Consulte a documentação de referência da API para AddCatalogAttribute.

  • ReplaceCatalogAttribute: modifica uma configuração de atributo individual. Isso substitui o CatalogAttribute especificado no AttributesConfig atualizando o atributo do catálogo com o mesmo CatalogAttribute.key.

    Consulte a documentação de referência da API para ReplaceCatalogAttribute.

  • RemoveCatalogAttribute: remove uma configuração de atributo individual de AttributesConfig.

    Só é possível excluir CatalogAttributes que não estão sendo usados por produtos. Se um CatalogAttribute estiver em uso, RemoveCatalogAttribute não o excluirá, mas redefinirá as propriedades de configuração para os valores padrão. CatalogAttribute.inUse é definido como True se o atributo estiver em uso por algum produto.

    Consulte a documentação de referência da API para RemoveCatalogAttribute.

Configurar atributos com o método Product (descontinuado)

A definição de atributos com esse método não está disponível para novos usuários e não é recomendada.

Os campos a seguir definem as configurações indexáveis e pesquisáveis de um produto específico usando o método de API Product: