Dépréciation et versionnage des modèles d'IA : maintenir la stabilité des intégrations API

Une chaîne de caractères identifiant un modèle est la constante la plus dangereuse de votre base de code. Les équipes la traitent comme une simple étiquette, alors qu'elle détermine quel point de contrôle répond, le coût de l'appel et si la requête aboutira ou non. La dépréciation et le versionnage des modèles d'IA doivent donc faire partie intégrante de votre processus de publication, et non d'une décision prise une seule fois lors du lancement. Ce guide utilise l'API publique des modèles de TokenLab, telle qu'observée le 03/10/2026, pour montrer ce que vous pouvez vérifier automatiquement, ce que vous devez vérifier ailleurs et ce qu'il faut faire lorsqu'un ID cesse de fonctionner.

Points clés à retenir

• Les données relatives au cycle de vie se trouvent sur l'objet modèle. Lisez tokenlab.lifecycle depuis Get a Model (observé le 03/10/2026) au lieu de copier des dates depuis un article de blog.
• Les cinq modèles que nous avons vérifiés le 03/10/2026 étaient active, sans date de dépréciation ou de retrait. Nos preuves ne contiennent aucun modèle réellement déprécié ; le chemin d'échec ci-dessous est donc un comportement documenté, et non un événement que nous avons constaté.
• Un modèle manquant renvoie model_not_found, mais le statut diffère selon le point de terminaison. Effectuez une branchement sur le code, jamais sur le statut seul.
• Épinglez les ID exacts et conservez-les dans une couche de configuration unique. TokenLab indique qu'il ne remplace pas silencieusement le modèle que vous envoyez.
• Un recours (fallback) doit être un choix testé et pré-approuvé. Les capacités, les formats de requête, les limites et les prix diffèrent tous d'un modèle à l'autre.

Où la dépréciation et le versionnage des modèles d'IA apparaissent dans l'API

La référence Get a Model (observée le 03/10/2026) indique que le champ lifecycle couvre la disponibilité, la date de sortie, la date de dépréciation et le modèle de remplacement. La référence List Models (observée le 03/10/2026) ajoute tokenlab.lifecycle, tokenlab.aliases, tokenlab.commercial et tokenlab.badges à chaque élément de la liste. La même page répertorie tokenlab.accepted_request_formats et les limites de jetons, ce qui est important pour tout remplacement.

Voici ce que nous avons lu depuis l'API de modèle en direct pour claude-sonnet-5 le 03/10/2026. Il s'agit d'un rendu condensé des valeurs observées. Nos preuves ont enregistré les valeurs, et non les noms de clés imbriquées brutes, alors confirmez les clés exactes par rapport à une réponse en direct.

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

Mappez les cinq concepts de cycle de vie sur ces champs comme suit :

Concept	Champ dans la réponse observée	Valeur pour claude-sonnet-5
Étape	lifecycle stage	active
Sortie	released	2026-06-30
Dépréciation	deprecated_at	None
Retrait	retired_at	None
Remplacement	replacement model	None

Une valeur vide ne signale pas toujours un problème. Pour glm-5.2 et gpt-5.5, l'API en direct (observée le 03/10/2026) affiche released comme None alors que l'étape est active. Une vérification doit échouer sur un deprecated_at défini, un retired_at défini ou une étape non active. Elle ne doit pas échouer sur une date de sortie manquante.

Nous avons également lu deepseek-v4-pro et deepseek-v4-flash (tous deux sortis le 24/04/2026, tous deux actifs, aucun remplacement). Cela fait cinq modèles sans signal de dépréciation. Le champ de remplacement d'un modèle déprécié est la seule valeur que nous n'avons pas pu observer comme étant renseignée.

Un script qui échoue lorsqu'une dépendance devient défaillante

La vérification ci-dessous utilise uniquement le point de terminaison documenté GET /v1/models/{model}, qui ne nécessite aucune clé API car le catalogue est public. Elle échoue sur un ID manquant, un deprecated_at ou retired_at défini, une étape non active, ou un format de requête que le modèle n'accepte plus.

#!/usr/bin/env python3
"""Fail when a model ID we depend on is missing, deprecated, or retired."""
import json
import sys
import urllib.error
import urllib.request

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

# model ID -> the request format our code actually sends
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"could not verify: {exc.reason}"], {}, []
    if status in (400, 404):
        return [f"missing: HTTP {status}"], {}, []
    if status != 200:
        return [f"could not verify: HTTP {status}"], {}, []

    info = body.get("tokenlab", {})
    life = info.get("lifecycle") or {}
    problems = []
    if not life:
        problems.append("no lifecycle block returned")
    stage = life.get("stage")  # confirm the exact key against a live response
    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} not accepted")
    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()

Exécutez-le en CI et selon un calendrier nocturne, car un modèle peut changer d'état sans commit de votre côté. Imaginez une tâche nocturne qui renvoie un code de sortie 1 un mardi alors que votre dernier déploiement remonte à une semaine. C'est là tout l'intérêt : l'échec apparaît dans un pipeline, et non dans la fenêtre de chat d'un client. Le script imprime tout le bloc de cycle de vie en cas d'échec afin qu'un humain puisse voir la valeur de remplacement sans deviner les noms de clés.

Ce qu'un modèle retiré ou inconnu renvoie

Les preuves documentent les modèles inconnus et indisponibles, et non une réponse étiquetée séparément comme "retirée". Nous traitons donc le retrait comme la même famille d'erreurs jusqu'à preuve du contraire. Voici ce que disent les documents, tous observés le 03/10/2026 :

Où	Réponse	Source
GET /v1/models/{model}	404 model_not_found	Get a Model
Requête de chat avec un modèle mal orthographié ou indisponible	400 model_not_found, éventuellement avec did_you_mean, suggestions, hint	Errors agents can act on
L'opération n'a pas d'offre dans le niveau de livraison sélectionné	503 all_channels_failed ou 503 delivery_tier_unavailable, retryable: false	Errors agents can act on
La clé manque de permission pour le modèle	403 model_not_allowed	Handle API errors

Les codes de statut diffèrent selon les points de terminaison, donc une correction est importante : le code de recours de notre article source traitait 404 et 410 comme "identifiant disparu". C'est faux pour les requêtes de chat. La réponse de chat documentée est 400, et le guide des erreurs indique de gérer les erreurs par statut HTTP et code. Basez votre logique sur code == "model_not_found".

Par exemple, les documents montrent qu'un ID mal orthographié renvoie did_you_mean: "gpt-5.6-terra". Votre client doit réagir dans cet ordre :

1. Ne répétez pas la requête sans modification. Le guide des erreurs marque 400, 403 et 404 comme non répétables.
2. Traitez did_you_mean comme une suggestion. Ne changez que si votre produit a déjà la permission de changer de modèle.
3. Si le corps de la réponse 503 indique retryable: false, arrêtez de réessayer. Les documents indiquent que des noms similaires ne prouvent pas la disponibilité.
4. Enregistrez l'ID de requête des en-têtes de réponse avec le modèle et votre propre ID de tâche.
5. Alertez un humain. Un ID épinglé qui a disparu est un événement de publication, pas une erreur transitoire.

Épingler un ID exact ou suivre un alias

Le guide des meilleures pratiques (observé le 03/10/2026) indique de garder l'ID du modèle explicite dans chaque requête et de ne pas changer de modèle silencieusement. Il avertit qu'un remplacement peut modifier la qualité, le prix, la longueur du contexte, les outils ou la prise en charge des médias. Le guide des erreurs ajoute que TokenLab ne remplace pas silencieusement le modèle que vous envoyez.

Stratégie	Comportement	Risque principal
Épingler un ID exact tel que gpt-5.5	Vous obtenez ce modèle, ou une erreur	Un échec critique si l'ID est supprimé
Suivre un alias	Le nom peut pointer vers un nouvel endroit au fil du temps	Le comportement et le coût peuvent changer sans changement de code
Nom de route interne dans votre configuration	Votre code demande primary_chat ; la configuration le mappe vers un ID exact	Vous possédez et testez le mappage

Sur les alias, nous avons trouvé une lacune. La référence List Models indique que tokenlab.aliases existe sur chaque élément. Aucun des cinq extraits en direct que nous avons (claude-sonnet-5, deepseek-v4-pro, deepseek-v4-flash, glm-5.2, gpt-5.5) n'affiche de valeur d'alias. Nous ne pouvons pas vous dire quels alias ces modèles ont aujourd'hui. Le script ci-dessus imprime les aliases pour chaque dépendance, alors exécutez-le et lisez la sortie.

Deux autres faits sur le catalogue aident. Le catalogue du 02/10/2026 répertorie les versions comme des ID exacts distincts, par exemple claude-sonnet-4-6, claude-sonnet-5 et claude-sonnet-5-5. Être répertorié côte à côte ne fait pas de l'un le successeur de l'autre. La valeur replacement est le seul endroit d'où cette relation devrait provenir. Un ID, grok-voice-latest, contient "latest" dans son nom. Nous n'avons aucune preuve de ce qu'il suit, alors vérifiez sa page de modèle avant de lui faire confiance. Les ID préfixés de style place de marché ne sont pas des alias TokenLab. Le guide de migration indique que les ID TokenLab ne comportent aucun préfixe de fournisseur OpenRouter, et il suggère de garder votre propre alias LiteLLM séparé de l'ID TokenLab.

Un modèle de recours pour un modèle épinglé qui disparaît

Traitez un recours comme un second modèle épinglé que vous avez testé à l'avance. Choisissez-le par site d'appel, enregistrez quel modèle a servi chaque réponse et vérifiez-le avec le même script nocturne. Comparez les deux modèles avant de les associer :

Modèle (API en direct, observée le 03/10/2026)	Entrée / sortie par 1M de jetons	Max jetons d'entrée / sortie	Formats de requête	Capacités listées
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 $ hors pointe ; 1,32 $ / 3,96 $ pointe	1 000 000 / 384 000	anthropic_messages, openai_chat_completions, openai_responses	json-mode, prompt-cache, tool-use

La tarification pour les trois a été mise à jour pour la dernière fois le 02/10/2026 à 16:53:30.068Z. Les différences comptent. claude-sonnet-5 n'accepte pas openai_responses, donc un appelant basé sur Responses ne peut pas y avoir recours. deepseek-v4-pro ne liste ni vision ni raisonnement, donc une requête contenant une image y échouera. Les fenêtres de pointe de DeepSeek vont de 09h00 à 12h00 et de 14h00 à 18h00, heure de Pékin.

Voici une estimation des coûts avec le détail des calculs. Supposons une charge quotidienne de 10M de jetons d'entrée et 2M de jetons de sortie, ce qui est notre chiffre illustratif, et non une mesure :

• gpt-5.5 : 10 × 1,50 $ + 2 × 9,00 $ = 15 $ + 18 $ = 33 $ par jour.
• claude-sonnet-5 : 10 × 0,90 $ + 2 × 4,50 $ = 9 $ + 9 $ = 18 $ par jour.
• deepseek-v4-pro hors pointe : 10 × 0,66 $ + 2 × 1,98 $ = 6,60 $ + 3,96 $ = 10,56 $ par jour.
• deepseek-v4-pro pointe : 10 × 1,32 $ + 2 × 3,96 $ = 13,20 $ + 7,92 $ = 21,12 $ par jour.

Ce sont des estimations, et l'entrée mise en cache est tarifée différemment. Le code ci-dessous n'a recours qu'aux erreurs que les tentatives ne peuvent pas corriger. Une erreur 429 ou une erreur 5xx répétable doit suivre les règles de répétition normales.

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,  # we decide what is safe to repeat
)

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):
    """Return (model_that_answered, text). Record the model with the result."""
    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 and the like need a different fix
        log.warning("pinned model %s unavailable (%s); using %s",
                    cfg["model"], code, cfg["fallback"])
        return cfg["fallback"], _chat(cfg["fallback"], text)

Le recours saute une fois et ne s'enchaîne jamais. Si le recours échoue également, levez l'erreur et alertez quelqu'un. Une chaîne silencieuse de substitutions est le problème de dérive sous un autre nom.

Liste de contrôle de publication pour la dépréciation et le versionnage des modèles d'IA

Exécutez ceci avant de changer un ID de modèle en production. Il reflète le guide des meilleures pratiques (observé le 03/10/2026) et ajoute les vérifications du cycle de vie.

1. Listez chaque ID de modèle en production et nommez le site d'appel qui utilise chacun d'eux. Une couche de configuration devrait répondre à cela en quelques secondes.
2. Exécutez le script de cycle de vie par rapport aux ID actuels et candidats. Lisez deprecated_at, retired_at, l'étape et le remplacement.
3. Confirmez que le candidat accepte le format de requête que votre code envoie, en utilisant accepted_request_formats depuis Get a Model.
4. Comparez les jetons d'entrée max et de sortie max par rapport à votre requête réelle la plus longue et votre plafond de sortie.
5. Comparez les capacités. Confirmez la vision, l'utilisation d'outils, le mode json et le raisonnement là où votre produit en dépend.
6. Recalculez le coût à partir des prix actuels, avec le détail des calculs. Pour DeepSeek, séparez les périodes de pointe et hors pointe.
7. Rejouez des requêtes représentatives avec l'ID candidat exact et le format que vous allez expédier. Incluez un cas d'échec, tel qu'un ID inconnu.
8. Vérifiez le chemin d'erreur. Votre client doit se brancher sur le code, conserver l'ID de requête et ne pas réessayer 400, 403 ou 404.
9. Expédiez le changement sous forme de modification de configuration avec l'ancien ID conservé comme valeur de retour arrière documentée.
10. Vérifiez que chaque enregistrement de réponse stocke le modèle qui l'a réellement servi.
11. Relancez le script nocturne après la publication. Confirmez que l'ID de recours passe également.

Là où les documents sont silencieux, la liste de contrôle est la sauvegarde. Ils ne donnent aucun délai de préavis de dépréciation et aucun canal de notification. Vérifiez les avis des fournisseurs séparément et consultez la page du modèle pour toute note sur le cycle de vie.

FAQ

Comment savoir si un modèle TokenLab est déprécié ou retiré ?

Appelez GET /v1/models/{model} et lisez tokenlab.lifecycle. Vérifiez l'étape, deprecated_at, retired_at et le modèle de remplacement. Au 03/10/2026, les cinq modèles que nous avons lus étaient tous active sans dates définies. Interrogez à nouveau, car la valeur ne reflète que le moment où vous avez demandé.

Quel statut HTTP renvoie un ID de modèle inconnu ?

Cela dépend du point de terminaison. Get a Model renvoie 404 model_not_found, tandis qu'une requête de chat avec un mauvais modèle renvoie 400 model_not_found. Un modèle sans offre dans le niveau de livraison sélectionné renvoie une erreur 503. Effectuez un branchement sur le champ code.

Dois-je réessayer une erreur model_not_found ?

Non. Répéter la même requête ne changera pas le résultat. Vérifiez did_you_mean et suggestions s'ils sont présents, mais ne changez de modèle que lorsque votre produit a déjà la permission de le faire. Sinon, utilisez un recours pré-approuvé et alertez votre équipe.

TokenLab changera-t-il ma requête pour un autre modèle si le mien disparaît ?

La documentation indique qu'il ne remplace pas silencieusement le modèle que vous envoyez. Envoyez un ID explicite et gérez l'erreur vous-même. Votre recours doit être une valeur de configuration testée, et non une hypothèse sur la plateforme.

Comparez les ID, limites et prix actuels dans le répertoire des modèles avant votre prochain changement de modèle.