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

# Smart Router

> Roteie automaticamente cada requisição para o modelo ideal de um pool com base na complexidade da tarefa e no modo escolhido. Reduza custos sem abrir mão da qualidade.

Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) e a referência da API para os formatos completos de solicitação e resposta.

Nem toda requisição precisa do modelo mais capaz. O **Smart Router** encaminha cada requisição para o modelo ideal de um pool configurado, com base na complexidade da tarefa e no modo escolhido.

Em vez de fixar uma aplicação em um único modelo, configure um pool de 2 a 50 modelos e deixe o router decidir por requisição. Requisições simples vão para modelos econômicos; requisições complexas são escalonadas para modelos mais fortes. A aplicação chama uma referência de modelo estável; o roteamento acontece por trás dela.

## Casos de uso

* Reduzir gastos em cargas de trabalho de alto volume em que a maioria das requisições não precisa do modelo mais forte.
* Assistentes de atendimento ao cliente: perguntas frequentes simples e confirmações ficam em modelos rápidos e econômicos, enquanto reclamações delicadas ou dúvidas sobre políticas são escalonadas automaticamente.
* Assistentes de código: autocompletar e geração de código boilerplate continuam baratos; perguntas sobre depuração e arquitetura são escalonadas.
* Geração de conteúdo em escala: textos padronizados e de alto volume usam modelos econômicos; textos longos ou sensíveis à marca usam modelos mais fortes.
* Obter o melhor resultado disponível para cada requisição sem escolher manualmente um modelo por chamada.

Para escolher quais modelos fazem parte do pool, o **Model Arena** classifica os candidatos em confrontos diretos com prompts reais da carga de trabalho e relaciona cada avaliação ao seu custo.

## Como funciona

Todo modelo elegível tem um **Intelligence Index** obtido da [Artificial Analysis](https://artificialanalysis.ai). O **Smart Router** ordena o pool por esse índice e agrupa os modelos em faixas de complexidade: **Easy**, **Medium** e **Hard**. Cada requisição recebida é analisada quanto à complexidade da tarefa e encaminhada para um modelo da faixa correspondente, de modo que as faixas se adaptam automaticamente aos modelos que estiverem no pool.

O modo selecionado (**Cost**, **Balanced** ou **Quality**) ajusta o quanto o router prefere modelos econômicos a modelos mais fortes. Se o roteamento estiver indisponível, a requisição recorre ao modelo mais forte do pool, para que as requisições sempre sejam concluídas.

## Configurar o Smart Router

> [tab] AI Studio
>
> 1. Acesse **Smart Router** na barra lateral do **AI Gateway**.
> 2. Clique em <kbd> Smart Router</kbd>.
> 3. Preencha a configuração:
>    * **Name**: a chave de modelo estável usada nas requisições ao **Gateway**; apenas letras minúsculas, números e hifens, imutável após a criação.
>    * **Smart router mode**: **Cost**, **Balanced** ou **Quality**.
>    * **Models**: clique em <kbd>Add model</kbd> e selecione de 2 a 50 modelos; recomenda-se um pool com menos de 10 modelos. Consulte [Entender o preço do modelo](#understanding-the-model-price).
>    * **Session affinity**: fixa cada thread no modelo escolhido no primeiro turno. Consulte [Session Affinity](/docs/pt-BR/ai-gateway/session-affinity.md).
> 4. Clique em **Create**.

> [tab] API e SDK
>
> ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl -X POST https://router.toqan.ai/eu/v2/smart-routers \
>   -H "Authorization: Bearer $TOQAN_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "key": "my-smart-router",
>     "profile": "SMART_ROUTER_PROFILE_COST",
>     "models": ["openai/gpt-5.6-luna", "openai/gpt-5.6-sol"]
>   }'
> ```
>
> > [!TIP]
> >
> > Consulte a [referência da API Create Smart Router](/docs/pt-BR/reference/smart-routers/create-a-smart-router.md), além de [update](/docs/pt-BR/reference/smart-routers/update-a-smart-router.md), [retrieve](/docs/pt-BR/reference/smart-routers/retrieve-a-smart-router.md), [list](/docs/pt-BR/reference/smart-routers/list-smart-routers.md) e [delete](/docs/pt-BR/reference/smart-routers/delete-a-smart-router.md).

## Entender o preço do modelo

Cada linha de modelo no formulário do **Smart Router** mostra um Intelligence Index e um preço. O preço é um valor estático do catálogo para comparar os modelos do pool:

* **Base**: uma taxa combinada de entrada e saída em USD por 1M de tokens, ponderada em 3:1 a favor da entrada (`(3 × input price + output price) ÷ 4`)
* **Fonte**: dados de preços da [Artificial Analysis](https://artificialanalysis.ai)
* **Incluído**: apenas o preço de tabela dos tokens de entrada e saída
* **Excluído**: leituras e gravações no cache de prompt, tokens de raciocínio ou thinking cobrados separadamente, taxas de busca na web, preços de contexto estendido e de nível de serviço, taxas de batch, descontos de provedores e custos adicionados pelo **Toqan Router**
* **Precisão**: exibido em USD com duas casas decimais

O preço não seleciona o modelo: o **Smart Router** divide o pool nas faixas **Easy**, **Medium** e **Hard** pelo Intelligence Index e encaminha cada requisição de acordo com a complexidade da tarefa e o modo. Para os preços de tabela por token, consulte a [página Models](/docs/pt-BR/ai-gateway/using-the-router.md) no **AI Gateway**, que mostra as taxas de entrada e saída separadamente.

O gasto real não é derivado desse valor. Ele é calculado por requisição com base no uso real de tokens e nas taxas dos provedores, e aparece nos [Traces](/docs/pt-BR/ai-studio/observability/traces.md) de observabilidade sob os atributos `orq.billing.*`, em Billing & Usage e na [Reporting API](/docs/pt-BR/ai-studio/observability/reporting-api.md).

## Modos

| Modo | Comportamento |
| - | - |
| **Cost** | Prefere com mais intensidade os modelos econômicos do pool para economizar |
| **Balanced** | Equilibra custo e qualidade entre requisições simples e complexas |
| **Quality** | Encaminha mais requisições para os modelos mais fortes do pool |

Novos **Smart Routers** usam **Cost** por padrão.

## Session Affinity

Por padrão, o **Smart Router** escolhe um modelo por requisição, então turnos consecutivos de uma conversa podem ir para modelos diferentes. A **Session affinity** fixa uma thread no modelo escolhido no primeiro turno, para que os turnos seguintes reutilizem o mesmo modelo e o cache de prompt do provedor seja preservado. Ela vem desativada por padrão e é configurada por router. Consulte [Session Affinity](/docs/pt-BR/ai-gateway/session-affinity.md) para saber como as fixações são originadas, decididas, escalonadas e observadas.

## Modelos elegíveis

Qualquer modelo habilitado no **AI Gateway** que tenha dados de inteligência da Artificial Analysis pode entrar no pool, e modelos de provedores diferentes podem ser combinados livremente em um único pool. Consulte [Supported Models](/docs/pt-BR/ai-gateway/supported-models.md) para ver o catálogo. Modelos sem Intelligence Index e outros **Smart Routers** não podem ser adicionados.

O botão **Add model** fica desabilitado quando não restam modelos elegíveis para o Smart Router a adicionar, e um pool com menos de 2 modelos é rejeitado ao salvar. Habilite pelo menos 2 modelos elegíveis na [Model List](/docs/pt-BR/ai-gateway/using-the-router.md).

## Usar o Smart Router

Depois de criado, o **Smart Router** aparece no **AI Gateway** e pode ser referenciado em qualquer lugar onde um modelo seja aceito pela API ou pelos SDKs.

### Referenciar no código

Ao usar um **Smart Router** pelos SDKs, pela API ou pelas [Supported Libraries](/docs/pt-BR/ai-studio/integrations/frameworks/overview.md), referencie-o pela string `<workspacename>@orq/<name>`.

> Exemplo: `acme@orq/my-smart-router`

### Executar o Smart Router

Chame o **Smart Router** como qualquer outro modelo. O router escolhe um modelo do pool por requisição; nenhuma alteração de código é necessária quando o pool ou o modo mudam. Uma referência de **Smart Router** é aceita em `/v3/router/chat/completions`, `/v3/router/responses`, `/v3/anthropic/v1/messages`, `/v2/deployments/invoke` e **Agents**.

```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": "workspace_name@orq/my-smart-router",
    "input": "Summarize this support ticket in two sentences."
  }'
```

```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: "workspace_name@orq/my-smart-router",
  input: "Summarize this support ticket in two sentences.",
});

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="workspace_name@orq/my-smart-router",
    input="Summarize this support ticket in two sentences.",
)

print(response.output_text)
```

> [!NOTE]
>
> Desabilitar um **Smart Router** o torna indisponível para o **Gateway**; as requisições que o referenciam deixam de ser resolvidas até que ele seja habilitado novamente.

## Acompanhar o uso

As requisições atendidas por um **Smart Router** aparecem nos [Traces](/docs/pt-BR/ai-studio/observability/traces.md) como qualquer outra requisição do **Gateway**, com o modelo selecionado e o perfil registrados no span. Use o [App Tracking](/docs/pt-BR/ai-gateway/app-tracking.md) para atribuir custo e latência por aplicação.


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