Sobre os atributos do produto

A Pesquisa de e-commerce com IA pode usar atributos de produtos para indexação, facetas dinâmicas, capacidade de pesquisa, filtragem e qualidade do modelo. Nesta página, explicamos como definir configurações de atributos do produto e como elas são tratadas dependendo do método e da configuração usados.

Tipos de atributos

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

  • Atributos do sistema: atributos predefinidos do sistema são campos Product que fornecem mais informações sobre o produto. Isso inclui atributos do 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 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 AI Commerce Search. É possível criar atributos personalizados de nível de 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 refinamento dinâmico no nível do inventário.

Configurações de atributo disponíveis

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

Configuração Descrição Atributos do sistema Atributos personalizados Atributos no nível do inventário
Potencial de pesquisa Esse atributo pode ser pesquisado por consultas de pesquisa, o que aumenta o recall dele (somente atributos de texto). Sempre ativado (somente texto) Desativado por padrão (pode ser ativado; somente texto) Sem suporte
Capacidade de indexação A Pesquisa pode filtrar e criar facetas usando esse atributo. Sempre ativado Ativado por padrão (pode ser desativado). Sistema: sempre ativado
Personalizado: ativado por padrão (pode ser desativado).
Filtros de atributos dinâmicos A Pesquisa pode usar automaticamente esse atributo como um filtro dinâmico com base no comportamento anterior do usuário, como cliques e visualizações de filtros (somente atributos de texto). Ativado por padrão (se indexability = True) (pode ser desativado) Ativado por padrão (se indexability = True) (pode ser desativado) Sem suporte
Filtrável
(pré-lançamento)		 Esse atributo pode ser usado em expressões de filtro da Recommendations AI. Esse controle só é aplicável a atributos de texto. Desativado por padrão (pode ser ativado para texto, exceto FulfillmentInfo e Title). Desativado por padrão. Pode ser ativado para texto. Disponível apenas para availability=IN_STOCK
Correspondência exata Essa propriedade se aplica apenas a atributos personalizados textuais. Para ativar a pesquisa exata, o campo "indexable" precisa estar definido como "enabled". Sem suporte Desativado por padrão (pode ser ativado). Sem suporte

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

  • Indexável: a Pesquisa pode filtrar e criar atributos usando esse atributo.
  • Filtro dinâmico: a Pesquisa pode usar automaticamente esse atributo como um filtro dinâmico com base no comportamento anterior do usuário, como cliques e visualizações de filtros. 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 a recuperação 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. Use o controle recuperável em todo o site.

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

  • Filtrável (Acesso Antecipado): esse atributo pode ser usado em expressões de filtro de recomendações. Esse controle só é aplicável a atributos de texto.

Indexável

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

  • 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, as mudanças podem levar até 12 horas ou mais para entrar em vigor. Para testar se as mudanças foram aplicadas, acesse a página Avaliar.

Atributos dinâmicos

Quando os filtros de atributos dinâmicos estão ativados para um atributo, a pesquisa pode usar o atributo como um filtro 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 indexabilidade estiver definida como "true". É possível desativar o filtro dinâmico para qualquer atributo do sistema.
  • Atributos personalizados: ativados por padrão se a indexabilidade estiver definida como "true". É possível desativar o filtro dinâmico para qualquer atributo personalizado.
  • Atributos no nível do inventário: não são aceitos.
  • Dependências: para ativar o refinamento dinâmico de um atributo, primeiro é necessário ativar a indexabilidade 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 intervalos 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. Ela não é aplicável a atributos numéricos.

  • Atributos do sistema: atributos de texto predefinidos para Product têm as configurações de potencial de pesquisa definidas pela AI Commerce Search. Não é possível mudar essas configurações.
  • Atributos personalizados: desativados por padrão. É possível ativar essa configuração para qualquer atributo personalizado de texto.
  • Atributos no nível do inventário: não são aceitos.
  • Dependências: N/A
  • Pesquisa exata: a pesquisa segmentada retorna consultas de pesquisa 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

Embora haja um limite de 10 atributos filtráveis que podem ser agregados de variantes em produtos principais para 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. Você pode ativar essa configuração para qualquer atributo textual personalizado do 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 seu 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, podem ser pesquisados exatamente 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 "pesquisável" com um valor genérico, como battery.
  • Para evitar a subutilização de consultas de pesquisa, não defina campos especiais como tag (que pode ter "iphone" como um dos valores de string) como pesquisáveis por correspondência 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 do produto.

Práticas recomendadas de configuração de atributos

Essas práticas recomendadas são importantes para entender como indexar seus atributos personalizados corretamente, considerando alguns mecanismos de análise de linguagem que podem afetar a capacidade de pesquisa deles.

  • Como processar caracteres alfanuméricos (números de peças ou SKUs): como a análise linguística padrão é otimizada para linguagem natural, ela pode remover caracteres especiais, como hífens (-), de números de peças (por exemplo, convertendo part-123 em part e 123). Para que eles possam ser pesquisados, use a flag de atributo exact-searchable.
  • Solução alternativa de n-grama: para números de modelo altamente complexos que contêm caracteres especiais, a prática recomendada é dividir a string em n-gramas no seu próprio pipeline de dados antes da ingestão e armazenar a string original em um atributo personalizado marcado como exact searchable: true. Isso força a correspondência rígida com seus fragmentos de n-gramas.
  • Restrições de chave de atributo personalizado: as chaves de atributo personalizado não podem conter hífens nem caracteres especiais. Para ser indexável, a chave precisa corresponder estritamente ao padrão de expressão regular [a-zA-Z0-9][a-zA-Z0-9_]*. Para mais informações, consulte a página Sobre atributos de produto.
  • Requisito UTF-8: todos os atributos e valores de string precisam ser strings válidas com codificação UTF-8.

Comportamento de atribuição

Ao estruturar seu catálogo de produtos usando designações de produtos principais e variantes de produto, saiba como os atributos do produto são processados para filtragem. O comportamento deles 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 de produto. 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 AI Commerce Search otimiza a qualidade da pesquisa e da recomendação.

  • Para modelos de pesquisa, os atributos de variante são usados para o produto principal no índice da 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 do produto e atributos não são herdados do principal para a variante. Para uma qualidade ideal de recomendação, é fundamental que os produtos principais e variantes de produto 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 Principal 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. Considere a disponibilidade do produto: um produto principal pode ser marcado out-of-stock, mas se pelo menos uma das variantes estiver in-stock, o produto principal estará disponível para resultados da pesquisa se um filtro in-stock for aplicado.

  • 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. Se sim, filtros como availability: ANY("IN_STOCK") vão retornar 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 variantes de produto 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, você acaba com lvl1 e lvl2 (todos os seus produtos) como categorias sugeridas.

Práticas recomendadas de comportamento de atribuição

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

  • Preencha os atributos com precisão: garanta que os produtos principais e variantes de produto tenham detalhes completos e precisos para os atributos, especialmente 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 no potencial de pesquisa, indexabilidade e otimizações de relevância. Os atributos personalizados (Product.attributes) são para dados de produtos que não se encaixam em atributos de sistema predefinidos.

  • Definir o controle de campos recuperáveis em todo o site: a API é compatível com variantRollupKeys para variantes, permitindo recuperar 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 a performance 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 de produto 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 delas podem ser definidas.

  • 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 a 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 a fonte de verdade.

Antes, a configuração no nível do produto era o modo padrão. Se você ainda estiver no modo de configuração no nível do produto e precisar mudar para o modo de configuração no nível do catálogo, entre em contato com o suporte. A Pesquisa não permite voltar ao modo de configuração no nível do produto depois que você mudar.

Para verificar o modo de configuração, acesse a página Controles do console da AI Commerce Search no Gemini Enterprise for Customer Experience. 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 atributo das seguintes maneiras:

  • O console da Pesquisa de comércio com IA no Gemini Enterprise for Customer Experience: defina configurações de atributos no nível do catálogo usando o console da Pesquisa de comércio com IA no Gemini Enterprise for Customer Experience. Isso configura atributos globalmente em todos os produtos. A disponibilidade dessas configurações no console depende do modo de configuração. Consulte a próxima seção para mais detalhes sobre como configurar atributos no console.

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

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

Configurar atributos no console

Você pode definir opções de atributos globais em todos os produtos na página Controles do console da AI Commerce Search no Gemini Enterprise for Customer Experience, na guia Controles em todo o site. Para mais detalhes sobre como definir isso no console, consulte Gerenciar controles de atributos em todo o site.

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

As mudanças nas configurações de atributos para indexáveis e pesquisáveis 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. Para testar se as mudanças foram aplicadas, acesse a página Avaliar.

Configurar atributos com AttributesConfig

O recurso de API AttributesConfig permite 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 no catálogo ou inseridos se não existirem. 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 em uso por produtos. Se um CatalogAttribute estiver em uso, RemoveCatalogAttribute não o excluirá, mas vai 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.

Práticas recomendadas para nomear e estruturar atributos personalizados

Ao estender os dados de produtos além do esquema predefinido, a forma como você nomeia e formata seus atributos personalizados afeta diretamente a capacidade do AI Commerce Search de indexar, recuperar e segmentar seus produtos.

Siga estas práticas recomendadas para garantir a performance ideal da pesquisa e evitar erros de validação:

  1. Priorize os atributos nativos do sistema. Antes de criar um atributo personalizado, verifique se já existe um atributo padrão do sistema (como brands, colorInfo, sizes ou materials) para seus dados. Os modelos de IA de back-end entendem muito melhor os campos padrão do que os atributos personalizados e os consideram muito nas otimizações de relevância e recall.

    • Exemplo: não transmita informações da marca como Product.attributes.brand. Em vez disso, mapeie diretamente para o campo Product.brands padrão. Salve atributos personalizados para dados exclusivamente específicos, como Product.attributes.sleeve_length.

  2. Siga convenções de nomenclatura rigorosas para indexabilidade. Se você pretende usar um atributo personalizado para filtragem, refinamento ou reforço, ele precisa ser marcado como Indexable. Para ser indexável, a chave do atributo personalizado precisa obedecer ao padrão de expressão regular [a-zA-Z0-9][a-zA-Z0-9_]*.

    • Nomenclatura válida: sleeve_length ou KEY_1_LIKE_THIS.
    • Nomeação inválida: sleeve-length (hífens não são permitidos e impedem a indexação).
    • Limites: a chave de atributo precisa ser uma string codificada em UTF-8 com um tamanho máximo de 128 caracteres. Um único produto pode ter no máximo 200 atributos personalizados.

  3. Defina tipos de valores claros (texto ou números). A Pesquisa de comércio com IA exige estritamente que os valores de atributos personalizados sejam definidos como textuais (text) ou numéricos (numbers). É necessário definir exatamente um desses tipos para uma determinada chave. Tentar preencher text e numbers para o mesmo atributo vai retornar um erro INVALID_ARGUMENT.

    • Atributos textuais: são permitidos até 400 valores por atributo. Strings vazias ("") não são permitidas. Cada valor precisa ser uma string UTF-8 não vazia com um tamanho máximo de 256 caracteres.
    • Atributos numéricos: são permitidos até 400 valores por atributo.
    • Consideração sobre o refinamento:se você quiser usar um atributo numérico como um dynamicFacet, será necessário converter o tipo de dados numéricos em uma string Text no pipeline de dados antes da ingestão (por exemplo, transmitindo 10.99 como "10.99"). Caso contrário, os atributos numéricos só poderão ser usados como refinamentos estáticos em que é necessário definir manualmente e de forma explícita os intervalos na solicitação de pesquisa.

  4. Use correspondências exatas de forma estratégica. A configuração de pesquisa exata é projetada para strings alfanuméricas altamente específicas que não têm significado linguístico, como model_name (como "WA2300AH3000") ou part_number.

    • Exemplo: não use a correspondência exata em atributos personalizados que contenham substantivos comuns em inglês ou marcas conhecidas. Isso restringe os resultados da pesquisa quando essas palavras comuns aparecem em uma consulta de pesquisa, resultando em baixa recuperação de produtos e afetando negativamente as taxas de cliques (CTR).