Smart Selector

O Que é o Smart Selector

Em vez de escolher manualmente qual modelo usar, o Smart Selector aprende automaticamente qual modelo tem melhor desempenho para o seu caso de uso e roteia o tráfego de acordo. Ele executa um sistema de multi-armed bandit (MAB) que equilibra exploração (testar diferentes modelos para coletar dados) com exploitação (enviar tráfego para o melhor performer atual).

Com o tempo, o Smart Selector converge para o modelo ideal para sua carga de trabalho específica, sem necessidade de testes A/B manuais ou suposições. Ele se adapta continuamente — se um modelo degrada ou um novo melhora, o tráfego muda automaticamente.

Como Funciona

graph TD
    A[Request with floopy-smart-select header] --> B[Load Variant Scores from ClickHouse]
    B --> C{Min Samples Met?}
    C -->|No| D[Force Exploration: Round-Robin]
    C -->|Yes| E[Apply Algorithm]
    E --> F{Strategy}
    F -->|Epsilon-Greedy| G[Exploit best or explore random]
    F -->|UCB1| H[Balance score + uncertainty]
    F -->|Thompson Sampling| I[Bayesian probability sampling]
    G --> J[Select Variant]
    H --> J
    I --> J
    D --> J
    J --> K[Route to Selected Provider/Model]

Quando uma requisição chega com o header floopy-smart-select, o gateway carrega os scores de desempenho atuais de cada variante do ClickHouse. Se alguma variante tiver menos observações do que a contagem mínima de amostras configurada, o sistema força a exploração usando round-robin para coletar dados suficientes. Uma vez que todas as variantes atingem o mínimo, o algoritmo configurado seleciona a variante.

Pontuação

Cada variante é pontuada em cinco dimensões derivadas do feedback dos usuários e dados de custo:

O score composto é uma soma ponderada de todas as cinco dimensões. O Floopy oferece quatro presets:

Você também pode definir pesos customizados que somem 1.0.

Benchmark Prior para Novas Variantes

Quando uma nova variante (modelo) é adicionada a um Smart Selector sem dados históricos, o sistema utiliza scores de benchmarks públicos como estimativa inicial de qualidade, em vez de começar do zero.

Como funciona:

• Os scores de benchmark são obtidos do mesmo banco de dados curado de inteligência de modelos usado pelo Smart Cost Routing (MMLU, HumanEval, SWE-bench, GPQA e 8 outros benchmarks padronizados)
• O score é calculado usando pesos de intenção General: MMLU 30%, GPQA 15%, HumanEval 15%, MATH 15%, IFEval 15%, HellaSwag 10%
• Escalado para 0–100 para corresponder ao intervalo da dimensão de feedback: initial_composite = benchmark_score × 100
• Modelos sem dados de benchmark começam em 50 (neutro) — a exploração os testará de qualquer forma

Por que isso importa:

• Sem priors, uma nova variante precisa da fase completa de sub-amostragem (N × min_samples requisições) antes de competir com variantes estabelecidas
• Com priors, os algoritmos bandit tomam decisões informadas imediatamente
• Limite de confiança UCB1: score + √(2 × ln(total) / n) — com um score inicial significativo, o bônus de exploração é calibrado corretamente
• Thompson Sampling se beneficia de um prior que reflete a capacidade real do modelo

Exemplo: Adicionando Claude Sonnet 4.5 a um selector:

1. Dia 0: Começa com composite ~85 baseado em benchmarks (forte em MMLU, GPQA, HumanEval)
2. Fase de sub-amostragem: Recebe amostras mínimas para feedback de baseline
3. Dia 2+: Feedback real assume, o prior de benchmark desaparece naturalmente
4. O modelo compete de forma justa desde o início, em vez de ser penalizado por ser novo

Transição de prior para feedback: Conforme o ClickHouse acumula dados reais de feedback, a query de agregação naturalmente produz scores baseados em feedback que substituem o prior de benchmark. Sem lógica de transição explícita — a fonte de dados simplesmente muda de benchmarks estáticos para feedback dinâmico dos usuários.

Algoritmos

O Smart Selector suporta três algoritmos de seleção. Cada um equilibra exploração e exploitação de forma diferente.

Epsilon-Greedy (padrão)

O algoritmo mais simples. Com probabilidade exploration_rate ele escolhe uma variante aleatória (exploração); caso contrário, escolhe a variante com o maior score composto (exploitação).

Um exploration_rate de 0.1 significa que 10% das requisições vão para uma variante aleatória e 90% vão para a melhor atual. Valores menores exploram mais agressivamente; valores maiores coletam mais dados.

UCB1 (Upper Confidence Bound)

O UCB1 leva em conta a incerteza nas estimativas de score. Ele seleciona a variante que maximiza:

UCB = composite_score + sqrt(2 * ln(total_samples) / variant_samples)

Variantes com menos observações recebem um bônus de incerteza maior, garantindo que sejam testadas vezes suficientes para produzir estimativas confiáveis. Conforme os dados se acumulam, o bônus diminui e o algoritmo converge para a melhor variante. O UCB1 não requer parâmetros de ajuste.

Thompson Sampling

Uma abordagem Bayesiana que modela o score de cada variante como uma distribuição Beta:

Beta(alpha, beta) where:
  alpha = score_rate * n + 1
  beta  = (1 - score_rate) * n + 1

A cada requisição, o algoritmo amostra da distribuição de cada variante e seleciona a variante com a maior amostra. O Thompson Sampling equilibra naturalmente exploração e exploitação e converge mais rápido que o Epsilon-Greedy na maioria dos cenários.

Configuração

Crie um Smart Selector no dashboard em Smart Selectors. Cada selector define:

• Variants — duas ou mais combinações de provider/modelo para competir. Cada variante pode opcionalmente incluir uma substituição de prompt (útil para testar diferentes system prompts junto com diferentes modelos).
• Algorithm — Epsilon-Greedy, UCB1 ou Thompson Sampling.
• Optimization Mode — Composite, Single ou Cost-Aware (veja abaixo).
• Exploration Rate — aplica-se apenas ao Epsilon-Greedy. Padrão 0.1.
• Min Samples — observações mínimas por variante antes do algoritmo ser ativado. Padrão 30.
• Evaluation Window — janela de tempo para cálculo do score (ex.: últimos 7 dias). Dados mais antigos são excluídos, permitindo que o selector se adapte a mudanças nos modelos.
• Weight Preset — Balanced, Quality First, Cost Optimized, Safety Critical ou Custom.

Uso

Adicione o header floopy-smart-select com o ID do seu selector. O gateway cuida da seleção de variantes e do roteamento automaticamente.

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});

const response = await client.chat.completions.create(
  {
    model: "gpt-4o", // ignored when smart selector is active
    messages: [{ role: "user", content: "Draft a marketing email for our new feature." }],
  },
  {
    headers: {
      "floopy-smart-select": "sel_abc123",
    },
  },
);

console.log(response.choices[0].message.content);

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.floopy.ai/v1",
    api_key=os.environ["FLOOPY_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4o",  # ignored when smart selector is active
    messages=[{"role": "user", "content": "Draft a marketing email for our new feature."}],
    extra_headers={
        "floopy-smart-select": "sel_abc123",
    },
)

print(response.choices[0].message.content)

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "floopy-smart-select: sel_abc123" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Draft a marketing email for our new feature."}]
  }'

O campo model no corpo da requisição é ignorado quando um smart selector está ativo — o selector escolhe o modelo. A resposta inclui os headers Floopy-Provider e Floopy-Model indicando qual variante foi selecionada.

Modos de Otimização

Composite (padrão)

Otimiza para o score composto multi-objetivo ponderado. Todas as cinco dimensões contribuem de acordo com os pesos configurados. Este é o modo recomendado para a maioria dos casos de uso.

Single

Otimiza para uma única dimensão (ex.: relevance). Todas as outras dimensões são ignoradas durante a seleção de variantes. Use quando você tem uma prioridade clara e não quer que outros fatores influenciem o roteamento.

Cost-Aware

Seleciona a variante mais barata que atende a um limite de qualidade configurável. O algoritmo primeiro filtra qualquer variante cujo score composto fique abaixo do limite, e então escolhe a opção mais barata restante. Este modo é ideal para cargas de trabalho de alto volume e sensíveis a custo, onde a qualidade de saída tem um piso aceitável conhecido.

Monitoramento

O dashboard oferece visibilidade em tempo real do desempenho do Smart Selector em Smart Selectors > [Seu Selector]:

• Variante vencedora — qual variante atualmente possui o maior score composto.
• Distribuição de seleção — um gráfico mostrando que porcentagem do tráfego cada variante recebe ao longo do tempo. Um selector saudável mostra o tráfego se concentrando na melhor variante enquanto mantém uma pequena fatia de exploração.
• Tendências de score — gráficos de score por variante em todas as cinco dimensões, plotados ao longo da janela de avaliação.
• Volume de feedback — número de submissões de feedback por variante, para que você possa identificar variantes que precisam de mais dados.

Requisitos de Plano

O Smart Selector está disponível no plano Pro e superiores. A funcionalidade é controlada pela flag has_smart_selector no plano da sua organização. Planos Free e Starter podem visualizar a página de configuração do Smart Selector, mas não podem ativar selectors.