AI Modeli Kullanımdan Kaldırma ve Sürüm Oluşturma: API Entegrasyonlarını Stabil Tutun

Bir model dizisi, kod tabanınızdaki en tehlikeli sabittir. Ekipler ona bir etiket gibi davranır, ancak bu dizi hangi kontrol noktasının yanıt vereceğine, çağrının maliyetine ve isteğin başarılı olup olmayacağına karar verir. Bu nedenle AI modeli kullanım dışı bırakma ve sürümleme, tek seferlik bir lansman kararı değil, sürüm sürecinizin bir parçası olmalıdır. Bu kılavuz, 2026-10-03 tarihinde gözlemlendiği şekliyle TokenLab'in genel model API'sini kullanarak neleri otomatik olarak kontrol edebileceğinizi, neleri başka yerlerde doğrulamanız gerektiğini ve bir ID çalışmayı durdurduğunda ne yapmanız gerektiğini gösterir.

Önemli Çıkarımlar

• Yaşam döngüsü verileri model nesnesinde bulunur. Bir blog gönderisinden tarihleri kopyalamak yerine, Get a Model (2026-10-03 tarihinde gözlemlendi) üzerinden tokenlab.lifecycle değerini okuyun.
• 2026-10-03 tarihinde kontrol ettiğimiz beş modelin tamamı active durumdaydı ve herhangi bir kullanım dışı bırakma veya emeklilik tarihi yoktu. Kanıtlarımızda gerçekten kullanım dışı bırakılmış bir model bulunmamaktadır, bu nedenle aşağıdaki hata yolu gerçekleştiğini izlediğimiz bir durum değil, belgelenmiş bir davranıştır.
• Eksik bir model model_not_found döndürür, ancak durum kodu uç noktaya göre farklılık gösterir. Sadece duruma göre değil, her zaman code değerine göre dallanma yapın.
• Tam ID'leri sabitleyin ve bunları tek bir yapılandırma katmanında tutun. TokenLab, gönderdiğiniz modeli sessizce değiştirmediğini belirtir.
• Bir yedek (fallback), test edilmiş ve önceden onaylanmış bir seçenek olmalıdır. Yetenekler, istek formatları, limitler ve fiyatlar modeller arasında farklılık gösterir.

AI modeli kullanım dışı bırakma ve sürümleme API'de nerede görünür?

Get a Model referansı (2026-10-03 tarihinde gözlemlendi), lifecycle alanının kullanılabilirlik, yayın tarihi, kullanım dışı bırakma tarihi ve yedek modeli kapsadığını belirtir. List Models referansı (2026-10-03 tarihinde gözlemlendi) her liste öğesine tokenlab.lifecycle, tokenlab.aliases, tokenlab.commercial ve tokenlab.badges ekler. Aynı sayfa, herhangi bir değişim için önemli olan tokenlab.accepted_request_formats ve token limitlerini listeler.

2026-10-03 tarihinde claude-sonnet-5 için canlı model API'sinden okuduklarımız aşağıdadır. Bu, gözlemlenen değerlerin yoğunlaştırılmış bir sunumudur. Kanıtlarımız ham iç içe anahtar adlarını değil, değerleri kaydetti, bu nedenle tam anahtarları canlı bir yanıtla karşılaştırarak doğrulayın.

GET https://api.tokenlab.sh/v1/models/claude-sonnet-5
category:             chat
lifecycle stage:      active
released:             2026-06-30
replacement model:    None
deprecated_at:        None
retired_at:           None
max input tokens:     1000000
max output tokens:    128000
accepted formats:     anthropic_messages, openai_chat_completions

Beş yaşam döngüsü kavramını bu alanlarla şu şekilde eşleştirin:

Kavram	Gözlemlenen yanıttaki alan	claude-sonnet-5 için değer
Aşama	lifecycle stage	active
Yayın	released	2026-06-30
Kullanım Dışı Bırakma	deprecated_at	None
Emeklilik	retired_at	None
Yedek	replacement model	None

Boş bir değer her zaman bir sorun olduğu anlamına gelmez. glm-5.2 ve gpt-5.5 için canlı API (2026-10-03 tarihinde gözlemlendi), aşama active iken released değerini None olarak gösterir. Bir kontrol; ayarlanmış bir deprecated_at, ayarlanmış bir retired_at veya aktif olmayan bir aşama durumunda başarısız olmalıdır. Eksik bir yayın tarihi nedeniyle başarısız olmamalıdır.

Ayrıca deepseek-v4-pro ve deepseek-v4-flash modellerini de okuduk (her ikisi de 2026-04-24 tarihinde yayınlandı, her ikisi de aktif, yedek yok). Bu, kullanım dışı bırakma sinyali olmayan beş model eder. Kullanım dışı bırakılmış bir modelin yedek alanı, gözlemleyemediğimiz tek değerdir.

Bir bağımlılık bozulduğunda başarısız olan bir betik

Aşağıdaki kontrol, yalnızca belgelenmiş GET /v1/models/{model} uç noktasını kullanır; katalog herkese açık olduğu için API anahtarına ihtiyaç duymaz. Eksik bir ID, ayarlanmış bir deprecated_at veya retired_at, aktif olmayan bir aşama veya modelin artık kabul etmediği bir istek formatı durumunda başarısız olur.

#!/usr/bin/env python3
"""Bağımlı olduğumuz bir model ID'si eksik, kullanım dışı veya emekli olduğunda başarısız ol."""
import json
import sys
import urllib.error
import urllib.request

BASE = "https://api.tokenlab.sh/v1/models/"

# model ID -> kodumuzun aslında gönderdiği istek formatı
DEPENDENCIES = {
    "gpt-5.5": "openai_chat_completions",
    "claude-sonnet-5": "anthropic_messages",
    "deepseek-v4-pro": "openai_chat_completions",
}

def fetch(model_id):
    req = urllib.request.Request(BASE + model_id, headers={"Accept": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=15) as resp:
            return resp.status, json.load(resp)
    except urllib.error.HTTPError as exc:
        try:
            body = json.load(exc)
        except ValueError:
            body = {}
        return exc.code, body

def check(model_id, fmt):
    try:
        status, body = fetch(model_id)
    except urllib.error.URLError as exc:
        return [f"doğrulanamadı: {exc.reason}"], {}, []
    if status in (400, 404):
        return [f"eksik: HTTP {status}"], {}, []
    if status != 200:
        return [f"doğrulanamadı: HTTP {status}"], {}, []

    info = body.get("tokenlab", {})
    life = info.get("lifecycle") or {}
    problems = []
    if not life:
        problems.append("yaşam döngüsü bloğu döndürülmedi")
    stage = life.get("stage")  # tam anahtarı canlı bir yanıtla karşılaştırarak doğrulayın
    if stage not in (None, "active"):
        problems.append(f"stage={stage}")
    for key in ("deprecated_at", "retired_at"):
        if life.get(key):
            problems.append(f"{key}={life[key]}")
    if fmt not in info.get("accepted_request_formats", []):
        problems.append(f"format {fmt} kabul edilmiyor")
    return problems, life, info.get("aliases", [])

def main():
    failed = False
    for model_id, fmt in DEPENDENCIES.items():
        problems, life, aliases = check(model_id, fmt)
        if problems:
            failed = True
            print(f"FAIL {model_id}: {'; '.join(problems)}")
            if life:
                print(f"     lifecycle: {json.dumps(life)}")
        else:
            print(f"ok   {model_id} aliases={aliases}")
    sys.exit(1 if failed else 0)

if __name__ == "__main__":
    main()

Bunu CI'da ve gece planlanmış bir görev olarak çalıştırın, çünkü bir model sizin tarafınızda bir commit olmadan durum değiştirebilir. Son dağıtımınız bir hafta önceyken Salı günü 1 koduyla çıkan bir gece işi hayal edin. Önemli olan nokta budur: hata bir müşterinin sohbet penceresinde değil, bir işlem hattında (pipeline) görünür. Betik, hata durumunda tüm yaşam döngüsü bloğunu yazdırır, böylece bir insan anahtar adlarını tahmin etmek zorunda kalmadan yedek değeri görebilir.

Emekli veya bilinmeyen bir model ne döndürür?

Kanıtlar, ayrı olarak etiketlenmiş bir "emekli" yanıtını değil, bilinmeyen ve kullanılamayan modelleri belgeler. Bu nedenle, aksi doğrulanana kadar emekliliği aynı hata ailesi olarak ele alıyoruz. Belgelerin söyledikleri (hepsi 2026-10-03 tarihinde gözlemlendi) şöyledir:

Nerede	Yanıt	Kaynak
GET /v1/models/{model}	404 model_not_found	Get a Model
Yanlış yazılmış veya kullanılamayan bir modelle sohbet isteği	400 model_not_found, isteğe bağlı olarak did_you_mean, suggestions, hint ile	Ajanların işlem yapabileceği hatalar
İşlemin seçilen Teslimat katmanında arzı yok	503 all_channels_failed veya 503 delivery_tier_unavailable, retryable: false	Ajanların işlem yapabileceği hatalar
Anahtarın model için izni yok	403 model_not_allowed	API hatalarını yönetme

Durum kodları uç noktalar arasında farklılık gösterir, bu yüzden tek bir düzeltme önemlidir: kaynak makalemizin yedek kodu 404 ve 410 hatalarını "tanımlayıcı gitti" olarak ele alıyordu. Bu, sohbet istekleri için yanlıştır. Belgelenmiş sohbet yanıtı 400'dür ve hata kılavuzu, hataları HTTP durumuna ve code değerine göre yönetmenizi söyler. Mantığınızı code == "model_not_found" üzerine kurun.

Örneğin, belgeler yanlış yazılmış bir ID'nin did_you_mean: "gpt-5.6-terra" döndürdüğünü gösterir. İstemciniz şu sırayla tepki vermelidir:

1. İsteği değiştirmeden tekrarlamayın. Hata kılavuzu 400, 403 ve 404 hatalarını tekrarlanamaz olarak işaretler.
2. did_you_mean değerini bir öneri olarak değerlendirin. Yalnızca ürününüzün modeli değiştirme izni zaten varsa geçiş yapın.
3. 503 gövdesi retryable: false diyorsa, yeniden denemeyi durdurun. Belgeler, benzer isimlerin kullanılabilirlik kanıtı olmadığını belirtir.
4. Yanıt başlıklarındaki İstek ID'sini (Request ID), model ve kendi iş ID'nizle birlikte kaydedin.
5. Bir insanı uyarın. Kaybolan sabitlenmiş bir ID, geçici bir hata değil, bir sürüm olayıdır.

Tam bir ID sabitleyin veya bir takma adı takip edin

En iyi uygulamalar kılavuzu (2026-10-03 tarihinde gözlemlendi), model ID'sini her istekte açık tutmanızı ve modelleri sessizce değiştirmemenizi söyler. Bir yedeğin kaliteyi, fiyatı, bağlam uzunluğunu, araçları veya medya desteğini değiştirebileceği konusunda uyarır. Hata kılavuzu, TokenLab'in gönderdiğiniz modeli sessizce değiştirmediğini ekler.

Strateji	Davranış	Ana risk
gpt-5.5 gibi tam bir ID sabitleme	O modeli alırsınız veya bir hata alırsınız	ID kaldırılırsa ciddi bir hata oluşur
Bir takma adı takip etme	İsim zamanla yeni bir yere işaret edebilir	Davranış ve maliyet kod değişikliği olmadan değişebilir
Yapılandırmanızdaki dahili rota adı	Kodunuz primary_chat ister; yapılandırma bunu tam bir ID'ye eşler	Eşlemeye siz sahip olursunuz ve test edersiniz

Takma adlar konusunda bir boşluk bulduk. List Models referansı, her öğede tokenlab.aliases bulunduğunu söyler. Elimizdeki beş canlı alıntının hiçbiri (claude-sonnet-5, deepseek-v4-pro, deepseek-v4-flash, glm-5.2, gpt-5.5) bir takma ad değeri göstermiyor. Bugün bu modellerin hangi takma adlara sahip olduğunu size söyleyemeyiz. Yukarıdaki betik her bağımlılık için aliases değerini yazdırır, bu yüzden çalıştırın ve çıktıyı okuyun.

İki katalog gerçeği daha yardımcı olur. 2026-10-02 kataloğu sürümleri ayrı tam ID'ler olarak listeler, örneğin claude-sonnet-4-6, claude-sonnet-5 ve claude-sonnet-5-5. Yan yana listelenmeleri, birinin diğerinin halefi olduğu anlamına gelmez. replacement değeri, bu ilişkinin gelmesi gereken tek yerdir. grok-voice-latest adlı bir ID, isminde "latest" içerir. Neyi takip ettiğine dair hiçbir kanıtımız yok, bu yüzden güvenmeden önce model sayfasına bakın. Pazar yeri tarzı ön ekli ID'ler TokenLab takma adları değildir. Geçiş kılavuzu, TokenLab ID'lerinin OpenRouter sağlayıcı ön eki taşımadığını söyler ve kendi LiteLLM takma adınızı TokenLab ID'sinden ayrı tutmanızı önerir.

Kaybolan sabitlenmiş bir model için yedekleme modeli

Yedeği, önceden test ettiğiniz ikinci bir sabitlenmiş model olarak değerlendirin. Bunu çağrı sitesi başına seçin, her yanıtı hangi modelin sunduğunu kaydedin ve aynı gece betiği ile doğrulayın. İki modeli eşleştirmeden önce karşılaştırın:

Model (canlı API, 2026-10-03)	1M token başına giriş / çıkış	Maks giriş / çıkış token	İstek formatları	Listelenen yetenekler
gpt-5.5	$1.50 / $9.00	1,000,000 / 128,000	openai_chat_completions, openai_responses	kodlama, json-mode, prompt-cache, akıl yürütme, araç kullanımı, görme
claude-sonnet-5	$0.90 / $4.50	1,000,000 / 128,000	anthropic_messages, openai_chat_completions	json-mode, prompt-cache, akıl yürütme, araç kullanımı, görme
deepseek-v4-pro	$0.66 / $1.98 yoğun olmayan; $1.32 / $3.96 yoğun	1,000,000 / 384,000	anthropic_messages, openai_chat_completions, openai_responses	json-mode, prompt-cache, araç kullanımı

Üçü için de fiyatlandırma en son 2026-10-02T16:53:30.068Z tarihinde güncellendi. Farklılıklar önemlidir. claude-sonnet-5, openai_responses kabul etmez, bu nedenle Responses tabanlı bir çağırıcı ona yedeklenemez. deepseek-v4-pro ne görme ne de akıl yürütme listeler, bu nedenle görüntü içeren bir istek orada bozulur. DeepSeek'in yoğun saatleri Pekin saatiyle 09:00-12:00 ve 14:00-18:00 arasındadır.

İşte gösterilen çalışma ile bir maliyet tahmini. Günlük 10M giriş ve 2M çıkış tokeni yükü varsayın (bu bir ölçüm değil, örnekleyici bir sayıdır):

• gpt-5.5: 10 × $1.50 + 2 × $9.00 = $15 + $18 = günlük $33.
• claude-sonnet-5: 10 × $0.90 + 2 × $4.50 = $9 + $9 = günlük $18.
• deepseek-v4-pro yoğun olmayan: 10 × $0.66 + 2 × $1.98 = $6.60 + $3.96 = günlük $10.56.
• deepseek-v4-pro yoğun: 10 × $1.32 + 2 × $3.96 = $13.20 + $7.92 = günlük $21.12.

Bunlar tahminlerdir ve önbelleğe alınmış giriş farklı fiyatlandırılır. Aşağıdaki kod, yalnızca yeniden denemenin düzeltemeyeceği hatalarda yedeklemeye geçer. Bir 429 veya yeniden denenebilir bir 5xx hatası, normal yeniden deneme kurallarını izlemelidir.

import logging
import os

import openai

log = logging.getLogger("model-routing")

client = openai.OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,  # neyin tekrarlanmasının güvenli olduğuna biz karar veririz
)

ROUTES = {
    "primary_chat": {"model": "gpt-5.5", "fallback": "claude-sonnet-5"},
    "coding_agent": {"model": "claude-sonnet-5", "fallback": "deepseek-v4-pro"},
}

def _error(exc):
    body = exc.body if isinstance(exc.body, dict) else {}
    err = body.get("error", body)
    return err if isinstance(err, dict) else {}

def _chat(model_id, text):
    resp = client.chat.completions.create(
        model=model_id,
        messages=[{"role": "user", "content": text}],
    )
    return resp.choices[0].message.content

def call_model(route, text):
    """Yanıtlayan modeli ve metni döndür. Modeli sonuçla birlikte kaydet."""
    cfg = ROUTES[route]
    try:
        return cfg["model"], _chat(cfg["model"], text)
    except openai.APIStatusError as exc:
        err = _error(exc)
        code = err.get("code")
        gone = code == "model_not_found"
        no_supply = (
            code in ("all_channels_failed", "delivery_tier_unavailable")
            and err.get("retryable") is False
        )
        if not (gone or no_supply):
            raise  # 401/402/403/429 ve benzeri hatalar farklı bir düzeltme gerektirir
        log.warning("sabitlenmiş model %s kullanılamıyor (%s); %s kullanılıyor",
                    cfg["model"], code, cfg["fallback"])
        return cfg["fallback"], _chat(cfg["fallback"], text)

Yedekleme bir kez atlar ve asla zincirleme yapmaz. Yedekleme de başarısız olursa, hatayı yükseltin ve birine haber verin. Sessiz bir ikame zinciri, başka bir isim altındaki kayma sorunudur.

AI modeli kullanım dışı bırakma ve sürümleme için sürüm kontrol listesi

Bunu üretim model ID'sini değiştirmeden önce çalıştırın. En iyi uygulamalar kılavuzunu (2026-10-03 tarihinde gözlemlendi) yansıtır ve yaşam döngüsü kontrollerini ekler.

1. Üretimdeki her model ID'sini listeleyin ve her birini kullanan çağrı sitesini adlandırın. Bir yapılandırma katmanı buna saniyeler içinde cevap vermelidir.
2. Yaşam döngüsü betiğini mevcut ve aday ID'lere karşı çalıştırın. deprecated_at, retired_at, aşama ve yedeği okuyun.
3. Adayın, kodunuzun gönderdiği istek formatını kabul ettiğini, Get a Model'den accepted_request_formats kullanarak doğrulayın.
4. Maksimum giriş ve maksimum çıkış tokenlerini, en uzun gerçek isteğiniz ve çıkış sınırınızla karşılaştırın.
5. Yetenekleri karşılaştırın. Ürününüzün bağlı olduğu durumlarda görme, araç kullanımı, json-mode ve akıl yürütmeyi doğrulayın.
6. Maliyetleri güncel fiyatlardan, gösterilen çalışma ile yeniden hesaplayın. DeepSeek için yoğun ve yoğun olmayan saatleri ayırın.
7. Temsili istekleri, göndereceğiniz tam aday ID ve formatla yeniden oynatın. Bilinmeyen bir ID gibi bir hata durumunu dahil edin.
8. Hata yolunu doğrulayın. İstemciniz code değerine göre dallanmalı, İstek ID'sini saklamalı ve 400, 403 veya 404 hatalarını yeniden denememelidir.
9. Değişikliği, eski ID'nin belgelenmiş geri alma değeri olarak tutulduğu bir yapılandırma düzenlemesi olarak gönderin.
10. Her yanıt kaydının, onu gerçekten sunan modeli sakladığını kontrol edin.
11. Sürümden sonra gece betiğini yeniden çalıştırın. Yedek ID'nin de geçtiğini doğrulayın.

Belgelerin sessiz kaldığı yerlerde, kontrol listesi güvencedir. Herhangi bir kullanım dışı bırakma süresi ve bildirim kanalı vermezler. Sağlayıcı bildirimlerini ayrı ayrı doğrulayın ve herhangi bir yaşam döngüsü notu için modelin kendi sayfasını kontrol edin.

SSS

Bir TokenLab modelinin kullanım dışı mı yoksa emekli mi olduğunu nasıl anlarım?

GET /v1/models/{model} çağrısı yapın ve tokenlab.lifecycle değerini okuyun. Aşamayı, deprecated_at, retired_at ve yedek modeli kontrol edin. 2026-10-03 itibarıyla, okuduğumuz beş modelin tamamı active durumdaydı ve hiçbir tarih ayarlanmamıştı. Tekrar sorgulayın, çünkü değer yalnızca sorduğunuz anı yansıtır.

Bilinmeyen bir model ID'si hangi HTTP durumunu döndürür?

Uç noktaya bağlıdır. Get a Model 404 model_not_found döndürürken, hatalı bir modelle yapılan sohbet isteği 400 model_not_found döndürür. Seçilen Teslimat katmanında arzı olmayan bir model 503 döndürür. code alanına göre dallanma yapın.

Bir model_not_found hatasını yeniden denemeli miyim?

Hayır. Aynı isteği tekrarlamak sonucu değiştirmez. Varsa did_you_mean ve suggestions değerlerini kontrol edin, ancak yalnızca ürününüzün izni varsa modelleri değiştirin. Aksi takdirde, önceden onaylanmış bir yedek kullanın ve ekibinizi uyarın.

TokenLab, benimki kaybolursa isteğimi başka bir modele geçirir mi?

Belgeler, gönderdiğiniz modeli sessizce değiştirmediğini belirtir. Açık bir ID gönderin ve hatayı kendiniz yönetin. Yedeğiniz, platform hakkında bir varsayım değil, test edilmiş bir yapılandırma değeri olmalıdır.

Bir sonraki model değişikliğinizden önce model dizinindeki mevcut ID'leri, limitleri ve fiyatları karşılaştırın.