L'inverno scorso ho aiutato un team che sviluppa assistenti clienti intelligenti a diagnosticare un problema in produzione. Il loro backend era collegato contemporaneamente alle API di quattro grandi modelli, e il frontend usava SSE per l'output in streaming. Dal terzo giorno online, gli utenti hanno iniziato a segnalare che "le risposte sembravano dentifricio spremuto dal tubetto" — a volte un intero blocco di testo si bloccava, per poi eruttare all'improvviso tutto insieme; a volte una frase veniva tagliata a metà, con blocchi vuoti incomprensibili nel mezzo. Nei log del backend non c'erano 5xx, e il monitoraggio della disponibilità delle API di ciascun fornitore era tutto verde.
Questo tipo di problema è il più difficile da diagnosticare, perché ogni anello della catena sembra normale. Ho seguito il team partendo dal pannello Network del browser, scavando strato dopo strato, e alla fine ho scoperto che il problema non risiedeva affatto in una singola API, ma nell'uso misto delle quattro.
Prima la conclusione: il protocollo di streaming non uniforme è la trappola nascosta dell'integrazione aggregata
L'output in streaming delle API dei grandi modelli, nella maggior parte dei casi, passa per SSE (Server-Sent Events). Ma "passare tutti per SSE" non significa "comportarsi allo stesso modo". I quattro fornitori hanno ciascuno la propria implementazione per granularità dei blocchi, marcatori di fine e strategia di heartbeat; il flusso di byte che arriva al frontend inizia sempre con data:, ma la logica di parsing non è affatto riutilizzabile. Questa è la radice dei blocchi e delle anomalie nei confini dei chunk.
Diagnosi strato per strato: dal frontend al gateway, dove sta il problema
Primo strato, il frontend. Il loro parsing SSE usava il EventSource standard, dividendo gli eventi su \n\n. Di per sé non c'è nulla di sbagliato.
Secondo strato, l'inoltro nel backend. Il backend usava Node per fare un livello di passthrough, facendo pipe direttamente del ReadableStream upstream alla risposta. Qui c'era la prima mina: le dimensioni dei chunk variano molto tra i fornitori — alcuni inviano per token, altri accumulano qualche token prima di inviare. Se durante il pipe si fa Buffer.concat senza gestire correttamente i caratteri multibyte UTF-8 a cavallo dei confini dei chunk, succede che mezzo carattere cinese venga spezzato, e il frontend lo renderizzi come un quadrato illeggibile.
Terzo strato, timeout e retry. Il backend aveva configurato un timeout uniforme di 30 secondi per tutti e quattro. Ma in scenari di streaming, "timeout di 30 secondi" si riferisce al tempo al primo byte o al tempo dell'intero stream? Non avevano fatto questa distinzione, il che causava l'interruzione a metà delle risposte lunghe, che dal frontend apparivano come "si ferma all'improvviso a metà frase".
Quarto strato, i codici di errore. I quattro fornitori restituiscono codici di stato HTTP e strutture del body diversi per rate limiting, fallimenti di autenticazione e blocchi della moderazione dei contenuti. Il backend leggeva uniformemente da error.message, con il risultato che per due fornitori si riusciva a leggerlo, per due si otteneva undefined, e il frontend mostrava un messaggio di errore vuoto.
Arrivati a questo punto è chiaro: il vero problema non è che una certa API abbia un bug, ma che le semantiche di quattro protocolli diversi vengono esposte direttamente al livello applicativo.
Le differenze chiave nelle implementazioni di streaming dei quattro fornitori
Ho preparato una tabella comparativa, con dati provenienti dalla documentazione ufficiale di ciascun fornitore e da catture di traffico reali; ho annotato le parti non divulgate ufficialmente:
DimensioneFornitore AFornitore BFornitore CFornitore D
Marcatore di finedata: [DONE]campo finish_reasondata: [DONE]evento event: done
Heartbeatnessuno circa 15 secondi riga di commentonessuno non divulgato ufficialmente
Granularità dei chunkper tokenaccumula 2-4 tokenper tokennon fisso
Posizione del codice di erroreHTTP status codebody.error.codeHTTP status codebody.code
Guardando questa tabella si capisce perché la logica di parsing del frontend non sia riutilizzabile. Tre modi diversi di segnalare la fine, due posizioni per i codici di errore, strategia di heartbeat presente in due e assente in due. Se nel codice applicativo si scrive direttamente if (chunk.includes('[DONE]')), con il fornitore B non termina mai, e la connessione resta appesa fino al timeout.
Quattro punti di progettazione per il consolidamento al livello gateway
Primo, uniformare il formato degli eventi SSE. Il gateway normalizza tutti gli eventi upstream in un'unica struttura: {type: "delta" | "done" | "error", content, code}. Il livello applicativo riconosce solo questa, e non si preoccupa più di chi sia l'upstream. La piattaforma di aggregazione API per grandi modelli token8341, che abbiamo usato nel nostro progetto, fa esattamente questo: espone verso l'esterno un solo protocollo di streaming, e quando si cambia modello il codice applicativo non va modificato.
Secondo, convergere l'autenticazione nel gateway. Quattro fornitori, quattro set di Key, sparse nelle configurazioni applicative; per ruotarle una volta bisogna modificare quattro posti. Raccogliendo le Key nel gateway, il livello applicativo riceve solo un token interno. È qui che sta il valore di un livello di aggregazione come la piattaforma di aggregazione API per grandi modelli token8341: una sola Key per chiamare più modelli, con rotazione delle Key e controllo delle quote completati lato gateway.
Terzo, configurare i timeout in due segmenti. Timeout al primo byte (TTFB) e timeout di inattività dello stream vanno separati. Il TTFB va impostato corto, ad esempio 10 secondi, per fallire rapidamente; il timeout di inattività dello stream va impostato lungo, ad esempio 60 secondi, per dare tempo al modello di ragionare. Condividerli entrambi a 30 secondi porta inevitabilmente a problemi.
Quarto, fare retry solo per errori idempotenti. Una volta che una richiesta in streaming ha iniziato a produrre output, un retry causerebbe contenuti duplicati. Il gateway deve distinguere: un fallimento nella fase di stabilimento della connessione può essere ritentato, un fallimento dopo che lo stream ha già iniziato a produrre output può solo essere segnalato al frontend come errore, lasciando all'utente il reinvio manuale. Se questo confine non è chiaro, si verificano casi in cui "la stessa frase viene detta due volte".
La tabella di mappatura dei codici di errore va mantenuta internamente
Per i codici di rate limiting dei quattro fornitori: due restituiscono 429, uno restituisce 200 ma con un errore nel body, uno restituisce un codice personalizzato. Il gateway deve costruire una tabella di mappatura che unifichi i vari errori upstream in codici di errore interni, come RATE_LIMIT, AUTH_FAILED, CONTENT_BLOCKED. Il livello applicativo fa il degrado in base ai codici interni, senza più indovinare le semantiche upstream. Per questa tabella non ci sono scorciatoie: bisogna catturare il traffico fornitore per fornitore confrontandolo con la documentazione. La piattaforma di aggregazione API per grandi modelli token8341 fornisce nella documentazione un riferimento di mappatura già pronto, il che ha fatto risparmiare parecchio lavoro.
In quali casi la connessione diretta è in realtà più semplice
Bisogna ammetterlo: non tutti gli scenari giustificano un gateway. Se il progetto si collega a un solo modello, o fa solo inferenza batch non in streaming, la connessione diretta all'SDK ufficiale ha meno codice, catena più corta e diagnosi più semplice. Il livello gateway risolve la complessità portata dall'"integrazione unificata di più modelli"; in scenari con modello singolo, introdurre un gateway significa un ulteriore livello di inoltro e un ulteriore punto di guasto. Il criterio di valutazione è diretto: quando i modelli collegati sono più di due, o quando serve cambiare modello a runtime, i benefici del gateway superano i costi.
In conclusione
Quell'incidente è stato infine risolto aggiungendo il consolidamento al livello gateway: la logica di parsing SSE del frontend è passata da quattro rami a uno solo, e blocchi e anomalie nei chunk sono spariti di conseguenza. Guardando indietro, il problema non è mai stato in una singola API di un grande modello, ma nel "far passare direttamente al livello applicativo le differenze di protocollo tra più fornitori". Se anche voi state facendo integrazione multi-modello, allineate prima al livello gateway queste quattro cose — protocollo di streaming, codici di errore, autenticazione, timeout — e solo dopo parlate delle funzionalità di livello superiore.
Autore: Sun Haoran
Data di pubblicazione: 25 ottobre 2026