GenAI Wrapper
O genai-wrapper é o serviço centralizado de inteligência artificial generativa, visão computacional e busca vetorial da plataforma. Ele encapsula chamadas para provedores externos de LLM (OpenAI, Google Gemini), modelos locais de remoção de fundo e o banco vetorial Weaviate.
O serviço opera de forma stateless em relação a conversas: ele não armazena contexto de diálogo nem decide quando chamar cada modelo, disponibilizando recursos puros de inferência, recomendação e indexação para o Agente B2C, Agente B2B e WooCommerce Wrapper.
Papel na Plataforma
flowchart LR
b2c[Agente B2C] -->|Busca & Recomendações| ai[GenAI Wrapper]
b2b[Agente B2B] -->|Visão & Enriquecimento| ai
woo[WooCommerce Wrapper] -->|Indexação de Catálogo| ai
ai -->|LLM / Embeddings| openai[OpenAI API]
ai -->|LLM / Fallback| gemini[Google Gemini API]
ai -->|Visão & Recorte| rembg[rembg / Pillow]
ai <-->|Vector Store| weaviate[(Weaviate)]
ai -->|Tarifação & Auditoria| db[(ai_usage_events)]
style ai fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#0369a1
style weaviate fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style db fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style openai fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style gemini fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style rembg fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
style b2c fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
style b2b fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
Limites de Responsabilidade
| É responsabilidade do GenAI Wrapper | NÃO é responsabilidade do GenAI Wrapper |
|---|---|
| Executar tarefas de LLM estruturadas (descrição, classificação, pitch de vendas). | Decidir a máquina de estados (FSM) de clientes ou lojistas. |
| Pipeline completo de melhoria visual de fotos de produtos (ghost-mannequin). | Controlar estoque, preços ou regras de pagamento. |
| Gerar embeddings textuais e realizar busca por similaridade vetorial no Weaviate. | Manter conexão direta com o WhatsApp ou com a Meta. |
Garantir o isolamento multi-tenant das coleções vetoriais por merchant_id. |
Executar pedidos no WooCommerce. |
Registrar consumo de tokens, imagens e custos na tabela ai_usage_events. |
Armazenar arquivos de imagem brutos (pertencem ao MinIO). |
Pipeline Visual: Ghost-Mannequin (/llm/enhance-image)
O cadastramento de fotos no Agente B2B utiliza este pipeline para transformar fotos amadoras de roupas tiradas pelo lojista em fotos de catálogo profissional de estúdio:
flowchart TD
in[1. Imagem Base64 enviada pelo B2B] --> val[2. Validação de resolução e formato Pillow]
val --> bg[3. Remoção de fundo transparente com rembg]
bg --> prompt[4. Montagem de prompt estruturado com categoria]
prompt --> gen[5. Geração e composição via OpenAI Image Tool]
gen --> post[6. Pós-processamento e normalização visual]
post --> out[7. Retorno da imagem otimizada em Base64]
style in fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style val fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style bg fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
style prompt fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style gen fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
style post fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style out fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#166534
Busca Semântica e Vector Store
O Weaviate roda como serviço acoplado ao genai-wrapper. Nenhum outro serviço da plataforma acessa o banco vetorial diretamente.
flowchart LR
subgraph MultiTenantWeaviate [Weaviate Partitioning]
direction TB
c1[(Tenant: Loja A)]
c2[(Tenant: Loja B)]
c3[(Tenant: Loja C)]
end
query[Texto do Cliente B2C] --> embed[Gerar Embedding]
embed --> search[Busca Vetorial Cosine Distance]
search --> c2
c2 --> ranking[Reranking dos Produtos Mais Relevantes]
- Isolamento por Loja: Toda consulta exige
merchant_id. Produtos da Loja A nunca vazam para recomendações da Loja B. - Modelo de Embedding: Utiliza
text-embedding-3-smallda OpenAI por padrão, combinando título, descrição, atributos e categorias do produto. - Sincronização: O WooCommerce Wrapper chama
/vector/indexquando novos produtos são importados ou atualizados no WordPress.
Contratos de API
Todos os endpoints exigem o cabeçalho X-Internal-Key com o valor de AI_UTILS_API_KEY:
Endpoints de LLM (/llm/)
| Método | Rota | Consumidor | O que faz |
|---|---|---|---|
POST |
/llm/describe |
Agente B2B | Extrai título, descrição e campos técnicos a partir da foto do produto. |
POST |
/llm/classify |
Agente B2B | Escolhe a categoria mais precisa para o produto entre opções candidatas. |
POST |
/llm/enhance-image |
Agente B2B | Executa o pipeline de remoção de fundo e enquadramento ghost-mannequin. |
POST |
/llm/recommend-checkout |
Agente B2C | Gera pitch persuasivo relacionando o carrinho atual aos produtos complementares. |
POST |
/llm/validate-complements |
Agente B2C | Pontua afinidade entre produto principal e acessórios/cross-sell. |
POST |
/llm/chat |
Agentes | Completion genérico single-turn com system prompt e user prompt. |
Endpoints Vetoriais (/vector/)
| Método | Rota | Consumidor | O que faz |
|---|---|---|---|
POST |
/vector/embed |
Agentes | Retorna vetores densos (embeddings) para uma lista de strings. |
POST |
/vector/search |
Agente B2C | Localiza produto de referência e similares com base em score de proximidade. |
POST |
/vector/recommend |
Agente B2C | Gera recomendações contextuais a partir de intenção de busca. |
POST |
/vector/index |
WC Wrapper | Indexa ou atualiza as propriedades vetoriais de um produto no Weaviate. |
DELETE |
/vector/index/{merchant_id}/{product_id} |
WC Wrapper | Remove um produto excluído do catálogo vetorial. |
GET |
/vector/health/{merchant_id} |
Diagnóstico | Informa status de saúde e total de itens indexados da loja. |
Tarifação & Uso (/usage/)
| Método | Rota | O que faz |
|---|---|---|
GET |
/usage/report |
Retorna o resumo consolidado de tokens gastos e operações de IA por lojista. |
Configuração Essencial
A configuração de modelos e custos é definida via .env e arquivos TOML (llm_models.toml e model_prices.toml):
| Variável | Descrição |
|---|---|
AI_UTILS_API_KEY |
Chave de autenticação das chamadas internas ao serviço. |
OPENAI_API_KEY |
Chave de acesso à API da OpenAI (LLM, Embeddings e Imagens). |
GEMINI_API_KEY |
Chave da Google Gemini API (usada como alternativa ou em tarefas específicas). |
AI_UTILS_WEAVIATE_HOST |
Host do Weaviate na rede Docker (ex: weaviate). |
AI_UTILS_WEAVIATE_PORT |
Porta de comunicação do Weaviate (padrão: 8080). |
AI_UTILS_EMBEDDING_MODEL |
Nome do modelo vetorial (padrão: text-embedding-3-small). |
AI_UTILS_ENABLE_BACKGROUND_REMOVAL |
Flag booleana (true/false) para ativação da remoção local com rembg. |
DATABASE_URL |
Conexão PostgreSQL para registro das operações na tabela ai_usage_events. |
Diagnóstico Rápido
- Recomendações sem produtos retornados: Consulte
GET /vector/health/{merchant_id}. Se o total de produtos indexados for 0, o lojista precisa passar pela sincronização de catálogo do WooCommerce. - Lentidão em processamento de imagem: A remoção de fundo com
rembgrealiza inferência via CPU/ONNX. Verifique se o container dispõe de memória e CPU suficientes no host Docker (mínimo recomendado: 2 CPUs e 2 GB de RAM). - Erros de limite de taxa (Rate Limit) de IA: Monitore logs com a tag
ai_utils_llm_error. O serviço inclui retentativas exponenciais automáticas, mas caso o erro persista, avalie os limites de cota da conta OpenAI/Gemini. - Discrepância no saldo de créditos de IA: Todas as chamadas geram um registro síncrono ou assíncrono na tabela
genai.ai_usage_eventscom omerchant_id, tipo de operação e contagem exata de tokens/imagens.