Saltar para o conteúdo principal
O OrcaRouter permite que você salve uma estratégia de roteamento como um roteador nomeado. Chame-o do seu código como orcarouter/{name} e o OrcaRouter o resolve para um modelo concreto no momento da requisição, com base nas regras que você configurou. Isso é útil quando você quer:
  • Trocar o comportamento de roteamento sem reimplantar seu app (mude o roteador no painel; seu código permanece o mesmo).
  • Permitir que equipes ou serviços diferentes escolham sua própria política de roteamento independentemente do aplicativo que chama a API.
  • Referenciar lógica de roteamento que é complexa demais para inline em extra_body.

​
Usando um roteador

response = client.chat.completions.create(
    model="orcarouter/production-chat",
    messages=[...],
)
Para descobrir para qual modelo concreto um roteador resolveu, leia os cabeçalhos de resposta X-Orca-Router e X-Orca-Resolved-Model — veja Cabeçalhos de resposta. O campo model no próprio corpo da resposta reflete o que o upstream retornou (frequentemente o nome upstream puro, ex.: gpt-4o-mini-2024-07-18).

​
Criando um roteador

Roteadores são criados no painel em Routing. Cada roteador tem:
  • Nome — o {name} em orcarouter/{name}. Deve ser único dentro do seu workspace; letras minúsculas, dígitos, _ e - (1-50 caracteres). O nome orcarouter é reservado.
  • Modelos permitidos — um ou mais padrões glob (separados por vírgula ou nova linha, case-insensitive) limitando quais modelos este roteador pode escolher. Exemplos: openai/* ou openai/*, anthropic/claude-haiku-*. Vazio combina com todo modelo ao qual sua conta tem acesso.
  • Estratégia — como escolher entre os modelos correspondentes. Veja Estratégias abaixo.
  • Modelos mundanos / Modelos difíceis — listas adicionais de modelos usadas apenas pela estratégia Adaptive · Gated. Veja Adaptive abaixo.
  • Modelo padrão — um modelo de rede de segurança usado se o padrão resolver para nada.
  • Habilitado — desabilita o roteador sem excluí-lo.

​
Estratégias

O editor expõe quatro cartões de estratégia. Adaptive agrupa dois sub-modos de backend, para um total de cinco valores de enum que você pode persistir via API.

​
Cheapest

Escolhe o modelo com o menor preço por token entre candidatos ativos. Padrão para o roteador semeado orcarouter/auto. Melhor quando você quer o modelo de chat ativo mais barato em toda requisição e não se importa com consistência de estilo de saída entre chamadas.

​
Quality

Escolhe o modelo com a maior pontuação de qualidade entre candidatos ativos, independentemente do preço. Melhor quando a qualidade de saída domina o custo.

​
Balanced

Escolhe uma opção de baixo custo que ainda atende a uma barra de qualidade; se nada atender à barra, cai para a opção de maior qualidade. Padrão para novos roteadores que você cria. Funciona sem ajuste por roteador.

​
Adaptive

Um bandit contextual LinUCB por roteador que aprende com seu tráfego real de produção. Pondera qualidade, custo, latência e confiabilidade por requisição para escolher o melhor modelo. Novos roteadores se comportam como Balanced durante um breve período de cold-start (warm-up por modelo) antes que o bandit comece a guiar as escolhas — isso é esperado, não um bug. Dois sub-modos:
  • Standard (enum da API: linucb) — considera todo modelo Permitido para cada requisição. Melhor quando o tráfego é aproximadamente uniforme e você quer que o roteador encontre a melhor opção em toda a sua lista.
  • Gated (enum da API: gated_adaptive) — as requisições são primeiro classificadas como mundanas ou difíceis; requisições mundanas extraem de um pool menor de Modelos mundanos, requisições difíceis do pool mais forte de Modelos difíceis, e requisições de dificuldade média da lista Permitida completa. Melhor quando seu tráfego mistura chamadas simples e complexas. Cada pool é interseccionado com os modelos Permitidos; pools vazios ou sem sobreposição caem silenciosamente de volta para a lista Permitida completa, então as requisições nunca passam fome. Configure os dois pools (weak_pool e strong_pool no nível da API — até 2000 caracteres cada) no editor quando você escolher Gated.

​
Roteador semeado: orcarouter/auto

Toda conta OrcaRouter é semeada com um roteador padrão chamado auto no cadastro — veja Roteador automático. Você pode usá-lo imediatamente sem qualquer configuração.