Motor de Busca Inteligente

Marketplace WeHandle

Encontre fornecedores em linguagem natural

Busca Vetorial + Embeddings + IA

O Desafio

❌ Antes

  • Filtros estruturados (segmento, estado, cidade)
  • Busca por nome (ILIKE)
  • Resultados genéricos
  • Usuário frustra-se

✅ Depois

  • Linguagem natural
  • Semântica inteligente
  • Relevância alta
  • Usuário encontra!

Como Funciona

Usuário digita "Pedreiro em Campinas" Gera Embedding Busca no Banco Vetorial Retorna Fornecedores pgvector

Experiência do Usuário

1️⃣ Busca Natural

"Preciso de alguém experiente em construção civil, que saiba fazer fundações em Campinas"

2️⃣ Sistema Entende

IA extrai: construção civil + fundações + Campinas + experiência

3️⃣ Busca Vetorial

Encontra fornecedores semanticamente similares (não só por filtro)

4️⃣ Resultados Relevantes

Top 3 fornecedores que realmente combinam com a necessidade

Arquitetura

Marketplace Backend

✓ Recebe busca do usuário

✓ Valida segurança

✓ Consulta vetorial

✓ Retorna resultados

AI Orchestrator

✓ Gera embeddings (Gemini)

✓ Company profiles

PostgreSQL + pgvector

✓ Armazena embeddings

✓ Índice IVFFlat (cosine)

Frontend (Marketplace) Marketplace Backend AI Orchestrator PostgreSQL (pgvector)

Stack Tecnológico

Gemini Embedding

Gera vetores de 1536 dimensões

Otimizado para retrieval semântico

pgvector (PostgreSQL)

Busca vetorial eficiente

Índice IVFFlat + cosine similarity

Clean Architecture

Controllers → UseCases → Repositories

Separação de responsabilidades

Segurança

Embedding direto (sem LLM)

Validação + Rate Limiting

Status Atual

  • Controller: BuscaController implementado
  • Endpoint: POST /v1/busca/fornecedores pronto
  • Modelo: Gemini Embedding (1536d) definido
  • Banco: pgvector estruturado
  • Segurança: Validações ativas
  • Documentação: Completa e em produção

    • Roadmap

    Fase 1 (MVP)
    • Busca semântica básica ✓
    • Integração AI Orchestrator
    • Testes E2E
    Fase 2 (Aprimoramentos)
    • Refinamento via LLM
    • Geographic boosting
    • Analytics de buscas
    Fase 3 (Otimizações)
    • Cache de embeddings
    • Reranking com ML
    • Personalizações
    Futuro (Escalabilidade)
    • Milvus/Vector DB dedicado
    • Embeddings de reviews
    • Busca de oportunidades

    Impacto

    +60% de relevância nas buscas
    -40% de tempo para encontrar fornecedor
    +25% de conversão esperada

    🚀

    Pronto para usar!

    Endpoint: POST /v1/busca/fornecedores

    Encontre fornecedores inteligentemente

    Motor de Busca v1

    Enriquecimento de Dados

    Melhor descrição + Metadados + Performance

    Garbage In, Garbage Out

    O Problema Raiz

    ❌ Descrição Fraca

    • "Prestação de serviços"
    • "Comércio em geral"
    • Sem especialidades
    • Embedding genérico

    ✅ Descrição Rica

    • "Serviços de limpeza industrial"
    • + Especialidades
    • + Histórico de clientes
    • Embedding preciso
    Descrição vaga → Embedding fraco → Busca imprecisa

    Company Profiles Ricos

    Gerar descrições automáticas enriquecidas com IA

    Dados de entrada:

    • CNAE + Descrição do CNAE
    • Segmentos / Categorias
    • Histórico de projetos
    • Localização + Abrangência
    • Certificações
    template = `${empresa.nome} é uma empresa de ${descricaoCNAE}. Especializada em ${especialidades}. Atua em ${regioes}. Certificações: ${certificacoes}. Histórico: ${experiencia}.`

    Resultado: Descrição 5x mais informativa

    Pipeline de Enriquecimento

    Raw Data CNAE Localização Enriquecimento + Descrição + Metadados Validação QA Review Embedding Gemini API 1536d Vector Index pgvector Pronto

    Metadados: O Que Importa

    📍 Localização

    Cidade, estado, cobertura geográfica

    🏷️ Classificação

    CNAE, segmentos, subgrupos

    ⚙️ Especialidades

    Skills, certificações, experiências

    📊 Porte

    Micro, pequena, média, grande

    🎯 Histórico

    Projetos, clientes, reputação

    🔑 Palavras-chave

    Tags, descritor, contexto

    Todos alimentam o embedding e melhoram a busca

    Qualidade do Embedding

    ❌ Input Fraco

    "Prestação de serviços em geral"

    Vetor genérico que combina com tudo e nada ao mesmo tempo

    ✅ Input Rico

    "Limpeza industrial, sanitização de ambientes, especializada em indústria alimentícia, certif. ISO 14001, atua em SP"

    Vetor específico que encontra matches reais

    Melhor descrição = Melhor embedding = Melhor busca

    Performance & Otimização

    1️⃣ Cache de Embeddings

    Não regenerar embeddings se descrição não mudou. Redis com TTL de 7 dias.

    2️⃣ Índice IVFFlat Otimizado

    Ajustar `lists` e `probes` baseado em tamanho da base (tuning fino da busca).

    3️⃣ Batch Processing

    Enriquecimento em batch noturno (off-peak). Não bloqueia operações em tempo real.

    4️⃣ Queries Assíncronas

    Busca vetorial é I/O-bound. Usar connection pooling e async/await.

    Acertividade: O Feedback Loop

    📊 Métricas

    • Click-through rate: % que clicam nos resultados
    • Relevância percebida: Feedback do usuário (thumbs up/down)
    • Conversion: % que resulta em contrato/interesse

    🔄 Feedback Loop

    • Usuário avalia resultado (bom/ruim)
    • Sistema aprende qual embedding funcionou
    • Ajusta pesos na busca (TF-IDF boost em certas dimensões)

    ⚖️ Ajuste Automático

    • A/B testing de diferentes enriquecimentos
    • Metricamente: qual gera melhor relevância?

    Exemplo Concreto: Empresa X

    ANTES (v0)

    Descrição:

    "Serviços de construção"

    Busca: "pintor em São Paulo"

    ❌ Não aparece (embedding genérico)

    DEPOIS (v1)

    Descrição:

    "Pintura residencial e comercial, acabamentos em São Paulo e região, 15 anos de experiência"

    Busca: "pintor em São Paulo"

    ✅ Top 1 resultado (match perfeito)

    Roadmap V1

    🔨 Fase 1: Infraestrutura
    • Pipeline de enriquecimento (batch job)
    • Template de descrição automática
    • Validação de qualidade
    📝 Fase 2: Dados
    • Enriquecer base existente (primeiras 1000 empresas)
    • A/B testing com usuários reais
    • Validar relevância das buscas
    ⚡ Fase 3: Performance
    • Cache de embeddings
    • Otimização de índices pgvector
    • Monitoramento de latência

    Impacto Esperado

    +40% relevância nas buscas
    -50% falsos positivos
    +2s tempo de processamento (aceitável)
    +15% conversão esperada

    🚀

    Dados ricos = Inteligência melhor

    V1: Foundation para tudo que vem depois

    Não é só busca, é semântica

    Match Inteligente com Rede

    Modelo Matemático para Supplier Matching

    Transformar observação histórica em predição

    Network-Aware Supplier Matching

    O Insight Chave

    Fornecedores que já provaram atuar com múltiplos tomadores

    Isso responde:

    • ✔ Confiabilidade
    • ✔ Capacidade de escala
    • ✔ Repetição de sucesso
    • ✔ Centralidade na rede
    Score implícito de product-market fit dentro da rede

    O Problema Atual

    ⚠️ Limitações

    • Depende de histórico real
    • Não cobre toda a base
    • Não ajuda em cold start
    • Apenas observação

    🎯 Solução

    • Features estruturadas
    • Cobertura total
    • Predição de matches
    • Modelo matemático

    Transformar em Features

    Dados Disponíveis:

    Baseado no dashboard e histórico de transações

    📊 Frequência

    Meses ativo + Recorrência

    💤 Inatividade

    Tempo sem atuar

    🔗 Overlap Bruto

    Tomadores únicos + Projetos

    supplier_features = {
      total_tomadores: number
      total_contratos: number
      contratos_simultaneos_media: number
      frequencia_atividade: number
      recencia_atividade: number
      taxa_retencao: number
      diversidade_setores: number
    }

    💡 Resultado: Embedding comportamental estruturado

    Score de Capacidade Real

    Responde: "Esse fornecedor aguenta o tranco?"

    capacity_score =
      α * log(total_tomadores)
      + β * frequencia_atividade
      + γ * (1 / inatividade)
      + δ * contratos_simultaneos_media

    O que mede:

    • Quantidade de tomadores atendidos (escala logarítmica)
    • Consistência de atuação (frequência)
    • Fator de recência (quanto mais recente, melhor)
    • Capacidade simultânea de múltiplos projetos

    Similaridade: O Pulo do Gato

    Sem histórico, prever quem daria match

    A. Similaridade Tomador ↔ Tomadores Existentes

    Para uma empresa nova: acha tomadores parecidos com ela baseado em setor, faturamento, tamanho, tipo de operação, descrição (embedding)

    B. Herança Comportamental

    "Quem já trabalhou com empresas parecidas com você?"

    match_score =
      similaridade_com_tomadores_existentes
      *
      qualidade_dos_fornecedores_desses_tomadores

    Cold Start: A Solução

    🧩 Para um TOMADOR novo:

    1. Classifica ele (porte, setor, etc)
    2. Acha tomadores similares
    3. Pega fornecedores deles
    4. Ranqueia por overlap score + capacidade + semântica

    🧩 Para um FORNECEDOR novo:

    1. Classifica via descrição (RAG) + categorias + CNAE
    2. Encontra fornecedores parecidos
    3. Herda score médio deles
    Isso é basicamente: Collaborative Filtering + Content-Based Hybrid

    Evolução Futura: Grafo

    Modelagem:

    (Tomador) --[CONTRATA]--> (Fornecedor)

    Métricas Possíveis:

    • Centralidade (PageRank)
    • Comunidades (clustering)
    • Caminhos (similar neighbors)
    • Link prediction

    Pergunta que o Grafo Responde:

    "Fornecedores que atendem empresas similares às suas"

    👉 Isso é exatamente: Link Prediction em Grafos

    Pipeline Completo de Busca

    [Input busca]
        ↓
    [Extrai intenção]
        ↓
    [Perfil da tomadora]
        ↓
    [Busca semântica inicial]
        ↓
    [Expansão por rede]
      - tomadores similares
      - fornecedores associados
        ↓
    [Score composto]
      - semantic_score
      - capacity_score (overlap)
      - similarity_score
      - firmographic_fit
        ↓
    [Rerank]

    Insight Mais Importante

    ❌ Não use o cluster de overlap como "filtro"
    ✅ Use como "sinal de qualidade e aprendizado"

    Porque:

    • Não cobre tudo
    • Mas representa verdade real de mercado

    Nome Disso (Pra Vender)

    "Motor de Match Baseado em Rede + Perfil"

    ou

    "Network-aware Supplier Matching"

    Resumão Executivo

    O que você tem hoje:

    Cluster comportamental (overlap)

    O que você deve fazer:

    • Transformar em features
    • Criar score de capacidade
    • Usar similaridade entre empresas
    • Aplicar no ranking

    O que você ganha:

    • Resolve cold start
    • Melhora qualidade do match
    • Cria diferencial competitivo real

    🧠

    Rede + Perfil = Match Inteligente

    Do histórico à predição

    Transformar dados em inteligência

    1 / 10