AI API Ağ Geçitleri için Dahili Model Takma Adları: Ürün Ekiplerini Donduramayan Pin Sağlayıcı Sürümleri

Sağlayıcı tarafından kontrol edilen değişikliği kasıtlı olarak kabul etmediğiniz sürece, üretim uygulamalarının doğrudan latest, sonnet, flash gibi sağlayıcı kolaylık adlarına veya benzer takma adlara bağlı olmasına izin vermeyin. Çok modelli bir ortamda bu adlar hareketli işaretçilerdir. Deneyler için uygundurlar ancak üretim daraldığı için risklidirler.

Daha güvenli yöntem, chat-default, support-fast, agent-tools-safe, code-review-premium veya batch-extraction-cheap gibi ağ geçidine ait dahili takma adların açığa çıkarılmasıdır. Ürün ekipleri kararlı isimleri çağırır. Ağ geçidi yöneticileri, bu adları sabitlenmiş yukarı akış model sürümlerine çözümler, değerlendirme yoluyla değişiklikleri teşvik eder ve her uygulama ekibini, her sağlayıcının model sürümü oluşturma planını izlemeye zorlamadan geri alma işlemini gerçekleştirir.

Okuyucu sorunu: Sağlayıcı takma adları ürün sözleşmeleri değildir

Uygulama ekipleri, hatırlanması ve koda yapıştırılması kolay olduğundan genellikle sağlayıcı düzeyinde takma adlar seçer. Bu kolaylık, yukarı akış sağlayıcısı takma adın çözümlendiği şeyi değiştirdiğinde bir üretim riski haline gelir. Model takma adı değişikliği, yanıt ifadesinden daha fazlasını değiştirebilir. Gecikmeyi, belirteç hesaplamasını, çıktı formatı güvenilirliğini, araç çağrısı davranışını, bağlam penceresi varsayımlarını, güvenlik reddini, çok modlu desteği veya maliyeti değiştirebilir.

Gerçek: büyük model sağlayıcıları, sabit model kimlikleri ile takma adlar veya sürüm aşamaları arasında ayrım yapar. OpenAI belgeleri, tutarlı davranış gerektiren uygulamalar için sabitlenmiş model sürümlerini ve değerlendirmelerini önerir. Anthropic tarihli belgeler Claude model kimliklerini sabitlenmiş sürümler olarak sunarken, kullanışlı takma adlar daha yeni anlık görüntülere çözümlenebilir. Google Gemini belgeleri kararlı, önizleme, en son ve deneysel model sürümlerini birbirinden ayırıyor ve sürüm notları latest takma adın hedef sürümleri değiştirdiğini gösteriyor.

Öneri: Sağlayıcı tarafından yönetilen takma adları, kararlı uygulama arayüzleri olarak değil, harici bağımlılıklar olarak değerlendirin. Bir uygulamanın tekrarlanabilir davranışa ihtiyacı varsa, ağ geçidinin dahili bir takma adı açıkça sabitlenmiş bir yukarı akış model kimliğine çözümlemesi ve bu çözümü her istekte kaydetmesi gerekir.

Mimari: ürün adlarını yukarı akış model kimliklerinden ayırın

Dahili model takma adı, ağ geçidine ait, yetenek ve davranış sözleşmesine sahip bir addır. Bu sadece bir kısayol dizesi değil. Uygulama ekipleri ile temel sağlayıcı kataloğu arasındaki ürüne yönelik arayüzdür.

Yararlı bir takma ad kaydı en azından şu alanları içermelidir:

• Dahili takma ad: örneğin, support-fast veya rag-cheap-long-context.
• Sağlayıcı: OpenAI, Anthropic, Google, Azure'da barındırılan model, şirket içinde barındırılan model veya başka bir yukarı akış.
• Çözülmüş yukarı akış model kimliği: Sevkiyat sırasında kullanılan tam sağlayıcı modeli tanımlayıcısı.
• Hedef türü: pinned veya provider_managed_alias.
• Yayın aşaması: kararlı, önizleme, en son, deneysel, kullanımdan kaldırılmış veya dahili eşdeğeri.
• Bağlam penceresi: maksimum girdi ve çıktı bütçesi varsayımları.
• Modaliteler: metin, resim, ses, video, yerleştirmeler veya desteklenen diğer modlar.
• Araç desteği: modelin araç çağrısını, işlev çağrısını, paralel çağrıları veya aracı özelliklerini destekleyip desteklemediği.
• Yapılandırılmış çıkış desteği: JSON modu, şema desteği, kısıtlı kod çözme veya adaptör gerektiren doğrulama.
• Fiyatlandırma katmanı: Kesin genel fiyatlandırma olmayabilir, ancak ucuz, standart, premium veya özel gibi normalleştirilmiş bir ağ geçidi katmanı.
• Veri saklama uygunluğu: hangi kiracı hassasiyet sınıflarının hedefi kullanabileceği.
• Yedek uyumluluk: kabul edilebilir yedek takma adlar veya geri dönüşe izin verilmediğine dair açık ifade.
• Bilinen sınırlamalar: modele özgü tuhaflıklar, desteklenmeyen parametreler, gecikme uyarıları veya reddetme davranışı notları.

Bu katalog, geliştiricilerin sağlayıcı sürüm adları yerine iş yükü amacına göre seçim yapmasına olanak tanır. Bir destek ekibi support-fast numarasını isteyebilmektedir. Bir kod platformu code-review-high-accuracy kodunu isteyebilmelidir. Bir RAG sistemi rag-cheap-long-context kodunu isteyebilmelidir. Ağ geçidi ekibi temel sağlayıcı hedefini değiştirdiğinde bile bu adların sabit kalması gerekir.

İş yükü sözleşmelerine göre takma adlar tasarlayın

Kötü takma adlar uygulama ayrıntılarını sızdırıyor. İyi takma adlar, modelin yapması beklenen işi ifade eder.

Zayıf takma adlar

• openai-latest
• claude-sonnet
• gemini-flash
• cheap-model
• new-model-test

Bu adlar ya ekipleri bir sağlayıcıya bağlar, yukarı yönde hareket eden bir takma adı gizler ya da açık bir yetenek sözleşmesi içermez.

Daha güçlü takma adlar

• chat-default: genel üretim sohbeti iş yükü.
• support-fast: orta düzeyde muhakeme ihtiyaçları olan, düşük gecikmeli müşteri desteği yanıtları.
• agent-tools-safe: çağrı şeklinin ve güvenlik davranışının önemli olduğu araç çağırma iş yükleri.
• code-review-premium: Daha büyük bir maliyet bütçesiyle daha yüksek doğrulukta kod analizi.
• batch-extraction-cheap: birim maliyetin önemli olduğu, gecikmeye dayanıklı yapılandırılmış çıkarma.
• rag-long-context: geniş bilgi istemi pencerelerine sahip, almayla zenginleştirilmiş oluşturma.

Takma ad mükemmellik vaat etmemelidir. Amaçlanan ödünleşimi belirtmelidir: hız, doğruluk, bağlam uzunluğu, araç güvenilirliği, güvenlik kısıtlamaları veya maliyet.

Geçici düzenlemeleri değil tanıtım durumlarını kullanın

chat-default'nin arkasındaki hedefi değiştirmek bir sürümdür. Sıradan bir yapılandırma ayarı gibi ele alınmamalıdır.

Pratik bir yaşam döngüsünün altı durumu vardır:

• Taslak: Katalogda önerilen bir takma ad veya önerilen hedef değişikliği mevcut, ancak bunu hiçbir trafik kullanamıyor.
• Değerlendirme: hedef, temsili istemlere, şemalara, araç çağrılarına, gecikme bütçelerine ve maliyet beklentilerine göre test edilir.
• Canary: küçük bir kiracı, ekip, anahtar veya trafik yüzdesi yeni hedefi kullanabilir.
• Etkin: takma ad, amaçlanan üretim kapsamı için yeni hedefe çözümlenir.
• Kullanımdan kaldırıldı: hedef veya takma ad geçici olarak kullanılabilir durumda kalacak ancak yeni entegrasyonlar almamalı.
• Geri alma hedefi: önceki iyi bilinen hedef, hızlı geri dönüş için korunur.

Uygulamanın önemli detayı, ağ geçidinin takma ad geçmişini tutmasıdır. Önceki eşlemeyi, etkinleştirme zamanını, aktörü, nedeni ve değerlendirme özetini korumadan bir hedeften diğerine support-fast yazmayın.

Promosyondan önce bir uyumluluk sözleşmesi tanımlayın

Dahili takma adın bir uyumluluk sözleşmesine ihtiyacı vardır. Bu, yöneticilere yukarı yöndeki hedef değiştiğinde neyin doğru kalması gerektiğini söyleyen kontrol listesidir.

Öneri: bu sözleşmeyi takma ad tanımının yanında saklayın. Bir model sözleşmeyi karşılayamıyorsa, mevcut modeli sessizce değiştirmek yerine yeni bir takma ad oluşturun. Örneğin, daha yeni bir model daha ucuzsa ancak araç çağrıları için daha az güvenilirse, chat-default için uygun olabilir ancak agent-tools-safe.

Her takma ad güncellemesi için değerlendirilen tanıtımı çalıştırın

Değerlendirmenin operasyonel açıdan faydalı olması için akademik açıdan karmaşık olması gerekmez. Tekrarlanabilir olması ve takma ad sözleşmesine bağlı olması gerekir.

Pratik bir ağ geçidi tanıtım test paketi şunları içerebilir:

• Altın istemler: iş yükü sınıfı için temsili örnekler.
• Düşmanca veya uç istemler: geçmişte retlere, halüsinasyonlara, hatalı biçimlendirilmiş JSON veya aşırı araç çağrılarına neden olan durumlar.
• Şema testleri: doğrulama ve onarım oranı takibi ile gerekli yapılandırılmış çıktı şekilleri.
• Araç çağrısı fikstürleri: beklenen araç adları, bağımsız değişken şekilleri ve yan etki kontrolleri.
• Uzun bağlam testleri: beklenen üretim bağlamı boyutlarına yakın istemlerde bulunur.
• Maliyet simülasyonları: normalleştirilmiş jeton muhasebesi ve temsili trafik karışımı kullanılarak tahmini harcama etkisi.
• Gecikme kontrolleri: mümkün olduğunca üretimde kullanılanla aynı bölgede ve rota sınıfında ölçülmüştür.

İstem saklama kurallarının en aza indirilmesi gerektiğinde, düzeltilmiş istemleri, sentetik sabitleri veya müşteri tarafından onaylanmış test senaryolarını kullanın. Önemli olan hassas üretim konuşmalarını sonsuza kadar saklamak değil. Önemli olan, varsayılan takma ad taşınmadan önce önemli bir davranış değişikliğini tespit etmek için yeterli temsili kapsama sahip olmaktır.

Gerçek: sağlayıcı belgeleri, davranışın model anlık görüntüleri arasında farklılık gösterebileceğini kabul etmektedir. Öneri: Davranış önemli olduğunda değerlendirmeleri, kullanıcıların gerileme rapor etmesinden sonra takma ad hedefini değiştirmeden önce çalıştırın.

Kiracı ve ekip modeli profillerini uygulayın

Genel takma ad eşlemesi genellikle çok açıklayıcıdır. Farklı kiracıların ve ekiplerin farklı risk toleransı vardır.

Bir ağ geçidi, kiracı, çalışma alanı, ekip, ortam veya API anahtarına göre varsayılan takma ad çözümlemesini geçersiz kılan model profillerini destekleyebilir. Örneğin:

• Düzenlemelere tabi bir finans kiracısı, onaylanmış veri saklama uygunluğuna sahip muhafazakar sabitlenmiş bir modele çözümlenmiş chat-default'ı kullanır.
• Dahili bir araştırma ekibi, üretim tanıtımından önce önizleme davranışını test etmek için chat-default-next kodunu kullanır.
• Destek otomasyon ekibi normal bildirimler için support-fast, üst kademelere iletmeler için ise support-premium kullanır.
• Toplu işleme iş yükü, gecikmeye toleranslı bir rota ve daha sıkı harcama kontrolleri ile batch-extraction-cheap kullanır.

Yönlendirme kararı şu şekilde görünebilir:

{
  "tenant_id": "tenant_finance_123",
  "requested_model": "chat-default",
  "profile": "regulated-production",
  "resolved_provider": "provider_a",
  "resolved_model_id": "provider-a-model-2026-07-15",
  "target_type": "pinned",
  "alias_version": 42
}

Profiller karmaşıklık kattığı için sınırlara ihtiyaç duyar. Her ekibin inceleme yapmadan keyfi takma adlar oluşturmasına izin vermekten kaçının. İyi bir bölünme şu şekildedir: ürün ekipleri takma adlar talep eder ve temsili değerlendirme vakaları sunar; ağ geçidi yöneticileri katalog girişlerini, promosyonu, geri almayı ve sağlayıcı hedefi değişikliklerini onaylar.

Hem istenen takma adı hem de çözümlenen modeli günlüğe kaydedin

Ağ geçidi yalnızca chat-default sayısını günlüğe kaydederse, olay müdahalesi gerçekte ne olduğuna yanıt veremez. Yalnızca sağlayıcı model kimliğini günlüğe kaydederse ürün ekipleri kullanımı kendi terimleriyle anlayamaz. Her ikisini de günlüğe kaydet.

Her istek kaydı şunları içermelidir:

• İstenen dahili takma ad.
• Çözümlenmiş sağlayıcı.
• Çözülmüş yukarı akış model kimliği.
• Hedefin sabitlenip sabitlenmediği veya sağlayıcı tarafından yönetilip yönetilmediği.
• Takma ad sürümü veya katalog revizyonu.
• Kiracı, ekip, anahtar ve ortam tanımlayıcıları.
• Talep sırasındaki promosyon durumu.
• Kullanılıyorsa geri dönüş yolu.
• Jeton kullanımı, normalleştirilmiş maliyet, gecikme, durum ve hata sınıfı.

Bu, analiz, faturalandırma, hata ayıklama ve denetim için gereklidir. Bir kiracı Salı günü maliyetlerin neden değiştiğini sorduğunda cevap "model muhtemelen güncellendi" olmamalıdır. Ağ geçidi, o sırada kullanılan takma ad revizyonunu ve yukarı akış hedefini tam olarak göstermelidir.

Sağlayıcı tarafından yönetilen takma adları varsayılan üretim yollarının dışında tutun

Sağlayıcı tarafından yönetilen bir takma ad kullanmak için geçerli nedenler vardır. Deneyler için operasyonel ek yükü azaltabilir. Geliştirilmiş modellere erken erişim sağlayabilir. Keşif geliştirmeyi basitleştirebilir. Hata, bu riski varsayılan bir üretim takma adının arkasına saklamaktır.

Açık bir politika şudur:

• Üretim varsayılan takma adları, sabitlenmiş yukarı akış model kimliklerine çözümlenir.
• Önizleme veya deneysel hedefler chat-default-next, support-fast-preview veya research-latest gibi açık adlar kullanır.
• Sağlayıcı tarafından yönetilen takma adlar; katalog, analiz ve faturalandırma görünümlerinde etiketlenir.
• Kiracılar hızlı hareket eden hedefleri seçmelidir.
• Sağlayıcı takma ad çözümlemesi, değişikliklerin görülebilmesi için periyodik olarak örneklenmeli ve kaydedilmelidir.

Tahmin: Model yayın döngüleri hızlı kaldıkça, daha fazla kuruluş sağlayıcı model adlarını doğrudan uygulama ekiplerine göstermeyi bırakacak ve yönetilen dahili model profillerine yönelecek. Bunun nedeni geliştiricilerin modelleri seçememesi değil. Bunun nedeni, üretim sistemlerinin istikrarlı sözleşmelere, denetim yollarına ve geri alma işlemlerine ihtiyaç duymasıdır.

Etkinleştirmeden önce geri alma işlemini hazırlayın

Geri alma, takma ad etkinleştirilmeden önce tasarlanmalıdır. İyi bir geri alma planı şu sorulara yanıt verir:

• Geri alma hedefi hangi önceki hedeftir?
• Önceki hedef hâlâ sağlayıcıda mevcut mu?
• Kimlik bilgileri, ücret sınırları, bölgeler ve faturalandırma kuralları hâlâ geçerli mi?
• Önbelleğe alınmış istemler, araç çağrıları ve yapılandırılmış çıktı doğrulayıcıları çalışmaya devam edecek mi?
• Geri alma global olarak, kiracı başına, ekip başına veya API anahtarı başına uygulanabilir mi?
• Acil durum geri alma işlemini kim onaylayabilir?
• Etkilenen ekiplere nasıl bilgi verilecek?

Yalnızca bir kiracı veya iş yükü etkilendiğinde, cam kırma işlemini geçersiz kılma kullanışlıdır. chat-default çoğu ekip için başarıyla ilerliyorsa ancak düzenlenen kiracılardan biri kabul edilemez anlamsal sapma görüyorsa, sorun araştırılırken o kiracıyı önceki takma ad sürümünde dondurun. Bu, bir müşterinin gerilemesinin herkesin geri dönüşü ya da herkesin sorunu haline gelmesini önler.

Takma adlar değiştiğinde ekiplere bildirimde bulun

Sessiz model değişiklikleri kafa karışıklığı yaratır. Bildirimin ağır olması gerekmez ancak tutarlı olması gerekir.

Bir takma ad canary'ye girdiğinde, etkin hale geldiğinde, kullanımdan kaldırıldığında veya geri alındığında hafif bir model değişikliği özeti yayınlayın. Dahil et:

• Takma ad.
• Eski ve yeni yukarı akış model kimlikleri.
• Etkinlik süresi.
• Değişikliğin nedeni.
• Maliyet, gecikme, bağlam, araçlar veya çıktı biçimi üzerinde beklenen etki.
• Etkilenen kiracılar veya profiller.
• Geri alma hedefi.
• Varsa, kontrol paneli bağlantısı veya olay referansı.

Kontrol panelleri denetim ve geçmiş açısından faydalıdır. Sohbet veya Telegram tarzı bildirimler, zamanında operasyonel farkındalık açısından faydalıdır. Amaç, her geliştiricinin sağlayıcı değişiklik günlüklerini günlük olarak okumasına gerek kalmadan takma ad hareketini görünür kılmaktır.

Açıkça kabul edilecek ödünler

Bu model kontrolü iyileştirir ancak ücretsiz değildir.

• Sabitlenmiş sürümler tekrarlanabilirliği artırır ancak daha ucuz, daha hızlı veya daha yetenekli sağlayıcı sürümlerine erişimi geciktirebilir.
• Sağlayıcı tarafından yönetilen takma adlar bakımı azaltır ancak değişiklik kontrolünü ağ geçidinin dışına taşır ve regresyonların ilişkilendirilmesini zorlaştırır.
• Dahili takma adlar geliştirici deneyimini basitleştirir, ancak ekiplerin geçmiş sağlayıcı kullanımını incelemeye devam edebilmesi için güçlü günlüklere ihtiyaç duyarlar.
• Kiracı başına geçersiz kılmalar hassas müşterileri destekler ancak katalog karmaşıklığını ve test yükünü artırır.
• Değerlendirilen tanıtım riski azaltır, ancak ekipler temsili vakalara katkıda bulunmadığı sürece değerlendirme paketleri alana özel değişiklikleri kaçırabilir.
• Önizleme erişimi, ilk benimseyenlere yardımcı olur, ancak önizleme ve deneysel modeller, varsayılan üretim takma adlarından ayrı tutulmalıdır.

Uygulama kontrol listesi

1. Geçerli model dizelerinin envanterini çıkarın. Uygulamalarda, ortam değişkenlerinde, SDK sarmalayıcılarda, kuyruklarda ve iş akışı araçlarında sabit kodlanmış sağlayıcı model kimliklerini ve takma adlarını bulun.
2. Bir ağ geçidi modeli kataloğu oluşturun. Dahili takma ad, sağlayıcı, çözümlenen model kimliği, hedef türü, özellikler, fiyatlandırma katmanı, yayın aşaması, veri saklama uygunluğu ve sınırlamalar ekleyin.
3. İş yükü takma adlarını tanımlayın. Küçük bir kümeyle başlayın: chat-default, support-fast, agent-tools-safe, code-review-premium ve batch-extraction-cheap.
4. Üretim varsayılanlarını sabitleyin. Kiracı açıkça hareketli bir hedefi seçmediği sürece, varsayılan takma adları sabit yukarı akış model kimliklerine çözümleyin.
5. Takma ad yaşam döngüsü durumları ekleyin. Taslak, değerlendirme, canary, etkin, kullanımdan kaldırılmış ve geri alma hedef durumlarını zorunlu kılın.
6. Uyumluluk sözleşmeleri yazın. İstem biçimini, akışı, araçları, yapılandırılmış çıktıyı, güvenlik davranışını, belirteç muhasebesini, bağlam penceresini, gecikmeyi ve geri dönüşü kapsar.
7. Değerlendirme kapıları oluşturun. Her iş yükü sınıfı için düzenlenmiş, sentetik veya onaylanmış fikstürler kullanın.
8. Profilleri dikkatli bir şekilde destekleyin. Kiracı veya ekip geçersiz kılmalarına izin verin, ancak onayı merkezi tutun.
9. Her isteğin çözünürlüğünü günlüğe kaydedin. İstenen takma adı, çözümlenen sağlayıcı model kimliğini, takma ad sürümünü, hedef türünü ve promosyon durumunu saklayın.
10. Önce geri alma işlemini hazırlayın. Önceki iyi olduğu bilinen hedefi mevcut tutun ve geri alma işleminin hâlâ işe yarayıp yaramadığını test edin.
11. Değişiklik olduğunda bildir. Takma adlar canary'ye girdiğinde, etkinleştiğinde veya geri alındığında bir özet gönderin.

Harekete geçirilebilir sonuç

Dahili model takma adları, her uygulamayı sağlayıcı sürüm oluşturma projesine dönüştürmeden ürün ekiplerinin hızlı hareket etmesine olanak tanır. Önemli olan, takma adın takma ad değil, yönetilen bir sözleşme haline getirilmesidir.

Üretimde kolaylık sağlayan sağlayıcı adlarını kararlı ağ geçidi takma adlarıyla değiştirerek başlayın. Yukarı akış hedefini her üretim takma adının arkasına sabitleyin. Her çözünürlüğü kaydedin. Değişiklikleri değerlendirmeler, kanaryalar ve açık geri alma hedefleri aracılığıyla teşvik edin. Hızlı hareket eden modeller isteyen ekipler için önizleme takma adlarına izin verin ancak bunları varsayılan üretim yollarından ayrı tutun.

Pratik kural basittir: Uygulama ekipleri iş yükü amacını seçmelidir; ağ geçidi yöneticileri yukarı yöndeki model hareketini kontrol etmelidir.

İlgili okuma

• modelin kullanımdan kaldırılması ve geri alma runbook
• OpenAI uyumlu ağ geçidi geçişi için uyumluluk sözleşmesi
• ağ geçidi gözlemlenebilirliği ve istek düzeyi model izleme