AI API Ağ Geçitleri için Model Kullanımdan Kaldırma Runbook'u: Envanter, Test Etme, Taşıma ve Kullanım Ömrü Sonundan Önce Geri Alma

Sabit kodlanmış model kimlikleri sessiz üretim bağımlılıklarıdır. Bir sağlayıcı bir uç noktayı yeniden adlandırana, tarihli bir anlık görüntüyü kullanımdan kaldırana, bir takma adı değiştirene, bir önizleme modelini kaldırana veya API düzeyinde bir uyumsuzluk getirene kadar çalışırlar. Arıza nadiren tek bir temiz kesinti olarak ortaya çıkar. Şema hataları, daha yüksek gecikme süresi, beklenmedik retler, farklı araç çağrısı argümanları, değişen maliyetler veya aceleye getirilmiş bir geçişten sonra iş yükleri farklı davranan kiracılardan gelen müşteri biletleri olarak ortaya çıkar.

Pratik çözüm, model kimliklerini uygulama kodundaki statik dizeler gibi değil, yönetilen bağımlılıklar gibi ele almaktır. AI API ağ geçidinde bu, tekrarlanabilir bir model kullanımdan kaldırma runbook'u oluşturmak anlamına gelir: envanteri çıkarın, tespit edin, etkiyi değerlendirin, değiştirmeleri test edin, trafiği gölgeleyin, kademeli olarak kullanıma alın ve uyumluluk bozulduğunda hızla geri alın.

Gerçekler, öneriler ve tahminler

Gerçekler: Büyük model sağlayıcılar model katalogları, sürüm oluşturma kılavuzları, kullanımdan kaldırma bildirimleri ve geçiş kılavuzları yayınlar. Bu kaynaklar model kullanılabilirliğinin statik olmadığını göstermektedir. Bazı sağlayıcılar, uygun takma adları belirli model kimliklerinden ayırır ve bazı taşıma işlemleri, mevcut entegrasyonları bozan API düzeyindeki farklılıklar içerebilir.

Öneriler: Model yaşam döngüsü kontrolünü ağ geçidinin içine yerleştirin. Mantıksal model adlarını uygulama ekiplerine gösterin, sağlayıcı modeli kullanımını merkezi olarak izleyin, kullanımdan kaldırılan kaynakları izleyin ve üretim trafiğini değiştirmeden önce uyumluluk testleri yapın.

Tahminler: Model yaşam döngüsü işlemleri, yapay zeka platform mühendisliğinin normal bir parçası haline gelecek. Çok sağlayıcılı sistemler çalıştıran ekipler, modeller için bağımlılık tarzı kontrollere giderek daha fazla ihtiyaç duyacak: sürüm envanteri, değişiklik pencereleri, regresyon kontrolleri, geri alma planları ve müşteri bildirimleri.

Başarısızlık modu: uygulama koduna dağılmış sağlayıcı model kimlikleri

Ortak bir uygulama basit bir şekilde başlar:

{
  "model": "provider-model-preview-2025-06",
  "messages": [
    {"role": "user", "content": "Extract the invoice fields as JSON."}
  ]
}

Bu bir prototip için kolaydır ve üretim açısından risklidir. Model dizisi, arka uç hizmetleri, komut dosyaları, az kodlu iş akışları, dahili araçlar, müşteri entegrasyonları ve iş ortağı ürünleri genelinde çoğaltılabilir. Model kullanım ömrünün sonuna yaklaştığında hiçbir model sahibi tek başına temel soruları yanıtlayamaz:

• Hangi API tuşları hâlâ ona trafik gönderiyor?
• Hangi kiracılar JSON şemasına, araç çağrılarına, akışa, görüntüye, sese veya uzun bağlama bağlıdır?
• Günlük harcama ve gelir riski nedir?
• Hangi iş yükleri daha ucuz bir modeli tolere edebilir ve hangileri kalite incelemesi gerektirir?
• Ekip her uygulamayı yeniden dağıtmadan geri dönebilir mi?

Ağ geçidi, istekleri, anahtarları, kiracıları, sağlayıcıları, maliyetleri, gecikmeyi ve hataları zaten gördüğü için bunu çözecek doğal yerdir.

1. Adım: Bir model envanter tablosu oluşturun

Dayanıklı bir envanterle başlayın. Yalnızca sağlayıcı kontrol panellerine güvenmeyin çünkü kendi kiracınıza, anahtarınıza, faturalandırmanıza ve iş akışı bağlamınıza ihtiyacınız var.

Pratik bir model_inventory tablosu şunları içerebilir:

logical_model_name       support-fast
provider                 provider_a
provider_model_id         model-x-preview-2025-06
endpoint_type             chat_completions
alias_status              pinned_snapshot | provider_alias | internal_alias
status                    active | deprecated | blocked | retired
replacement_candidates    ["support-fast-v2", "support-balanced"]
first_seen_at             timestamp
last_seen_at              timestamp
deprecation_announced_at  timestamp
shutdown_at               timestamp
admin_override            text
owner_team                support-platform

Sonra bunu kullanım verileriyle birleştirin. Her sağlayıcı modeli ve mantıksal model için şunu izleyin:

• Etkin kiracılar ve API anahtar
• Günlük istekler ve günlük jetonlar
• Harcama, marj veya dahili maliyet tahsisi
• Yalnızca ortalamalar değil, gecikme yüzdelikleri
• 5xx oranı, sağlayıcı hata oranı, zaman aşımı oranı ve yeniden deneme oranı
• Yapılandırılmış çıktı kullanımı ve şema başarısızlık oranı
• Araç çağrısı kullanımı ve araç yürütmenin yan etkileri
• Akış kullanımı
• Metin, resim, ses ve dosya girişi gibi yöntemler
• Bağlam uzunluğu dağılımı

Bu envanter, kullanımdan kaldırma duyurusunu panikten sorguya dönüştürür.

2. Adım: Mantıksal model adları üzerinden yönlendirin

Uygulama ekiplerinin her sağlayıcının model yaşam döngüsü kurallarını bilmesi gerekmemelidir. Onlara iş yükünün amacını temsil eden kararlı mantıksal adlar verin:

• support-fast
• support-quality
• coding-premium
• invoice-extractor-v2
• content-moderation-default

Ağ geçidi bu adları sağlayıcı model kimlikleriyle eşleştirir:

{
  "logical_model": "invoice-extractor-v2",
  "routing_policy": {
    "primary": {
      "provider": "provider_a",
      "model": "model-x-stable-2025-09"
    },
    "constraints": {
      "requires_json_schema": true,
      "max_input_tokens": 64000,
      "region": "eu"
    }
  }
}

Bu, tüm sağlayıcı ayrıntılarının gizlenmesi anlamına gelmez. Bu, sağlayıcıya özgü yetenekleri ürün koduna dağıtmak yerine ağ geçidi meta verilerine yerleştirmek anlamına gelir. İyi bir soyutlama hem uygulamanın ne istediğini hem de sağlayıcının gerçekte ne yapabileceğini belirtir.

3. Adım: Kullanımdan kaldırmaları planlanmış işlemler olarak izleyin

Kullanımdan kaldırma izleyicisi bir programa göre çalışmalı ve manuel geçersiz kılmaları desteklemelidir. Sağlayıcı model kataloglarını, kullanımdan kaldırma sayfalarını, değişiklik günlüklerini, sürüm notlarını ve dahili yönetici girişlerini kontrol etmelidir. Her yaşam döngüsü sinyali, makine tarafından okunabilen temiz bir API aracılığıyla elde edilemeyeceğinden, operatörün tarihleri eklemesine veya düzeltmesine izin verin.

Monitör bir yaşam döngüsü olayı algıladığında dahili bir kayıt oluşturun:

provider_model_id: model-x-preview-2025-06
status: deprecated
shutdown_at: 2026-02-15
recommended_replacements:
  - model-x-stable-2025-09
  - model-y-mini-2025-10
source_type: provider_deprecation_page
confidence: confirmed

Ardından etki analizini otomatik olarak tetikleyin. Kullanımdan kaldırma bildirimi, birisi onu araştırmayı hatırlayana kadar sohbet kanalında yer almamalıdır.

4. Adım: Bir etki raporu oluşturun

Etki raporu mühendislik, finans, destek ve iş ortağı ekipleri için yeterince spesifik olmalıdır. Dahil et:

• Kullanımdan kaldırılan sağlayıcı modeli ve etkilenen mantıksal adlar
• Kapatma tarihi ve önerilen karar için son tarih
• Etkilenen kiracılar, ekipler ve API anahtar
• Günlük istek hacmi ve jeton hacmi
• Günlük maliyet, müşteri faturalandırma riski ve varsa marj etkisi
• Modeli kullanan en iyi uç noktalar veya ürünler
• İstem kategorileri veya kayıtlı bilgi istemi şablonları
• Şemaların, işlev veya araç çağrılarının, akışın, görüntülerin, sesin, dosyaların veya uzun bağlamın JSON kullanımı
• Mevcut gecikme yüzdelikleri ve hata oranları
• Bilinen sözleşme veya veri ikamet kısıtlamaları

İş Ortağı API kullanıcıları için bu meta verilerin filtrelenmiş bir sürümünü yayınlayın; böylece ajanslar, satıcılar ve yerleşik AI ürün oluşturucuları, bir sağlayıcının kapatılmasının alt hizmetleri etkilemesi öncesinde kendi müşterilerini uyarabilir.

5. Adım: Yeteneğe göre bir değiştirme kısa listesi oluşturun

Yalnızca marka adına göre bir yedek ürün seçmeyin. Adayları iş yüküne göre puanlayın.

En yeni amiral gemisi modeli her zaman en iyi alternatif olmayabilir. Daha küçük ve yeni bir model, yüksek hacimli iş yükleri için gecikmeyi ve maliyeti koruyabilir. Karmaşık kodlama, çıkarma veya akıl yürütme iş akışları için daha yetenekli bir model gerekli olabilir. Runbook, varsayılan olarak her kullanımdan kaldırma işlemini yükseltmeye dönüştürmek yerine bunu açıkça belirtmelidir.

6. Adım: Uyumluluk değerlendirme paketi çalıştırın

Üretim yönlendirmesini değiştirmeden önce, gerçek iş yükü riskini yansıtan bir değerlendirme paketi çalıştırın.

Minimum değerlendirme kümesi

• Altın istemler: tek bir kesin yanıtın olması gerekmeyen, beklenen özelliklere sahip kararlı örnekler.
• Şema geçerliliği testleri: JSON ayrıştırma başarısı, gerekli alanlar, numaralandırma değerleri, uzunluk sınırları ve iç içe geçmiş nesne kontrolleri.
• Araç çağrısı testleri: doğru araç seçimi, geçerli bağımsız değişkenler, güvenli olmayan yinelenen yan etkiler yok.
• Güvenlik ve reddetme kontrolleri: meşru iş isteklerinin hâlâ tamamlandığını doğrulayın.
• Maliyet karşılaştırması: giriş jetonları, çıkış jetonları, yeniden denemeler ve yinelenen çağrılar.
• Gecikme karşılaştırması: p50, p95, p99, zaman aşımı oranı ve ilgili olduğu yerde akış ilk belirteç gecikmesi.
• İnsan incelemesi:, otomatik kontrollerin yetersiz olduğu yüksek değerli veya belirsiz iş akışları için gereklidir.

Yapılandırılmış iş akışları için tek bir doğal dil kalite puanı yeterli değildir. Değiştirme, aşağı akış kodunun ayrıştırabileceği ve güvenebileceği çıktılar üretmelidir.

7. Adım: Üretim trafiğini güvenli bir şekilde gölgeleyin

Gölge testi, kullanıcıya yalnızca mevcut modelin cevabını döndürürken üretim isteklerinin bir örneğini aday modele kopyalamak anlamına gelir. Karşılaştırma için aday yanıtını ayrı olarak saklayın.

if route.shadow_enabled and request.is_safe_to_shadow:
    primary_response = call(current_model, request)
    enqueue_shadow_call(candidate_model, request, trace_id)
    return primary_response

Her şeyi gölgelemeyin. Araç yürütme katmanı devre dışı bırakılmadığı veya taklit edilmediği sürece, yan etkili araç çağrıları içeren isteklerin kopyalanmasından kaçının. Hassas veriler, saklama kuralları ve kiracı sözleşmeleri konusunda dikkatli olun. Gölge testi, geçici jeton harcamasını artırır ancak yalnızca seçilmiş test senaryolarından ziyade gerçek istemlerden elde edilen kanıtlar sağlar.

Gölge sonuçlarını karşılaştırın:

• Şema geçerliliği
• Araç çağrısı uyumluluğu
• Çıktı uzunluğu
• Başarılı istek başına maliyet
• Gecikme dağılımı
• Reddetme ve hata kalıpları
• Göreve özel inceleme sonuçları

8. Adım: Yüzdeye dayalı yönlendirmeyi uygulamaya koyun

Aday değerlendirmeyi geçtiğinde aşamalı olarak kullanıma açın. Her uygulamayı yeniden dağıtmak yerine ağ geçidindeki yönlendirme kontrollerini kiracıya, anahtara veya mantıksal modele göre tercih edin.

Konservatif bir dizi:

1. Yalnızca dahili kiracılar
2. Uygun üretim trafiğinin %1'i
3. %5
4. %25
5. %50
6. %100

Kullanıma sunma başlamadan önce geri alma eşiklerini tanımlayın:

rollback_if:
  schema_failure_rate_increase: "> 1.0 percentage point"
  provider_5xx_rate: "> 2x baseline"
  p95_latency_increase: "> 30%"
  cost_per_successful_request: "> 25% over approved budget"
  tool_argument_validation_failures: "> 0.5%"
  tenant_blocklist_hit: "any critical tenant"

Eşikler iş yüküne göre ayarlanmalıdır. Bir sohbet robotu genellikle fatura çıkarma hattına göre daha fazla ifade değişikliğini tolere edebilir. Arka planda özetleme işi, etkileşimli destek asistanına göre daha yüksek gecikmeyi tolere edebilir.

9. Adım: Taşıma sırasında faturalandırma ilişkilendirmesini koruyun

Ağ geçidi yalnızca sağlayıcı model kimliklerini kaydediyorsa model taşıma, kullanım analizlerini bozabilir. Hem mantıksal hem de fiziksel model boyutlarını koruyun:

tenant_id
api_key_id
logical_model_name
provider
provider_model_id
migration_id
input_tokens
output_tokens
provider_cost
customer_charge
latency_ms
status
schema_valid

migration_id önemlidir. Finans ve desteğin, kullanıma sunma penceresi sırasında eski ve yeni davranışları karşılaştırmasına olanak tanır. Yeni model daha pahalıysa işletme, farkı karşılamaya, fiyatlandırmayı güncellemeye, bazı kiracıları daha küçük bir modele taşımaya veya müşteri onayı isteyip istemediğine karar verebilir.

10. Adım: Bir denetim günlüğü ve geri alma planı tutun

Her taşıma işlemi bir kayıt bırakmalıdır:

• Kullanımdan kaldırılan model ve değiştirme modeli
• Etkilenen mantıksal model adları
• Karar sahibi ve onaylayanlar
• Etki raporu bağlantısı
• Değerlendirme sonuçları
• Gölge trafik özeti
• Kullanıma sunma zaman damgaları
• Geri alma eşikleri
• Müşteri veya iş ortağı bildirimleri
• Son durum ve öğrenilen dersler

Geri alma planı istek uyandırıcı değil, işlevsel olmalıdır. Eski sağlayıcı modeli yakında kapatılacaksa geri alma, ikinci bir yedek adaya yönlendirme, bir özelliği devre dışı bırakma, daha katı bir istem kullanma veya etkilenen kiracıları geçici olarak sınırlama anlamına gelebilir. Geçişten önce mevcut seçenekleri belgeleyin.

Yönetilmesi gereken ödünler

• Sabitlenen model kimlikleri tekrarlanabilirliği artırır ancak anlık görüntüler kullanımdan kaldırıldığında kullanım ömrü sonu riskini artırır.
• Sağlayıcı takma adları bakımı azaltır ancak bir uygulamanın altındaki davranışı değiştirebilir, dolayısıyla regresyonun izlenmesi gerekir.
• Ağ geçidi düzeyinde soyutlama, geçişi kolaylaştırır ancak yetenek meta verileri açık olmadığı sürece sağlayıcıya özgü yetenekleri gizleyebilir.
• Gölge testi güveni artırır ancak istekler yinelendiğinden geçici jeton harcamasını artırır.
• Otomatik geçiş, kesinti riskini azaltır ancak değiştirmeler yalnızca fiyata veya genel karşılaştırma puanlarına göre seçilirse anlamsal gerilemeler oluşturabilir.
• Kiracı başına geçersiz kılmalar önemli müşterileri korur ancak operasyonel karmaşıklığı ve destek yükünü artırır.
• Katı uyumluluk kapıları, yapılandırılmış iş akışlarını korur ancak istem veya şema değişiklikleri gerektiren daha iyi modellerin benimsenmesini yavaşlatabilir.

Uygulama kontrol listesi

• Sağlayıcı modellerinin ve mantıksal model adlarının merkezi bir envanterini oluşturun.
• Mümkün olduğunda uygulama ekiplerinin doğrudan sağlayıcı model kimliklerini engelleyin.
• Sağlayıcı yaşam döngüsü izleme ve manuel yönetici geçersiz kılma işlemleri ekleyin.
• Her kullanımdan kaldırma etkinliği için etki raporları oluşturun.
• Değiştirme işlemlerini yetenek, maliyet, gecikme, uyumluluk ve uyumluluğa göre puanlayın.
• Altın istemler, şema kontrolleri, araç çağırma kontrolleri, güvenlik kontrolleri ve maliyet karşılaştırmaları çalıştırın.
• Değiştirmeyi açığa çıkarmadan önce güvenli üretim trafiğini gölgeleyin.
• Önceden tanımlanmış geri alma eşikleri ile kiracıya, anahtara veya yüzdeye göre kullanıma sunma.
• Kullanım analizinde mantıksal modeli, sağlayıcı modelini ve taşıma kimliğini izleyin.
• Alt müşteriler etkilendiğinde, iş ortaklarına yönelik API'ler aracılığıyla kullanımdan kaldırılan meta verileri açığa çıkarın.

Harekete geçirilebilir sonuç

Modelin kullanımdan kaldırılması sürecini tasarlamanın en güvenli zamanı bir sonraki kapatma bildiriminden önceki zamandır. Tek bir kuralla başlayın: uygulamalar mantıksal model adları ister ve ağ geçidi, sağlayıcı eşlemesinin sahibidir. Ardından bu kuralın etrafına operasyonel katmanı ekleyin: envanter, izleme, etki raporları, değerlendirmeler, gölge trafik, aşamalı dağıtım, geri alma ve denetim günlükleri.

Bu, model geçişini son dakika dize değişiminden yönetilen bir bağımlılık iş akışına dönüştürür. Amaç model davranışını sonsuza kadar dondurmak değil. Amaç, kaliteyi, maliyeti, gecikmeyi, yapılandırılmış çıktı davranışını ve faturalandırma ilişkilendirmesini korurken modelleri kasıtlı olarak değiştirmektir.

İlgili okuma

• yapılandırılmış çıktı ve araç çağrısı uyumluluk kontrolleri
• LLM için yönlendirme kontrolleri ve geri alma davranışı API'ler
• iş ortaklarına yönelik kiracı ve kullanım meta verileri