IA e busca semântica

O genai-wrapper centraliza chamadas de modelos, tratamento de imagens, geração de embeddings, indexação e pesquisa no Weaviate. Os consumidores incluem B2B, B2C e WooCommerce Wrapper.

Provedores por capacidade

Capacidade implementada	OpenAI	Google/Gemini	Anthropic/Claude
Conversação e recomendações	Sim	Sim	Sim
Análise de imagens	Conforme o modelo selecionado	Conforme o modelo selecionado	Conforme o modelo selecionado
Geração de imagens no pipeline atual	OpenAI Responses/Image Tool	Não implementada nesse caminho	Não implementada nesse caminho
Embeddings no código atual	text-embedding-3-small	Ainda não integrado para embeddings	Não integrado para embeddings

Essa tabela descreve a implementação do Flow, não todas as capacidades comerciais de cada fornecedor. Os modelos e chaves são selecionados nas configurações da plataforma; compatibilidade e acesso à API devem ser conferidos antes de trocar um modelo.

Da busca à resposta

flowchart LR
    Q[Busca do cliente] --> E[Embedding da consulta]
    E --> V[Pesquisa no catálogo vetorial da loja]
    V --> P[Produtos encontrados]
    P --> L[Modelo de conversação ou recomendação]
    L --> R[Resposta ao cliente]

Embeddings representam textos numericamente. Os produtos são indexados com o mesmo modelo usado nas consultas. Um LLM conversacional interpreta o pedido e os produtos encontrados; ele não substitui automaticamente o índice vetorial.

É possível conversar com Claude enquanto OpenAI gera apenas os embeddings. Trocar o provedor de conversa não exige reindexar o catálogo. Trocar o modelo de embeddings exige uma migração do índice e nova vetorização dos produtos, mesmo se as dimensões dos vetores coincidirem.

Configuração e consumo

As credenciais são resolvidas pelas configurações da plataforma, obtidas via frontend-entrypoint. As definições de etapas ficam em llm_models.toml; preços de referência ficam em model_prices.toml. Uso e custos são registrados em genai.ai_usage_events quando possível. Falhas de persistência não devem ser confundidas com garantia de ausência de consumo no fornecedor.

O gateway inclui retentativas, circuit breaker e fallback conforme a etapa. Se configurar um fallback, cadastre também sua chave e confirme acesso ao modelo. Repetir chamadas pode aumentar o consumo.

Respostas em blocos são normalizadas para entregar apenas texto ao usuário. Blocos internos de raciocínio, assinaturas e metadados não devem ser serializados para o WhatsApp.

Diagnóstico

Sintoma	Conferir
Nenhum produto encontrado	Loja/contexto, sincronização e índice do catálogo; depois a consulta e a chamada de embedding.
Erro de autenticação	Chave cadastrada no painel do ambiente e permissões do fornecedor.
Limite de taxa ou saldo	Quota, cobrança, retries e fallback do provedor efetivamente usado.
Retorno vazio ou interrompido	Limite de saída, motivo de término e formato da resposta; não mostrar blocos internos como fallback.
Divergência de versão/modelo	Configuração da plataforma, imagem implantada e registro de uso.

Use logs com request_id e dados de teste. Não imprima chaves nem respostas internas completas para investigar.