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
Model kimliklerini yönetilen bağımlılıklar olarak işlemeye yönelik pratik bir runbook: envanter kullanımı, kullanımdan kaldırmaları algılama, değiştirmeleri puanlama, uyumluluk testleri çalıştırma, trafiği gölgeleme, kademeli olarak kullanıma sunma ve faturalandırma ilişkilendirmesini koruma.
Sabit kodlu 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 aceleyle yapılan bir geçişten sonra iş yükleri farklı davranan kiracılardan gelen müşteri biletleri olarak ortaya çıkıyor.
Pratik çözüm, model kimliklerini uygulama kodundaki statik dizeler gibi değil, yönetilen bağımlılıklar gibi ele almaktır. Bir 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, kolaylık takma adlarını belirli model kimliklerinden ayırır ve bazı taşıma işlemleri, mevcut entegrasyonları bozan API düzeyinde 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: sağlayıcı model kimlikleri uygulama koduna dağılmış
Ortak bir uygulama basit bir şekilde başlar:
<ön>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 anahtarları hâlâ kendisine 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 kaliteli inceleme 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:
mantıksal_model_adı desteği hızlı
sağlayıcı sağlayıcı_a
sağlayıcı_model_id model-x-önizleme-2025-06
bitiş noktası_tipi sohbet_tamamlamaları
takma ad_durum pinned_snapshot | sağlayıcı_alias | dahili_alias
durum aktif | kullanımdan kaldırıldı | engellendi | emekli
replacement_candidates ["hızlı-v2 desteği", "dengeli destek"]
First_seen_at zaman damgası
last_seen_at zaman damgası
deprecation_announced_at timestamp
kapatma_at zaman damgası
admin_override metni
owner_team destek platformuDaha sonra bunu kullanım verileriyle birleştirin. Her sağlayıcı modeli ve mantıksal model için şunları izleyin:
- Etkin kiracılar ve API anahtarları
- 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ı boyunca 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:
hızlı destekdestek kalitesikodlama-premiumfatura çıkarıcı-v2içerik-denetim-varsayılan
Ağ geçidi bu adları sağlayıcı model kimlikleriyle eşleştirir:
<ön>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. Tüm yaşam döngüsü sinyalleri, makine tarafından okunabilen temiz bir API aracılığıyla sağlanamayacağından, 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
durum: kullanımdan kaldırıldı
kapatma_at: 2026-02-15
önerilen_değiştirmeler:
- model-x-stable-2025-09
- model-y-mini-2025-10
kaynak_türü: sağlayıcı_deprecation_page
güven: onaylandı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. Şunları 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 anahtarları
- Günlük istek hacmi ve jeton hacmi
- Günlük maliyet, müşteri faturalandırma riski ve varsa marj etkisi
- Modeli kullanan başlıca uç noktalar veya ürünler
- İstem kategorileri veya kayıtlı bilgi istemi şablonları
- JSON şemalarının, işlev veya araç çağrılarının, akışın, görüntülerin, sesin, dosyaların veya uzun bağlamın 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ı, sağlayıcının kapatılması alt hizmetleri etkilemeden önce kendi müşterilerini uyarabilir.
5. Adım: Yeteneğe göre bir yedek kısa liste oluşturun
Yalnızca marka adına göre bir yedek parça 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 paketini ç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 seti
- Altın ipuçları: tek bir kesin yanıt olmasa da beklenen özelliklere sahip istikrarlı ö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 argümanlar, güvenli olmayan yinelenen yan etkiler yok.
- Güvenlik ve ret 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 işlemi, 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.
route.shadow_enabled ve request.is_safe_to_shadow ise:
birincil_yanıt = çağrı(geçerli_model, istek)
enqueue_shadow_call(aday_modeli, istek, trace_id)
birincil_yanıtı döndürHer ş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 uygulamaya geçin. 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:
- Yalnızca dahili kiracılar
- Uygun üretim trafiğinin %1'i
- %5
- %25
- %50
- %100
Kullanıma sunma başlamadan önce geri alma eşiklerini tanımlayın:
rollback_if:
schema_failure_rate_increase: "> yüzde 1,0 puan"
sağlayıcı_5xx_rate: "> 2 kat temel değer"
p95_latency_increase: "> %30"
cost_per_successful_request: "> Onaylanan bütçenin %25 üzerinde"
tool_argument_validation_failures: "> %0,5"
tenant_blocklist_hit: "herhangi bir kritik kiracı"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çidinin yalnızca sağlayıcı model kimliklerini kaydetmesi durumunda model geçişi kullanım analizlerini bozabilir. Hem mantıksal hem de fiziksel model boyutlarını koruyun:
tenant_id
api_key_id
mantıksal_model_adı
sağlayıcı
sağlayıcı_model_id
taşıma_kimliği
input_tokens
çıktı_belirteçleri
sağlayıcı_maliyeti
müşteri_ücreti
gecikme_ms
durum
schema_validmigration_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 geçiş bir kayıt bırakmalıdır:
- Kullanımdan kaldırılan model ve değiştirme modeli
- Mantıksal model adları etkilendi
- 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ının hevesli değil, işlevsel olması gerekir. 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, bu nedenle regresyon izlemeye ihtiyaç duyarlar.
- 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.
- Kalıcı geçersiz kılmalar önemli müşterileri korur ancak operasyonel karmaşıklığı ve destek yükünü artırır.
- Sıkı uyumluluk kapıları, yapılandırılmış iş akışlarını korur ancak hızlı 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ılmaları ekleyin.
- Her kullanımdan kaldırma etkinliği için etki raporları oluşturun.
- Yetenek, maliyet, gecikme, uyumluluk ve uyumluluğa göre değiştirmeleri puanlayın.
- Altın istemler, şema kontrolleri, araç çağrısı kontrolleri, güvenlik kontrolleri ve maliyet karşılaştırmaları çalıştırın.
- Değiştirmeyi kullanıma sunmadan ö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 geçiş 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ç
Bir 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.