Feedback

O Floopy coleta feedback de qualidade sobre respostas de LLMs e o utiliza como sinal primário para otimização de roteamento. Cada envio de feedback alimenta diretamente o Smart Cost Routing e o Smart Selector, criando um ciclo de auto-aperfeiçoamento: quanto mais feedback você envia, melhores se tornam suas decisões de roteamento.

Sem feedback, o roteamento depende de scores de benchmarks públicos. Com feedback, o roteamento aprende o que realmente funciona para seus prompts, seus usuários e seu padrão de qualidade.

Arquitetura

graph LR
    S1[Session feedback<br/>POST /v1/feedback] --> W[Dynamic weighting]
    S2[Auto feedback<br/>LLM-as-judge] --> W
    S3[Manual rating<br/>dashboard] --> W
    S4[Benchmark scores<br/>MMLU / HumanEval / …] --> W
    W --> R[Router]
    R --> CH[(ClickHouse<br/>session_feedback)]
    CH -.->|60s–5min TTL| RD[(Redis<br/>aggregated scores)]
    RD --> D[Routing decision]

Quatro fontes de sinal alimentam uma função de pesos dinâmicos. A saída da ponderação direciona o router, que persiste o feedback de sessão no ClickHouse e lê scores pré-agregados do Redis no caminho crítico. O router nunca consulta o ClickHouse durante uma requisição — ele lê do Redis, e o Redis é atualizado em segundo plano.

Coletando Feedback

Envie feedback no nível de sessão através do endpoint de feedback. Use a mesma API key que você usa para requisições de chat. O session_id é o valor enviado no header floopy-session-id durante as requisições de chat.

Endpoint: POST /v1/feedback

await fetch("https://api.floopy.ai/v1/feedback", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLOOPY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: '{"session_id":"sess_abc123","score":8,"useful":true}',
});

import requests
import os

requests.post(
    "https://api.floopy.ai/v1/feedback",
    headers={"Authorization": f"Bearer {os.environ['FLOOPY_API_KEY']}"},
    json={"session_id": "sess_abc123", "score": 8, "useful": True},
)

curl https://api.floopy.ai/v1/feedback \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "score": 8,
    "useful": true
  }'

Campos

Armazenamento de Feedback

O feedback de sessão é armazenado na tabela session_feedback do ClickHouse, vinculado a todas as requisições daquela sessão via session_id. Não é necessário atualizar requisições individuais — o feedback se aplica a toda a sessão automaticamente.

Isso permite agregação em múltiplos eixos:

• Por modelo: NPS médio de gpt-4o vs claude-sonnet-4-6 para sua carga de trabalho
• Por provedor: Qualidade agregada de todos os modelos de um único provedor
• Por padrão de prompt: Tendências de qualidade para tipos específicos de requisições
• Por janela de tempo: Detectar degradação de qualidade ao longo de horas, dias ou semanas

Para acesso rápido durante decisões de roteamento, scores agregados de feedback são cacheados no Redis com TTL de 60 segundos a 5 minutos dependendo do sinal. Isso significa que o mecanismo de roteamento nunca consulta o ClickHouse no caminho crítico — ele lê scores pré-computados do cache, e o cache é atualizado automaticamente em segundo plano.

Como o Feedback Impulsiona o Smart Cost Routing

O Smart Cost Routing usa feedback como 40% de sua fórmula de seleção de modelo. Ao decidir qual modelo mais barato pode lidar com um prompt simples, o sistema calcula um score de desempenho para cada candidato:

performance_score = (success_rate × 0.4) + (quality × 0.4) + (cost_savings × 0.2)

Onde:

• success_rate = successful_requests / total_requests. Um HTTP 2xx conta como sucesso. Um modelo que retorna erros 5% das vezes tem success rate de 0.95.
• quality = uma combinação ponderada de múltiplas fontes de feedback (veja abaixo), normalizada para escala 0.0–1.0. Quando não existe feedback para um modelo, o sistema usa o score de qualidade de benchmark derivado de avaliações públicas.
• cost_savings = 1.0 - (candidate_cost / default_cost), limitado a 0.0–1.0. Se o modelo padrão custa $15/M tokens e o candidato custa $3/M tokens, cost_savings = 1.0 - (3/15) = 0.80.

Sinal de Qualidade: Multi-Fonte com Pesos Dinâmicos

O sinal de qualidade combina três fontes com pesos dinâmicos que se adaptam com base na disponibilidade de dados:

Os pesos mudam dinamicamente com base nos dados disponíveis:

Isso significa que o sistema começa com scores de benchmark no dia zero, transiciona para feedback automático conforme as requisições se acumulam, e converge para feedback de sessão quando os usuários finais começam a enviar scores NPS. Quanto mais sinal do mundo real disponível, menos o sistema depende de benchmarks sintéticos.

Por Que 40/40/20?

O peso igual entre taxa de sucesso e qualidade reflete um princípio de design fundamental: um modelo que nunca falha mas produz resultados medíocres não é melhor que um modelo que produz resultados excelentes mas falha frequentemente. Ambos importam igualmente. Economia de custo recebe 20% porque é a razão pela qual o Smart Cost Routing existe — mas nunca deve sobrepor confiabilidade ou qualidade.

Limite Mínimo de Requisições

Um modelo precisa de pelo menos 10 requisições antes que o sistema mude do modo de exploração para o de exploitação. Abaixo de 10 requisições, o score de desempenho é muito ruidoso para confiar. Durante esta fase, o modelo recebe tráfego de exploração para construir um score confiável.

Como o Feedback Impulsiona o Smart Selector

O Smart Selector usa feedback em um nível mais granular. Em vez de calcular a média de todas as quatro dimensões em um único score de qualidade, ele aplica pesos configuráveis a cada dimensão independentemente:

composite = relevance × w₁ + coherence × w₂ + helpfulness × w₃ + safety × w₄ + cost_efficiency × w₅

A eficiência de custo é calculada como (min_cost / variant_cost) × 100, onde min_cost é o modelo mais barato no conjunto de variantes. Isso recompensa modelos mais baratos proporcionalmente em vez de usar um limite binário.

Presets de Pesos

Escolha um preset que corresponda ao seu caso de uso. Um chatbot de suporte ao cliente se beneficia do Safety-Critical. Uma ferramenta interna de geração de código se beneficia do Quality-First. Um pipeline de classificação de alto volume se beneficia do Cost-Optimized.

Algoritmos Bandit

O Smart Selector usa algoritmos multi-armed bandit para equilibrar exploração (testar modelos) e exploitação (usar o melhor modelo). Três estratégias estão disponíveis:

• Epsilon-Greedy: Explora o melhor modelo (1 - ε) do tempo, explora um modelo aleatório ε do tempo. Simples e previsível. Bom padrão.
• UCB1 (Upper Confidence Bound): Seleciona o modelo que maximiza score + √(2 × ln(total) / n), onde total é o total de requisições em todos os modelos e n são as requisições para este modelo. O termo da raiz quadrada é um bônus de confiança que diminui conforme o modelo obtém mais dados. Modelos com menos observações recebem um bônus de exploração maior, garantindo que modelos pouco testados sejam experimentados.
• Thompson Sampling: Mantém uma distribuição Beta para a qualidade esperada de cada modelo, parametrizada por sucessos e falhas. Amostra de cada distribuição e escolhe a amostra mais alta. Equilibra naturalmente exploração e exploitação — modelos incertos (distribuições largas) ocasionalmente amostram alto, sendo testados. Converge mais rápido que UCB1 na prática.

O Ciclo Auto-Corretivo

O feedback cria um ciclo fechado onde as decisões de roteamento melhoram automaticamente ao longo do tempo. Três mecanismos trabalham juntos para fazer isso acontecer.

Fase 1: Prior de Benchmark (Cold Start)

Quando um novo modelo é adicionado, o sistema não começa do zero. Ele inicializa scores de qualidade a partir de dados de benchmarks públicos — MMLU, HumanEval, SWE-bench, MT-Bench e outros. Não são palpites; são computados a partir de datasets de avaliação reais.

Um modelo que pontua 92% no HumanEval começa forte para tarefas de geração de código no dia zero. Um modelo com top scores no MT-Bench começa forte para tarefas conversacionais. Isso significa que o roteamento é razoável desde a primeira requisição, antes de qualquer feedback existir.

Fase 2: Exploração (Descoberta)

Dez por cento das requisições são roteadas para o modelo menos testado no conjunto de candidatos. Esta fase de exploração serve três propósitos:

1. Novos modelos são testados. Um modelo adicionado ontem recebe tráfego imediatamente.
2. Modelos degradados são retestados. Um modelo que era ruim mês passado pode ter sido atualizado.
3. Alternativas melhores são descobertas. Um modelo mais barato pode superar o melhor atual para sua carga de trabalho específica.

A seleção de modelo durante a exploração é round-robin determinístico entre modelos sub-amostrados (aqueles com menos de 10 requisições na janela atual). Isso garante cobertura uniforme em vez de ruído aleatório.

Fase 3: Exploitação com Feedback (Convergência)

Noventa por cento das requisições vão para o modelo com maior score. Conforme o feedback se acumula, sinais reais dos usuários substituem os priors de benchmark. O score de qualidade transiciona por três estágios:

1. Apenas benchmark — sem dados de feedback ainda, a qualidade vem inteiramente de avaliações públicas.
2. Auto + benchmark — após 10 requisições com feedback automático, o sistema combina scoring automatizado com benchmarks.
3. Sessão + auto + benchmark — após 10 sessões com feedback NPS, o feedback de sessão se torna o sinal dominante (peso 0.5).

A transição é automática e gradual. Nenhuma mudança de configuração necessária.

Cenário de Degradação

Veja como o sistema responde quando um provedor degrada, sem intervenção manual em nenhuma etapa:

O Modelo A é excluído inteiramente. Sem necessidade de alerta, sem chamada de plantão, sem mudança de configuração.

Cenário de Recuperação

O sistema também se recupera automaticamente quando um provedor corrige seus problemas:

A fase de exploração é o que torna a recuperação possível. Sem ela, um modelo excluído em T=3h ficaria excluído para sempre. A taxa de exploração de 10% é a apólice de seguro que mantém o sistema auto-recuperável.

Visualizando Dados de Feedback

Os dados de feedback aparecem em três lugares no dashboard:

• Página de Requisições: Cada requisição mostra seus scores de feedback inline, para que você possa correlacionar qualidade com modelo, latência e custo.
• Detalhe do Smart Selector: A visualização do experimento mostra distribuições de feedback por variante, deixando claro qual modelo seus usuários preferem.
• Widget de Smart Cost Savings: Compara scores de feedback entre requisições roteadas para modelos baratos e requisições com modelo padrão, provando que a economia de custo não está vindo às custas da qualidade.

Quando você ainda não tem feedback do usuário final

Se seu produto ainda não coleta NPS ou feedback de usuário hoje, o Floopy continua melhorando o roteamento desde o primeiro dia. O feedback automático (LLM-as-judge em cada resposta) combinado com scores de benchmark públicos inicia o ciclo de aprendizado imediatamente. O NPS de sessão é o sinal mais forte, mas o sistema funciona sem ele — você obtém o benefício de otimização mesmo antes de construir um pipeline de coleta de feedback. A tabela de transição de pesos acima mostra como os sinais entram em cena conforme os dados se acumulam.

Boas Práticas

• Colete feedback de sessão dos usuários finais. Mesmo um prompt NPS simples (“Como você avaliaria esta conversa? 0-10”) após uma sessão dá ao mecanismo de roteamento um sinal de alta confiança. Busque feedback em pelo menos 10% das sessões.
• Sempre inclua tanto score quanto useful. Ambos os campos são obrigatórios e dão ao mecanismo de roteamento o quadro completo — NPS mede satisfação enquanto useful captura valor prático.
• Automatize a coleta de feedback. Use LLM-as-judge (um modelo barato avaliando a saída de um modelo caro) ou scoring heurístico (tamanho da resposta, conformidade de formato, sinais de engajamento do usuário) para gerar feedback automático em escala sem revisão manual. Isso serve como baseline automatizado enquanto o feedback de sessão se acumula.
• Monitore a taxa de exploração. Se a exploração está consistentemente roteando para um modelo que pontua mal, considere remover esse modelo do conjunto de candidatos.
• Comece com o preset Balanced e depois ajuste. Após 1.000+ requisições com feedback, revise o detalhamento do sinal de qualidade para ver quais pesos correspondem às suas prioridades reais de qualidade.

Migrando de sistemas de feedback por requisição

Se você está migrando de um sistema de feedback por requisição (Helicone, LangSmith, PromptLayer), a tradução é direta: em vez de avaliar cada resposta individual, avalie a conversa ponta a ponta. Um único score NPS por sessão cobre cada decisão de roteamento naquela sessão — múltiplos turnos, chamadas de ferramentas, raciocínio encadeado. Você pode continuar capturando dados por requisição em paralelo para debugging, mas o mecanismo de roteamento consome sinal em nível de sessão para otimização. Avaliações existentes por requisição podem ser migradas agregando-as sob cada session_id; o primeiro POST sob um session_id prevalece.

Disponibilidade

A coleta de feedback está disponível em todos os planos. O roteamento orientado por feedback (integração com Smart Cost Routing e Smart Selector) está disponível no plano Pro.

Avaliação Contínua

Mesmo quando o feedback de usuários finais é escasso, o motor de roteamento mantém o Model Ranking por (assunto, complexidade) atualizado via uma passagem noturna de avaliação contínua. Um cron do Coolify (continuous-eval, diariamente às 04:00 UTC) amostra até 50 pares (requisição, resposta) recentes de cada um dos 18 buckets (6 assuntos × 3 complexidades) e pede a um LLM-como-juiz que avalie cada resposta em uma escala 0–100. As pontuações são gravadas na tabela continuous_eval_scores e roladas em continuous_eval_latest para consultas por chave.

A query de ranking do dashboard combina a pontuação de avaliação contínua com o feedback do usuário em tempo de leitura:

final_score = (1 − CONTINUOUS_EVAL_WEIGHT) × user_feedback_score
            +  CONTINUOUS_EVAL_WEIGHT      × continuous_eval_score

O peso padrão é 0,3 (30% avaliação contínua, 70% feedback de usuário). Quando apenas um lado existe, o final_score cai para o lado disponível; quando nenhum existe, o ranking volta ao prior de benchmark.

Apenas requisições de organizações com shares_to_shared_pool = true são amostradas, respeitando a mesma fronteira de privacidade usada pelo Shared Intelligence Pool. O modelo juiz é configurável via CONTINUOUS_EVAL_JUDGE_MODEL (padrão meta-llama/Llama-3.3-70B-Instruct-Turbo via Together API).

O dashboard administrativo (/admin/continuous-eval) com histórico de execuções e tendências por bucket está planejado para o v3.5 — esta release entrega apenas o pipeline de pontuação.