Gestione dei canali nell'AI Gateway

Il «canale (Channel)» è la configurazione di un punto di accesso a un provider nell'AI Gateway: contiene l'indirizzo di un provider, la vera API Key, i modelli disponibili e informazioni su prezzi e quote. Il gateway utilizza questi canali per instradare le richieste inviate dalle applicazioni al provider corrispondente. Questo articolo spiega come aggiungere, configurare, testare e gestire i canali.

Prerequisiti

• ServBay installato e in esecuzione, con account ServBay già connesso (è necessario effettuare l'accesso prima di aggiungere un canale).
• La vera API Key del provider di destinazione già pronta (per i provider locali come Ollama / LM Studio può essere omessa).
• Se non conosci già l'architettura complessiva dell'AI Gateway, ti consigliamo di leggere prima Introduzione all'AI Gateway.

Aggiungere un canale

Vai alla pagina AI Gateway → Canali (Channels) e fai clic su Aggiungi (Add) per aprire la procedura guidata. La procedura guidata si articola in tre passaggi.

Primo passaggio: scegliere il provider

I provider sono mostrati raggruppati per categoria; fai clic su una scheda per selezionarla:

• Mainstream: OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• Cina (China): DeepSeek, Qwen (Tongyi Qianwen), Zhipu GLM, Kimi, Doubao·Volcano, ERNIE Bot (Wenxin Yiyan), Hunyuan, MiniMax, 01.AI (Yi), StepFun (Jieyue Xingchen).
• Locale (Local): Ollama, LM Studio.
• Personalizzato (Custom): OpenAI Compatible, Custom.

Dopo aver scelto il provider, il gateway compilerà automaticamente il Base URL predefinito del provider.

Passaggio tra due regioni

Provider cinesi come Qwen (Tongyi Qianwen), Zhipu GLM, Kimi, Doubao·Volcano, Hunyuan, MiniMax e StepFun offrono sia endpoint nazionali (Cina) sia globali. Quando selezioni uno di questi provider, nella procedura guidata compare un selettore «Regione» (🇨🇳 Cina / 🌐 Globale); dopo il passaggio, il Base URL viene aggiornato automaticamente con l'indirizzo della regione corrispondente.

Secondo passaggio: compilare la configurazione

• Nome canale (obbligatorio) — serve a identificare il canale nell'elenco; è personalizzabile.
• Base URL (obbligatorio) — indirizzo API del provider. Per la maggior parte dei provider è già compilato automaticamente; per Azure OpenAI e Custom devi inserirlo manualmente.
• API Key (facoltativa) — la vera chiave del provider. Se lasciata vuota, potrai testare solo la raggiungibilità dell'endpoint, ma non la validità della chiave; per i provider locali (Ollama / LM Studio) di solito non è necessaria.
• Modelli — ci sono due modalità, scegline una:
  • Scoperta automatica: dopo aver fatto clic su Scopri, il gateway chiama l'API di elenco modelli del provider per recuperare i modelli disponibili; puoi selezionarli più di uno sotto forma di chip.
  • Inserimento manuale: digita direttamente il nome del modello. Per i canali Azure devi inserire il nome della distribuzione (Deployment name) e non il nome del modello.
• Priorità / Peso — quando più canali possono servire lo stesso modello, il gateway usa questi valori per decidere routing e distribuzione del carico.

Nota su Azure OpenAI

Nel campo «Modelli» dei canali Azure devi inserire il nome della distribuzione (Deployment name) creato nel portale Azure, non il nome del modello sottostante. Anche nel Base URL devi indicare l'endpoint della tua risorsa Azure.

Terzo passaggio: conferma e invio

Controlla il riepilogo della configurazione e invia. Dopo l'invio, il nuovo canale comparirà nell'elenco dei canali con lo stato di salute in tempo reale.

Rilevamento delle capacità e strategia di routing

Dopo aver aggiunto un canale, il gateway esegue sul canale un rilevamento delle capacità (capability probing): è il meccanismo di routing intelligente più importante dell'AI Gateway. L'esito del rilevamento determina se strumenti come Claude Code possono essere usati direttamente oppure se è necessario creare una mappatura dei modelli, e come scegliere il modello di destinazione.

Due indicatori chiave del rilevamento

Il gateway rileva due fatti fondamentali per ogni canale (entrambi con tre stati: true / false / non rilevato):

Elemento rilevato	Significato	true	false	Non rilevato
Riconosce i nomi dei modelli Claude (accepts_claude_names)	Se il canale riconosce nativamente nomi di modello come claude-opus-* / claude-sonnet-* / claude-haiku-*	Connessione diretta, nessuna mappatura necessaria	Non li riconosce: è necessario creare una mappatura che traduca i nomi claude-* nei veri nomi dei modelli upstream	Rilevamento non eseguito o fallito: non si può concludere
Differenziazione per fascia (tier_aware)	Se l'upstream restituisce modelli diversi in base alla fascia opus / sonnet / haiku	L'upstream gestisce già le fasce: basta delegare all'upstream	Non differenzia (restituisce lo stesso modello per tutte le fasce): serve una mappatura del gateway	Non rilevabile o mai rilevato

Perché rilevare invece di indovinare

Il comportamento dei provider varia molto. OpenAI non riconosce nativamente i nomi dei modelli claude-*; alcuni provider intermedi li riconoscono tramite inoltro; i provider con piani di codifica (ad esempio abbonamenti Claude Pro/Max) potrebbero riconoscere solo nomi di modello specifici legati all'abbonamento. Il gateway non indovina in base al tipo di canale: esegue un rilevamento reale e poi decide la strategia di routing.

Determinazione del routing: cinque stati

Quando esegui «Presa in carico con un clic» per Claude Code nella pagina AI Gateway → Gestione accessi → Clienti, il gateway aggrega i risultati del rilevamento di tutti i canali candidati e produce una decisione di routing:

Stato dei canali candidati	Decisione	Significato
Nessun canale candidato disponibile (nessun canale / tutti non integri / nessun canale nell'ambito della chiave virtuale)	Nessun canale candidato	Devi prima aggiungere o riparare un canale
Il valore di rilevamento di almeno un canale candidato è non rilevato	Non rilevato	È necessario eseguire prima un rilevamento; non si può creare una mappatura senza verifica
Tutti i canali candidati riconoscono i nomi dei modelli Claude	Connessione diretta	Nessuna mappatura; le richieste vengono inoltrate così come sono
Nessun canale candidato riconosce i nomi dei modelli Claude	Mappatura obbligatoria	Il gateway crea mappature per le tre fasce, traducendo claude-* nei veri nomi dei modelli upstream
Tra i candidati alcuni li riconoscono e altri no	Misto	Serve una decisione manuale (quelli che li riconoscono vanno diretti, gli altri passano dalla mappatura)

Mappatura dei modelli: tradurre claude-* nei veri modelli upstream

Quando la decisione è «Mappatura obbligatoria», il gateway crea tre regole di mappatura dei modelli per Claude Code, una per ciascuna delle tre fasce:

Nome modello inviato da Claude Code	Regola di mappatura (carattere jolly)	Mappato a
claude-opus-*	Corrisponde a tutte le richieste della fascia opus	Modello di punta tra i canali candidati
claude-sonnet-*	Corrisponde a tutte le richieste della fascia sonnet	Modello di punta o modello standard tra i canali candidati
claude-haiku-*	Corrisponde a tutte le richieste della fascia haiku	Modello leggero tra i canali candidati

Regole di scelta del modello di destinazione (con fallback in ordine di priorità):

1. Preset di famiglia: se tra i modelli candidati compare una parola chiave di famiglia nota (ad esempio glm), prendi direttamente il modello di punta di quella famiglia (ad esempio glm-5.2) come destinazione per le fasce opus/sonnet, e il modello leggero della stessa famiglia (ad esempio glm-4.7-flash) come destinazione per la fascia haiku.
2. Corrispondenza per parole chiave: in assenza di un preset di famiglia, per opus/sonnet si prende il primo modello dell'elenco dei candidati; per haiku si prende il primo modello tra i candidati che corrisponde a una parola chiave di modello leggero (flash / mini / lite / air / small / turbo / haiku).
3. Fallback: se ancora nessuna corrispondenza, per tutte e tre le fasce si prende il primo modello dell'elenco dei candidati.

Un errore nella fascia haiku costa più di tutti

La fascia haiku di Claude Code è quella con il maggior numero di chiamate (ogni chiamata leggera di una conversazione la usa). Se inserisci per errore un modello di punta nella fascia haiku, la bolletta può moltiplicarsi. La tabella di corrispondenza per parole chiave del gateway copre 7 suffissi leggeri (flash / mini / lite / air / small / turbo / haiku), per evitare che un modello pesante finisca nella fascia haiku.

Meccanismo di scrittura delle mappature

Dopo la conferma della presa in carico, il gateway scrive i record di mappatura tramite l'API /admin/model-mappings. Ogni record di mappatura contiene:

• Protocollo di origine (source_protocol): anthropic (le richieste inviate da Claude Code sono in formato Anthropic)
• Corrispondenza modello di origine (source_model_pattern): carattere jolly, ad esempio claude-opus-*
• Protocollo di destinazione (target_protocol): openai (convertite in formato OpenAI e inviate all'upstream)
• Modello di destinazione (target_model): il nome specifico del modello scelto dal rilevamento

La scrittura è idempotente: una presa in carico ripetuta non genera mappature duplicate; prima della scrittura viene recuperato l'elenco delle mappature esistenti per il confronto.

Regole di routing a runtime: failover e degradazione

Oltre alle mappature statiche scritte durante la presa in carico, il gateway supporta anche regole di routing a runtime (routing rules), che prendono decisioni dinamiche quando le richieste attraversano il gateway:

Campo della regola	Funzione
Condizione di attivazione (condition_type)	Quando attivare la degradazione, ad esempio esaurimento della quota del canale (quota_exhausted)
Soglia di costo (cost_threshold_usd)	Opzionale: si attiva quando il costo cumulativo del canale supera la soglia
Azione (action_type)	Cosa fare dopo l'attivazione, ad esempio passare a un canale di riserva specifico (switch_to)
Canale di destinazione (target_channel_id)	Il canale di riserva a cui degradare
Modello di destinazione (target_model)	Opzionale: cambiare modello passando al canale di riserva

Combinando più regole di routing puoi ottenere, ad esempio: passare automaticamente dall'abbonamento del canale A all'endpoint a consumo del canale B quando la quota di abbonamento si esaurisce; degradare a un modello più economico quando il costo di un canale nelle 24 ore supera il limite.

Bilanciamento del carico e priorità

Quando più canali integri possono servire lo stesso modello, il gateway sceglie in base alla seguente strategia:

• Modalità priorità (predefinita): vengono usati solo i canali con la priorità più alta; tra canali con la stessa priorità il gateway distribuisce in base ai pesi interni.
• Modalità round-robin (round_robin): distribuisce le richieste a turno tra tutti i canali candidati integri.

La priorità si imposta nella configurazione del canale (un numero più alto indica priorità maggiore); allowed_channels della chiave virtuale limita l'insieme dei canali selezionabili.

Test di connettività

Nell'elenco dei canali puoi eseguire un test di connettività su un singolo canale. Il test copre due dimensioni:

• Raggiungibilità dell'endpoint (reachable) — verifica se il Base URL è raggiungibile (rete e indirizzo corretti).
• Validità della chiave (authenticated) — chiama realmente l'API del provider per verificare se l'API Key è valida. Viene verificata solo se è stata inserita un'API Key.

Il risultato del test mostra: latenza andata e ritorno (millisecondi), badge di stato ed eventuali messaggi di errore.

TIP

Nella procedura guidata di aggiunta, se l'endpoint non è raggiungibile non puoi passare al passaggio successivo; se l'endpoint è raggiungibile ma la chiave non è valida, viene mostrato solo un avviso e puoi comunque continuare (ad esempio se intendi aggiungere la chiave in un secondo momento).

Configurazione avanzata

Quando aggiungi o modifichi un canale, puoi espandere la configurazione avanzata per il calcolo dei costi e il controllo delle quote:

• Moltiplicatore di prezzo (Rate Multiplier) — moltiplica per un coefficiente il prezzo ufficiale del provider, per calcolare in base al tuo costo reale o al prezzo di rivendita; valore predefinito 1.0.
• Struttura di fatturazione — specifica il metodo di fatturazione del canale, ad esempio a consumo (pay as you go), abbonamento (subscription) o pacchetto (package).
• Saldo — l'origine del saldo può essere un valore fisso, una fattura OSS o la gestione manuale; scegliendo la fattura OSS puoi anche specificarne il tipo. Saldo e data di aggiornamento sono mostrati in sola lettura nei dettagli del canale.
• Data di scadenza dell'abbonamento — per i canali con abbonamento / pacchetto è possibile registrare la data di scadenza.
• Limiti di quota — puoi impostare un limite massimo in base al numero di token, al numero di richieste o all'importo, scegliendo un periodo (giornaliero / settimanale / mensile / personalizzato). Quando la quota si esaurisce, il canale viene automaticamente escluso dal routing: è una valvola di sicurezza contro spese impreviste.

Modificare ed eliminare i canali

• Modifica — apri un canale nell'elenco per modificarne nome, Base URL, API Key, modelli e configurazione avanzata.
• Eliminazione — dopo aver eliminato un canale, le chiavi virtuali che dipendono da esso non potranno più instradare richieste verso di esso; procedi con cautela.

Stato di salute

L'elenco dei canali e la pagina Panoramica mostrano in tempo reale lo stato di salute di ogni canale (normale / degradato / non disponibile), aiutandoti a individuare rapidamente configurazioni provider non più funzionanti.

Domande frequenti (FAQ)

• D: Quando aggiungo un canale mi viene chiesto di accedere?
  • R: L'AI Gateway è una funzione a valore aggiunto di ServBay; prima di aggiungere canali / chiavi devi accedere al tuo account ServBay. Segui le indicazioni dell'interfaccia per effettuare l'accesso.
• D: Viene segnalato che il numero di canali ha raggiunto il limite?
  • R: Il numero di canali creabili dipende dal piano dell'account; quando raggiungi il limite puoi eliminare i canali inutilizzati o passare a un piano superiore.
• D: La scoperta automatica dei modelli non recupera l'elenco?
  • R: Verifica innanzitutto che il Base URL sia corretto e che l'API Key sia valida (puoi usare la «Validità della chiave» del test di connettività); alcuni provider richiedono una chiave valida per restituire l'elenco dei modelli. In alternativa, inserisci manualmente il nome del modello.
• D: Per collegare Ollama / LM Studio in locale serve una Key?
  • R: Di solito no. Assicurati solo che il servizio locale corrispondente sia avviato e in ascolto sulla porta predefinita (Ollama 11434, LM Studio 1234).

Riepilogo

I canali sono la base su cui l'AI Gateway instrada le richieste. Con la procedura guidata in tre passaggi puoi collegare rapidamente quasi 20 provider; grazie al passaggio tra due regioni, alla scoperta automatica dei modelli e al test di connettività su due dimensioni puoi assicurarti che la configurazione sia corretta, mentre con configurazioni avanzate come prezzi e quote puoi gestire i costi con precisione. Una volta configurati i canali, puoi creare le chiavi virtuali da usare nelle applicazioni e negli strumenti.