Kanalen beheren in de AI-gateway

Een 'kanaal (channel)' is de configuratie van een provider-toegangspunt in de AI-gateway: het bevat onder meer het adres van een provider, de echte API Key, beschikbare modellen en gegevens over prijsstelling en limieten. Op basis van deze kanalen routeert de gateway verzoeken van applicaties naar de juiste provider. In dit artikel lees je hoe je kanalen toevoegt, configureert, test en beheert.

Vereisten

• ServBay is geïnstalleerd en actief, en je bent ingelogd op je ServBay-account (inloggen is vereist voordat je een kanaal toevoegt).
• Je hebt de echte API Key van de beoogde provider bij de hand (bij lokale providers zoals Ollama / LM Studio mag dit veld leeg blijven).
• Als je nog niet bekend bent met de algemene architectuur van de AI-gateway, lees dan eerst de Inleiding tot de AI-gateway.

Een kanaal toevoegen

Ga naar de pagina AI-gateway → Kanalen (Channels) en klik op Toevoegen (Add) om de wizard te openen. De wizard bestaat uit drie stappen.

Stap 1: Provider kiezen

Providers worden per categorie gegroepeerd weergegeven. Klik op een kaart om er een te selecteren:

• Mainstream: OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• China: DeepSeek, Qwen, Zhipu GLM, Kimi, Doubao·Volcano, ERNIE Bot, Hunyuan, MiniMax, 01.AI, StepFun.
• Lokaal: Ollama, LM Studio.
• Aangepast (Custom): OpenAI Compatible, Custom.

Nadat je een provider hebt gekozen, vult de gateway automatisch de standaard Base URL van die provider in.

Schakelen tussen twee regio's

Chinese providers zoals Qwen, Zhipu GLM, Kimi, Doubao·Volcano, Hunyuan, MiniMax en StepFun bieden zowel binnenlandse als wereldwijde eindpunten. Wanneer je zo'n provider kiest, verschijnt in de wizard een regio-selector (🇨🇳 Binnenland / 🌐 Wereldwijd). Na het wisselen wordt de Base URL automatisch bijgewerkt naar het adres van de betreffende regio.

Stap 2: Configuratie invullen

• Kanaalnaam (verplicht) — om het kanaal in de lijst te herkennen; vrij te kiezen.
• Base URL (verplicht) — het API-adres van de provider. Bij de meeste providers is dit al automatisch ingevuld; bij Azure OpenAI en Custom moet je dit handmatig invullen.
• API Key (optioneel) — de echte sleutel van de provider. Als je dit leeg laat, kun je alleen testen of het eindpunt bereikbaar is, maar niet of de sleutel geldig is; bij lokale providers (Ollama / LM Studio) hoef je deze meestal niet in te vullen.
• Model — er zijn twee manieren, waarvan je er één kiest:
  • Automatische detectie: nadat je op detecteren klikt, roept de gateway de modellenlijst-API van de provider aan om de beschikbare modellen op te halen, die je vervolgens als chips kunt selecteren.
  • Handmatig invullen: voer de modelnaam direct in. Voor Azure-kanalen moet je de implementatienaam (Deployment name) invullen in plaats van de modelnaam.
• Prioriteit / gewicht — wanneer meerdere kanalen hetzelfde model kunnen bedienen, bepaalt de gateway hiermee de routing en de verdeling van de belasting.

Let op bij Azure OpenAI

Vul in het veld 'Model' van een Azure-kanaal de implementatienaam (Deployment name) in die je in de Azure-portal hebt aangemaakt, niet de naam van het onderliggende model. Ook voor de Base URL moet je het eindpunt van je Azure-resource invullen.

Stap 3: Bevestigen en verzenden

Controleer de samenvatting van de configuratie en verzend deze. Na een geslaagde verzending verschijnt het nieuwe kanaal in de kanalenlijst, met de actuele gezondheidsstatus.

Capaciteitsdetectie en routeringsstrategie

Nadat je een kanaal hebt toegevoegd, voert de gateway capaciteitsdetectie (capability probing) uit op dat kanaal. Dit is het belangrijkste intelligente routeringsmechanisme van de AI-gateway. De uitkomst van de detectie bepaalt of tools zoals Claude Code direct gebruikt kunnen worden of dat er een modeltoewijzing nodig is, en ook hoe het doelmodel wordt gekozen.

De twee belangrijkste detectie-indicatoren

De gateway detecteert voor elk kanaal twee kernfeiten (elk met drie toestanden: true / false / onbekend):

Detectie-item	Betekenis	true	false	Onbekend
Herkent Claude-modelnamen (accepts_claude_names)	Of het kanaal de modelnamen claude-opus-* / claude-sonnet-* / claude-haiku-* native herkent	Directe verbinding volstaat, geen toewijzing nodig	Wordt niet herkend, er moet een toewijzing komen die claude-* vertaalt naar de echte modelnaam van de upstream	Detectie is niet uitgevoerd of mislukt; geen conclusie mogelijk
Maakt onderscheid naar tier (tier_aware)	Of de upstream zelf verschillende modellen retourneert op basis van de opus/sonnet/haiku-tier	Upstream maakt al onderscheid; laat de upstream dit afhandelen	Geen onderscheid (voor alle tiers wordt hetzelfde model geretourneerd); de gateway moet een toewijzing maken	Niet vast te stellen of nooit onderzocht

Waarom detecteren in plaats van gokken

Het gedrag van providers loopt sterk uiteen. OpenAI herkent claude-*-modelnamen niet native; sommige doorgeefproviders herkennen ze via forwarding; en providers met codeerabonnementen (zoals een Claude Pro/Max-abonnement) herkennen mogelijk alleen de specifieke modelnaam die aan het abonnement is gekoppeld. De gateway gokt niet op basis van het kanaaltype, maar bepaalt de routeringsstrategie pas na een daadwerkelijke detectie.

Routeringsbeslissing: vijf toestanden

Wanneer je op de pagina AI Gateway → Toegangsbeheer → Clients Claude Code via 'overnemen met één klik' instelt, bundelt de gateway de detectieresultaten van alle kandidaat-kanalen tot een routeringsbeslissing:

Status van kandidaat-kanalen	Beslissing	Betekenis
Geen beschikbare kandidaat-kanalen (geen kanalen / allemaal ongezond / geen kanalen binnen het bereik van de virtuele sleutel)	Geen kandidaat-kanalen	Je moet eerst kanalen toevoegen of repareren
Bij een of meer kandidaat-kanalen is de detectiewaarde onbekend	Niet gedetecteerd	Er moet eerst een detectie worden uitgevoerd; je mag geen toewijzing maken zonder verificatie
Alle kandidaat-kanalen herkennen claude-modelnamen	Directe verbinding	Geen toewijzing; verzoeken worden ongewijzigd doorgestuurd
Geen enkel kandidaat-kanaal herkent claude-modelnamen	Toewijzing verplicht	De gateway maakt een toewijzing voor drie tiers, die claude-* vertaalt naar de echte modelnaam van de upstream
Sommige kandidaten herkennen het wel, andere niet	Gemengd	Menselijke beslissing nodig (herkende kanalen gaan direct, niet-herkende via toewijzing)

Modeltoewijzing: claude-* vertalen naar het echte upstream-model

Wanneer de beslissing 'Toewijzing verplicht' is, stelt de gateway drie modeltoewijzingsregels op voor Claude Code, elk voor één tier:

Modelnaam die Claude Code verstuurt	Toewijzingsregel (wildcard)	Toegewezen aan
claude-opus-*	Komt overeen met alle verzoeken op opus-tier	Het vlaggenschipmodel onder de kandidaat-kanalen
claude-sonnet-*	Komt overeen met alle verzoeken op sonnet-tier	Het vlaggenschipmodel of het standaardmodel onder de kandidaat-kanalen
claude-haiku-*	Komt overeen met alle verzoeken op haiku-tier	Het lichtgewicht model onder de kandidaat-kanalen

Regels voor het kiezen van het doelmodel (terugval op basis van prioriteit):

1. Familie-preset: als onder de kandidaat-modellen een bekend familie-trefwoord voorkomt (zoals glm), neem dan direct het vlaggenschipmodel van die familie (zoals glm-5.2) als doel voor de opus/sonnet-tier, en het lichtgewicht model van die familie (zoals glm-4.7-flash) als doel voor de haiku-tier.
2. Trefwoordmatching: als er geen familie-preset is, neem dan voor opus/sonnet het eerste model uit de kandidatenlijst; voor haiku het eerste model uit de kandidaten dat overeenkomt met een lichtgewicht-trefwoord (flash / mini / lite / air / small / turbo / haiku).
3. Vangnet: als er nog steeds geen match is, gebruiken alle drie de tiers het eerste model uit de kandidatenlijst.

Een verkeerde haiku-tier is het duurst

De haiku-tier van Claude Code wordt het meest aangeroepen (elke lichtgewicht aanroep in een gesprek gebruikt deze). Als je per ongeluk een vlaggenschipmodel in de haiku-tier zet, kan de rekening meerdere malen hoger uitvallen. De trefwoordmatchingtabel van de gateway dekt zeven lichtgewicht-achtervoegsels (flash / mini / lite / air / small / turbo / haiku), zodat er geen zwaar model in de haiku-tier belandt.

Het mechanisme voor het wegschrijven van toewijzingen

Nadat de overname is bevestigd, schrijft de gateway de toewijzingsrecords weg via de /admin/model-mappings-API. Elk toewijzingsrecord bevat:

• Bronprotocol (source_protocol): anthropic (de verzoeken die Claude Code verstuurt, hebben het Anthropic-formaat)
• Bronmodel-patroon (source_model_pattern): wildcard, zoals claude-opus-*
• Doelprotocol (target_protocol): openai (wordt uniform omgezet naar OpenAI-formaat en naar de upstream gestuurd)
• Doelmodel (target_model): de specifieke modelnaam die de detectie heeft uitgekozen

Het wegschrijven is idempotent: herhaald overnemen levert geen dubbele toewijzingen op; vóór het wegschrijven wordt eerst de bestaande toewijzingslijst opgehaald en vergeleken.

Routeringsregels tijdens runtime: failover en degradatie

Naast de statische toewijzingen die tijdens de overnamefase worden weggeschreven, ondersteunt de gateway ook routeringsregels tijdens runtime, die dynamisch beslissingen nemen wanneer een verzoek door de gateway gaat:

Regelveld	Functie
Triggervoorwaarde (condition_type)	Wanneer degradatie wordt geactiveerd, zoals wanneer de limiet van een kanaal is uitgeput (quota_exhausted)
Kostendrempel (cost_threshold_usd)	Optioneel: wordt geactiveerd wanneer de cumulatieve kosten van dat kanaal de drempel overschrijden
Actie (action_type)	Wat er gebeurt na activering, zoals overschakelen naar een opgegeven reservekanaal (switch_to)
Doelkanaal (target_channel_id)	Het reservekanaal waarnaar wordt gedegradeerd
Doelmodel (target_model)	Optioneel: schakel tegelijk van model over bij degradatie naar het reservekanaal

Door meerdere routeringsregels te combineren, kun je bijvoorbeeld: automatisch overschakelen naar het pay-as-you-go-eindpunt van kanaal B wanneer het abonnementsquotum van kanaal A is uitgeput; of degraderen naar een goedkoper model wanneer de 24-uurskosten van een kanaal de limiet overschrijden.

Load balancing en prioriteit

Wanneer meerdere gezonde kanalen hetzelfde model kunnen bedienen, kiest de gateway volgens de volgende strategie:

• Prioriteitsmodus (standaard): er wordt alleen het kanaal met de hoogste prioriteit gebruikt; onder kanalen met dezelfde prioriteit verdeelt de gateway op basis van interne gewichten.
• Round-robin-modus (round_robin): verzoeken worden bij toerbeurt over alle gezonde kandidaat-kanalen verdeeld.

De prioriteit stel je in bij de kanaalconfiguratie (hoe hoger het getal, hoe hoger de prioriteit). De allowed_channels van een virtuele sleutel beperken het bereik van beschikbare kanalen.

Connectiviteitstest

In de kanalenlijst kun je voor een afzonderlijk kanaal een connectiviteitstest uitvoeren. De test kent twee dimensies:

• Bereikbaarheid van het eindpunt (reachable) — controleert of de Base URL bereikbaar is (of netwerk en adres correct zijn).
• Geldigheid van de sleutel (authenticated) — roept daadwerkelijk de API van de provider aan om te verifiëren of de API Key geldig is. Wordt alleen geverifieerd als er een API Key is ingevuld.

Het testresultaat toont: de round-tripvertraging (in milliseconden), een statusbadge en eventuele foutmeldingen.

TIP

In de toevoegwizard word je tegengehouden om verder te gaan als het eindpunt niet bereikbaar is; als het eindpunt wel bereikbaar is maar de sleutel ongeldig is, krijg je alleen een waarschuwing en kun je toch doorgaan (bijvoorbeeld als je van plan bent de sleutel later aan te vullen).

Geavanceerde configuratie

Bij het toevoegen of bewerken van een kanaal kun je de geavanceerde configuratie uitklappen, die dient voor kostenberekening en limietbeheer:

• Tariefvermenigvuldiger (Rate Multiplier) — vermenigvuldigt de officiële prijs van de provider met een factor, handig om te rekenen met je werkelijke kosten of doorverkoopprijs; standaard 1.0.
• Factureringsstructuur — beschrijft de manier van factureren van het kanaal, zoals pay as you go, abonnement (subscription) of pakket (package).
• Saldo — de saldobron kan een vaste waarde, een OSS-factuur of handmatig onderhoud zijn; bij keuze voor een OSS-factuur kun je ook het factuurtype opgeven. Saldo en tijdstip van bijwerken worden in de kanaaldetails alleen-lezen weergegeven.
• Vervaldatum van het abonnement — voor kanalen met een abonnement of pakket kan de vervaldatum worden vastgelegd.
• Limieten — je kunt een bovengrens instellen op basis van het aantal tokens, het aantal verzoeken of een bedrag, en daarbij een periode kiezen (dagelijks / wekelijks / maandelijks / aangepast). Zodra de limiet is bereikt, wordt het kanaal automatisch uitgesloten van de routering. Dit is een veiligheidsklep tegen onverwachte overschrijdingen.

Kanalen bewerken en verwijderen

• Bewerken — open een kanaal in de kanalenlijst om de naam, Base URL, API Key, modellen en geavanceerde configuratie te wijzigen.
• Verwijderen — na het verwijderen van een kanaal kunnen virtuele sleutels die ervan afhankelijk zijn er niet meer naartoe routeren; ga hier dus zorgvuldig mee om.

Gezondheidsstatus

De kanalenlijst en de overzichtspagina tonen de gezondheidsstatus van elk kanaal in realtime (normaal / gedegradeerd / niet beschikbaar), zodat je snel niet-werkende providerconfiguraties kunt opsporen.

Veelgestelde vragen (FAQ)

• V: Bij het toevoegen van een kanaal krijg ik de melding dat ik moet inloggen?
  • A: De AI-gateway is een premiumfunctie van ServBay. Voordat je kanalen of sleutels toevoegt, moet je inloggen op je ServBay-account; volg hiervoor de aanwijzingen in de interface.
• V: Ik krijg de melding dat het maximum aantal kanalen is bereikt?
  • A: Het aantal kanalen dat je kunt aanmaken, hangt af van je accountpakket. Bij het bereiken van de limiet kun je ongebruikte kanalen verwijderen of je pakket upgraden.
• V: Automatische modeldetectie haalt geen lijst op?
  • A: Controleer eerst of de Base URL correct is en de API Key geldig is (dit kun je verifiëren met 'Geldigheid van de sleutel' in de connectiviteitstest). Sommige providers vereisen een geldige sleutel voordat ze de modellenlijst retourneren; je kunt ook de modelnaam handmatig invullen.
• V: Heb ik een Key nodig om lokale Ollama / LM Studio aan te sluiten?
  • A: Meestal niet. Zorg ervoor dat de betreffende lokale service actief is en luistert op de standaardpoort (Ollama 11434, LM Studio 1234).

Samenvatting

Kanalen vormen de basis van de routering van verzoeken in de AI-gateway. Met de wizard in drie stappen sluit je snel aan op bijna 20 providers. Dankzij het schakelen tussen twee regio's, automatische modeldetectie en connectiviteitstests met twee dimensies zorg je dat de configuratie klopt, en met geavanceerde configuratie zoals prijsstelling en limieten houd je de kosten nauwkeurig onder controle. Zodra de kanalen zijn geconfigureerd, kun je virtuele sleutels aanmaken voor gebruik door applicaties en tools.