> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Balanceamento de carga entre provedores

> Distribua requisições de LLM entre provedores usando roteamento por latência, por peso ou round robin para otimizar custos, executar testes A/B e garantir redundância.

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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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}
      ]
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

> [!WARNING]
>
> Uma [Routing Rule](/docs/pt-BR/ai-gateway/configuration/routing-rules.md#load-balancer) 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.

> [!NOTE]
>
> `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](/docs/pt-BR/ai-gateway/features/retries.md#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.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

> [accordion] Fluxo completo de seleção
>
> ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
> flowchart TD
>     A["Nova requisição"] --> B{"Sorteio de exploração de 10%?"}
>     B -- "Sim" --> C["Escolher um modelo pelo peso configurado"]
>     B -- "Não" --> D{"Dados recentes para todos os modelos? (< 5 min)"}
>
>     D -- "Não" --> E["Sondar um modelo desconhecido ou desatualizado pelo peso"]
>     D -- "Sim" --> F{"As duas menores latências empatam em até 0,5 ms?"}
>
>     F -- "Sim" --> G["Vence o maior peso configurado"]
>     F -- "Não" --> H["Vence a menor latência"]
>
>     C --> I["Chamar o modelo"]
>     E --> I
>     G --> I
>     H --> I
>
>     I --> J["Registrar a duração, ou uma penalidade em caso de falha, no histórico de latência"]
> ```

> [card] [Veja também: balanceamento de carga no nível da organização](/docs/pt-BR/ai-gateway/configuration/routing-rules.md#load-balancer)
>
> 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

```typescript Weight-based config patterns theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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}
      ]
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

> [!NOTE]
>
> 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](/docs/pt-BR/ai-gateway/features/retries.md#fallbacks).

## Exemplos de código

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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}
      ]
    }
  }'
```

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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}
      ]
    }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 },
    ],
  },
});
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```typescript Metrics tracking example theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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:**

```typescript Environment weight config theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:**

```typescript Dynamic weight calculation theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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:**

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.