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.

graph LR
    S1[Feedback de sessão] --> CH[(ClickHouse)]
    S2[Feedback automático] --> CH
    S3[Feedback manual] --> CH
    CH -->|Consulta com timeout| W[Pesos do Feedback-driven]
    S4[Prior de benchmark] --> W
    W --> D[Decisão de roteamento]

O Feedback-driven consulta agregados de requests e feedback no ClickHouse durante o planejamento, com timeout. Auto, manual e sessão permanecem sinais separados. Histórico vazio bem-sucedido usa priors de benchmark; erro na consulta preserva a baseline aprovada. Smart Selector é um recurso separado, com seu próprio cache de scores de variantes.

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
  }'

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

O roteamento consulta agregados do ClickHouse com timeout. Requests são deduplicadas antes dos joins: múltiplos feedbacks não multiplicam a contagem. Sucesso significa HTTP 2xx. Auto, manual e sessão são sinais separados; auto/composite usa escala 0–100, sessão 0–10 e thumbs manual vira 0 ou 1. Feedback de sessão é associado às requests da mesma organização e sessão.

Quando ativo, Feedback-driven controla o ranking de qualidade, os targets aprovados e a exploração. Ausência de feedback não desliga seu switch nem ativa Smart Cost. No modo conjunto, Smart Cost só introduz externos em Explore ou ExploreUntested; qualidade maior não perde por economia, e externos não entram automaticamente no exploit. Veja o fluxo de decisão.

Cada peso multiplica a média de sua própria fonte. Fontes ausentes são omitidas e os pesos restantes são normalizados; a mesma média não é reutilizada como auto, manual e sessão. As fases usam contadores da organização, mas os scores e amostras correspondem ao par provider/model.

Sem Feedback-driven, Smart Cost mantém pesos fixos:

performance_score = 0.4 × success_rate + 0.4 × quality + 0.2 × savings_ratio

Qualidade usa média manual, depois auto, depois benchmark. Economia de seleção compara custo médio por token com a baseline; a economia registrada usa tokens efetivos e preços conhecidos. Esses pesos não substituem a qualidade do Feedback-driven no modo conjunto.

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.

O Smart Cost isolado exige pelo menos 10 requests para exploit. No modo conjunto, Feedback-driven pode usar exploit entre targets aprovados com priors antes desse limiar; externos com menos de 10 requests ficam restritos a ExploreUntested. Nenhum modelo tem tráfego garantido fora do orçamento de exploração configurado.

Smart Selector é um recurso separado. Seus presets e algoritmos descritos abaixo não governam a política conjunta de Feedback-driven/Smart Cost.

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.

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.

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.

A janela de histórico é de 7 dias. Testado significa pelo menos 10 requests, não 10 feedbacks. Um único sorteio divide o orçamento entre ExploreUntested (menos de 10 requests), Explore (testados com qualidade suficiente) e Exploit (targets aprovados). A escolha exploratória usa Thompson sampling com sucessos e falhas HTTP, sem round-robin nem garantia de cobertura imediata.

ExploreUntested dispensa apenas o piso estatístico de qualidade. Constraints, preços, suporte e aprovação shadow exigida continuam valendo. Um externo que completa 10 requests pode passar para Explore, mas só entra em Exploit quando aprovado explicitamente nos targets.

Taxa zero, pool vazio ou confiança baixa podem impedir testes. Falha no histórico mantém a baseline configurada e desliga exploração; histórico vazio bem-sucedido permite exploração dentro do orçamento. Modelos testados abaixo do piso não recebem Explore até recuperarem qualidade na janela; não há promessa de recuperação automática por tráfego fora desses limites.

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.

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.

• 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.

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.

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.

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.