Per la stessa funzione, il frontend deve richiamare quattro modelli: GPT-4o si occupa del fallback, DeepSeek esegue l'inferenza principale, Qwen gestisce i testi lunghi in cinese, Doubao si occupa delle risposte dell'assistenza clienti. Quattro SDK, quattro sistemi di autenticazione, quattro documentazioni. Nella prima settimana dal lancio, solo per allineare queste differenze abbiamo consumato due giornate-uomo.
Non è un'esagerazione. Abbiamo misurato che, dopo aver integrato quattro fornitori di modelli, la parte del codice applicativo relativa alle chiamate ai modelli è cresciuta di quasi tre volte. Ogni volta che si cambia modello, bisogna riscrivere il metodo di chiamata, la logica di parsing e la gestione degli errori. Ancora più fastidioso: ogni volta che un fornitore aggiorna l'SDK, bisogna ritestare tutto. Questo articolo ripercorre in modo completo gli ostacoli che abbiamo incontrato e la soluzione di gateway che abbiamo infine adottato, sperando di poter aiutare i team che si dibattono tra più modelli.
I. Autenticazione: quattro sistemi, quattro modi di scrivere il codice
L'autenticazione è il primo ostacolo che si incontra. La famiglia OpenAI usa Bearer Token: basta mettere Authorization: Bearer sk-xxx nell'header della richiesta. Qwen richiede la firma con AccessKey: ogni richiesta deve calcolare un HMAC usando AK/SK, concatenando anche timestamp e stringa casuale. Doubao usa AK/SK più timestamp, ma l'algoritmo di firma è diverso da quello di Qwen. DeepSeek, pur essendo compatibile con il formato OpenAI, ha il proprio base_url e la propria mappatura dei nomi dei modelli, e il metodo di inizializzazione non è del tutto identico a quello dell'SDK ufficiale.
Il risultato è che nel codice ci sono if-else ovunque. Un'istanza client per ogni fornitore, una configurazione per ogni istanza. La gestione delle chiavi è ancora più problematica: le Key dei quattro fornitori sono conservate in quattro posti diversi, e alla rotazione bisogna modificarle in quattro punti; se se ne dimentica uno, si verifica un incidente in produzione.
Successivamente abbiamo unificato a livello di layer di accesso: verso l'esterno esponiamo un'unica API Key, mentre internamente effettuiamo la traduzione dei protocolli. In pratica, il layer di accesso mantiene una tabella di routing dei fornitori, e ogni fornitore corrisponde al proprio adattatore di autenticazione. Il lato business riceve una sola Key, la richiesta arriva al layer di accesso, che in base al nome del modello individua il fornitore corrispondente e usa l'adattatore per completare firma e inoltro.
Successivamente abbiamo provato a unificare il base_url su token8341: con una sola Key si possono richiamare GPT-4o, Claude, Gemini, DeepSeek, Qwen, ERNIE, Doubao, è compatibile con l'SDK OpenAI e basta cambiare una riga di base_url per passare da uno all'altro. Il lavoro sporco dell'autenticazione viene bloccato fuori dal layer di accesso, e il codice applicativo è diventato molto più pulito. Anche la rotazione delle chiavi è diventata un'unica operazione, e il costo operativo è sceso direttamente di un ordine di grandezza.
II. Chunking dello streaming SSE: quattro formati, un solo rendering
Il chunking dello streaming SSE è il secondo ostacolo, e ancora più subdolo dell'autenticazione. Nel chunk di GPT-4o il delta.content può essere null, soprattutto nel primo e nell'ultimo chunk; se il frontend non fa il controllo di nullità e renderizza direttamente, compare un undefined. DeepSeek porta l'usage nell'ultimo chunk, e la struttura dei suoi campi usage non è del tutto identica a quella di OpenAI. Qwen distingue i tipi di evento in modo più fine, con tipi come add, finish, error e altri, e la struttura del payload è diversa per ogni tipo di evento. Anche il marcatore di fine di Doubao è diverso: usa un campo speciale finish_reason per indicare la fine dello stream.
Quando il frontend riceve quattro formati, la logica di rendering si spezza. All'inizio la nostra soluzione era di fare l'adattamento nel frontend, scrivendo quattro funzioni di parsing; il risultato è che ogni volta che si aggiungeva un nuovo modello bisognava modificare il frontend. Poi siamo passati alla normalizzazione a livello di gateway: unificare tutto nella struttura dei chunk di OpenAI, filtrare direttamente i delta vuoti, estrarre l'usage separatamente e accumularlo. Le regole concrete sono: tutte le risposte in streaming dei fornitori vengono convertite nel formato data: {"choices":[{"delta":{"content":"..."}}]}, la fine è contrassegnata uniformemente con data: [DONE], e l'usage viene restituito nell'ultimo chunk nel formato OpenAI.
Il frontend riconosce un solo formato e non deve preoccuparsi di chi ci sia dietro. Questa modifica ha ridotto il codice del frontend relativo ai modelli da oltre 400 righe a circa 80 righe, e quando si aggiungono nuovi modelli il frontend non richiede alcuna modifica.
III. Codici di errore: errori nascosti dentro HTTP 200
Il livello di confusione dei codici di errore ha superato le aspettative. Per lo stesso rate limiting, OpenAI restituisce 429 con rate_limit_exceeded, Qwen restituisce un errore business con un campo code, mentre Doubao infila direttamente l'errore nel body di un HTTP 200: il codice di stato è 200, ma nel body c'è un campo error. DeepSeek per la maggior parte delle volte è coerente con OpenAI, ma occasionalmente restituisce strutture di errore personalizzate.
Con il monitoraggio e gli alert non è possibile unificare nulla. Non puoi scrivere una regola che dica "se 429 allora alert", perché alcuni fornitori non restituiscono 429 quando fanno rate limiting. Non puoi nemmeno guardare solo il codice di stato HTTP, perché il 200 di Doubao potrebbe contenere un errore.
Nel layer di accesso abbiamo creato una tabella di mappatura che riconduce i codici di errore di ciascun fornitore a un sistema di errori interno: rate limiting, timeout, autenticazione fallita, moderazione dei contenuti, servizio non disponibile. La logica di mappatura concreta è: prima si guarda il codice di stato HTTP, poi si guarda l'error code nel body, e si decide combinando i due. Per esempio, se Doubao restituisce 200 ma nel body c'è un error, si mappa in base all'error code; se Qwen restituisce 400 con un codice business, si mappa in base al code. Le regole di alert si scrivono in un solo modo, e in fase di diagnosi si guarda poi il codice di errore originale.
Questa tabella di mappatura l'abbiamo mantenuta con circa 60 regole, coprendo gli scenari di errore comuni dei quattro fornitori. Dopo il lancio, l'accuratezza degli alert è passata da circa il 60% a oltre il 95%, e i falsi positivi sono praticamente scomparsi.
IV. Statistiche di utilizzo: quattro numeri che non tornano
I criteri di conteggio dell'utilizzo sono la cosa più facile da trascurare, ma al momento della riconciliazione finanziaria saltano fuori di sicuro. Il conteggio dei token di GPT-4o include il system prompt, i token con cache hit di DeepSeek sono fatturati separatamente, Qwen calcola input e output separatamente, e l'unità di fatturazione di Doubao è ancora diversa. Al momento della riconciliazione finanziaria i quattro numeri non tornano, ed è impossibile calcolare chiaramente il costo effettivo di ciascun modello.
La soluzione di aggregazione è registrare a livello di gateway, per ogni richiesta, model, input_tokens, output_tokens, cache_hit, salvando tutto a database con un criterio di fatturazione unificato per token. In pratica: il gateway, quando inoltra la richiesta, registra l'ora di inizio e di fine, estrae il campo usage di ciascun fornitore dalla risposta e lo converte in un formato standard. Per i fornitori con unità di fatturazione diverse, si effettua una conversione a livello di gateway, riconducendo tutto al costo per token.
In questo modo, indipendentemente da chi ci sia sotto, i costi possono essere allineati e visualizzati nella stessa tabella. Successivamente abbiamo anche creato una dashboard dei costi basata su questa tabella, consultabile per modello, per linea di business e per giorno. Una volta abbiamo scoperto che il costo di una linea di business era improvvisamente aumentato del 40%; indagando, la strategia di routing stava mandando un gran numero di richieste a GPT-4o, e dopo aver aggiustato il routing il costo è calato immediatamente. Senza un'aggregazione unificata dell'utilizzo, un problema del genere non sarebbe mai stato individuato.
V. L'architettura a quattro livelli del gateway dei modelli
Di quali livelli dovrebbe occuparsi il gateway dei modelli? La mia suddivisione è in quattro livelli.
Primo livello: traduzione dei protocolli. Unificare i formati di richiesta e risposta di ciascun fornitore in un'interfaccia compatibile con OpenAI. Questo è l'unico livello con cui il codice applicativo viene direttamente a contatto: si occupa di tradurre le richieste nel formato OpenAI standard nei formati di ciascun fornitore, e di ritradurre indietro le risposte.
Secondo livello: routing. Scegliere il modello in base al tipo di task, per esempio i testi lunghi in cinese vanno su Qwen, il codice su DeepSeek, il fallback su GPT-4o. La strategia di routing può essere configurabile, supportando diverse dimensioni come tipo di task, priorità, costo. Abbiamo anche aggiunto una logica di degradazione: se il modello principale va in timeout o in rate limiting, si passa automaticamente al modello di fallback.
Terzo livello: aggregazione dell'utilizzo. Fatturazione e quote unificate. Il consumo di token, i cache hit e i tempi di risposta di ogni richiesta vengono registrati in questo livello, che fornisce all'esterno un'interfaccia unificata di interrogazione dell'utilizzo.
Quarto livello: osservabilità. Log, tracing distribuito, convergenza dei codici di errore. Ogni richiesta ha un trace_id, tracciabile lungo tutta la catena dall'ingresso all'uscita. I codici di errore vengono mappati in modo unificato in questo livello, e anche le regole di alert vengono configurate solo qui.
Il codice applicativo richiama solo l'interfaccia del primo livello; i tre livelli successivi sono per esso trasparenti. Il vantaggio di questo approccio è che cambiare modello non richiede modifiche al codice applicativo, aggiungere un modello non richiede modifiche al codice applicativo, e nemmeno regolare la strategia di routing richiede modifiche al codice applicativo. Il team di business deve solo preoccuparsi di "devo richiamare un modello"; al resto pensa il gateway.
VI. Avvertenze per evitare gli ostacoli
Non importate direttamente gli SDK di ciascun fornitore nel codice applicativo. Una volta che il fornitore aggiorna l'interfaccia o dovete cambiare modello, la superficie delle modifiche diventa enorme. Abbiamo visto team che richiamavano direttamente gli SDK nel codice applicativo, e poi, al momento di cambiare modello, hanno modificato più di 30 file e hanno testato per una settimana prima di andare in produzione.
Dedicare due giorni in più al layer di accesso fa risparmiare due settimane dopo. Questo rapporto costo-beneficio nel nostro caso è stato verificato sul campo: dopo il lancio del gateway, per aggiungere un nuovo modello basta aggiungere un adattatore a livello di gateway, il codice applicativo non richiede modifiche, e l'integrazione e i test si completano in mezza giornata.
Altri due piccoli consigli: primo, fare l'aggregazione dell'utilizzo il prima possibile, non aspettate la riconciliazione finanziaria per scoprire che non si riesce a calcolare nulla; secondo, la tabella di mappatura dei codici di errore va mantenuta con continuità, e quando si integra un nuovo fornitore la prima cosa da fare è completare la mappatura dei codici di errore.
Autore: Sun Haoran
Data di pubblicazione: 9 novembre 2026