Deprekasi dan Versi Model AI: Menjaga Stabilitas Integrasi API

String model adalah konstanta paling berbahaya dalam basis kode Anda. Tim sering memperlakukannya seperti label, padahal string tersebut menentukan checkpoint mana yang menjawab, berapa biaya panggilannya, dan apakah permintaan tersebut berhasil atau tidak. Oleh karena itu, deprekasi dan pembuatan versi model AI harus menjadi bagian dari proses rilis Anda, bukan keputusan peluncuran satu kali. Panduan ini menggunakan API model publik TokenLab, sebagaimana diamati pada 2026-10-03, untuk menunjukkan apa yang dapat Anda periksa secara otomatis, apa yang harus Anda verifikasi di tempat lain, dan apa yang harus dilakukan ketika sebuah ID berhenti berfungsi.

Poin Penting

• Data siklus hidup (lifecycle) terdapat pada objek model. Baca tokenlab.lifecycle dari Get a Model (diamati 2026-10-03) alih-alih menyalin tanggal dari postingan blog.
• Kelima model yang kami periksa pada 2026-10-03 berstatus active tanpa tanggal deprekasi atau penghentian (retirement). Bukti kami tidak mengandung model yang benar-benar dideprekasi, jadi jalur kegagalan di bawah ini adalah perilaku yang didokumentasikan, bukan sesuatu yang kami saksikan terjadi.
• Model yang hilang mengembalikan model_not_found, tetapi statusnya berbeda tergantung endpoint. Lakukan percabangan (branch) pada code, jangan pernah hanya pada statusnya saja.
• Sematkan (pin) ID yang tepat dan simpan dalam satu lapisan konfigurasi. TokenLab menyatakan bahwa mereka tidak mengganti model yang Anda kirim secara diam-diam.
• Fallback harus berupa pilihan yang sudah diuji dan disetujui sebelumnya. Kemampuan, format permintaan, batas, dan harga semuanya berbeda antar model.

Di mana deprekasi dan pembuatan versi model AI muncul di API

Referensi Get a Model (diamati 2026-10-03) menyatakan bahwa field lifecycle mencakup ketersediaan, tanggal rilis, tanggal deprekasi, dan model pengganti. Referensi List Models (diamati 2026-10-03) menambahkan tokenlab.lifecycle, tokenlab.aliases, tokenlab.commercial, dan tokenlab.badges ke setiap item daftar. Halaman yang sama mencantumkan tokenlab.accepted_request_formats dan batas token, yang penting untuk setiap penggantian.

Berikut adalah apa yang kami baca dari API model langsung untuk claude-sonnet-5 pada 2026-10-03. Ini adalah rendering ringkas dari nilai yang diamati. Bukti kami mencatat nilai-nilainya, bukan nama kunci bersarang (nested key) mentah, jadi konfirmasikan kunci yang tepat terhadap respons langsung.

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

Petakan kelima konsep siklus hidup ke field tersebut seperti ini:

Konsep	Field dalam respons yang diamati	Nilai untuk claude-sonnet-5
Tahap	lifecycle stage	active
Rilis	released	2026-06-30
Deprekasi	deprecated_at	None
Penghentian	retired_at	None
Penggantian	replacement model	None

Nilai kosong tidak selalu menandakan masalah. Untuk glm-5.2 dan gpt-5.5, API langsung (diamati 2026-10-03) menunjukkan released sebagai None sementara tahapannya adalah active. Pemeriksaan harus gagal jika deprecated_at diatur, retired_at diatur, atau tahapannya tidak aktif. Pemeriksaan tidak boleh gagal karena tanggal rilis yang hilang.

Kami juga membaca deepseek-v4-pro dan deepseek-v4-flash (keduanya dirilis 2026-04-24, keduanya aktif, tidak ada penggantian). Itu membuat lima model tanpa sinyal deprekasi. Field pengganti model yang dideprekasi adalah satu-satunya nilai yang tidak dapat kami amati terisi.

Skrip yang gagal ketika dependensi bermasalah

Pemeriksaan di bawah ini hanya menggunakan endpoint GET /v1/models/{model} yang didokumentasikan, yang tidak memerlukan API key karena katalognya bersifat publik. Skrip ini gagal jika ada ID yang hilang, deprecated_at atau retired_at yang diatur, tahapan tidak aktif, atau format permintaan yang tidak lagi diterima oleh model.

#!/usr/bin/env python3
"""Gagal ketika ID model yang kita andalkan hilang, dideprekasi, atau dihentikan."""
import json
import sys
import urllib.error
import urllib.request

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

# model ID -> format permintaan yang sebenarnya dikirim oleh kode kita
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"tidak dapat memverifikasi: {exc.reason}"], {}, []
    if status in (400, 404):
        return [f"hilang: HTTP {status}"], {}, []
    if status != 200:
        return [f"tidak dapat memverifikasi: HTTP {status}"], {}, []

    info = body.get("tokenlab", {})
    life = info.get("lifecycle") or {}
    problems = []
    if not life:
        problems.append("tidak ada blok siklus hidup yang dikembalikan")
    stage = life.get("stage")  # konfirmasikan kunci yang tepat terhadap respons langsung
    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} tidak diterima")
    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"GAGAL {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()

Jalankan skrip ini di CI dan pada jadwal harian, karena model dapat berubah status tanpa adanya commit di sisi Anda. Bayangkan sebuah pekerjaan harian yang keluar dengan status 1 pada hari Selasa sementara penerapan terakhir Anda adalah seminggu yang lalu. Itulah intinya: kegagalan muncul di pipeline, bukan di jendela obrolan pelanggan. Skrip mencetak seluruh blok siklus hidup saat gagal sehingga manusia dapat melihat nilai pengganti tanpa menebak nama kunci.

Apa yang dikembalikan oleh model yang dihentikan atau tidak diketahui

Bukti mendokumentasikan model yang tidak diketahui dan tidak tersedia, bukan respons yang diberi label "dihentikan" secara terpisah. Oleh karena itu, kami memperlakukan penghentian sebagai keluarga kesalahan yang sama sampai Anda memverifikasinya. Berikut adalah apa yang dikatakan dokumentasi, semuanya diamati pada 2026-10-03:

Di mana	Respons	Sumber
GET /v1/models/{model}	404 model_not_found	Get a Model
Permintaan obrolan dengan model yang salah eja atau tidak tersedia	400 model_not_found, opsional dengan did_you_mean, suggestions, hint	Kesalahan yang dapat ditindaklanjuti agen
Operasi tidak memiliki pasokan di tier Pengiriman yang dipilih	503 all_channels_failed atau 503 delivery_tier_unavailable, retryable: false	Kesalahan yang dapat ditindaklanjuti agen
Key tidak memiliki izin untuk model tersebut	403 model_not_allowed	Menangani kesalahan API

Kode status tidak konsisten di seluruh endpoint, jadi satu perbaikan penting: kode fallback artikel sumber kami memperlakukan 404 dan 410 sebagai "pengenal hilang." Itu salah untuk permintaan obrolan. Respons obrolan yang didokumentasikan adalah 400, dan panduan kesalahan mengatakan untuk menangani kesalahan berdasarkan status HTTP dan code. Arahkan logika Anda pada code == "model_not_found".

Sebagai contoh, dokumentasi menunjukkan ID yang salah eja mengembalikan did_you_mean: "gpt-5.6-terra". Klien Anda harus bereaksi dalam urutan ini:

1. Jangan ulangi permintaan tanpa perubahan. Panduan kesalahan menandai 400, 403, dan 404 sebagai tidak dapat diulang.
2. Perlakukan did_you_mean sebagai saran. Beralihlah hanya jika produk Anda sudah memiliki izin untuk mengubah model.
3. Jika body 503 mengatakan retryable: false, berhentilah mencoba lagi. Dokumentasi mengatakan nama yang mirip tidak membuktikan ketersediaan.
4. Simpan Request ID dari header respons dengan model dan ID pekerjaan Anda sendiri.
5. Beri tahu manusia. ID yang disematkan yang hilang adalah peristiwa rilis, bukan kesalahan sementara.

Sematkan ID yang tepat atau ikuti alias

Panduan best-practices (diamati 2026-10-03) mengatakan untuk menjaga ID model tetap eksplisit dalam setiap permintaan dan tidak beralih model secara diam-diam. Panduan tersebut memperingatkan bahwa penggantian dapat mengubah kualitas, harga, panjang konteks, alat, atau dukungan media. Panduan kesalahan menambahkan bahwa TokenLab tidak secara diam-diam mengganti model yang Anda kirim.

Strategi	Perilaku	Risiko utama
Sematkan ID yang tepat seperti gpt-5.5	Anda mendapatkan model tersebut, atau kesalahan	Kegagalan total jika ID dihapus
Ikuti alias	Nama mungkin mengarah ke tempat baru seiring waktu	Perilaku dan biaya dapat berubah tanpa perubahan kode
Nama rute internal dalam konfigurasi Anda	Kode Anda meminta primary_chat; konfigurasi memetakannya ke ID yang tepat	Anda memiliki dan menguji pemetaan tersebut

Mengenai alias, kami menemukan celah. Referensi List Models mengatakan tokenlab.aliases ada pada setiap item. Tidak satu pun dari lima kutipan langsung yang kami miliki (claude-sonnet-5, deepseek-v4-pro, deepseek-v4-flash, glm-5.2, gpt-5.5) menunjukkan nilai alias. Kami tidak dapat memberi tahu Anda alias apa yang dimiliki model tersebut saat ini. Skrip di atas mencetak aliases untuk setiap dependensi, jadi jalankan dan baca outputnya.

Dua fakta katalog lagi membantu. Katalog 2026-10-02 mencantumkan versi sebagai ID tepat yang terpisah, misalnya claude-sonnet-4-6, claude-sonnet-5, dan claude-sonnet-5-5. Terdaftar berdampingan tidak membuat salah satunya menjadi penerus. Nilai replacement adalah satu-satunya tempat hubungan tersebut harus berasal. Satu ID, grok-voice-latest, memiliki "latest" dalam namanya. Kami tidak memiliki bukti tentang apa yang diikutinya, jadi periksa halaman modelnya sebelum mempercayainya. ID dengan awalan gaya marketplace bukanlah alias TokenLab. Panduan migrasi mengatakan ID TokenLab tidak membawa awalan penyedia OpenRouter, dan menyarankan untuk menjaga alias LiteLLM Anda sendiri terpisah dari ID TokenLab.

Pola fallback untuk model yang disematkan yang menghilang

Perlakukan fallback sebagai model kedua yang disematkan yang telah Anda uji sebelumnya. Pilih fallback per situs panggilan, catat model mana yang melayani setiap jawaban, dan verifikasi dengan skrip harian yang sama. Bandingkan kedua model sebelum Anda memasangkannya:

Model (API langsung, diamati 2026-10-03)	Input / output per 1 juta token	Maks token input / output	Format permintaan	Kemampuan yang tercantum
gpt-5.5	$1.50 / $9.00	1.000.000 / 128.000	openai_chat_completions, openai_responses	coding, json-mode, prompt-cache, reasoning, tool-use, vision
claude-sonnet-5	$0.90 / $4.50	1.000.000 / 128.000	anthropic_messages, openai_chat_completions	json-mode, prompt-cache, reasoning, tool-use, vision
deepseek-v4-pro	$0.66 / $1.98 off-peak; $1.32 / $3.96 peak	1.000.000 / 384.000	anthropic_messages, openai_chat_completions, openai_responses	json-mode, prompt-cache, tool-use

Harga untuk ketiganya terakhir diperbarui 2026-10-02T16:53:30.068Z. Perbedaannya penting. claude-sonnet-5 tidak menerima openai_responses, jadi pemanggil berbasis Responses tidak dapat melakukan fallback ke model tersebut. deepseek-v4-pro tidak mencantumkan vision maupun reasoning, jadi permintaan yang membawa gambar akan rusak di sana. Jendela puncak (peak) DeepSeek berjalan pukul 09:00-12:00 dan 14:00-18:00 waktu Beijing.

Berikut adalah estimasi biaya dengan perhitungan yang ditampilkan. Asumsikan beban harian 10 juta input dan 2 juta output token, yang merupakan angka ilustrasi kami, bukan pengukuran:

• gpt-5.5: 10 × $1.50 + 2 × $9.00 = $15 + $18 = $33 per hari.
• claude-sonnet-5: 10 × $0.90 + 2 × $4.50 = $9 + $9 = $18 per hari.
• deepseek-v4-pro off-peak: 10 × $0.66 + 2 × $1.98 = $6.60 + $3.96 = $10.56 per hari.
• deepseek-v4-pro peak: 10 × $1.32 + 2 × $3.96 = $13.20 + $7.92 = $21.12 per hari.

Ini adalah estimasi, dan input yang di-cache dihargai secara berbeda. Kode di bawah ini hanya melakukan fallback pada kesalahan yang tidak dapat diperbaiki dengan mencoba lagi. 429 atau 5xx yang dapat dicoba lagi harus mengikuti aturan percobaan ulang yang normal.

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,  # kita memutuskan apa yang aman untuk diulang
)

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):
    """Kembalikan (model_yang_menjawab, teks). Catat model dengan hasilnya."""
    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 dan sejenisnya memerlukan perbaikan berbeda
        log.warning("model yang disematkan %s tidak tersedia (%s); menggunakan %s",
                    cfg["model"], code, cfg["fallback"])
        return cfg["fallback"], _chat(cfg["fallback"], text)

Fallback melompat sekali dan tidak pernah berantai. Jika fallback juga gagal, munculkan kesalahan dan panggil seseorang. Rantai substitusi diam-diam adalah masalah pergeseran dengan nama lain.

Daftar periksa rilis untuk deprekasi dan pembuatan versi model AI

Jalankan ini sebelum mengubah ID model produksi. Ini mencerminkan panduan best-practices (diamati 2026-10-03) dan menambahkan pemeriksaan siklus hidup.

1. Daftarkan setiap ID model dalam produksi dan beri nama situs panggilan yang menggunakan masing-masing ID. Satu lapisan konfigurasi harus menjawab ini dalam hitungan detik.
2. Jalankan skrip siklus hidup terhadap ID saat ini dan kandidat. Baca deprecated_at, retired_at, tahapan, dan penggantian.
3. Konfirmasikan kandidat menerima format permintaan yang dikirim kode Anda, menggunakan accepted_request_formats dari Get a Model.
4. Bandingkan token input maks dan output maks terhadap permintaan nyata terpanjang Anda dan batas output Anda.
5. Bandingkan kemampuan. Konfirmasikan vision, tool-use, json-mode, dan reasoning di mana produk Anda bergantung padanya.
6. Hitung ulang biaya dari harga saat ini, dengan perhitungan yang ditampilkan. Untuk DeepSeek, pisahkan peak dan off-peak.
7. Putar ulang permintaan representatif dengan ID kandidat dan format yang tepat yang akan Anda kirim. Sertakan satu kasus kegagalan, seperti ID yang tidak diketahui.
8. Verifikasi jalur kesalahan. Klien Anda harus melakukan percabangan pada code, menyimpan Request ID, dan tidak mencoba ulang 400, 403, atau 404.
9. Kirim perubahan sebagai edit konfigurasi dengan ID lama disimpan sebagai nilai rollback yang didokumentasikan.
10. Periksa bahwa setiap catatan respons menyimpan model yang sebenarnya melayaninya.
11. Jalankan kembali skrip harian setelah rilis. Konfirmasikan ID fallback juga lulus.

Di mana dokumentasi diam, daftar periksa adalah perlindungannya. Mereka tidak memberikan waktu tunggu deprekasi dan tidak ada saluran pemberitahuan. Verifikasi pemberitahuan penyedia secara terpisah, dan periksa halaman model itu sendiri untuk catatan siklus hidup apa pun.

FAQ

Bagaimana cara mengetahui apakah model TokenLab dideprekasi atau dihentikan?

Panggil GET /v1/models/{model} dan baca tokenlab.lifecycle. Periksa tahapannya, deprecated_at, retired_at, dan model penggantinya. Per 2026-10-03, kelima model yang kami baca semuanya active tanpa tanggal yang ditetapkan. Lakukan polling lagi, karena nilainya hanya mencerminkan saat Anda bertanya.

Status HTTP apa yang dikembalikan oleh ID model yang tidak diketahui?

Itu tergantung pada endpoint. Get a Model mengembalikan 404 model_not_found, sementara permintaan obrolan dengan model yang buruk mengembalikan 400 model_not_found. Model tanpa pasokan di tier Pengiriman yang dipilih mengembalikan 503. Lakukan percabangan pada field code.

Haruskah saya mencoba ulang kesalahan model_not_found?

Tidak. Mengulangi permintaan yang sama tidak akan mengubah hasilnya. Periksa did_you_mean dan suggestions jika ada, tetapi beralihlah model hanya jika produk Anda sudah memiliki izin untuk melakukannya. Jika tidak, gunakan fallback yang telah disetujui sebelumnya dan beri tahu tim Anda.

Akankah TokenLab mengalihkan permintaan saya ke model lain jika model saya menghilang?

Dokumentasi mengatakan mereka tidak secara diam-diam mengganti model yang Anda kirim. Kirim ID eksplisit dan tangani kesalahan sendiri. Fallback Anda harus berupa nilai konfigurasi yang diuji, bukan asumsi tentang platform.

Bandingkan ID, batas, dan harga saat ini di direktori model sebelum perubahan model Anda berikutnya.