Gestione dei Canali su AI Gateway

Un canale (Channel) è la configurazione di un punto di accesso fornitore all’interno dell’AI Gateway. Esso memorizza l’indirizzo del fornitore, la vera API Key, i modelli disponibili, la tariffazione, i limiti e altre informazioni rilevanti. Il gateway utilizza questi canali per indirizzare le richieste provenienti dalle applicazioni verso il relativo fornitore. In questo articolo viene spiegato come aggiungere, configurare, testare e gestire i canali.

Prerequisiti

• ServBay deve essere installato, in funzione e l’accesso all’account ServBay deve essere effettuato (è necessario effettuare il login prima di aggiungere un canale).
• Procurati una vera API Key del fornitore di destinazione (per fornitori locali come Ollama / LM Studio il campo può rimanere vuoto).
• Se non conosci l’architettura generale dell’AI Gateway, si consiglia di leggere prima la Introduzione all’AI Gateway.

Aggiunta di un Canale

Vai su AI Gateway → Canali (Channels) e clicca su Aggiungi (Add) per avviare la procedura guidata. La guida prevede tre passaggi.

Primo Passaggio: Selezione del Fornitore

I fornitori sono raggruppati per categoria. Seleziona quello desiderato cliccando sulla relativa scheda:

• Principali (Mainstream): OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• Cina (China): DeepSeek, Qwen (通义千问), Zhipu GLM, Kimi, Doubao Volcengine, Wenxin, Hunyuan, MiniMax, 01.ai, StepStar.
• Locale (Local): Ollama, LM Studio.
• Personalizzato (Custom): OpenAI Compatible, Custom.

Dopo la selezione, il gateway inserirà automaticamente il Base URL predefinito del fornitore.

Switch regione doppia

Fornitori cinesi come Qwen, Zhipu GLM, Kimi, Doubao Volcengine, Hunyuan, MiniMax e StepStar offrono endpoint nazionali e globali. Quando selezioni questi fornitori, nella procedura comparirà un selettore "Regione" (🇨🇳 Nazionale / 🌐 Globale); cambiando scelta, il Base URL verrà aggiornato automaticamente all’indirizzo corrispondente.

Secondo Passaggio: Compilazione della Configurazione

• Nome canale (obbligatorio) — Serve per identificare il canale nella lista, campo personalizzabile.
• Base URL (obbligatorio) — Indirizzo API del fornitore. La maggior parte viene valorizzata automaticamente; per Azure OpenAI e Custom dovrai inserirlo manualmente.
• API Key (opzionale) — La vera chiave segreta del fornitore. Se lasciata vuota, potrai solo testare la raggiungibilità dell’endpoint, ma non la validità della chiave; per fornitori locali (Ollama / LM Studio) di solito non serve.
• Modelli — Due modalità alternative, scegline una:
  • Rilevamento automatico: premendo su rileva, il gateway interrogherà l’API del fornitore e mostrerà i modelli disponibili, selezionabili con tag (chip).
  • Inserimento manuale: digita direttamente il nome del modello. Nei canali Azure va inserito il nome della distribuzione (Deployment name), non del modello.
• Priorità / Peso — Quando più canali supportano lo stesso modello, il gateway utilizza questo valore per gestire il routing e il bilanciamento del carico.

Avviso Azure OpenAI

Nel campo "Modello" del canale Azure inserisci il nome della distribuzione (Deployment name) creato nel portale Azure, non il nome del modello sottostante. Anche il Base URL deve essere quello del tuo endpoint Azure Resource.

Terzo Passaggio: Conferma e Invio

Controlla il riepilogo della configurazione e invia. In caso di successo, il nuovo canale apparirà nell’elenco con relativa indicazione dello stato di salute in tempo reale.

Test di Connessione

È possibile effettuare un test di connessione su ogni singolo canale. Il test funziona su due dimensioni:

• Raggiungibilità endpoint (reachable) — Controlla se il Base URL è accessibile (verifica rete e indirizzo).
• Validità della chiave (authenticated) — Richiede una vera chiamata all’API del fornitore per verificare la validità dell’API Key. Questa verifica avviene solo se viene fornita una API Key.

I risultati mostreranno: tempi di risposta (millisecondi), badge dello stato e informazioni sugli errori.

TIP

Durante la procedura guidata, se l’endpoint non è raggiungibile, non potrai proseguire alla fase successiva; se invece è raggiungibile ma la chiave è invalida, verrà solo mostrato un avviso e potrai continuare (ad esempio se intendi inserire la chiave in un secondo momento).

Configurazioni Avanzate

Durante l’aggiunta o la modifica di un canale puoi accedere alle configurazioni avanzate, utili per la gestione dei costi e dei limiti:

• Moltiplicatore tariffa (Rate Multiplier) — Moltiplica la tariffa ufficiale del fornitore, per adeguarla al tuo reale costo o prezzo di rivendita. Valore predefinito 1.0.
• Struttura tariffaria — Descrive il metodo di pagamento del canale: a consumo (“pay as you go”), abbonamento (“subscription”) o pacchetto (“package”).
• Saldo — Puoi scegliere saldo fisso, estratto da fattura OSS, o gestione manuale; usando la fattura OSS puoi specificare anche il tipo di fatturazione. Il saldo e la data di aggiornamento sono visibili solo in lettura nel dettaglio canale.
• Scadenza abbonamento — Nei canali ad abbonamento/pacchetto puoi specificare la data di scadenza.
• Limite — Puoi impostare un plafond per token, numero di richieste o importo, con frequenza (giornaliero / settimanale / mensile / personalizzato), e abilitare “tolleranza” per consentire un certo margine di superamento. La funzionalità limiti è riservata agli account a pagamento.

Modifica e Cancellazione dei Canali

• Modifica — Aprendo un canale nell’elenco puoi cambiare nome, Base URL, API Key, modelli e opzioni avanzate.
• Eliminazione — Dopo la cancellazione, le chiavi virtuali che dipendono da quel canale non saranno più instradate. Attenzione!

Stato di Salute

Nell’elenco canali e nella pagina panoramica viene mostrato in tempo reale lo stato di salute di ciascun canale (Ok / Degradato / Non disponibile), per aiutarti a individuare rapidamente eventuali problemi nei fornitori configurati.

Domande Frequenti (FAQ)

• D: Perché mi viene richiesto di accedere quando aggiungo un canale?
  • R: AI Gateway è una funzione premium di ServBay; è necessario accedere all’account ServBay prima di aggiungere canali e chiavi, come richiesto dall’interfaccia.
• D: Ho raggiunto il limite massimo di canali?
  • R: Il numero di canali dipende dal tipo di account; puoi eliminare canali inutilizzati o aggiornare il piano per aumentarne il numero.
• D: Non riesco a rilevare automaticamente l’elenco dei modelli?
  • R: Verifica che il Base URL sia corretto e che la API Key sia valida (usa il test di “Validità della chiave”). Alcuni fornitori richiedono una chiave valida per restituire la lista modelli; altrimenti, puoi inserire i nomi manualmente.
• D: Serve inserire una Key per usare Ollama / LM Studio in locale?
  • R: Normalmente no. Basta che il relativo servizio locale sia avviato e pronto ad ascoltare sulla porta predefinita (Ollama 11434, LM Studio 1234).

Conclusione

Il canale costituisce il fondamento per il routing delle richieste nell’AI Gateway. Attraverso una semplice procedura guidata in tre passi puoi integrare rapidamente quasi 20 fornitori, sfruttando la doppia regione, il rilevamento automatico dei modelli e il test completo di connessione per una configurazione senza errori. Grazie alle opzioni avanzate di tariffazione e limiti, puoi gestire in maniera ottimale i costi. Una volta creato il canale, potrai aggiungere chiavi virtuali da utilizzare in applicazioni e tool.