429 e 5xx com backoff exponencial.
Escolher como os provedores são classificados
Defina o padrão do espaço de trabalho em Painel -> Configurações -> Roteamento, com
phaseo settings update --routing-mode <mode> ou com routing_mode em PATCH /v1/settings. Para uma única solicitação, envie provider.sort ou routing.mode, ou adicione um sufixo ao ID do modelo:
Um sufixo substitui
routing.mode, provider.sort e os modos da predefinição e do espaço de trabalho. As listas de permitidos, as regiões, os guardrails e os tetos de preço continuam valendo.
A página de configurações de Roteamento também tem opções para os canais beta e alpha, para que os provedores em prévia só recebam tráfego quando você optar por isso.
Como o modo balanced classifica os provedores
Em solicitações de texto (Chat Completions, Responses e Messages), obalanced estima o custo por resposta bem-sucedida de cada provedor:
- Tokens: quanto custa uma solicitação típica desse modelo no provedor, usando os tamanhos medidos de prompt e de saída do modelo e a taxa medida de acerto de cache do provedor.
- Espera: o tempo até o primeiro token e até a resposta completa, convertido em dólares pelo preço típico por segundo do modelo.
- Falhas: o total dividido pela taxa de sucesso recente do provedor, mais uma penalidade por erros do provedor e uma menor por limites de taxa.
Modelos alternativos no nível da solicitação
Liste os modelos alternativos emmodels. O Phaseo tenta model primeiro e depois cada entrada, na ordem:
429, 500, 502, 503 ou 504. Um 429 de um orçamento do Phaseo ou de uma cota de modelo gratuito também passa adiante, já que outro modelo pode caber no limite restante. O mesmo vale para um modelo que nenhum provedor serve mais, por exemplo um modelo aposentado.
O que não passa. Erros do cliente, como 400, 401, 402, 403, 404, 408, 413 e 422, retornam imediatamente. O mesmo acontece com falhas antes de o primeiro modelo ser executado, como autenticação ou limites de taxa da chave de API.
Regras da lista:
modelé obrigatório; enviar apenasmodelsretorna400.modelsaceita de 1 a 25 entradas. Duplicatas e cópias demodelsão ignoradas.- As entradas podem ser IDs de modelo, IDs qualificados por provedor ou predefinições como
@support. - Cada tentativa é validada como uma solicitação própria (endpoint, parâmetros, modelos do espaço de trabalho, guardrails, predefinições, preços, BYOK). Uma alternativa que não consegue atender à solicitação é pulada e registrada; ela nunca substitui o erro que você receberia de outra forma. Uma tentativa idêntica a uma já feita também é pulada.
model da resposta indica o modelo que respondeu, e o rastro de roteamento dela lista o ID da solicitação principal, a ordem das alternativas e cada tentativa anterior.
Streaming, vídeo e música. Um stream só passa para uma alternativa antes do primeiro byte; depois disso, os erros chegam no stream. Vídeo e música só passam para uma alternativa enquanto a tarefa está sendo enviada.
Com outros controles de roteamento. As alternativas de uma rota dinâmica vinculada têm precedência sobre models, e um modelo fixo escolhido pela rota continua valendo em cada tentativa. Uma predefinição aplica as próprias restrições a cada tentativa em que é usada. O phaseo/auto gerencia as próprias alternativas e não pode ser combinado com models.
Os endpoints multipart aceitam campos
models repetidos, campos models[] ou uma string com um array JSON. Veja também Limites de taxa e Erros.
Fixar um provedor
Coloque o provedor antes do ID do modelo para usar exatamente esse provedor:baseten:google/gemma-4-26b-a4b:free. IDs de modelo qualificados por provedor traz a sintaxe completa e os erros.
Limitar quais provedores são usados
Vincular regras de roteamento a chaves de API
Uma rota dinâmica é um fluxo de regras vinculado a uma ou mais chaves de API de inferência. Ela pode:- ramificar por campos do corpo da solicitação, cabeçalhos,
metadatapersonalizado, endpoint, modelo ou ID de sessão - dividir o tráfego por porcentagem para testes A/B e lançamentos graduais
- limitar solicitações ou custo diários, semanais ou mensais por chave
- trocar o modelo, o modo de roteamento, a preferência de provedor e os modelos alternativos (até oito)
- ativar a afinidade de provedor baseada em cache e em sessão
/v1/routing/dynamic-routes com uma chave de gerenciamento.
O metadata personalizado vai no corpo da solicitação nos endpoints de texto compatíveis com OpenAI:
Manter uma conversa em um provedor
O roteamento baseado em cache vem ativado por padrão na geração de texto. Uma solicitação que enviaprompt_cache_key ou session_id, ou ativa o cache com cache_control (no nível superior, em provider_options.anthropic ou como marca cache_control ou prompt_cache_breakpoint em um bloco de mensagem ou ferramenta), fica fixada no provedor e na rota que atenderam a primeira solicitação bem-sucedida. As outras solicitações ficam fixadas por 15 minutos assim que um provedor informa uma leitura ou gravação de cache para o mesmo contexto de abertura, se a entrada em cache desse provedor for mais barata que a entrada padrão.
Desative isso em uma solicitação com
provider.cache_aware_routing: false, ou mantenha a afinidade de cache e ignore a sessão com routing.session_affinity: false:
Explicar uma decisão de roteamento
Abra Painel -> Configurações -> Uso -> Registros de solicitações, selecione uma solicitação e expanda Observabilidade do roteamento em Respostas do provedor. Ela mostra:- cada provedor classificado com a pontuação final, e quais foram selecionados e tentados
- os provedores excluídos antes da classificação, com o motivo
- os provedores rebaixados pelo status de lançamento ou de roteamento
- as entradas, os pesos, as contribuições e os multiplicadores de cada pontuação
O que conta contra a disponibilidade de um provedor
Restrições geográficas e limites de taxa são acompanhados separadamente, porque não significam que o provedor está fora do ar. Em produção, registre os IDs de solicitação, os códigos de status e os IDs de modelo para poder associar as falhas a esses rastros.
Modelos aposentados
Um modelo aposentado continua funcionando enquanto algum provedor ainda o servir. Depois disso, as solicitações falham com410 model_retired, a menos que o espaço de trabalho as envie para um substituto com o roteamento de modelos aposentados. A sua própria lista models é sempre tentada primeiro. Veja Descontinuação e aposentadoria de modelos.
Considerações sobre BYOK
Com , o Phaseo roteia e registra a solicitação, enquanto o seu provedor cobra o uso do modelo.
Restrinja cada chave aos modelos e às chaves de API que precisam dela. Para impedir que uma solicitação BYOK que falhou tente de novo com créditos do Phaseo, desative a alternativa em Painel -> Configurações -> BYOK ou defina
byok_fallback_enabled em PATCH /v1/settings com uma chave de gerenciamento. Adicione chaves no mesmo lugar ou com POST /v1/byok e uma chave de gerenciamento.