ChromaDB permite procurar produtos pelo significado de uma descrição e combinar essa busca com filtros de preço, categoria e disponibilidade. A implantação começa por um catálogo consistente: cada variante vendável precisa de um identificador estável, um texto útil para busca e metadados que representem suas restrições comerciais.
Para experimentar, você pode usar o cliente persistente em Python e salvar a coleção em disco. Antes de colocar a busca na loja, teste atualização de estoque, recuperação após reinício e consultas em português. O índice vetorial ajuda a encontrar candidatos; o sistema comercial continua responsável por confirmar preço e disponibilidade.
Resumo rápido
- Use texto descritivo para significado e metadados para filtros exatos.
- Crie um registro por variante quando tamanho ou cor afetarem a compra.
- Mantenha o mesmo processo de embeddings na indexação e na consulta.
- Teste persistência reiniciando o processo e consultando os mesmos dados.
- Revalide estoque e preço no sistema de origem antes da compra.
Onde a busca semântica ajuda no catálogo
Uma pessoa pode procurar “bolsa pequena para levar no avião”, enquanto o cadastro usa “mochila compacta de viagem”. Busca semântica procura aproximar essas descrições por meio de embeddings, representações numéricas de conteúdo. Ela complementa campos estruturados; não transforma semelhança em confirmação de medidas ou compatibilidade.
O artigo sobre o que são embeddings explica esse mecanismo. No catálogo, a decisão prática é escolher quais informações entram no texto representado pelo vetor. Nome, finalidade, material e características verificadas costumam ser mais úteis do que repetir slogans.
Busca por código exige outra abordagem. Se alguém informa um SKU completo, consulte esse identificador diretamente no sistema comercial. Um item parecido não resolve uma solicitação por peça específica. Você pode construir um fluxo que tente correspondência exata antes de acionar a busca por significado.
Também não é necessário gerar uma resposta com um modelo de linguagem. Uma lista de produtos com imagem, preço confirmado e explicação curta pode resolver a experiência. Se houver um assistente depois, a arquitetura se aproxima do uso de bancos vetoriais em RAG, mas o mecanismo de seleção de produtos deve continuar testável separadamente.
Modele produtos, variantes e metadados
Escolha a unidade que o cliente consegue comprar. Uma camiseta de determinado tamanho e cor pode precisar de registro próprio, pois o estoque muda por variante. Compartilhar um único registro para todas as opções pode devolver um produto aparentemente disponível cuja combinação desejada está esgotada.
Use o código da variante como identificador estável. Guarde o identificador do produto principal nos metadados para agrupar resultados na interface. Evite gerar um novo identificador a cada importação: isso dificulta atualizar itens e pode deixar versões antigas no índice.
| Informação | Representação sugerida | Finalidade |
|---|---|---|
| Nome e aplicação | Texto do documento | Relacionar a intenção de busca ao item |
| Categoria | String normalizada | Restringir o conjunto pesquisado |
| Preço | Inteiro em centavos | Aplicar limite sem interpretar moeda |
| Disponibilidade | Booleano | Excluir variantes indisponíveis |
| SKU | ID estável | Atualizar e localizar a variante |
Essa tabela é uma proposta de esquema para a aplicação. O uso de centavos evita carregar valores formatados como “R$ 199,90” para filtros numéricos. Na tela, você formata o inteiro como moeda. Na importação, valide explicitamente a conversão e rejeite entradas ambíguas.
Escreva documentos curtos e informativos. “Mochila de nylon, capacidade informada no cadastro, compartimento para notebook e alças ajustáveis” descreve o item. Não acrescente “impermeável” por dedução a partir do material. A busca pode repetir ou privilegiar uma característica inexistente se você a inventar durante o enriquecimento do catálogo.
Crie uma coleção persistente em Python
A referência oficial distingue o cliente em memória do PersistentClient, que grava dados em disco. Ela indica o cliente persistente para desenvolvimento e testes locais e recomenda uma instância com servidor para produção. O exemplo abaixo é um laboratório local, com dados fictícios.
Instale chromadb em um ambiente Python isolado e registre a versão instalada no arquivo de dependências. O código usa a função de embeddings padrão da coleção para demonstrar o fluxo; isso não representa uma recomendação de qualidade para português. A primeira utilização pode exigir recursos adicionais do ambiente, como download de componentes.
import chromadb
client = chromadb.PersistentClient(path="./indice_catalogo")
catalogo = client.get_or_create_collection("produtos_demo")
catalogo.upsert(
ids=["MOCH-001-AZ", "MOCH-002-PT"],
documents=[
"Mochila compacta azul para deslocamento urbano e viagem.",
"Mochila preta com compartimento para notebook e livros."
],
metadatas=[
{"categoria": "mochilas", "preco_centavos": 15990,
"disponivel": True},
{"categoria": "mochilas", "preco_centavos": 22990,
"disponivel": False}
]
)
print(catalogo.count())Os valores são apenas entradas de demonstração. O método upsert permite inserir identificadores novos e atualizar os existentes, conforme a documentação de atualização. Em uma carga recorrente, valide o lote antes de enviá-lo e registre quais identificadores foram processados. Repetir uma importação não deve criar outra identidade para a mesma variante.
O caminho relativo é resolvido a partir do diretório de execução. Se você iniciar o script em outra pasta, pode criar outro banco e pensar que perdeu os registros. Para uma rotina estável, configure um caminho absoluto sob controle da aplicação e verifique permissões de leitura e escrita.
Depois de inserir, encerre o processo. Execute outro script, abra o mesmo caminho e use get_collection("produtos_demo"). Confira a contagem e busque os IDs gravados. Esse teste diferencia persistência real de um resultado que só existia durante a execução original.
Combine intenção com filtros comerciais
A API usa query para busca por proximidade e get para recuperar registros sem esse ranqueamento. Quando você fornece query_texts, a coleção utiliza sua função de embeddings. Se enviar vetores prontos, mantenha o mesmo modelo e o mesmo tratamento de texto usados na indexação.
Um pedido como “mochila para viagem até duzentos reais” contém intenção e restrição. O trecho sobre uso pode orientar a busca semântica; o valor máximo deve virar um filtro numérico. Não espere que proximidade vetorial respeite orçamento.
resultado = catalogo.query(
query_texts=["mochila compacta para viagem"],
n_results=5,
where={"$and": [
{"categoria": "mochilas"},
{"disponivel": True},
{"preco_centavos": {"$lte": 20000}}
]},
include=["documents", "metadatas", "distances"]
)
print(resultado["ids"][0])O exemplo combina condições por $and, conforme a documentação de filtros. As estruturas de retorno de consultas agrupam os resultados por entrada consultada; por isso, o acesso usa a primeira posição. O limite solicitado não garante que existam cinco itens elegíveis.
Se nenhum registro satisfizer os filtros, mostre esse resultado claramente. Você pode oferecer ao cliente a opção de ampliar o orçamento ou pesquisar outra categoria. Não retire uma restrição silenciosamente para preencher a vitrine.
Distância também não deve aparecer como “probabilidade de adequação”. Seu significado depende da configuração do índice e dos vetores. Para decidir quando deixar de recomendar, avalie consultas reais com produtos relevantes e irrelevantes e estabeleça um critério local. Não copie um limiar numérico de outro catálogo.
Quando a categoria é ambígua, peça esclarecimento ou preserve alternativas. “Bolsa de viagem” pode significar uma mochila, uma mala pequena ou uma bolsa esportiva. Uma extração automática excessivamente confiante pode aplicar um filtro incorreto e esconder todos os produtos úteis.
Exemplo: loja de acessórios em Curitiba
Imagine uma loja fictícia de acessórios em Curitiba com vendas pelo site e retirada presencial. O exemplo é ilustrativo, sem números de melhoria. A equipe recebe buscas como “mochila para trabalhar e pegar ônibus” e quer apresentar opções disponíveis na unidade escolhida.
Na importação, cada variante recebe seu SKU. O documento contém características verificadas e finalidade descrita pelo fabricante. Os metadados incluem categoria, preço em centavos e disponibilidade para aquela unidade. Se a disponibilidade depender de vários locais, a modelagem precisa representar essa relação de forma explícita.
Para a consulta “até duzentos reais para retirar no centro”, o sistema identifica o orçamento e a unidade a partir de campos confirmados pelo usuário. A busca semântica procura a finalidade, enquanto os filtros limitam os candidatos. A interface consulta o cadastro comercial antes de mostrar as condições finais.
Um roteiro de teste inclui produto esgotado, preço acima do teto, retirada em outra unidade e dois itens semanticamente parecidos. Para cada consulta, um responsável pelo catálogo marca quais resultados seriam aceitáveis. A equipe compara a lista recuperada com esse julgamento e registra as falhas.
Depois, simula uma alteração: a variante disponível fica sem estoque. Atualiza o registro e repete a consulta. Também reinicia o processo e testa novamente. Esses passos verificam comportamentos que uma demonstração com dados estáticos não mostra.
Por fim, testa a jornada completa até a página do produto. Um bom resultado de busca não serve se o link abre outra variante ou mostra condições incompatíveis. A aceitação envolve identificação, disponibilidade e navegação, além da semelhança entre frases.
Erros comuns
Misturar modelos de embeddings na mesma coleção. Mesmo quando as dimensões coincidem, vetores de modelos diferentes podem não compartilhar significado comparável. Ao trocar o modelo ou a preparação do texto, crie uma coleção nova, reindexe e compare as buscas antes da mudança.
Tratar persistência como backup. Gravar em disco mantém dados entre execuções, mas não protege contra exclusão ou falha do armazenamento. Defina recuperação testada e mantenha o catálogo de origem capaz de reconstruir o índice. Em ambiente com servidor, adote o procedimento de backup compatível com a implantação.
Atualizar texto e esquecer atributos comerciais. Uma alteração de preço pode exigir atualização de metadados sem mudança na descrição. Defina quais eventos do cadastro alimentam o índice e como identificar importações atrasadas. O horário da última sincronização ajuda a investigar resultados inconsistentes.
Apagar a coleção para corrigir um item. Prefira operações direcionadas por identificador e valide a intenção antes de excluir registros. Uma rotina de reconciliação deve detectar produtos removidos da origem e tratá-los explicitamente, sem deixar itens antigos eternamente disponíveis.
Avaliar apenas uma consulta bonita. Inclua nomes incompletos, sinônimos, códigos, restrições incompatíveis e ausência de resultados. Meça relevância junto de cumprimento dos filtros. Uma recomendação muito parecida, mas indisponível, pode ser inadequada para a compra.
Perguntas frequentes
ChromaDB substitui o banco da loja?
Neste desenho, ele funciona como índice de recuperação. Pedidos, pagamentos, estoque e condições comerciais continuam no sistema de origem. A aplicação combina os candidatos recuperados com dados atuais antes de apresentar ou confirmar uma compra.
Preciso de um modelo generativo para pesquisar?
Não. A busca usa embeddings e pode devolver produtos diretamente. Um modelo generativo só entra se você quiser interpretar uma conversa ou redigir explicações. Mesmo nesse caso, filtros e validações continuam sendo responsabilidades explícitas da aplicação.
Como sei se o modelo entende português?
Teste consultas escritas pelos clientes e julgamentos de pessoas que conhecem o catálogo. Inclua regionalismos, erros comuns e linguagem informal. A existência de uma integração não demonstra, por si só, qualidade suficiente para seu conjunto de produtos.
O cliente persistente serve para produção?
A documentação oficial o apresenta para desenvolvimento e testes locais e orienta preferir uma implantação com servidor em produção. Use o laboratório para validar dados e consultas; planeje operação, acesso, disponibilidade e recuperação para o ambiente final.
O que fazer quando o resultado vem vazio?
Confira filtros, tipos dos campos, sincronização e existência de produtos elegíveis. Se as restrições estiverem corretas, comunique a ausência de opções. Ofereça ajustes explícitos ao cliente, sem fingir que um produto fora das condições atende ao pedido.
