Ana içeriğe geç

Neden her LLM çağrısının önüne bir gateway koyuyorum?

· 7 dakikalık okuma

Bir model sağlayıcısını çağıran ilk servis bunu doğrudan yapar ve bunda bir sorun yok. Dördüncü serviste her biri kendi provider key'ini tutuyor, her birinin kendi retry politikası var ve fatura gelene kadar şirketin modellere ne harcadığını kimse söyleyemiyor.

Gateway, her model çağrısının yolunda duran tek bir servis. Akıllı bir şey değil. Key'leri tutuyor, parayı sayıyor, limitleri uyguluyor, ne olduğunu kaydediyor ve bir sağlayıcı çöktüğünde trafiği başka yere taşıyor. Bunların çoğu sıradan tesisat. Bir kısmı, iki kez ödemeden retry yapmak, bu yazının büyük bölümünü hak edecek kadar ince.

Genel yapı​

Gateway, client'ların zaten bildiği bir API'yi konuşuyor. OpenAI tarzı chat completions şekli yaygın tercih, çünkü çoğu SDK ve framework onunla konuşabiliyor; bir servisi gateway'in arkasına almak yeniden yazmak değil, base URL ve key değiştirmek oluyor. Servisler gateway'e kendi key'leriyle authenticate oluyor. Sağlayıcılara yalnızca gateway authenticate oluyor.

Provider key'leri tek bir yerde​

Her servis bir provider key'i tuttuğunda, onu rotate etmek her servise dokunmak demek; herhangi birinden sızan key de hesabın tamamının sızması demek.

Gateway'le provider key'leri tek bir secret store'da duruyor ve tek bir servis tarafından okunuyor. Her takım, gateway dışında hiçbir değeri olmayan ve tek başına iptal edilebilen bir gateway key'i alıyor. O key bir isteği hangi takımın yaptığını da söylüyor; bu yazıdaki diğer her şey o cevaba dayanıyor.

Harcamayı gerçekten durduran bütçeler​

Aylık fatura bir rapor, bir kontrol değil. Can yakan arıza bir kesinti değil; bütün hafta sonu modeli çağırmaya devam eden bir batch job'daki döngü. Hard cap'li takım bazında bir bütçe, bunu ay sonundaki bir sürpriz yerine cumartesi sabahı reddedilen bir isteğe çeviriyor.

Akla gelen ilk implementasyon yanlış: harcamayı oku, cap'le karşılaştır, çağır, maliyeti ekle. Aynı anda gelen iki istek aynı bakiyeyi okuyor, ikisi de geçiyor, ikisi de harcıyor. Agent'lar ve batch job'larla bu normal durum.

İşe yarayan yöntem, çağrıdan önce rezerve edip sonra mutabakat yapmak. Sağlayıcıyı çağırmadan önce en kötü durumu tahmin edin: prompt token'ları artı max_tokens, modelin fiyatıyla. O tutarı tek bir koşullu statement'la rezerve edin:

UPDATE team_budgets
SET reserved_micros = reserved_micros + @estimate
WHERE team_id = @team
AND spent_micros + reserved_micros + @estimate <= cap_micros
RETURNING cap_micros - spent_micros - reserved_micros AS remaining_micros;

Satır dönmemesi takımın bütçesinin bittiği anlamına geliyor ve istek daha hiç para harcanmadan reddediliyor. Cevap geldiğinde rezervasyonu serbest bırakın ve sağlayıcının usage rakamlarından gelen gerçek maliyeti ekleyin. Serileştirmeyi veritabanı yapıyor; oku-sonra-yaz penceresi yok.

Parayı küçük birimlerin tam sayı adedi olarak tutun, burada para biriminin milyonda biri; asla floating-point olarak değil. Sınırda "aşağı yukarı" doğru olan bir cap, cap değildir.

Rate limit'ler: sizinkiler ve onlarınki​

İki türü var. Sağlayıcılar hesabınızı limitliyor ve her takım bu limiti paylaşıyor; bir takımın backfill'i başka bir takımın kullanıcıya dönük özelliğini aç bırakabiliyor. Bir de takım başına kendi limitlerinizi istiyorsunuz; paylaşım bir kaza değil, bir karar olsun diye.

Gateway key'i başına bir token bucket çoğu durumu karşılıyor. Yalnızca istekleri değil, token'ları da limitleyin: sağlayıcılar token sayıyor ve tek bir büyük doküman yüz küçük soru kadar tutabiliyor.

Loglama ve prompt meselesi​

Gateway her istek için kimin gönderdiğini, hangi model ve sağlayıcının cevap verdiğini, input ve output token'larını, maliyeti, gecikmeyi, durumu ve çağırana da döndürdüğü bir request id'yi kaydediyor. Bunlar bir tabloda olunca takım ve model bazında harcama bir proje değil, bir sorgu oluyor; aynı veri OpenTelemetry trace'leri olarak da yavaş bir kullanıcı isteğini onu yavaşlatan model çağrısına bağlıyor.

Zor kısım prompt'lar. Onları loglamak kötü bir cevabı debug etmeyi çok kolaylaştırıyor. Ama bir prompt, kullanıcıların yazdığı ve retrieval'ın getirdiği her şeyi içeriyor: kişisel veriler, müşteri dosyaları, bazen yanlışlıkla yapıştırılmış credential'lar. Prompt'ları loglamak bunların hepsinin ikinci bir kopyasını oluşturuyor, genellikle orijinalinden daha geniş erişimli ve daha uzun saklama süreli bir sistemde.

Benim varsayılanlarım: metadata her zaman, prompt metni kapalı. Bir takımın debug için prompt'lara ihtiyacı varsa, redact edilmiş olarak, kısa saklama süresiyle ve yalnızca o takımın erişebileceği şekilde saklayın. Bu bir trade-off ve onu yapmanın doğru yeri, her serviste ayrı ayrı değil, bir kez gateway'de.

Sağlayıcılar arasında failover​

Çağıranlar fast ya da default gibi bir alias istiyor, gateway de onu sıralı bir backend listesine eşliyor. İlki çöktüğünde ya da rate limit'e takıldığında sıradaki isteğe cevap veriyor; sürekli hata veren bir sağlayıcıya trafik göndermeyi de bir circuit breaker durduruyor.

Failover'ın ne olduğu konusunda dürüst olun: farklı bir model farklı cevap verir ve farklı structured output özelliklerini destekleyebilir. Bir alias'ın arkasındaki backend'ler, aynı request body'yi kabul eden herhangi bir şey değil, kendi prompt'larınızla test ettikleriniz olmalı. En kırılgan durum structured extraction; Bir LLM'den yapılandırılmış veri almak yazısına bakın.

İnce kısım: asla iki kez ödememek​

Bir sağlayıcının ürettiği completion, gateway'iniz cevabı alsa da almasa da faturalanmıştır. O noktadan sonra yapılan bir retry ya da failover aynı cevap için tekrar ödüyor. Yani her retry'dan önceki soru "başarısız oldu mu?" değil, "çalışmadığını biliyor muyum?".

Birincisi, retry yapma hakkı yalnızca tek bir katmanda. Client SDK'sı, bir HTTP resilience handler'ı ve gateway'in kendi failover'ı ayrı ayrı retry yapabilir ve üst üste binince çarpılırlar: iki katmanın her birinde üç deneme, tek bir istek için dokuz çağrıya kadar çıkar. Retry'ların sahibi gateway; altındaki transport'taki retry'lar kapalı, client'lardan da kendilerininkini kapalı tutmaları isteniyor.

İkincisi, yalnızca ilk isteğin çalışmadığını kanıtlayan hatalarda failover yapın:

using System.Net;

// Yalnızca hata, sağlayıcının hiç completion üretmediğini gösteriyorsa true;
// o zaman sıradaki sağlayıcıyı denemek faturalanacak ikinci bir completion üretemez.
static bool SafeToFailOver(HttpResponseMessage? response, Exception? error) =>
(response, error) switch
{
({ StatusCode: HttpStatusCode.TooManyRequests }, _) => true,
({ StatusCode: HttpStatusCode.Unauthorized or HttpStatusCode.Forbidden }, _) => true,
(null, HttpRequestException
{
HttpRequestError: HttpRequestError.NameResolutionError
or HttpRequestError.ConnectionError
or HttpRequestError.SecureConnectionError
}) => true,
_ => false, // 5xx, timeout'lar, yarıda kesilen stream'ler: çalışmış olabilir
};

429, sağlayıcının isteği reddettiğini söylüyor; 401 ya da 403 de isteğin daha hiçbir iş başlamadan reddedildiğini, genellikle o sağlayıcının key'i yanlış olduğu için. Başarısız bir DNS çözümlemesi, bağlantı ya da TLS handshake'i isteğin hiç ulaşmadığı anlamına geliyor. Bunlar kanıt. 400 de bir kanıt, ama failover işe yaramaz: isteğin kendisi yanlış ve sıradaki sağlayıcı da onu reddeder. 500 ise bir şeyin bozulduğunu söylüyor, ne zaman bozulduğunu değil. Herhangi bir şeyi false kolundan çıkarmadan önce sağlayıcınızın kendi status code'ları için ne dokümante ettiğine bakın.

En önemli belirsiz durum timeout'lar. Gateway beklemekten vazgeçtiğinde sağlayıcı hâlâ üretiyor olabilir ve ürettiği her şeyi faturalar. O noktada failover yapmak iki kez ödemek ve bunun nadir olmasını ummak demek. Benim varsayılanım belirsiz hatalarda bir hata döndürmek ve rezervasyonu harcanmış saymak, çünkü harcanmadığını kanıtlayamıyorum. Bir alias için gecikme maliyetten daha önemliyse orada timeout'ta bilerek failover yapın ve fatura ile sizin rakamlarınız tutsun diye iki denemeyi de ledger'a yazın.

Streaming pencereyi daha da daraltıyor: ilk chunk çağırana ulaştıktan sonra sağlayıcı değiştirmek, her birinden yarım bir cevap demek. Failover ya ilk byte'tan önce olur ya da hiç olmaz.

Üçüncüsü, client'ın kendi retry'larını güvenli hale getirin. Gateway'i beklerken timeout'a düşen bir client isteği tekrar gönderecek. Her mantıksal istekte bir idempotency key olursa gateway sonucu o key altında saklıyor: ilki hâlâ çalışırken gelen tekrar onu bekliyor, bittikten sonra gelen tekrar saklanan cevabı alıyor ve hiçbir şey yeniden çalışmıyor. Sağlayıcının sizin yerinize tekrarları ayıklayacağını varsaymayın.

Benim yaptığım​

Ben de bir tane yaptım: Tollgate. README'si yukarıdaki parçaları anlatıyor: OpenAI uyumlu bir endpoint, tek bir koşullu statement'la rezerve edilip sonra mutabakatı yapılan bütçeler, transport retry'ları kapalıyken retry'ların sahibi olan bir failover akışı ve saklanmadan önce redact edilen prompt'lar. Failover testi de gateway'in kendi sayımına güvenmiyor: testteki mock sağlayıcılara gerçekte kaç completion ürettiklerini soruyor.

Ne zaman uğraşmamalı?​

Gateway, sahip olduğunuz her AI özelliğinin kritik yolunda bir hop daha. O çökerse hepsi çöker; bu yüzden birden fazla instance'a ihtiyacı var. Tek servis ve tek takımla, bir secret store'daki key ve sağlayıcıdan gelen bir bütçe alarmı yeterli olabilir.

İkinci bir takım, ikinci bir sağlayıcı ya da harcama hakkında kimsenin cevaplayamadığı bir soru ortaya çıktığı an, gateway'in olmasını tercih ederim. Sıkıcı tutun: iletmeli, saymalı ve reddetmeli; prompt yeniden yazmamalı, iş mantığı taşımamalı.