Çok Modelli API Ağ Geçidinde İstemi Önbellek Kontrolü: Kararlı Önekler, Kiracı Yalıtımı ve Önbellek İsabeti Analizi

Hızlı önbelleğe alma işleminin israf edilmesi kolaydır. Bir ekibin yeniden kullanılabilir olması gereken 40.000 jetonlu bir sistem istemi, araç şeması, politika bloğu, depo haritası veya aracı belleği olabilir, daha sonra istemin üst kısmına yanlışlıkla bir zaman damgası, istek kimliği, kullanıcı adı, alma snippet'i veya rastgele araç sıralaması koyabilir. Sağlayıcı farklı bir önek görüyor, önbellek gözden kaçıyor, gecikme artıyor ve fatura kafa karıştırıcı görünüyor.

Tek sağlayıcılı bir uygulamada bunu uygulama şablonunun içinde düzeltebilirsiniz. Çok modelli bir ağ geçidinde sorun daha büyüktür: her sağlayıcı farklı önbellek kontrollerini, belirteç eşiklerini, yaşam süresi davranışını, kullanım alanlarını ve faturalandırma semantiğini ortaya çıkarır. Ağ geçidinin, önbellek açısından güvenli istemleri bir araya getirmek, önbellek davranışını ölçmek, kiracıları izole etmek ve maliyeti ilişkilendirmek için taşınabilir bir kontrol düzlemi modeline ihtiyacı vardır.

Bu makalede bir referans mimarisi açıklanmaktadır. Bu bir müşteri vaka çalışması değildir ve karşılaştırma sonuçları iddia etmez. Aşağıdaki gerçekler sağlayıcı belgelerinden ve kamuya açık araştırmalardan alınmıştır; tasarım önerileri ağ geçidi düzeyinde işletim kılavuzudur.

Başarısızlık modu: önbellek bozma istemi derlemesi

İstem önbelleğe alma genellikle tekrarlanan bilgi istemi öneklerini ödüllendirir. Tam mekanizma sağlayıcıya göre değişir, ancak pratik çıkarım tutarlıdır: İstemin ön tarafı değişirse yeniden kullanım olumsuz etkilenir.

Yaygın önbellek kırıcılar şunları içerir:

• İstek başına meta veriler üstte: zaman damgaları, izleme kimlikleri, oturum kimlikleri, dağıtım kimlikleri veya oluşturulan istek etiketleri.
• Önekteki kullanıcıya özel veriler: yeniden kullanılabilir politika veya araç bloklarından önce yerleştirilen adlar, hesap özellikleri, izinler veya özel tercihler.
• Kararsız araç serileştirmesi: değişen boşluklarla veya oluşturulan kimliklerle, belirli olmayan bir sırayla yayılan araç şemaları.
• Snippet'ler çok erken alınıyor: RAG bağlamı, kararlı sistem talimatlarından veya paylaşılan depo bağlamından önce eklendi.
• Şablon kayması: Sürüm oluşturma veya önbellek teşhisi olmadan sık sık yayınlanan küçük ifade değişiklikleri.

Bir ağ geçidi, kararsız bir öneki sihirli bir şekilde önbelleğe alınabilir hale getiremez, ancak hızlı bir derleme sözleşmesi uygulayabilir ve önbellek kayıplarını görünür hale getirebilir.

Etrafında tasarım yapılacak gerçekleri sağlayın

Ayrıntılar önemlidir çünkü bir ağ geçidinin, sağlayıcıların aynı olduğunu iddia etmeden davranışı normalleştirmesi gerekir.

• OpenAI: OpenAI, önceden hesaplanan en uzun bilgi istemi öneki için bilgi istemini önbelleğe almayı belgeledi. 1.024 jetonla başlar, 128 jetonluk artışlarla artar ve kullanım alanlarında önbelleğe alınmış jeton sayımlarını ortaya çıkarır. OpenAI ayrıca istem önbelleklerinin genellikle 5-10 dakika işlem yapılmaması durumunda temizlendiğini ve her zaman önbelleğin son kullanımından sonraki bir saat içinde kaldırıldığını belirtir.
• Anthropic: Anthropic istemi önbelleğe alma cache_control ile istenebilir. Belgeleri, araçlar, sistem içeriği ve mesajlar gibi bilgi istemi bileşenleri üzerinden önbellek kontrolü ile işaretlenmiş bloğa kadar önbellek eşleştirmesini açıklar. Anthropic, 5 dakikalık bir süre ve ek ücret karşılığında 1 saatlik bir seçenek içeren geçici bir önbelleği belgeliyor.
• Gemini: Google Gemini bağlamı önbelleğe alma, total_cached_tokens gibi kullanım meta verileri aracılığıyla önbellek isabetli jeton sayımlarını ortaya çıkarır ve belgeleri, modele göre minimum giriş jetonu sayılarını listeler.
• Veri kontrolü etkisi: OpenAI'nin API veri kontrolü belgeleri, genişletilmiş bilgi istemi önbelleğe almanın, anahtar/değer tensörlerinin GPU yerel depolamasında uygulama durumu olarak depolanmasını gerektirdiğini belirtir. Sağlayıcılar izolasyon garantilerini sürdürseler bile ağ geçitleri, önbellek davranışını paylaşılan bir uygulama veri deposu olarak değil, hassas altyapı olarak ele almalıdır.
• Araştırma sinyali: Kamuya açık araştırmalar, ağ geçidi tarzı mimarilerin, sağlayıcı düzeyinde önbellek izolasyonu varsayımlarını atlayan istemi önbelleğe alma güvenlik açıklarına neden olup olamayacağını inceledi. Bu, belirli bir ağ geçidinin savunmasız olduğunu kanıtlamaz ancak muhafazakar kiracı izolasyon tasarımını destekler.

Öneri: önbellek kontrolünü, tekrarlanan istemlerin kazara yan etkisi olarak değil, açık politikalara sahip bir ağ geçidi özelliği olarak uygulayın.

Üç bölgeli hızlı montaj sözleşmesi

En önemli tasarım kararı, istek sağlayıcı bağdaştırıcısına ulaşmadan önce kararlı ve geçici içeriği ayırmaktır.

Bölge 1: kararlı önek

Kararlı önek, aynı uygulama, model rotası ve bilgi istemi şablonu sürümü için birçok istekte aynı kalması beklenen içeriktir. Örnekler şunları içerir:

• temel sistem talimatları;
• güvenlik ve politika engellemeleri;
• araç şemaları;
• statik ürün dokümantasyonu;
• kodlama aracıları için depo haritaları;
• sabit çıktı biçimi talimatları.

Bu bölge deterministik olmalıdır. Ağ geçidinin onu sürümlendirilmiş şablonlardan, standartlaştırılmış JSON'den ve kararlı sıralama kurallarından oluşturması gerekir. Bir araç kaydı varsa, araçları sabit araç kimliğine göre sıralayın. JSON şeması dahil edilmişse bunları deterministik anahtar sıralamasıyla ve zaman damgası oluşturulmadan serileştirin.

Bölge 2: yarı kararlı kiracı veya çalışma alanı bağlamı

Yarı kararlı bölge, bireysel isteklere göre daha az sıklıkta değişir ancak küresel olarak paylaşılmaz. Örnekler şunları içerir:

• kiracıya özel politika geçersiz kılmaları;
• çalışma alanı düzeyindeki araç izin verilenler listeleri;
• müşteriye özel terminoloji;
• ekip kodlama kuralları;
• uzun ömürlü proje bağlamı.

Bu bölgenin kapsamı bir kiracı, çalışma alanı veya uygulama sınırına göre belirlenmelidir. Hâlâ önbelleğe alınabilir ancak ağ geçidi hiçbir zaman başka bir kiracının onu güvenli bir şekilde yeniden kullanabileceğini varsaymamalıdır.

Bölge 3: geçici son ek

Geçici son ek, istek başına kısımdır:

• kullanıcı mesajı;
• bu sorgu için snippet'ler alındı;
• gerçekten gerekliyse geçerli zaman damgası;
• istek kimliği ve izleme meta verileri (eğer istemde yer alıyorsa);
• kısa süreli konuşmalar değişir;
• çalışma zamanı aracı sonuçları.

Uygulama tasarımından kaynaklanan önbellek kayıplarının çoğu, geçici son ek verilerinin yanlışlıkla öneke yerleştirilmesi nedeniyle meydana gelir. Ağ geçidi tarafındaki bir oluşturucunun bunu zorlaştırması gerekir.

Uygulama modeli: kararlı önek oluşturucular

Pratik bir ağ geçidi uygulaması, her uygulamadan tek bir opak bilgi istemi dizesi kabul etmek yerine bir bilgi istemi derleme arayüzünü ortaya çıkarabilir.

{
  "template_id": "code-agent-v3",
  "tenant_id": "tenant_123",
  "route": "coding-long-context",
  "stable_prefix": {
    "system_policy_version": "2026-08-01",
    "toolset_version": "tools-v12",
    "repo_context_version": "repo-map-8491"
  },
  "semi_stable_context": {
    "workspace_policy_version": "workspace-44-v6"
  },
  "volatile_suffix": {
    "user_message": "Explain why this test fails...",
    "retrieval_context_ids": ["chunk_7", "chunk_19"],
    "trace_id": "not_inserted_into_prompt"
  }
}

Ağ geçidi daha sonra sağlayıcıya özel isteği işler. Bu, ağ geçidine kuralları uygulayabileceği bir yer sağlar:

• kararlı önek alanlarındaki zaman damgalarını reddet;
• araç şemalarını standartlaştırın;
• her bölgeye ayrı ayrı karma işlemi uygulayın;
• sağlayıcının desteklediği yere önbellek denetimleri ekleyin;
• geçici materyali daha sonra taşırken bilgi istemi anlambilimini koruyun;
• teşhis için şablon ve önek parmak izlerini kaydedin.

Yalnızca ham iletiler gönderen eski uygulamalar için, ağ geçidi hala bir tüy bırakmama modu sağlayabilir: ileti sırasını inceleyin, önek parmak izlerini hesaplayın ve başlangıçta istemi yeniden yazmaya gerek kalmadan olası önbellek kesicileri bildirin.

Sağlayıcı bağdaştırıcı katmanı: farklılıkları gizlemeden önbellek kullanımını normalleştirin

Çok modelli bir ağ geçidi, ilgisiz üç önbellek raporunu geliştiricilere sunmamalıdır. Ayrıca, sağlayıcıya özel ekonomiyi, faturaların açıklanması imkansız hale gelecek kadar agresif bir şekilde düzleştirmemelidir.

Şu gibi alanlarla normalleştirilmiş bir önbellek defteri oluşturun:

{
  "request_id": "req_abc",
  "tenant_id": "tenant_123",
  "app_id": "code-agent",
  "route": "coding-long-context",
  "provider": "provider_name",
  "model": "model_id",
  "template_id": "code-agent-v3",
  "stable_prefix_hash": "sha256:...",
  "semi_stable_hash": "sha256:...",
  "input_tokens_total": 58200,
  "input_tokens_uncached": 8200,
  "cache_write_tokens": 50000,
  "cache_read_tokens": 0,
  "output_tokens": 1300,
  "cache_ttl_class": "ephemeral_5m",
  "provider_cache_fields": {
    "raw_field_names": "stored_or_redacted_provider_usage"
  }
}

Bağdaştırıcı, sağlayıcı kullanımını normalleştirilmiş kategorilerle eşleştirir:

• Önbelleğe alınmamış giriş jetonları: jetonlar, önbellek okuma indirimi veya önbellek okuma hesaplaması olmadan işlenir.
• Önbellek yazma belirteçleri: Sağlayıcı bu ayrımı bildirdiğinde sağlayıcı tarafında bir önbellek girişi oluşturan veya yenileyen belirteçler.
• Önbellek okuma jetonları: önbellekten sunulan veya sağlayıcı kullanım meta verileri tarafından önbelleğe alınmış olarak sayılan jetonlar.
• Çıktı belirteçleri:, istem önbellek ekonomisinden ayrı kalması gereken, oluşturulan belirteçler.
• TTL seçeneği: sağlayıcının bir seçeneği sunduğu seçili önbellek süresi sınıfı.

Öneri: Ham sağlayıcı kullanımını, normalleştirilmiş alanlarla birlikte düzenlenmiş, şema sürümüne sahip bir formda saklayın. Normalleştirme, gösterge tabloları için kullanışlıdır; Sağlayıcının semantiği değiştiğinde mutabakat için ham alanlar gereklidir.

Önbellek gözlemlenebilirliği: kaçırılanları açıklayan kontrol panelleri

Faydalı bir önbellek kontrol paneli, önbelleğe alınan toplam jetonları göstermekten daha fazlasını yapar. Ekiplerin şu soruyu yanıtlamasına yardımcı olmalıdır: "Hangi iş yükü öneki bozuyor ve ne değişti?"

Önbellek metriklerini şuna göre izleyin:

• kiracı;
• çalışma alanı veya uygulama;
• model rota;
• sağlayıcı ve model;
• istem şablonu sürümü;
• kararlı önek karması;
• yarı kararlı bağlam karması;
• API anahtar veya hizmet hesabı (uygun olduğu yerde);
• özellikle önbellek TTL'lerinin birçok iş yükü için kısa olması nedeniyle zaman aralığı.

Yararlı türetilmiş metrikler şunları içerir:

• Önbellek okuma oranı: önbelleğe alınmış giriş jetonunun, önbelleğe almaya uygun toplam giriş jetonlarına bölümü.
• Önek kaybı: şablon sürümü başına saat başına farklı kararlı önek karmalarının sayısı.
• Şablon kayması: Şablonun yayınlanmasından sonra önbellek isabet değişiklikleri.
• Soğuk başlangıç maliyeti: Bir seri çekimdeki ilk istek için önbelleğe yazma veya önbelleğe alınmamış giriş harcaması.
• Rota karşılaştırması: Aynı mantıksal iş yükü için sağlayıcı rotalarındaki isabet oranları.

Hata ayıklama için ham istemleri varsayılan olarak saklamayın. Karma değerleri, bölge uzunluklarını, şablon kimliklerini, standartlaştırma uyarılarını ve düzeltilmiş farkları tercih edin. Bir ekibin daha derin hata ayıklamaya ihtiyacı varsa açık erişim kontrolleri ve saklama sınırları isteyin.

Kiracı izolasyon politikası: kiracılar arası yeniden kullanım için tasarım yapmayın

En güvenli ağ geçidi varsayımı basittir: önbelleğe alınabilir davranış kiracı kapsamına alınmalıdır. İki kiracı aynı genel politika bloğunu paylaşsa bile ağ geçidi, kiracılar arası önbelleğin yeniden kullanımından yararlanmak amacıyla trafiği kasıtlı olarak yönlendirmemeli veya şekillendirmemelidir.

İhtiyatlı bir politika şunları içerir:

• Kiracıyı tanıyan yönlendirme: kiracıyı, çalışma alanını ve uygulama sınırlarını kullanarak önbelleğe alınabilir trafiği yönlendirin.
• Paylaşılan sır içeren önek yok: hiçbir zaman kiracı sırlarını, kimlik bilgilerini, özel belgeleri veya kullanıcıya özel verileri yeniden kullanılabilir bir paylaşılan öneke yerleştirmeyin.
• Ayrı önek parmak izleri: oluşturulan metin aynı olsa bile ağ geçidi defterine kiracı kapsamı dahil edilerek parmak izlerini hesaplayın.
• Kuruluş düzeyindeki kontroller: yöneticilerin hassas iş yükleri için sağlayıcı önbellek özelliklerini devre dışı bırakmasına olanak tanır.
• Sağlayıcı izolasyonu yeniden satılacak bir ürün özelliği değildir: Sağlayıcı önbellek izolasyonunu, müşteriler arası önbellek havuzu oluşturma izni olarak değil, temel koruma olarak değerlendirin.

Tahmin: Uzun bağlam aracıları daha yaygın hale geldikçe, önbellek davranışı yalnızca maliyet incelemelerinin değil, güvenlik incelemelerinin de bir parçası haline gelecektir. Kiracı kapsamlı önbellek politikasını kanıtlayabilen ağ geçitlerinin yönetimi daha kolay olacaktır.

Faturalandırma ilişkilendirmesi: ayrı önbellek okumaları, yazmaları ve normal jetonlar

İstemi önbelleğe alma, tüm giriş jetonlarının tek bir sayı olarak gösterilmesi durumunda faturaların anlaşılmasını zorlaştırabilir. Faturalandırma defteri en az beş kategoriyi korumalıdır:

1. önbelleğe alınmamış giriş jetonları;
2. yazma belirteçlerini önbelleğe al;
3. okuma belirteçlerini önbelleğe al;
4. çıkış jetonları;
5. sağlayıcıya özel TTL veya önbellek kontrolü ücretleri.

Bir sağlayıcı önbelleğe alınan okumalara indirim yaptığında, başka bir sağlayıcı önbellek yazma işlemleri için farklı ücretlendirdiğinde ve diğeri daha uzun bir TTL seçeneğini sunduğunda bu durum önemlidir. Bir müşteri faturası, benzer toplam giriş jetonlarına sahip iki isteğin neden farklı maliyetlere sahip olduğunu açıklayabilmelidir.

Dahili ters ibraz için, önbellek etkilerini istekte bulunan kiracı ve uygulamayla ilişkilendirin. Önbellek okuma avantajını bir kiracıdan diğerine tahsis etmekten kaçının. Paylaşılan dahili platform ekibi, kararlı bilgi istemi şablonuna sahipse şablon düzeyindeki önbellek performansını kiracı faturalarından ayrı olarak raporlayın.

Önbellek doldurma kontrol listesi

Önbellek uygulamasını etkinleştirmeden önce, tüy bırakmayan bir kontrol listesi aracılığıyla bilgi istemi şablonlarını çalıştırın:

• Kararlı sistem talimatları geçici kullanıcı girişinden önce görünür.
• Araç şemaları, kararlı kimliğe veya ada göre sıralanır.
• JSON deterministik olarak serileştirilir.
• Kararlı önekte zaman damgası, rastgele kimlik, istek kimliği veya izleme kimliği görünmüyor.
• Paylaşılan yeniden kullanılabilir bloklarda kullanıcıya özel sırlar görünmez.
• RAG parçacıkları, kasıtlı olarak yapılmaması için bir neden olmadığı sürece, yeniden kullanılabilir politika ve araç bölümlerinin sonrasına yerleştirilir.
• İstem şablonlarının açık versiyonları vardır.
• Şablon sürümleri, önbellek isabet oranı değişiklikleriyle ilişkilendirilebilir.
• Sağlayıcı önbellek kontrolleri, dağınık uygulama mantığıyla değil, yalnızca bağdaştırıcı kodu aracılığıyla kullanılır.
• Ham istemi günlüğe kaydetme, varsayılan olarak devre dışıdır veya katı saklama ve erişim kurallarıyla korunur.

Kullanıma sunma planı

1. İstemleri değiştirmeden önce dikkate alın

Mevcut trafik için sağlayıcı kullanım alanlarını ve normalleştirilmiş önbellek ölçümlerini toplayarak başlayın. İlk N belirteci veya ağ geçidi tanımlı bilgi istemi bölgeleri için önek parmak izlerini hesaplayın. Amaç, yüksek ön ek kaybına sahip, yüksek hacimli, uzun bağlamlı rotalar bulmaktır.

2. İş yüklerini sınıflandırın

Trafiği kategoriler halinde gruplandırın: temsilci oturumları, kodlama asistanları, RAG, destek otomasyonu, belge analizi, toplu işler ve kısa sohbet. İstemi önbellek çalışması genellikle en fazla dikkati uzun bağlamlı ve tekrarlanan önek iş yüklerine verir. Sağlayıcı eşiklerinin altındaki kısa istemler fayda sağlamayabilir.

3. Sabit önek oluşturucuları tanıtın

Bir iş yükünü ham bilgi istemi yapısından bölge bazlı derlemeye taşıyın. Oluşturulan sağlayıcı isteğini anlamsal olarak eşdeğer tutun. Bu değişikliği model taşıma, aracın yeniden tasarlanması veya ana istemin yeniden yazılmasıyla birleştirmeyin; aksi takdirde metrik değişikliklerine neyin sebep olduğunu bilemezsiniz.

4. Kanarya bir rota

Bir kiracının veya dahili uygulamanın küçük bir kısmı için önbellek kontrollerini etkinleştirin. Önbellek okuma oranını, önek kaybını, ilk jetona kadar geçen süreyi, hata oranını ve maliyet kategorilerini karşılaştırın. Sağlayıcı faturaları ağ geçidi defterleriyle mutabakata varıncaya kadar tasarruf talebinde bulunmaktan kaçının.

5. Kademeli olarak uygulayın

Kanaryadan sonra tüy bırakmayan uyarıları politika kontrollerine dönüştürün. Örneğin, ilk başta dengesiz araç sırası konusunda uyarıda bulunun, ardından kararlı önekte geçici meta veriler içeren yeni şablon sürümlerini reddedin.

Ödüşümler

• Daha yüksek önbellek isabet oranı ve istem esnekliği: kararlı önekler yeniden kullanımı iyileştirir, ancak ekiplerin dinamik talimatları daha sonra taşıması veya şablonları yeniden tasarlaması gerekebilir.
• Sağlayıcıda yerel önbelleğe alma ve taşınabilirlik: Her sağlayıcının önbellek kontrollerini kullanmak ekonomiyi iyileştirebilir ancak eşikler, TTL'ler, alanlar ve fiyatlandırma semantiği farklılık gösterir.
• Gözlemlenebilirlik ve hassas günlük kaydı: istem farklılıkları, hata ayıklamada hata ayıklamaya yardımcı olur, ancak karmalar ve düzeltilmiş teşhisler daha güvenli varsayılanlardır.
• Kiracı izolasyonu ve maksimum yeniden kullanım: geniş kapsamlı yeniden kullanım çekici görünebilir, ancak kiracı kapsamlı davranışın daha güvenli ve açıklanması daha kolaydır.
• Daha uzun elde tutma ve maliyet ve politika karmaşıklığı: daha uzun TTL seçenekleri temsilci oturumlarına yardımcı olabilir, ancak farklı fiyatlandırma ve veri kontrolü hususlarına yol açabilir.

Harekete geçirilebilir sonuç

İstem önbelleğe almayı sağlayıcı onay kutusu olarak değil, ağ geçidi kontrol düzlemi sorunu olarak ele alın. Pratik model şu şekildedir: kararlı, yarı kararlı ve geçici bilgi istemi bölgelerini tanımlamak; onları deterministik olarak işlemek; sağlayıcıya özel önbellek kontrollerini tek bir arayüzün arkasına uyarlayın; önbellek kullanımını bir deftere normalleştirin; kiracıya, uygulamaya, rotaya ve şablon sürümüne göre önbellek isabet teşhislerini açığa çıkarın; ve kiracı kapsamlı varsayımları uygulayın.

İlk yararlı adım yeniden yazmak değildir. En uzun istemlerinize önbellek gözlemlenebilirliği ekleyin, önek kaybını tanımlayın ve en çok gözden kaçmaya neden olan şablonları lintleyin. Önbellek davranışını açıklayabildiğinizde, bunu güvenli bir şekilde optimize edebilirsiniz.

İlgili okuma

• faturalandırma defterinde önbelleğe duyarlı kategoriler oluşturun
• güvenli LLM gözlemlenebilirliği ile önbellek ölçümlerine katılın
• tut RAG iş yüklerinde kiracı kapsamlı alma bağlamı