Pular para conteúdo

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-small da OpenAI por padrão, combinando título, descrição, atributos e categorias do produto.
  • Sincronização: O WooCommerce Wrapper chama /vector/index quando 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

  1. 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.
  2. Lentidão em processamento de imagem: A remoção de fundo com rembg realiza 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).
  3. 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.
  4. 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_events com o merchant_id, tipo de operação e contagem exata de tokens/imagens.