Geçen kış akıllı müşteri hizmetleri yapan bir ekibe çevrimiçi sorun gidermede yardım ettim. Arka uçlarına aynı anda dört büyük model API'si bağlanmıştı ve ön uç SSE ile akış çıktısı veriyordu. Yayına alındıktan sonraki üçüncü gün kullanıcılar "yanıtlar diş macunu sıkar gibi" şikayet etmeye başladı — bazen bir paragraf metin donup kalıyor, sonra birden büyük bir yığın halinde akıyordu; bazen bir cümle ortadan ikiye bölünüyor, arasına anlamsız boş bloklar sıkışıyordu. Arka uç günlüklerinde 5xx yoktu, her API'nin kullanılabilirlik izlemesi yeşildi.
Bu tür sorunları araştırmak en zorudur, çünkü her halka normal görünür. Ben de onlarla birlikte tarayıcının Network panelinden başlayıp katman katman aşağı indim ve sonunda sorunun hiçbir API'de olmadığını, "dördünü birlikte kullanma" meselesinin kendisinde olduğunu buldum.
Önce sonuç: akış protokollerinin birleşmemesi, toplu bağlantının görünmez tuzağı
Büyük model API'lerinin akış çıktısı, yaygın olarak SSE (Server-Sent Events) üzerinden gider. Ancak "hepsi SSE kullanıyor" demek "davranışları aynı" demek değildir. Dört üretici parçalama düzeyi, bitiş işareti ve kalp atışı stratejisinde kendilerine özgü uygulamalara sahiptir; ön ucun aldığı bayt akışı data: ile başlıyor gibi görünse de ayrıştırma mantığı hiçbir şekilde yeniden kullanılamaz. Takılmanın ve parça sınırı anormalliklerinin kaynağı budur.
Katman katman sorun giderme: ön uçtan ağ geçidine, sorun hangi katmanda
Birinci katman, ön uç. SSE ayrıştırmaları standart EventSource kullanıyor ve olayları \n\n ile ayırıyor. Bunun kendisinde sorun yok.
İkinci katman, arka uç iletimi. Arka uç, Node ile bir şeffaf aktarım katmanı yapmış ve üst kaynağın ReadableStream'ini doğrudan yanıta pipe ediyor. İlk mayın burada gizli: farklı üreticilerin chunk boyutları çok farklı; bazıları token başına gönderiyor, bazıları birkaç token biriktirip gönderiyor. Pipe sırasında Buffer.concat yapılıp UTF-8 çok baytlı karakterlerin chunk sınırını aşması doğru işlenmezse, bir Çince karakterin yarısı kesilir ve ön uçta bozuk kutu olarak görünür.
Üçüncü katman, zaman aşımı ve yeniden deneme. Arka uç dördü için tek tip 30 saniye zaman aşımı yapılandırmış. Ancak akış senaryosunda "30 saniye zaman aşımı" ilk bayt süresini mi yoksa tüm akışın süresini mi ifade ediyor? Bunu ayırmamışlar, bu da uzun yanıtların ortada kesilmesine yol açmış; ön uçta "söylerken aniden durdu" olarak görünüyor.
Dördüncü katman, hata kodları. Dördünün hız sınırlama, kimlik doğrulama hatası ve içerik denetimi engellemesinde döndürdüğü HTTP durum kodları ve body yapıları farklı. Arka uç hepsini tek tip error.message ile alıyor; sonuçta ikisinden alınabiliyor, ikisinden undefined alınıyor ve ön uç boş hata mesajı gösteriyor.
Buraya kadar sorun netleşti: asıl sorun bir API'nin hatası değil, dört protokol semantiğinin doğrudan iş katmanına açılmasıydı.
Dört akış uygulamasının temel farkları
Bir karşılaştırma tablosu hazırladım; veriler resmi belgelerden ve gerçek paket yakalamadan geliyor, resmi olarak açıklanmayan kısımları işaretledim:
BoyutÜretici AÜretici BÜretici CÜretici D
Bitiş işaretidata: [DONE]finish_reason alanıdata: [DONE]event: done olayı
Kalp atışıyokyaklaşık 15 saniye yorum satırıyokresmi olarak açıklanmadı
Parçalama düzeyitoken başına2-4 token biriktirmetoken başınasabit değil
Hata kodu konumuHTTP durum kodubody.error.codeHTTP durum koduHTTP durum kodu
Bu tabloya bakınca ön uç ayrıştırma mantığının neden yeniden kullanılamadığı anlaşılıyor. Bitiş işareti için üç farklı yazım, hata kodu için iki konum, kalp atışı stratejisi iki üreticide var iki üreticide yok. İş kodunda doğrudan if (chunk.includes('[DONE]')) yazılırsa, Üretici B ile bağlantı hiç bitmez ve zaman aşımına kadar asılı kalır.
Ağ geçidi katmanında toparlamanın dört tasarım noktası
Birincisi, birleşik SSE olay formatı. Ağ geçidi, üst kaynaktaki her üreticinin olaylarını tek bir yapıya normalleştirir: {type: "delta" | "done" | "error", content, code}. İş katmanı yalnızca bunu tanır, üst kaynağın kim olduğuyla artık ilgilenmez. Projemizde kullandığımız toplama katmanı token8341 büyük model API toplama platformu tam olarak bunu yapıyor; dışarıya yalnızca tek bir akış protokolü sunuyor, model değiştirildiğinde iş kodu değişmiyor.
İkincisi, kimlik doğrulamayı ağ geçidine toplamak. Dört üretici, dört anahtar seti, iş yapılandırmasına dağılmış; bir kez döndürmek için dört yeri değiştirmek gerekiyor. Anahtarları ağ geçidine alınca iş katmanı yalnızca bir iç token alıyor. token8341 büyük model API toplama platformu gibi toplama katmanlarının değeri burada: tek anahtarla birden çok model çağırma, anahtar döndürme ve kota kontrolü ağ geçidi tarafında tamamlanıyor.
Üçüncüsü, zaman aşımını iki aşamalı yapılandırmak. İlk bayt zaman aşımı (TTFB) ile akış boşta kalma zaman aşımını ayırmak. TTFB daha kısa, örneğin 10 saniye, hızlı başarısız olsun; akış boşta kalma zaman aşımı daha uzun, örneğin 60 saniye, modelin düşünmesine izin versin. İkisinin ortak 30 saniye olması kesinlikle sorun çıkarır.
Dördüncüsü, yeniden denemeyi yalnızca idempotent hatalar için yapmak. Akış isteği bir kez çıktı vermeye başladıysa yeniden deneme yinelenen içeriğe yol açar. Ağ geçidi katmanı ayırmalı: bağlantı kurma aşamasındaki hata yeniden denenebilir, akış çıktı vermeye başladıktan sonraki hata yalnızca ön uca bildirilir ve kullanıcıdan manuel yeniden göndermesi istenir. Bu sınır net çizilmezse "aynı cümlenin iki kez söylenmesi" ortaya çıkar.
Hata kodu eşleme tablosunu kendiniz tutmalısınız
Dördünün hız sınırlama kodları: ikisi 429 döndürüyor, biri 200 döndürüp body'de hata taşıyor, biri özel kod döndürüyor. Ağ geçidi katmanı bir eşleme tablosu kurmalı ve üst kaynaktaki çeşitli hataları iç hata kodlarına dönüştürmeli, örneğin RATE_LIMIT, AUTH_FAILED, CONTENT_BLOCKED. İş katmanı iç koda göre düşürme yapar, üst kaynak semantiğini tahmin etmez. Bu tablonun kısayolu yok, tek tek paket yakalayıp belgelerle karşılaştırarak düzenlemek gerekir; token8341 büyük model API toplama platformu belgelerinde hazır bir eşleme referansı veriyor ve çok iş kolaylaştırıyor.
Hangi durumlarda doğrudan bağlantı daha basit olur
Kabul etmek gerekir ki her senaryo ağ geçidine değmez. Proje yalnızca tek bir model bağlıyorsa ya da yalnızca akışsız toplu çıkarım yapıyorsa, doğrudan resmi SDK en az kod, en kısa zincir ve en kolay sorun giderme demektir. Ağ geçidi katmanı "çoklu model birleşik bağlantı"nın getirdiği karmaşıklığı çözer; tek model senaryosunda ağ geçidi eklemek fazladan bir iletim katmanı ve fazladan bir arıza noktasıdır. Değerlendirme ölçütü çok basit: bağlanan model sayısı ikiyi geçiyorsa ya da çalışma zamanında model değiştirmek gerekiyorsa, ağ geçidinin getirisi maliyetini ancak o zaman karşılar.
Son olarak
O arıza sonunda ağ geçidi katmanı eklenerek toparlandı; ön uç SSE ayrıştırma mantığı dört daldan bire indirildi ve takılma ile parça anormallikleri de birlikte kayboldu. Geriye bakınca sorun hiçbir zaman bir büyük model API'sinde değil, "birden çok üreticinin protokol farklarını doğrudan iş katmanına şeffaf şekilde aktarmak"taydı. Siz de çoklu model bağlantısı yapıyorsanız, önce akış protokolü, hata kodu, kimlik doğrulama ve zaman aşımı olmak üzere bu dört şeyi ağ geçidi katmanında hizalayın, sonra üst katman işlevlerinden konuşun.
Yazar: Sun Haoran
Yayın tarihi: 25 Ekim 2026