Busca com IA
A busca com IA entende uma consulta escrita com palavras comuns: “tênis de corrida impermeável até 100 euros, menos Contoso”, “presente para quem corre”, “mochila para notebook de 15 polegadas”. A IA transforma a consulta em filtros do catálogo — categorias, marcas, características, preço e exclusões — e a busca de produtos mostra os produtos por esses filtros. Acima dos produtos aparecem uma dica curta da IA e chips de refinamento: “mais barato”, “femininos”, “outra cor”. Os resultados normais aparecem na hora, como sempre, e os resultados da IA os substituem quando a análise fica pronta. Se a IA não responder, ficam os resultados normais.
A busca com IA faz parte da busca de produtos: são necessários o rastreador, o catálogo e o widget de busca ou um plugin de loja. A IA é cobrada por consumo do saldo do projeto e funciona em um plano pago; veja Cobrança e limites.
Como ativar
Na página Site → Busca de produtos, no bloco Busca com IA, escolha Quando usar a IA. A escolha é salva na hora.

| Modo | Quando a IA analisa a consulta |
|---|---|
| Desativada | nunca: a busca funciona como sempre |
| Automática | consulta descritiva — com três palavras ou mais, ou uma pergunta; consultas curtas (“tênis”, “nike”) são buscadas como sempre |
| Botão | só quando o cliente clicou em “Perguntar à IA” |
| Sempre | todas as consultas |
Nos modos Automática e Botão, o visitante tem o botão Perguntar à IA — ao lado da ordenação dos resultados e como uma linha na camada de busca: com ele, a IA analisa também uma consulta curta.
- Resposta curta da IA acima dos produtos — uma ou duas frases sobre os produtos encontrados: o que combina melhor e em que faixa de preço. Desative se você só precisa dos filtros.
- Verificar o benefício da IA — metade dos visitantes recebe a busca normal, e o relatório compara cliques e compras dos dois grupos; veja Verificação do benefício da IA.
Verificar a análise
O campo Verificar análise mostra o que a IA entendeu da consulta: texto buscado, categorias, marcas, características, preço, exclusões, ordenação e refinamentos. Digite a consulta como um cliente a escreveria e clique em Analisar. A análise é cobrada da mesma forma que no site; uma nova análise da mesma consulta vem do cache de graça, e abaixo do resultado aparece “Do cache, sem chamar o modelo”.
Se a IA não encontrou nada do catálogo na consulta, a busca usará o texto — isso aparece escrito abaixo do campo. É um motivo para adicionar ao catálogo as categorias ou características que os clientes procuram.
O que o cliente vê
- O cliente digita uma consulta — os resultados normais aparecem na hora.
- Acima dos produtos aparece “A IA está escolhendo produtos…”. Em um ou dois segundos, os resultados da IA substituem os normais.
- A resposta da IA é escrita conforme o modelo responde, abaixo do título “Dica da IA”.
- Os chips A IA entendeu: mostram os filtros aplicados: categoria, marcas, características, preço, exclusões com o sinal “−”. Um chip pode ser removido — os resultados são atualizados na hora, sem chamar o modelo.
- Refinamentos — chips e o campo “Refine: mais barato, outra cor…”. Um refinamento continua a consulta anterior: “mais barato” depois de “tênis de corrida Northwind” mantém a marca e baixa o preço.
- Perguntar no chat abre o chat do site com a consulta do cliente, se o chat estiver conectado.
- Busca normal volta aos resultados normais até a consulta mudar.
Se o catálogo não tiver o que foi pedido, a IA relaxa os filtros: primeiro remove características e exclusões, depois o preço, e então busca pelo texto original. Acima dos produtos aparece então “Nenhum resultado exato: mostrando produtos semelhantes.”.
Se o visitante escolheu filtros ou ordenação nos resultados por conta própria, a IA não sobrescreve a escolha dele: a ordenação escolhida é aplicada sobre os resultados da IA, e os filtros do próprio visitante trazem de volta os resultados normais.
Como a IA analisa a consulta
- Só o catálogo. A IA recebe as categorias, as marcas e os valores de características do seu catálogo e escolhe entre eles. Tudo o que não existe no catálogo é descartado: a IA não inventa uma marca ou um tamanho.
- Idioma. A consulta pode ser escrita em qualquer idioma: a IA traduz o texto buscado para o idioma do catálogo e escreve os refinamentos no idioma do cliente.
- Cache. A análise de uma consulta fica guardada por 7 dias: a mesma consulta no mesmo idioma é analisada sem o modelo e de graça. Toda noite, as buscas populares do site dos últimos 30 dias são analisadas com antecedência — até 100 consultas por projeto —, por isso as consultas frequentes respondem na hora.
- A resposta acima dos produtos é escrita só a partir das fichas dos produtos encontrados: nome, marca, preço, disponibilidade e características. Uma frase com um número que não está nas fichas (preço, desconto, prazo) é removida. A resposta pronta para a mesma consulta e os mesmos produtos fica guardada por um dia.
- A ordem dos produtos continua sendo a da busca: o aprendizado com cliques, os interesses do visitante e a busca por sentido também funcionam nos resultados da IA; veja Como os produtos são encontrados.
Plugins de lojas
Os plugins do WooCommerce e do Magento 2 e o módulo do 1C-Bitrix, no modo de busca de produtos, mostram os resultados da IA na página de busca da loja. O tema da loja desenha os produtos como sempre, e acima deles o rastreador mostra o bloco da IA: a dica, os chips “A IA entendeu”, os refinamentos e “Busca normal”. Remover um chip ou refinar a consulta abre a mesma página de busca com os novos parâmetros.
O plugin espera a análise por no máximo 2,5 segundos. As consultas populares são analisadas à noite e abrem na hora; uma nova consulta descritiva abre de 1 a 2 segundos mais devagar que o normal. Se a análise não ficar pronta a tempo, a loja mostra os resultados normais. São necessários o plugin do WooCommerce 1.18.0, do Magento 2 1.15.0 ou o módulo do 1C-Bitrix 1.14.0 ou mais recentes.
Página de resultados própria
Se a página de resultados for sua, obtenha os resultados da IA pelo rastreador:
const result = await cdp.searchAi(q, { perPage: 24 });
if (result.ai) {
// result.items — produtos, result.ai.understood — chips “A IA entendeu”, result.ai.refinements — refinamentos,
// result.ai.relaxed — filtros relaxados, result.ai.state — análise para a próxima consulta
await cdp.searchAiAnswer(q, result.items.slice(0, 6).map((item) => item.id), (text) => { answer.textContent = text; });
} else {
// a consulta não precisa da IA, a IA está indisponível ou não respondeu a tempo — mostre os resultados normais cdp.search(q)
}
Opções de cdp.searchAi: previous — result.ai.state da resposta anterior junto com a frase de refinamento (“mais barato”), state — análise sem o chip removido (resultados sem chamar o modelo), asked: true — o visitante clicou em “Perguntar à IA”, além de sort, page, perPage. A análise espera a resposta do modelo por até 8 segundos. É necessário o rastreador 1.37.0.
Os servidores podem fazer a mesma requisição com uma chave de gravação — POST https://cdp.onetrace.pro/api/v1/search/ai; no PHP SDK — search()->ai(). A lista completa de parâmetros está na referência da API: https://cdp.onetrace.pro/api/v1/openapi.json.
Relatório
Enquanto a busca com IA estiver ativada, abaixo do relatório de buscas na página Site → Busca de produtos aparece o relatório Busca com IA do mesmo período.

| Indicador | O que mostra |
|---|---|
| Buscas com IA e Parcela de todas as buscas | quantos resultados a IA mostrou e que parte das buscas do site isso representa |
| Do cache | parcela dos resultados sem chamar o modelo — gratuitos e instantâneos |
| Análise: p50 / p95 | em quanto tempo o modelo analisa a consulta em metade e em 95 % das buscas |
| Primeiras palavras da resposta | depois de quanto tempo o cliente vê o início da dica da IA |
| Relaxadas | parcela de buscas em que não havia correspondência exata e a IA removeu alguns filtros |
| Falhas | análises que o modelo não respondeu; nesses casos o cliente viu os resultados normais |
| Custo por 1000 buscas | quanto foi cobrado do saldo pela busca com IA, calculado por 1000 buscas |
Abaixo dos indicadores: quantos refinamentos foram feitos sem o modelo, quantas respostas da IA houve e quanto foi cobrado no período. Na tabela: as consultas que a IA analisou, com o número de produtos encontrados e a parcela de relaxamento; consultas com alta parcela de relaxamento mostram o que falta no sortimento.
Verificação do benefício da IA
Ative Verificar o benefício da IA para saber se a IA ajuda a vender. Os visitantes para quem a IA seria usada são divididos igualmente em dois grupos: um recebe a busca com IA, o outro a busca normal. O visitante sempre fica no seu grupo. Quem clica em “Perguntar à IA” ou refina a consulta recebe a IA em qualquer grupo. As buscas do grupo de busca normal não são cobradas como IA.
No relatório, o bloco Benefício da IA compara os grupos:
- Clique nos resultados em 30 minutos — parcela de buscas após as quais o visitante clicou em um produto nos resultados dessa consulta;
- Compra em até 7 dias após a busca — parcela de buscas após as quais o mesmo cliente comprou algo. Aparece se um evento de compra estiver definido nas configurações de recomendações; veja Recomendações e catálogo de produtos.
A conclusão funciona como nas outras comparações de variantes: enquanto houver poucos dados, o relatório diz isso; quando a diferença for estatisticamente significativa, ele indica o vencedor. Se a busca normal for melhor, verifique a análise das consultas frequentes no campo Verificar análise. Os cliques nos resultados são registrados pelo widget de busca; na página de busca dos plugins, o tema da loja não registra cliques, por isso lá só as compras são comparadas. Depois que a verificação é desativada, o relatório mostra os resultados do período em que ela funcionou.
Cobrança e limites
Cada análise e resposta da IA custa de acordo com o volume de texto (tokens) processado pelo modelo, com a margem da plataforma. O valor é cobrado do saldo do projeto, na categoria de gasto “Busca com IA”. A análise do cache, a remoção de um chip, as páginas seguintes e a mudança de ordenação são feitas sem o modelo e são gratuitas. O modelo é escolhido pela plataforma; a análise de uma consulta costuma custar uma fração de centavo.
- A busca com IA funciona em um plano pago com busca de produtos. No período de teste, sem dinheiro no saldo ou ao atingir o limite de gastos, a IA não é ativada — os clientes veem a busca normal.
- Uma requisição à IA é mais uma busca no limite mensal do plano; veja Limite de buscas. O widget busca os resultados normais e os da IA ao mesmo tempo, por isso uma consulta descritiva no widget conta duas vezes; nos plugins de lojas, uma vez. Consultas para as quais a IA não foi necessária ou estava indisponível e as buscas do grupo de busca normal na verificação do benefício não contam uma segunda vez.
- Um visitante pode chamar o modelo no máximo 10 vezes por minuto e 100 vezes por dia; acima disso, ele vê os resultados normais. Respostas do cache não entram nesses limites.
- A partir de um mesmo endereço, no máximo 30 chamadas ao modelo por minuto e 300 por dia para todas as funções de IA do site; o servidor da loja com o plugin e a chave secreta não tem esse limite. Quanto a IA do site pode gastar por dia é definido pelo orçamento diário: quando ele acaba, a busca normal funciona até a meia-noite.