Apps de IA multimodelo: roteamento e fallbacks

Um app de IA em produção deveria sobreviver à queda de um modelo sem acordar ninguém. O padrão que leva você até lá é entediante e confiável: um cliente compatível com OpenAI, uma lista priorizada de modelos, regras de roteamento que preferem provedores baratos porém saudáveis, e tetos de preço rígidos.

O que você vai construir neste tutorial:

• Um único cliente capaz de chamar GPT, Claude, Gemini, DeepSeek e outros trocando uma única string

• Fallbacks automáticos — se o modelo principal falhar ou estourar o tempo limite, a requisição é repetida no próximo modelo da sua lista

• Controle de custos — roteamento pelo mais barato primeiro e tetos max_price para que um pico de tráfego não possa torrar seu orçamento

• Visibilidade de gastos — contabilidade de custo por requisição que você pode logar e usar em alertas

Tudo abaixo usa o OpenRouter como camada de roteamento; a mesma arquitetura funciona com qualquer gateway compatível com OpenAI, incluindo o APIMart quando você precisa de modelos de imagem, vídeo ou áudio no mesmo app.

Por que multimodelo vence modelo único

Quedas são questão de quando, não de se

Todo grande provedor tem incidentes visíveis. Se o seu app tem um único fornecedor hardcoded, cada um desses incidentes é o seu incidente. Uma cadeia de fallbacks transforma "provedor fora do ar" em um breve solavanco de latência.

Cada modelo tem seu ponto forte

Modelos baratos e rápidos cuidam de classificação e extração; modelos de fronteira cuidam da geração pesada em raciocínio. Misturar níveis por tarefa costuma cortar a conta de inferência pela metade ou mais.

Os preços mudam todo mês

Os preços dos modelos caem constantemente. Se trocar de modelo é uma mudança de uma linha, você pode perseguir o melhor custo-benefício a cada trimestre sem um projeto de migração.

Passo 1: um cliente, muitos modelos

Aponte o SDK oficial da OpenAI para o gateway — sem código HTTP customizado:

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-..."
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Summarize this contract clause..."}],
)
print(resp.choices[0].message.content)

Mudar para deepseek/deepseek-chat ou google/gemini-2.5-pro é apenas uma string model diferente. Mantenha os nomes de modelos na configuração, não no código.

Versão TypeScript

import OpenAI from "openai";

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

const resp = await client.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Classify this ticket: ..." }],
});

Um registro de modelos, não strings espalhadas

Centralize o mapeamento de tarefa → nível de modelo uma única vez:

{
  "extract": "deepseek/deepseek-chat",
  "chat": "anthropic/claude-sonnet-4.5",
  "reason": "openai/gpt-5.2"
}

Passo 2: fallbacks que disparam sozinhos

O array models

O OpenRouter repete a requisição no lado do servidor percorrendo uma lista priorizada quando o modelo principal falha, é limitado por rate limit ou estoura o tempo limite ^[1]:

{
  "model": "openai/gpt-5.2",
  "models": ["anthropic/claude-sonnet-4.5", "deepseek/deepseek-chat"],
  "messages": [{ "role": "user", "content": "..." }]
}

A resposta informa qual modelo de fato atendeu a requisição — registre isso no log.

Failover no nível do provedor

Abaixo dos fallbacks de modelo, cada modelo pode ser servido por vários provedores. As preferências de roteamento fixam ou excluem upstreams específicos ^[2]:

{
  "model": "meta-llama/llama-3.3-70b-instruct",
  "provider": {
    "order": ["deepinfra", "together"],
    "allow_fallbacks": true
  }
}

Último recurso no lado do cliente

Envolva a chamada em uma única nova tentativa contra outro gateway (ou uma resposta em cache) para o raro caso em que o próprio roteador está inacessível. Limite-se a uma tentativa — tempestades de retry são quedas autoinfligidas.

Passo 3: controle de custos impossível de burlar

Roteamento pelo mais barato primeiro

Ordene os provedores por preço quando a latência for secundária — por requisição ("provider": {"sort": "price"}) ou usando o sufixo de modelo :floor para jobs em lote.

Tetos de preço rígidos

O max_price rejeita qualquer provedor cotando acima do seu teto (dólares por 1M de tokens):

{
  "model": "openai/gpt-5.2",
  "max_price": { "prompt": 1.5, "completion": 10 },
  "messages": [{ "role": "user", "content": "..." }]
}

Isso é uma garantia, não uma preferência — requisições que não podem ser atendidas dentro do teto falham rápido em vez de custar mais em silêncio.

Acompanhe o custo por requisição

As respostas incluem usage; multiplique pelas tarifas do modelo que atendeu e emita como métrica. Alerte sobre o desvio do custo por tarefa, não só sobre o gasto total — o desvio é como um fallback silencioso para um modelo mais caro aparece.

Além do texto: o mesmo padrão para imagem, vídeo e áudio

Roteadores de LLM param nos modelos de linguagem. Produtos de verdade também geram imagens, vídeo e fala — e fazer malabarismo com mais cinco SDKs de fornecedores reintroduz exatamente o problema que você acabou de resolver.

Um gateway para todas as modalidades

O APIMart expõe 500+ modelos — chat mais GPT-Image-2, Sora 2, Kling, Veo, Suno — atrás de uma única API compatível com OpenAI e um único saldo.

Integração familiar, tarifas com desconto

A configuração do cliente é idêntica à do Passo 1 com outra base URL, e os preços por modelo ficam cerca de 20% abaixo da tabela oficial — veja a página de preços para as tarifas exatas por modelo.

Misturar roteadores não tem problema

Um layout de produção comum: OpenRouter ou APIs diretas para texto, APIMart para geração de mídia — ambos atrás da mesma abstração no seu código, ambos substituíveis via configuração.

Adicione modelos de imagem, vídeo e áudio ao seu app

Mantenha a arquitetura multimodelo que você acabou de construir e estenda-a além do texto — 500+ modelos, uma API compatível com OpenAI, pagamento por uso ~20% abaixo da tabela.

Obter uma API Key

Checklist de produção

Lance com as cinco peças: registro de modelos guiado por configuração, cadeia de fallbacks no servidor, roteamento pelo mais barato primeiro onde a latência permite, tetos max_price em cada chamada e métricas de custo por requisição com alertas de desvio. É essa combinação que permite a uma equipe de duas pessoas operar um app multimodelo sem um plantão de ops dedicado.