Gateway do Modelo RouterBase

Visão Geral

Use o routerbase quando um aplicativo precisar de uma superfície de API compatível com OpenAI para roteamento de modelos em cargas de trabalho GPT, Claude, Gemini, imagem, vídeo, áudio e embedding. Essa habilidade ajuda os agentes a migrar chamadas existentes do SDK da OpenAI, documentar as compensações na seleção de modelos e produzir trechos de implementação seguros sem expor credenciais.

A disponibilidade de modelos, preços e capacidades do provedor do RouterBase podem mudar, portanto, trate os exemplos como pontos de partida e verifique os dados atuais do catálogo antes de fazer recomendações de produção.

Quando Usar Esta Habilidade

• Use ao migrar um cliente compatível com OpenAI para o RouterBase, alterando a URL base e o ID do modelo.
• Use ao selecionar modelos primários e de fallback para chat, raciocínio, visão, geração de mídia, áudio ou embeddings.
• Use ao depurar a configuração de requisições do RouterBase, cabeçalhos, variáveis de ambiente, streaming, chamadas de ferramentas, modo JSON ou payloads multimodais.
• Use ao documentar um plano interno de roteamento de modelos que equilibra custo, latência, qualidade e redundância do provedor.

Como Funciona

Etapa 1: Classificar a Carga de Trabalho

Identifique a modalidade e as restrições rígidas antes de escolher um modelo:

• Modalidade: chat, visão, imagem, vídeo, áudio, embeddings ou misto.
• Meta de qualidade: rascunho, produção, revisão de alto risco ou tarefa de fundo automatizada.
• Restrições de tempo de execução: orçamento de latência, comprimento do contexto, streaming, modo JSON, chamada de ferramentas e tolerância a retentativas.
• Restrições de negócios: teto de preço, preferência do provedor, requisitos regionais e regras de fallback.

Etapa 2: Configurar o Cliente Compatível com OpenAI

Mantenha a chave de API do RouterBase no lado do servidor em uma variável de ambiente, como ROUTERBASE_API_KEY. Não coloque chaves em código de navegador, mobile ou repositório público.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTERBASE_API_KEY"],
    base_url="https://routerbase.com/v1",
)

response = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{"role": "user", "content": "Write one sentence about model routing."}],
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROUTERBASE_API_KEY,
  baseURL: "https://routerbase.com/v1",
});

const response = await client.chat.completions.create({
  model: "google/gemini-2.5-flash",
  messages: [{ role: "user", content: "Write one sentence about model routing." }],
});

console.log(response.choices[0].message.content);

Etapa 3: Validar IDs e Capacidades de Modelos

Quando as credenciais e o acesso à rede estiverem disponíveis, verifique o catálogo ao vivo antes de fixar um ID de modelo ou uma recomendação sensível ao preço.

curl "https://routerbase.com/api/v1/models?task=chat" \
  -H "Authorization: Bearer $ROUTERBASE_API_KEY"

Confirme as suposições de recursos com um pequeno fixture de requisição:

• O streaming funciona quando stream: true está definido.
• A chamada de ferramentas aceita o esquema exato usado pelo aplicativo.
• O modo JSON retorna saída analisável e ainda passa na validação do aplicativo.
• Os payloads de visão ou mídia usam a forma de conteúdo compatível com OpenAI esperada.

Etapa 4: Projetar Fallbacks Conservadoramente

Use fallbacks explícitos no nível do aplicativo, a menos que a conta do usuário no RouterBase já tenha uma política de roteamento inteligente configurada.

const modelPlan = [
  "anthropic/claude-sonnet-4-6",
  "google/gemini-2.5-flash",
];

for (const model of modelPlan) {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    if (!isRetryableRouterBaseError(error)) throw error;
  }
}

Trate erros de rede transitórios, timeouts, limites de taxa e erros de servidor como candidatos para retentativa. Não retente cegamente falhas de autenticação, IDs de modelo inválidos, erros de validação ou recusas de política.

Exemplos

Checklist de Migração

Ao converter uma integração existente do SDK da OpenAI:

1. Altere a URL base para https://routerbase.com/v1.
2. Leia ROUTERBASE_API_KEY da configuração de ambiente do lado do servidor.
3. Substitua o nome do modelo por um ID de modelo do RouterBase que corresponda à tarefa.
4. Preserve os campos de requisição padrão da OpenAI, a menos que a documentação do RouterBase diga o contrário.
5. Execute um teste de fumaça mínimo antes de enviar.

Formato do Plano de Roteamento

Use esta tabela ao recomendar uma estratégia de modelo:

…