Come funziona

Questa pagina spiega i concetti alla base di Model Router: leggila una volta e tutte le altre pagine risulteranno più chiare.

Il saldo prepagato

La tua struttura dispone di un saldo prepagato in USD, che si muove solo in due direzioni:

• Aumenta quando ricarichi (manualmente, tramite la ricarica automatica o con una rettifica accreditata sul tuo account). Le ricariche compaiono immediatamente.
• Diminuisce man mano che l'utilizzo matura. L'utilizzo viene segnalato in tempo reale dal servizio di inferenza e riconciliato con il saldo prepagato ogni 15 minuti, quindi l'attività molto recente può richiedere alcuni minuti per comparire in Monthly usage. La cronologia delle transazioni elenca solo ricariche e rettifiche del saldo.

Il saldo è la barriera finanziaria: quando raggiunge lo zero, le richieste di inferenza vengono bloccate con un errore di insufficient credits finché non ricarichi. L'elenco dei modelli funziona anche con saldo zero, così le integrazioni possono scoprire il catalogo prima che tu finanzi l'account.

Il catalogo dei modelli

Il catalogo contiene modelli di molti fornitori, ciascuno con un prezzo per milione di token (input e output hanno prezzi separati, mostrati nelle impostazioni Models). Tutti i modelli sono attivati per impostazione predefinita per la tua struttura; puoi:

• Disattivare modelli per l'intero account in Settings → Models (almeno un modello deve restare attivato).
• Limitare i modelli per chiave API o per servizio connesso: un elenco più ristretto in aggiunta all'insieme attivato per la struttura.

Una voce speciale del catalogo, auto (l'Auto Router), non ha un prezzo proprio. Per ogni richiesta seleziona automaticamente il modello migliore in base alla complessità del prompt e ti viene addebitata la tariffa del modello scelto. Vedi Models.

Due modi per usare i modelli

1. Servizi connessi

I dispositivi Agente AI associati alla tua struttura si connettono a Model Router automaticamente (nessuna chiave API viene mai inserita sul dispositivo) e anche i Workflows possono connettersi. Ogni servizio connesso compare in Settings → Service Access & API Keys sotto Connected Services con i propri dati di spesa e puoi assegnare a ciascuno limiti di spesa, restrizioni sui modelli e sostituzioni dei guardrail propri. Vedi Connected Services.

2. Le tue chiavi API

Puoi creare chiavi API (iniziano con phk_) in modo che il software e i sistemi di terze parti che supportano il BYOK (Bring Your Own Key) possano connettersi ai modelli pubblicati dal Performance Hub. L'endpoint è compatibile con OpenAI: indirizza qualsiasi SDK o strumento OpenAI all'URL di base e autenticati con la tua chiave. Vedi Chiavi API e Connettere la tua applicazione.

Entrambi i percorsi attingono allo stesso saldo, rispettano gli stessi limiti di spesa a livello di account, compaiono nelle stesse analisi Activity e negli stessi Logs e possono essere delimitati singolarmente.

Saldo e limiti di spesa a confronto

Si tratta di due meccanismi diversi ed entrambi si applicano:

I limiti di spesa dell'account prevedono tre finestre: giornaliero (si azzera ogni giorno a mezzanotte, ora locale della struttura), mensile (si azzera il 1° di ogni mese, ora locale della struttura) e un tetto massimo complessivo (conteggia la spesa dall'ultimo azzeramento manuale; non si azzera mai da solo). Può essere attiva qualsiasi combinazione contemporaneamente e i limiti si applicano a tutte le chiavi API e a tutti i servizi connessi complessivamente. Il saldo prepagato resta comunque valido in aggiunta.

I limiti per chiave e per servizio funzionano allo stesso modo (giornaliero, mensile, complessivo) ma conteggiano solo la spesa di quella chiave o di quel servizio. Quando un limite viene raggiunto, viene bloccata solo quella chiave o quel servizio: il resto della struttura continua a funzionare.

Come viene elaborata una richiesta

Quando una richiesta arriva all'endpoint, i controlli vengono eseguiti in questo ordine:

1. Autenticazione: una chiave API o un'identità di servizio connesso valida. Per una chiave API, una struttura in cui Model Router non è attivato viene rifiutata qui con HTTP 403 ("Model Router is not enabled for this facility"). L'elenco dei modelli (GET /v1/models) riceve risposta subito dopo l'autenticazione, quindi continua a funzionare con saldo zero.
2. Controllo del credito prepagato: il saldo disponibile deve essere superiore a $0 (per i servizi connessi, inoltre, Model Router deve essere attivato); in caso contrario la richiesta viene rifiutata con un errore di insufficient credits (HTTP 402).
3. Limiti di spesa dell'account: se viene superato un tetto giornaliero, mensile o complessivo, la richiesta viene rifiutata con un errore di budget exceeded (HTTP 402) che indica quando la finestra si azzera, nel fuso orario della tua struttura.
4. Limiti di spesa per chiave / per servizio: lo stesso controllo, limitato alla chiave o al servizio chiamante.
5. Controlli del prompt: la protezione dalla prompt injection e i tuoi filtri dei contenuti personalizzati vengono eseguiti sul prompt. Un filtro di blocco o un rilevamento di injection rifiuta la richiesta (HTTP 403, content policy violation); i filtri di oscuramento riscrivono le corrispondenze in [REDACTED] e lasciano proseguire la richiesta.
6. Instradamento del modello: auto viene risolto in un modello concreto dall'Auto Router (una richiesta contenente un'immagine viene inviata a un modello con capacità di visione da te consentito). I modelli di riserva vengono filtrati in base a quelli che la chiave può usare, la tua impostazione di ragionamento viene applicata quando la richiesta non ne imposta una propria e i limiti di output richiesti vengono ridotti a quanto supportato dal modello.
7. Inferenza: il mascheramento dei dati personali e l'oscuramento dei segreti (se attivati) vengono applicati dal servizio di inferenza prima che il prompt raggiunga il modello; la richiesta viene quindi inviata al fornitore del modello e la risposta viene trasmessa in streaming.

I limiti di frequenza (richieste/min e token/min, se impostati sulla chiave o sul servizio) vengono applicati in ogni fase; il loro superamento restituisce HTTP 429.

Cosa viene registrato

Ogni richiesta viene registrata con i suoi metadati: ora, modello (sia quello richiesto sia quello scelto dal router), fornitore, token (prompt, completamento, memorizzati nella cache, ragionamento), costo, latenza, tempo al primo token, velocità, stato e la chiave o il servizio chiamante. Il contenuto dei prompt e delle risposte non viene mai memorizzato.

I dati di utilizzo e di spesa mostrati nel modulo sono gli stessi usati per l'applicazione dei limiti, quindi ciò che vedi come "limit reached" è esattamente ciò che viene bloccato.

Glossario