Roteamento

Visao Geral

As regras de roteamento controlam como o gateway Floopy distribui requisicoes entre seus provedores de LLM configurados. Voce pode criar multiplas regras de roteamento e atribui-las a diferentes API keys, dando controle granular sobre o fluxo de trafego.

Alteracoes nas regras de roteamento entram em vigor imediatamente. O cache do gateway e invalidado automaticamente quando voce atualiza uma regra no dashboard.

Estrategias de Roteamento

Fallback

Envia requisicoes para provedores em uma ordem de prioridade que voce define. Se o primeiro provedor falhar ou estiver indisponivel, o gateway tenta novamente com o proximo provedor da lista.

Use fallback quando confiabilidade for sua maior prioridade.

Round-Robin

Distribui requisicoes uniformemente entre provedores em rotacao. Cada requisicao sucessiva vai para o proximo provedor da lista.

Use round-robin para balancear carga uniformemente quando os provedores tem desempenho similar.

Ponderado

Distribui requisicoes com base em pesos percentuais que voce atribui. Por exemplo, voce pode enviar 70% do trafego para OpenAI e 30% para Anthropic.

Use roteamento ponderado para otimizacao de custos, testes A/B de modelos ou migracoes graduais.

OpenAI:     70%
Anthropic:  30%

Baseado em Latencia

Roteia automaticamente cada requisicao para o provedor com a menor latencia P50 com base em dados de desempenho recentes. O gateway mede continuamente os tempos de resposta e ajusta o roteamento em tempo real.

Use roteamento baseado em latencia quando a velocidade de resposta for mais importante.

Como as Estrategias de Roteamento Funcionam

Esta secao explica a mecanica interna de cada estrategia — como as requisicoes sao distribuidas, como as falhas sao tratadas e quais garantias cada estrategia oferece.

Fallback em Detalhe

graph TD
    A[Request] --> B[Try Provider 1]
    B -->|Success| C[Return Response]
    B -->|Failure| D[Circuit Breaker Records Failure]
    D --> E[Try Provider 2]
    E -->|Success| C
    E -->|Failure| F[Try Provider 3]
    F -->|Success| C
    F -->|No More Providers| G[502 All Providers Exhausted]

Os provedores sao tentados na ordem de prioridade que voce define. Se um provedor retornar um erro 5xx, timeout ou tiver um circuit breaker aberto, o gateway imediatamente passa para o proximo provedor da lista. O header de resposta Floopy-Fallback-Used: true e definido sempre que um provedor nao-primario atende a requisicao, para que sua aplicacao possa detectar quando um fallback ocorreu.

Round-Robin em Detalhe

O round-robin usa um contador atomico armazenado no Redis para distribuir requisicoes uniformemente entre provedores. Cada requisicao que chega incrementa o contador e seleciona o provedor no indice counter % num_providers. Como o contador e armazenado no Redis e incrementado atomicamente, a distribuicao permanece uniforme entre multiplas instancias do gateway. O contador e isolado por regra de roteamento, entao regras diferentes mantem rotacoes independentes.

Ponderado em Detalhe

Cada provedor em uma regra ponderada tem um peso entre 0 e 100. Quando uma requisicao chega, um numero aleatorio e gerado (semeado pelo ID da requisicao para replay deterministico durante depuracao) e mapeado para a distribuicao cumulativa de pesos. Por exemplo, se OpenAI tem peso 70 e Anthropic tem peso 30, aproximadamente 70% das requisicoes sao roteadas para OpenAI e 30% para Anthropic. Os pesos nao precisam somar 100 — o gateway os normaliza automaticamente.

Baseado em Latencia em Detalhe

O gateway rastreia a latencia P50 (mediana) por provedor usando dados recentes de requisicoes do ClickHouse. Provedores com menor latencia recebem proporcionalmente mais trafego usando ponderacao inversa:

weight(provider) = 1 / p50_latency(provider)
selection_probability = weight(provider) / sum(all_weights)

Por exemplo, se o Provedor A tem P50 de 200ms e o Provedor B tem P50 de 800ms, o Provedor A recebe 4x mais trafego que o Provedor B. Provedores com circuit breakers abertos sao excluidos da selecao inteiramente, garantindo que provedores em falha nao recebam trafego independentemente de sua latencia historica.

Circuit Breaker

stateDiagram-v2
    [*] --> Closed
    Closed --> Open : Failure rate > threshold
    Open --> HalfOpen : Cooldown elapsed
    HalfOpen --> Closed : Probe succeeds
    HalfOpen --> Open : Probe fails

Cada par (organizacao, provedor) tem seu proprio circuit breaker independente. O circuit breaker rastreia falhas dentro de uma janela de tempo deslizante e transiciona entre tres estados:

• Closed — Operacao normal. Requisicoes sao enviadas ao provedor. O circuit breaker monitora a taxa de falha (falhas / total de requisicoes) dentro da janela de rastreamento (padrao: 60 segundos).
• Open — Quando a taxa de falha excede o limite (padrao: 50%), o circuito abre. Todas as requisicoes ignoram este provedor imediatamente — nenhuma chamada de rede e feita. Isso previne desperdicio de latencia com um provedor que esta sabidamente falhando.
• Half-Open — Apos o periodo de cooldown (padrao: 30 segundos), o circuito transiciona para half-open. Uma unica requisicao de teste e permitida. Se ela tiver sucesso, o circuito fecha e o provedor e totalmente reabilitado. Se falhar, o circuito reabre por outro periodo de cooldown.

O circuit breaker funciona com todas as estrategias de roteamento e e ativado automaticamente. Voce nao precisa configura-lo manualmente.

Criando uma Regra de Roteamento

1. Va para Settings > Routing no dashboard.
2. Clique em Create routing rule.
3. Insira um nome para a regra (ex.: production-fallback, low-latency).
4. Selecione uma estrategia (fallback, round-robin, ponderada ou baseada em latencia).
5. Adicione os provedores que deseja incluir e configure sua ordem, pesos ou prioridade.
6. Clique em Save.

Atribuindo uma Regra de Roteamento a uma API Key

Depois de criar uma regra de roteamento, atribua-a a uma ou mais API keys:

1. Va para Settings > API Keys.
2. Clique na API key que deseja configurar.
3. Selecione a regra de roteamento no dropdown Routing rule.
4. Salve as alteracoes.

Todas as requisicoes feitas com essa API key agora seguirao a estrategia de roteamento selecionada.

Sobrescrevendo o Roteamento por Requisicao

Voce pode sobrescrever a regra de roteamento para requisicoes individuais usando o header floopy-routing-rule. Voce tambem pode usar os headers floopy-ab-test e floopy-smart-select para testes A/B e selecao inteligente de modelo.

import { OpenAI } from "openai";

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

// Override routing rule
const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-routing-rule": "low-latency-us-east",
    },
  },
);

// A/B test between models
const abResponse = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-ab-test": "experiment-q2-2026",
    },
  },
);

from openai import OpenAI
import os

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

# Override routing rule
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "floopy-routing-rule": "low-latency-us-east",
    },
)

# A/B test between models
ab_response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "floopy-ab-test": "experiment-q2-2026",
    },
)

# Override routing rule
curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "floopy-routing-rule: low-latency-us-east" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# A/B test between models
curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "floopy-ab-test: experiment-q2-2026" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Circuit Breaker

O gateway inclui um circuit breaker integrado que desabilita automaticamente um provedor quando ele falha repetidamente. Isso previne falhas em cascata e desperdicio de latencia com provedores que estao fora do ar.

Quando a taxa de erro de um provedor excede o limite, o circuit breaker abre e o gateway ignora esse provedor por um periodo de cooldown. Apos o cooldown, o gateway envia uma requisicao de teste para verificar se o provedor se recuperou. Se o teste tiver sucesso, o provedor e reabilitado.

O circuit breaker funciona com todas as estrategias de roteamento. Voce nao precisa configura-lo manualmente — ele e ativado automaticamente.

Comportamento de Fallback

Quando um provedor retorna um erro (5xx, timeout ou falha de conexao), o comportamento do gateway depende da estrategia de roteamento:

• Fallback — Tenta o proximo provedor na ordem de prioridade.
• Round-robin / Ponderado — Tenta novamente com o proximo provedor disponivel.
• Baseado em latencia — Faz fallback para o provedor com a proxima menor latencia.

Se todos os provedores falharem, o gateway retorna uma resposta 502 Bad Gateway com detalhes sobre quais provedores foram tentados. O header de resposta Floopy-Fallback-Used e definido como "true" quando um provedor de fallback atendeu a requisicao.

Exemplo de Configuracao

Uma configuracao de producao comum:

1. Crie uma regra de roteamento chamada production com estrategia fallback:
   • Prioridade 1: OpenAI (gpt-4o)
   • Prioridade 2: Anthropic (claude-3-5-sonnet)
   • Prioridade 3: Google Gemini (gemini-2.5-pro)
2. Atribua esta regra a sua API key de producao.

Se a OpenAI sofrer uma interrupcao, sua aplicacao automaticamente faz fallback para Anthropic, depois Gemini — sem alteracoes de codigo e sem downtime.

Smart Cost Routing

Combine estrategias de roteamento com otimizacao inteligente de custos. Quando ativado em uma regra de roteamento, o Smart Cost Routing analisa a complexidade do prompt e roteia automaticamente requisicoes simples para modelos mais baratos.

Saiba mais sobre Smart Cost Routing →