Balanceamento de carga entre provedores

Casos de uso

Distribuir o tráfego entre várias contas de provedores para ficar dentro dos limites de taxa por chave.
Fazer testes A/B de provedores roteando uma porcentagem configurável do tráfego para cada um.
Espalhar o tráfego entre vários provedores para reduzir o impacto da indisponibilidade de um único provedor.
Maximizar a vazão quando a capacidade de um provedor é um gargalo.
Minimizar o tempo de resposta roteando para o modelo disponível mais rápido.

Início rápido

Distribua requisições entre vários provedores usando roteamento ponderado.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Write a marketing slogan",
    "load_balancer": {
      "type": "weight_based",
      "models": [
        {"model": "openai/gpt-5.4-mini", "weight": 0.7},
        {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.3}
      ]
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Write a marketing slogan",
  load_balancer: {
    type: "weight_based",
    models: [
      { model: "openai/gpt-5.4-mini", weight: 0.7 },
      { model: "anthropic/claude-haiku-4-5-20251001", weight: 0.3 },
    ],
  },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Write a marketing slogan",
    extra_body={
        "load_balancer": {
            "type": "weight_based",
            "models": [
                {"model": "openai/gpt-5.4-mini", "weight": 0.7},
                {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.3},
            ],
        }
    },
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Write a marketing slogan" }],
  load_balancer: {
    type: "weight_based",
    models: [
      { model: "openai/gpt-5.4-mini", weight: 0.7 },
      { model: "anthropic/claude-haiku-4-5-20251001", weight: 0.3 },
    ],
  },
});

Configuração

Parâmetro	Tipo	Obrigatório	Descrição
`load_balancer`	Object	Sim	Configuração do balanceador de carga (nível superior)
`load_balancer.type`	string	Sim	Tipo de estratégia (`weight_based`, `round_robin` ou `latency_based`)
`load_balancer.models`	Array	Sim	Lista de modelos com pesos
`models[].model`	string	Sim	Identificador do modelo
`models[].weight`	number	Sim	Peso atribuído a este modelo (0.001 - 1.0)

Cálculo dos pesos:

Os pesos são normalizados: [0.4, 0.8] → [33%, 67%].
Peso maior = mais tráfego.
Peso mínimo: 0.001.
O peso é ignorado na seleção round robin; todos os modelos da lista continuam recebendo uma parcela igual do tráfego.

Uma Routing Rule correspondente com seus próprios modelos de destino configurados substitui completamente este parâmetro load_balancer, independentemente do que a requisição envia. A estratégia e os modelos da própria Routing Rule são usados no lugar; as duas configurações nunca são mescladas.

load_balancer seleciona um modelo por requisição. Ele não repete uma chamada com falha em outro modelo do pool. O model de nível superior é usado como está apenas quando load_balancer não consegue produzir uma seleção, por exemplo, com uma lista models vazia. Para ter failover quando uma chamada falha, combine load_balancer com Fallbacks.

Roteamento por latência

Roteie cada requisição para o modelo com a menor latência observada recentemente, em vez de uma divisão fixa do tráfego.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Write a marketing slogan",
    "load_balancer": {
      "type": "latency_based",
      "models": [
        {"model": "openai/gpt-5.4-mini", "weight": 0.5},
        {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.5}
      ]
    }
  }'

Como funciona a seleção:

A latência é acompanhada por modelo como uma média móvel que dá mais peso às chamadas recentes, de modo que a seleção se adapta rapidamente quando um provedor fica mais rápido ou mais lento.
Com dados recentes (amostras dos últimos 5 minutos) para todos os modelos configurados, o modelo com menor latência é selecionado. Um modelo sem dados, ou com dados desatualizados, é sondado novamente em vez de ser descartado.
Dez por cento das seleções exploram o pool completo de acordo com o peso configurado, para manter as medições de latência atualizadas. Chamadas com falha são penalizadas para que uma falha rápida não pareça um sucesso rápido.
Os pesos configurados decidem a exploração e os quase empates: quando os dois modelos mais rápidos estão a até 0,5 ms um do outro, vence o de maior peso. Com dados claros, a menor latência sempre vence.

Fluxo completo de seleção

Veja também: balanceamento de carga no nível da organização

Para aplicar balanceamento de carga em toda a sua organização sem alterar o código das requisições, use as Routing Rules para configurar as estratégias Fallback, Latency, Weighted e Round Robin no nível do workspace.

Roteamento por peso

Divida o tráfego entre modelos por pesos percentuais em vez de latência ou de uma rotação fixa.

Padrões

// Equal distribution
load_balancer: {
  type: "weight_based",
  models: [
    { model: "openai/gpt-5.6-sol", weight: 1.0 },
    { model: "anthropic/claude-sonnet-5", weight: 1.0 },
  ],
}

// Cost optimization (cheap model primary)
load_balancer: {
  type: "weight_based",
  models: [
    { model: "openai/gpt-5.4-mini", weight: 0.8 },
    { model: "openai/gpt-5.6-sol", weight: 0.2 },
  ],
}

// A/B testing
load_balancer: {
  type: "weight_based",
  models: [
    { model: "current-model", weight: 0.9 },
    { model: "experimental-model", weight: 0.1 },
  ],
}

// Multi-provider redundancy
load_balancer: {
  type: "weight_based",
  models: [
    { model: "openai/gpt-5.6-sol", weight: 0.5 },
    { model: "anthropic/claude-sonnet-5", weight: 0.3 },
    { model: "azure/gpt-5.6-sol", weight: 0.2 },
  ],
}

Casos de uso

Cenário	Abordagem	Exemplo
Otimização de custos	Foco em modelos mais baratos	80% GPT-5.4 Mini, 20% GPT-5.6 Sol
Testes de desempenho	Pouco tráfego para o novo modelo	95% atual, 5% experimental
Redundância de provedores	Divisão entre provedores	60% OpenAI, 40% Anthropic
Gerenciamento de capacidade	Distribuição durante picos	Divisão igual entre modelos

Roteamento Round Robin

Alterne entre os modelos configurados de forma uniforme, uma requisição por vez, em vez de dividir o tráfego por peso ou latência.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Write a marketing slogan",
    "load_balancer": {
      "type": "round_robin",
      "models": [
        {"model": "openai/gpt-5.4-mini", "weight": 0.5},
        {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.5}
      ]
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Write a marketing slogan",
  load_balancer: {
    type: "round_robin",
    models: [
      { model: "openai/gpt-5.4-mini", weight: 0.5 },
      { model: "anthropic/claude-haiku-4-5-20251001", weight: 0.5 },
    ],
  },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Write a marketing slogan",
    extra_body={
        "load_balancer": {
            "type": "round_robin",
            "models": [
                {"model": "openai/gpt-5.4-mini", "weight": 0.5},
                {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.5},
            ],
        }
    },
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Write a marketing slogan" }],
  load_balancer: {
    type: "round_robin",
    models: [
      { model: "openai/gpt-5.4-mini", weight: 0.5 },
      { model: "anthropic/claude-haiku-4-5-20251001", weight: 0.5 },
    ],
  },
});

Como funciona a seleção:

Cada requisição seleciona, na sua vez, o próximo modelo da lista, voltando ao primeiro modelo depois do último. Com dois modelos, as requisições se alternam; com três, a rotação percorre os três.
Os pesos devem ser incluídos na requisição, mas não afetam a seleção: o round robin é puramente rotativo, então todos os modelos recebem uma parcela igual do tráfego ao longo do tempo, independentemente dos pesos.
O round robin apenas seleciona um modelo por requisição; ele não repete nem faz failover de uma chamada com falha.

O round robin seleciona um modelo por requisição, mas não faz failover quando esse modelo apresenta erro. Para adicionar failover ao round robin, combine load_balancer com Fallbacks.

Exemplos de código

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Write a creative marketing slogan for an eco-friendly coffee brand",
    "load_balancer": {
      "type": "weight_based",
      "models": [
        {"model": "openai/gpt-5.4-mini", "weight": 0.4},
        {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.6}
      ]
    }
  }'

curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "Write a creative marketing slogan for an eco-friendly coffee brand"
      }
    ],
    "load_balancer": {
      "type": "weight_based",
      "models": [
        {"model": "openai/gpt-5.4-mini", "weight": 0.4},
        {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.6}
      ]
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Write a creative marketing slogan for an eco-friendly coffee brand",
  load_balancer: {
    type: "weight_based",
    models: [
      { model: "openai/gpt-5.4-mini", weight: 0.4 },
      { model: "anthropic/claude-haiku-4-5-20251001", weight: 0.6 },
    ],
  },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Write a creative marketing slogan for an eco-friendly coffee brand",
    extra_body={
        "load_balancer": {
            "type": "weight_based",
            "models": [
                {"model": "openai/gpt-5.4-mini", "weight": 0.4},
                {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.6},
            ],
        }
    },
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [
    {
      role: "user",
      content: "Write a creative marketing slogan for an eco-friendly coffee brand",
    },
  ],
  load_balancer: {
    type: "weight_based",
    models: [
      { model: "openai/gpt-5.4-mini", weight: 0.4 },
      { model: "anthropic/claude-haiku-4-5-20251001", weight: 0.6 },
    ],
  },
});

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {
            "role": "user",
            "content": "Write a creative marketing slogan for an eco-friendly coffee brand",
        }
    ],
    extra_body={
        "load_balancer": {
            "type": "weight_based",
            "models": [
                {"model": "openai/gpt-5.4-mini", "weight": 0.4},
                {"model": "anthropic/claude-haiku-4-5-20251001", "weight": 0.6},
            ],
        }
    },
)

Monitoramento

Acompanhe estas métricas para um balanceamento de carga ideal:

// Example monitoring setup
const metrics = {
  requestsByModel: {}, // Count per model
  costsByModel: {}, // Cost per model
  latencyByModel: {}, // Response time per model
  errorsByModel: {}, // Error rate per model
};

Métricas principais:

Distribuição do tráfego: porcentagens reais vs. esperadas.
Custo por modelo: monitore os gastos entre provedores.
Tempos de resposta: compare a latência por modelo.
Taxas de erro: acompanhe as falhas por provedor.

Com latency_based, o tempo de resposta já é o sinal de seleção. Não é necessário ajustar os pesos manualmente para desempenho; ajuste os pesos apenas para influenciar a exploração, a sondagem na partida a frio e o comportamento em quase empates.

Solução de problemas

Distribuição desigual

Verifique se os pesos estão normalizados corretamente.
Confirme que há volume suficiente de requisições (mínimo de 100 requisições para ter precisão).
Monitore por períodos mais longos.

Custos inesperados

Acompanhe a distribuição de custos real vs. esperada.
Monitore o uso excessivo de modelos caros.
Configure alertas de custo por provedor.

Problemas de desempenho

Verifique as diferenças de latência entre os modelos.
Monitore lentidões específicas de provedores.
Ajuste os pesos com base nos dados de desempenho.

Todo o tráfego indo para um único modelo com latency_based

Esperado quando um modelo é consistentemente o mais rápido. Dez por cento das requisições continuam explorando o restante do pool para manter seus dados de latência atualizados.
Confirme que load_balancer.type está definido com a estratégia pretendida, caso se esperasse uma divisão igual.

A seleção demora a se adaptar após um deploy ou uma reinicialização

Esperado. O histórico de latência fica em memória: após uma reinicialização, todos os modelos são tratados como desconhecidos até que novas amostras sejam coletadas.

Limitações

Roteamento probabilístico: no curto prazo, o tráfego pode não corresponder exatamente aos pesos.
Volume mínimo necessário: requer requisições suficientes para ter precisão estatística.
Variações nas respostas: modelos diferentes podem retornar saídas de qualidade variável.
Complexidade de custos: gerenciamento de cobrança entre vários provedores.
Dependências de provedores: requer acesso por API a todos os modelos.
Estado de latência em memória: com latency_based, o histórico de latência fica em memória e não persiste entre reinicializações.

Uso avançado por peso

Pesos específicos por ambiente:

const weights = {
  development: {
    type: "weight_based",
    models: [
      { model: "openai/gpt-5.4-mini", weight: 1.0 }, // Cheap for dev
    ],
  },
  production: {
    type: "weight_based",
    models: [
      { model: "openai/gpt-5.6-sol", weight: 0.7 }, // Quality primary
      { model: "anthropic/claude-sonnet-5", weight: 0.3 }, // Backup
    ],
  },
};

Ajuste dinâmico de pesos:

// Adjust weights based on performance
const calculateWeight = (latency: number, cost: number, quality: number) =>
  quality / (latency * cost);

const adjustWeights = (models) => ({
  type: "weight_based",
  models: models.map((model) => ({
    model: model.model,
    weight: calculateWeight(model.latency, model.cost, model.quality),
  })),
});

Com outras funcionalidades:

{
  "model": "openai/gpt-5.6-sol",
  "load_balancer": {
    "type": "weight_based",
    "models": [
      { "model": "openai/gpt-5.6-sol", "weight": 0.6 },
      { "model": "anthropic/claude-sonnet-5", "weight": 0.4 }
    ]
  },
  "retry": { "count": 2, "on_codes": [429] },
  "timeout": { "call_timeout": 15000 }
}

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Início rápido

Configuração

Roteamento por latência

Veja também: balanceamento de carga no nível da organização

Roteamento por peso

Padrões

Casos de uso

Roteamento Round Robin

Exemplos de código

Monitoramento

Solução de problemas

Limitações

Uso avançado por peso

​Início rápido

​Configuração

​Roteamento por latência

Veja também: balanceamento de carga no nível da organização

​Roteamento por peso

​Padrões

​Casos de uso

​Roteamento Round Robin

​Exemplos de código

​Monitoramento

​Solução de problemas

​Limitações

​Uso avançado por peso

Início rápido

Configuração

Roteamento por latência

Roteamento por peso

Padrões

Casos de uso

Roteamento Round Robin

Exemplos de código

Monitoramento

Solução de problemas

Limitações

Uso avançado por peso