Como funciona

Esta página explica os conceitos por trás do Model Router — leia-a uma vez, e todas as outras páginas farão mais sentido.

O saldo pré-pago

A sua instalação mantém um saldo pré-pago em USD. Ele só se move em duas direções:

• Para cima quando você faz uma recarga (manualmente, por recarga automática ou por um ajuste creditado na sua conta). As recargas aparecem instantaneamente.
• Para baixo conforme o uso se acumula. O uso é informado em tempo real pelo serviço de inferência e conciliado com o seu saldo pré-pago a cada 15 minutos, então uma atividade muito recente pode levar alguns minutos para aparecer em Monthly usage. O histórico de transações lista somente recargas e ajustes de saldo.

O saldo é a barreira financeira: quando ele chega a zero, as solicitações de inferência são bloqueadas com um erro de créditos insuficientes até que você faça uma recarga. A listagem de modelos continua funcionando com saldo zero, para que as integrações possam descobrir o catálogo antes de você adicionar fundos à conta.

O catálogo de modelos

O catálogo contém modelos de vários provedores, cada um com preço por milhão de tokens (entrada e saída com preços separados, exibidos nas configurações de Models). Todos os modelos vêm habilitados por padrão para a sua instalação; você pode:

• Desabilitar modelos para toda a conta em Settings → Models (pelo menos um modelo deve permanecer habilitado).
• Restringir modelos por chave de API ou por serviço conectado — uma lista mais restrita sobre o conjunto habilitado na instalação.

Uma entrada especial do catálogo, auto (o Auto Router), não tem preço próprio. Para cada solicitação, ele seleciona automaticamente o melhor modelo com base na complexidade do prompt, e você é cobrado pela tarifa do modelo escolhido. Consulte Models.

Duas formas de consumir modelos

1. Serviços Conectados

Os dispositivos de Agente de IA pareados com a sua instalação se conectam ao Model Router automaticamente — nenhuma chave de API é inserida no dispositivo —, e os Workflows também podem se conectar. Cada serviço conectado aparece em Settings → Service Access & API Keys, em Connected Services, com os seus próprios números de gasto, e você pode dar a cada um os seus próprios limites de gasto, restrições de modelos e substituições de proteções. Consulte Connected Services.

2. As suas próprias chaves de API

Você pode provisionar chaves de API (elas começam com phk_) para que softwares e sistemas de terceiros com suporte a BYOK (Bring Your Own Key) possam se conectar aos modelos publicados pelo Performance Hub. O endpoint é compatível com a OpenAI — aponte qualquer SDK ou ferramenta da OpenAI para o URL base e autentique-se com a sua chave. Consulte Chaves de API e Como conectar o seu aplicativo.

As duas formas consomem o mesmo saldo, respeitam os mesmos limites de gasto de toda a conta, aparecem nas mesmas análises de Activity e nos mesmos Logs e podem ser limitadas individualmente.

Saldo vs. limites de gasto

São dois mecanismos diferentes, e ambos se aplicam:

Os limites de gasto da conta têm três janelas — diário (redefinido todos os dias à meia-noite, no horário local da instalação), mensal (redefinido no dia 1º de cada mês, no horário local da instalação) e um teto vitalício rígido (conta o gasto desde a última redefinição manual; nunca é redefinido sozinho). Qualquer combinação pode estar ativa ao mesmo tempo, e os limites se aplicam a todas as chaves de API e a todos os serviços conectados em conjunto. O saldo pré-pago continua valendo por cima.

Os limites por chave e por serviço funcionam da mesma forma (diário, mensal, vitalício), mas contam somente o gasto dessa chave ou desse serviço. Quando um limite é atingido, somente essa chave ou esse serviço é bloqueado — o restante da instalação continua funcionando.

Como uma solicitação é processada

Quando uma solicitação chega ao endpoint, as verificações são executadas nesta ordem:

1. Autenticação — uma chave de API válida ou uma identidade de serviço conectado. No caso de uma chave de API, uma instalação em que o Model Router não está habilitado é rejeitada aqui com HTTP 403 ("Model Router is not enabled for this facility"). A listagem de modelos (GET /v1/models) é respondida logo após a autenticação, por isso continua funcionando com saldo zero.
2. Verificação de crédito pré-pago — o saldo disponível precisa estar acima de $0 (para serviços conectados, o Model Router também precisa estar habilitado); caso contrário, a solicitação é rejeitada com um erro de créditos insuficientes (HTTP 402).
3. Limites de gasto da conta — se um teto diário, mensal ou vitalício for ultrapassado, a solicitação é rejeitada com um erro de orçamento excedido (HTTP 402) que informa quando a janela é redefinida, no fuso horário da sua instalação.
4. Limites de gasto por chave / por serviço — a mesma verificação, com escopo na chave ou no serviço que fez a chamada.
5. Verificações do prompt — o escudo contra injeção de prompt e os seus filtros de conteúdo personalizados são executados no prompt. Um filtro de bloqueio ou uma detecção de injeção rejeita a solicitação (HTTP 403, violação da política de conteúdo); os filtros de ocultação substituem as correspondências por [REDACTED] e deixam a solicitação continuar.
6. Roteamento do modelo — auto é resolvido para um modelo concreto pelo Auto Router (uma solicitação que contém uma imagem é enviada a um modelo com recursos de visão que você permite). Os modelos de fallback são filtrados de acordo com os que a chave pode usar, a sua configuração de raciocínio é aplicada quando a solicitação não define a própria, e os limites de saída solicitados são ajustados ao que o modelo suporta.
7. Inferência — o mascaramento de PII e a ocultação de segredos (quando habilitados) são aplicados pelo serviço de inferência antes que o prompt chegue ao modelo; em seguida, a solicitação vai para o provedor do modelo, e a resposta é transmitida de volta.

Os limites de taxa (solicitações/min e tokens/min, se definidos na chave ou no serviço) são aplicados em todo o processo; excedê-los retorna HTTP 429.

O que é registrado

Cada solicitação é registrada com os seus metadados: horário, modelo (tanto o modelo solicitado quanto aquele resolvido pelo roteador), provedor, tokens (de prompt, de conclusão, em cache, de raciocínio), custo, latência, tempo até o primeiro token, velocidade, status e a chave ou o serviço que fez a chamada. O conteúdo dos prompts e das respostas nunca é armazenado.

Os números de uso e de gasto exibidos no módulo são os mesmos usados para a aplicação dos limites, então o que você vê como "limite atingido" é exatamente o que é bloqueado.

Glossário