Voor dezelfde functie moet de frontend vier modellen aanroepen: GPT-4o dient als fallback, DeepSeek draait de zware inferentie, Qwen verwerkt lange Chinese teksten en Doubao neemt de klantenservice-gesprekken voor zijn rekening. Vier SDK's, vier authenticatiesystemen, vier documentaties. In de eerste week na livegang kostte het alleen al afstemmen van deze verschillen twee persoonsdagen.
Dat is geen overdrijving. We hebben het uitgerekend: na het aansluiten van vier leveranciers was het deel van de bedrijfscode dat met modelaanroepen te maken heeft bijna drie keer zo groot geworden. Bij elke modelwissel moest de aanroepwijze, de parsing-logica en de foutafhandeling opnieuw worden aangepast. Vervelender nog: elke keer dat een leverancier de SDK upgradet, moet alles opnieuw worden getest. Dit artikel zet de valkuilen die wij zijn tegengekomen en de gateway-oplossing die we uiteindelijk hebben geïmplementeerd volledig uiteen, in de hoop teams te helpen die net als wij worstelen met meerdere modellen.
1. Authenticatie: vier systemen, vier manieren
Authenticatie was het eerste waar we tegenaan liepen. De OpenAI-familie werkt met een Bearer Token, gewoon Authorization: Bearer sk-xxx in de request-header. Qwen vereist AccessKey-signing: bij elke request moet met AK/SK een HMAC worden berekend, plus een tijdstempel en een random string. Doubao gebruikt AK/SK plus tijdstempel, maar het signatuur-algoritme verschilt weer van dat van Qwen. DeepSeek is wel compatibel met het OpenAI-formaat, maar heeft zijn eigen base_url en modelnaam-mapping, en de initialisatie wijkt ook niet helemaal af van de officiële SDK.
Het resultaat: if-else overal in de code. Eén client-instantie per leverancier, één set configuratie per instantie. Key-beheer was nog vervelender — de Keys van vier leveranciers lagen op vier plekken, bij rotatie moest je vier plekken aanpassen, en één gemiste plek betekende een productie-incident.
Later hebben we dit in de access-laag uniform gemaakt: naar buiten toe wordt slechts één API Key blootgesteld, intern doen we protocolvertaling. Concreet houdt de access-laag een leverancier-routingtabel bij, waarbij elke leverancier zijn eigen authenticatie-adapter heeft. De bedrijfskant heeft maar één Key, requests gaan naar de access-laag, die op basis van de modelnaam de juiste leverancier vindt en via de adapter de signering en doorsturing afhandelt.
We hebben later de base_url uniform op token8341 gezet en uitgeprobeerd: met één Key kun je GPT-4o, Claude, Gemini, DeepSeek, Qwen, ERNIE en Doubao aanroepen, compatibel met de OpenAI SDK, en met één gewijzigde base_url regel je de omschakeling. Het vuile werk van authenticatie wordt buiten de access-laag gehouden, en de bedrijfscode werd een stuk schoner. Key-rotatie werd één enkele handeling, en de operationele kosten daalden met een orde van grootte.
2. SSE-streaming-chunks: vier formaten, één rendering
SSE-streaming-chunks waren de tweede valkuil, en bovendien verraderlijker dan authenticatie. In de chunk van GPT-4o kan delta.content null zijn, vooral in de eerste en de laatste chunk; als de frontend niet op null controleert en direct rendert, flitst er undefined door het beeld. DeepSeek stuurt in de laatste chunk usage mee, en de structuur van dat usage-veld wijkt niet helemaal af van OpenAI. Qwen heeft fijnmaziger event-types, met onder meer add, finish en error, en elke event heeft een andere payload-structuur. De eindmarkering van Doubao is weer anders: die gebruikt een speciaal finish_reason-veld om het einde van de stream aan te geven.
Toen de frontend vier formaten binnenkreeg, spatte de rendering-logica uiteen. Ons eerste plan was om in de frontend te adapteren en vier parse-functies te schrijven, maar dan moest de frontend bij elk nieuw model worden aangepast. Daarna zijn we het in de gateway-laag gaan normaliseren: alles uniformeren naar de chunk-structuur van OpenAI, lege delta's direct filteren, usage apart eruit halen en accumuleren. De concrete regel is: alle streaming-responses van leveranciers worden omgezet naar het formaat data: {"choices":[{"delta":{"content":"..."}}]}, het einde wordt uniform gemarkeerd met data: [DONE], en usage wordt in de laatste chunk in OpenAI-formaat teruggegeven.
De frontend kent nog maar één formaat en hoeft zich niet bezig te houden met wie er aan de achterkant zit. Deze wijziging bracht de modelgerelateerde code in de frontend van ruim 400 regels terug naar ongeveer 80, en bij nieuwe modellen is er aan de frontend nul aanpassing nodig.
3. Foutcodes: fouten verborgen in HTTP 200
De chaos rond foutcodes overtrof onze verwachtingen. Bij rate limiting bijvoorbeeld retourneert OpenAI een 429 met rate_limit_exceeded, Qwen retourneert een bedrijfsfout met een code-veld, en Doubao stopt de fout gewoon in de body van een HTTP 200 — de statuscode is 200, maar in de body staat een error-veld. DeepSeek komt meestal overeen met OpenAI, maar retourneert af en toe zelfgedefinieerde foutstructuren.
Monitoring en alerting waren totaal niet uniform te krijgen. Je kunt geen regel schrijven als "bij 429 een alert", want sommige leveranciers retourneren bij rate limiting geen 429. Je kunt ook niet alleen naar de HTTP-statuscode kijken, want de 200 van Doubao kan een fout bevatten.
We hebben in de access-laag een mappingtabel opgezet die de foutcodes van alle leveranciers terugbrengt tot één intern foutsysteem: rate limiting, timeout, authenticatiefout, contentmoderatie, dienst niet beschikbaar. De concrete mapping-logica is: eerst naar de HTTP-statuscode kijken, dan naar de error code in de body, en beide gecombineerd beoordelen. Als Doubao bijvoorbeeld 200 retourneert maar de body bevat een error, dan wordt op basis van de error code gemapt; als Qwen een 400 met bedrijfscode retourneert, dan wordt op basis van de code gemapt. De alertregels worden maar één keer geschreven, en bij het troubleshooten kijk je naar de oorspronkelijke foutcode.
Deze mappingtabel hebben we met zo'n 60 regels onderhouden, die de gangbare foutscenario's van de vier leveranciers afdekken. Na livegang steeg de alertnauwkeurigheid van ongeveer 60% naar meer dan 95%, en valse meldingen verdwenen vrijwel volledig.
4. Verbruiksstatistieken: vier getallen die niet kloppen
Verschillende meetmethoden voor verbruik worden het makkelijkst over het hoofd gezien, maar bij de financiële afstemming komen ze gegarandeerd aan het licht. De token-telling van GPT-4o bevat de system prompt, bij DeepSeek worden tokens uit cache-hits apart geprijsd, Qwen rekent input en output apart, en de facturatie-eenheid van Doubao is weer anders. Bij de financiële afstemming kloppen de vier getallen niet, en dan valt de werkelijke kostprijs per model niet te berekenen.
De aggregatie-oplossing is om in de gateway-laag per request de model, input_tokens, output_tokens en cache_hit vast te leggen, en alles uniform volgens de token-facturatiemaatstaf in de database op te slaan. Concreet legt de gateway bij het doorsturen van een request de begin- en eindtijd vast, haalt het usage-veld van elke leverancier uit de response en zet dat om naar een standaardformaat. Voor leveranciers met een andere facturatie-eenheid doet de gateway-laag eenmalig een omrekening, zodat alles wordt teruggerekend naar kosten per token.
Zo kunnen de kosten, ongeacht welke leverancier eronder zit, in één tabel naast elkaar worden gelegd. We hebben later op basis van deze tabel ook een kosten-dashboard gebouwd, dat per model, per businesslijn en per dag kan worden uitgesplitst. Op een keer zagen we dat de kosten van een bepaalde businesslijn plotseling met 40% stegen; navraag wees uit dat de routing-strategie een grote hoeveelheid requests naar GPT-4o stuurde, en na aanpassing van de routing daalden de kosten onmiddellijk. Zonder uniforme verbruiksaggregatie was zo'n probleem nooit ontdekt.
5. De vierlaagsarchitectuur van de modelgateway
Welke lagen moet een modelgateway dragen? Mijn indeling is vier lagen.
Eerste laag: protocolvertaling. De request- en response-formaten van alle leveranciers uniformeren naar een OpenAI-compatibele interface. Deze laag is de enige laag waar de bedrijfscode direct mee in aanraking komt; hij vertaalt requests in standaard OpenAI-formaat naar het formaat van elke leverancier en vertaalt de responses weer terug.
Tweede laag: routing. Modelkeuze op basis van taaktype, bijvoorbeeld Chinese lange teksten naar Qwen, code naar DeepSeek, fallback naar GPT-4o. De routing-strategie is configureerbaar en ondersteunt meerdere dimensies zoals taaktype, prioriteit en kosten. We hebben ook degradatielogica toegevoegd: als het primaire model een timeout geeft of rate limited wordt, wordt automatisch naar het fallback-model geschakeld.
Derde laag: verbruiksaggregatie. Uniforme facturatie en quota. Het token-verbruik, de cache-hits en de responstijd van elk request worden in deze laag vastgelegd, en naar buiten toe is er één uniforme interface voor verbruiksopvraging.
Vierde laag: observeerbaarheid. Logging, tracing, convergentie van foutcodes. Elk request heeft een trace_id en is van begin tot eind over de hele keten traceerbaar. Foutcodes worden in deze laag uniform gemapt, en alertregels worden ook alleen in deze laag geconfigureerd.
De bedrijfscode roept alleen de interface van de eerste laag aan; de drie lagen daarachter zijn voor haar transparant. Het voordeel hiervan is: modelwissel vereist geen aanpassing van bedrijfscode, een model toevoegen vereist geen aanpassing van bedrijfscode, en het aanpassen van de routing-strategie vereist ook geen aanpassing van bedrijfscode. Het business-team hoeft zich alleen bezig te houden met "ik wil een model aanroepen"; de rest laat men aan de gateway over.
6. Waarschuwingen om valkuilen te vermijden
Importeer de SDK's van leveranciers niet rechtstreeks in de bedrijfscode. Zodra een leverancier de interface upgradet of jij van model wilt wisselen, wordt het aan te passen oppervlak heel groot. We hebben teams gezien die de SDK rechtstreeks in de bedrijfscode aanriepen en bij een latere modelwissel meer dan 30 bestanden moesten aanpassen en een week moesten testen voordat het live kon.
Twee dagen extra in de access-laag bespaart later twee weken. Deze verhouding tussen investering en opbrengst is bij ons daadwerkelijk bewezen — na livegang van de gateway hoeft voor een nieuw model alleen een adapter in de gateway-laag te worden toegevoegd, is er nul aanpassing aan de bedrijfscode nodig, en is de aansluiting en het testen in een halve dag gedaan.
Nog twee kleine tips: ten eerste, doe de verbruiksaggregatie zo vroeg mogelijk, wacht niet tot de financiële afstemming om erachter te komen dat het niet te berekenen valt; ten tweede, onderhoud de foutcode-mappingtabel continu, en zorg bij de aansluiting van een nieuwe leverancier dat de foutcode-mapping als eerste compleet is.
Auteur: Sun Haoran
Publicatiedatum: 9 november 2026