إيقاف نماذج الذكاء الاصطناعي وإصداراتها: الحفاظ على استقرار تكاملات الـ API

سلسلة تعريف النموذج (model string) هي الثابت الأكثر خطورة في قاعدة الكود الخاصة بك. تتعامل معها الفرق كأنها مجرد تسمية، ومع ذلك فهي التي تقرر أي نقطة فحص (checkpoint) ستقدم الإجابة، وما هي تكلفة الاستدعاء، وما إذا كان الطلب سينجح من الأساس. لذلك، يجب أن يكون إيقاف دعم نماذج الذكاء الاصطناعي وإصداراتها جزءاً من عملية الإصدار الخاصة بك، وليس قراراً يُتخذ مرة واحدة عند الإطلاق. يستخدم هذا الدليل واجهة برمجة تطبيقات النماذج العامة لـ TokenLab، كما رُصدت في 2026-10-03، لتوضيح ما يمكنك التحقق منه تلقائياً، وما يجب عليك التحقق منه في مكان آخر، وما يجب فعله عندما يتوقف معرف (ID) معين عن العمل.

أهم النقاط

• توجد بيانات دورة الحياة (Lifecycle) في كائن النموذج. اقرأ tokenlab.lifecycle من Get a Model (تم الرصد في 2026-10-03) بدلاً من نسخ التواريخ من منشور مدونة.
• جميع النماذج الخمسة التي فحصناها في 2026-10-03 كانت في حالة active (نشطة) بدون تاريخ إيقاف دعم أو تقاعد. لا تحتوي أدلتنا على أي نموذج متوقف فعلياً، لذا فإن مسار الفشل الموضح أدناه هو سلوك موثق، وليس شيئاً شهدنا حدوثه.
• النموذج المفقود يُرجع model_not_found، لكن الحالة تختلف حسب نقطة النهاية (endpoint). قم بالتفرع بناءً على code، ولا تعتمد على الحالة (status) وحدها أبداً.
• ثبّت المعرفات الدقيقة واحتفظ بها في طبقة إعدادات واحدة. تؤكد TokenLab أنها لا تستبدل النموذج الذي ترسلُه بشكل صامت.
• يجب أن يكون النموذج البديل (fallback) خياراً مختبراً ومعتمداً مسبقاً. تختلف القدرات، وتنسيقات الطلبات، والحدود، والأسعار بين النماذج.

أين يظهر إيقاف دعم نماذج الذكاء الاصطناعي وإصداراتها في API

يشير مرجع Get a Model (تم الرصد في 2026-10-03) إلى أن حقل lifecycle يغطي التوفر، وتاريخ الإصدار، وتاريخ إيقاف الدعم، والنموذج البديل. ويضيف مرجع List Models (تم الرصد في 2026-10-03) كلاً من tokenlab.lifecycle، وtokenlab.aliases، وtokenlab.commercial، وtokenlab.badges لكل عنصر في القائمة. كما تسرد الصفحة نفسها tokenlab.accepted_request_formats وحدود التوكن، وهي أمور مهمة لأي عملية تبديل.

إليك ما قرأناه من واجهة برمجة تطبيقات النماذج الحية للنموذج claude-sonnet-5 في 2026-10-03. هذا عرض مكثف للقيم المرصودة. سجلت أدلتنا القيم، وليس أسماء المفاتيح المتداخلة الخام، لذا تأكد من المفاتيح الدقيقة مقابل استجابة حية.

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

قم بتعيين مفاهيم دورة الحياة الخمسة على تلك الحقول كما يلي:

المفهوم	الحقل في الاستجابة المرصودة	القيمة لـ claude-sonnet-5
المرحلة	lifecycle stage	active
الإصدار	released	2026-06-30
إيقاف الدعم	deprecated_at	None
التقاعد	retired_at	None
الاستبدال	replacement model	None

القيمة الفارغة لا تشير دائماً إلى وجود مشكلة. بالنسبة لـ glm-5.2 وgpt-5.5، تظهر واجهة API الحية (تم الرصد في 2026-10-03) قيمة released كـ None بينما المرحلة هي active. يجب أن يفشل الفحص عند وجود قيمة لـ deprecated_at، أو retired_at، أو مرحلة غير نشطة. لا ينبغي أن يفشل بسبب تاريخ إصدار مفقود.

قرأنا أيضاً deepseek-v4-pro وdeepseek-v4-flash (كلاهما أُصدرا في 2026-04-24، وكلاهما نشط، ولا يوجد بديل). هذا يجعل خمسة نماذج بدون إشارة إيقاف دعم. حقل الاستبدال الخاص بنموذج متوقف هو القيمة الوحيدة التي لم نتمكن من رصدها وهي ممتلئة.

سكربت يفشل عندما تتعطل إحدى التبعيات

يستخدم الفحص أدناه فقط نقطة النهاية الموثقة GET /v1/models/{model}، والتي لا تحتاج إلى مفتاح API لأن الكتالوج عام. يفشل الفحص عند فقدان المعرف (ID)، أو وجود قيمة لـ deprecated_at أو retired_at، أو مرحلة غير نشطة، أو تنسيق طلب لم يعد النموذج يقبله.

#!/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()

قم بتشغيله في CI وفي جدول زمني ليلي، لأن النموذج يمكن أن يغير حالته دون التزام (commit) من جانبك. تخيل وظيفة ليلية تخرج برمز الخطأ 1 يوم الثلاثاء بينما كان آخر إصدار لك قبل أسبوع. هذا هو الهدف: يظهر الفشل في خط الأنابيب (pipeline)، وليس في نافذة دردشة العميل. يطبع السكربت كتلة دورة الحياة بالكامل عند الفشل حتى يرى الشخص قيمة الاستبدال دون تخمين أسماء المفاتيح.

ما الذي يُرجعه نموذج متقاعد أو غير معروف

توثق الأدلة النماذج غير المعروفة وغير المتاحة، وليس استجابة مصنفة بـ "متقاعد" بشكل منفصل. لذلك نتعامل مع التقاعد كعائلة الأخطاء نفسها حتى تثبت خلاف ذلك. إليك ما تقوله المستندات، وكلها رُصدت في 2026-10-03:

المكان	الاستجابة	المصدر
GET /v1/models/{model}	404 model_not_found	Get a Model
طلب دردشة بنموذج مكتوب بشكل خاطئ أو غير متاح	400 model_not_found، اختيارياً مع did_you_mean، suggestions، hint	Errors agents can act on
العملية ليس لها إمداد في فئة التسليم المحددة	503 all_channels_failed أو 503 delivery_tier_unavailable، retryable: false	Errors agents can act on
المفتاح يفتقر إلى إذن للنموذج	403 model_not_allowed	Handle API errors

تختلف رموز الحالة عبر نقاط النهاية، لذا يهم إصلاح واحد: كود البديل في مقالتنا المصدرية تعامل مع 404 و410 على أنهما "المعرف مفقود". هذا خطأ بالنسبة لطلبات الدردشة. استجابة الدردشة الموثقة هي 400، ويقول دليل الأخطاء بالتعامل مع الأخطاء حسب حالة HTTP وcode. اجعل منطقك يعتمد على code == "model_not_found".

على سبيل المثال، تُظهر المستندات معرفاً مكتوباً بشكل خاطئ يُرجع did_you_mean: "gpt-5.6-terra". يجب أن يتفاعل عميلك بهذا الترتيب:

1. لا تكرر الطلب دون تغيير. يحدد دليل الأخطاء 400 و403 و404 كأخطاء غير قابلة للتكرار.
2. عامل did_you_mean كاقتراح. قم بالتبديل فقط إذا كان منتجك يمتلك بالفعل إذناً لتغيير النموذج.
3. إذا كان نص 503 يقول retryable: false، توقف عن إعادة المحاولة. تقول المستندات إن الأسماء المتشابهة لا تثبت التوفر.
4. احفظ معرف الطلب (Request ID) من رؤوس الاستجابة مع النموذج ومعرف الوظيفة الخاص بك.
5. نبه بشراً. المعرف المثبت الذي اختفى هو حدث إصدار، وليس خطأ عابراً.

تثبيت معرف دقيق أو اتباع اسم مستعار (alias)

يقول دليل أفضل الممارسات (تم الرصد في 2026-10-03) بضرورة إبقاء معرف النموذج صريحاً في كل طلب وعدم تبديل النماذج بصمت. ويحذر من أن الاستبدال يمكن أن يغير الجودة، والسعر، وطول السياق، والأدوات، أو دعم الوسائط. ويضيف دليل الأخطاء أن TokenLab لا تستبدل النموذج الذي ترسلُه بصمت.

الاستراتيجية	السلوك	المخاطرة الرئيسية
تثبيت معرف دقيق مثل gpt-5.5	تحصل على ذلك النموذج، أو خطأ	فشل حاد إذا تمت إزالة المعرف
اتباع اسم مستعار	قد يشير الاسم إلى مكان جديد بمرور الوقت	قد يتغير السلوك والتكلفة دون تغيير الكود
اسم مسار داخلي في إعداداتك	يطلب كودك primary_chat؛ وتعيّنه الإعدادات لمعرف دقيق	أنت تمتلك وتختبر التعيين

بخصوص الأسماء المستعارة، وجدنا فجوة. يقول مرجع List Models إن tokenlab.aliases موجود في كل عنصر. لا تُظهر أي من المقتطفات الحية الخمسة التي لدينا (claude-sonnet-5، deepseek-v4-pro، deepseek-v4-flash، glm-5.2، gpt-5.5) قيمة اسم مستعار. لا يمكننا إخبارك بالأسماء المستعارة التي تمتلكها تلك النماذج اليوم. يطبع السكربت أعلاه aliases لكل تبعية، لذا قم بتشغيله واقرأ المخرجات.

تساعد حقيقتان إضافيتان عن الكتالوج. يسرد كتالوج 2026-10-02 الإصدارات كمعرفات دقيقة منفصلة، على سبيل المثال claude-sonnet-4-6، وclaude-sonnet-5، وclaude-sonnet-5-5. كونها مدرجة جنباً إلى جنب لا يجعل أحدهما خليفة للآخر. قيمة replacement هي المكان الوحيد الذي يجب أن تأتي منه تلك العلاقة. معرف واحد، grok-voice-latest، يحتوي على "latest" في اسمه. ليس لدينا دليل على ما يتبعه، لذا تحقق من صفحة النموذج الخاصة به قبل الوثوق به. المعرفات ذات البادئات على طراز السوق ليست أسماء مستعارة لـ TokenLab. يقول دليل الترحيل إن معرفات TokenLab لا تحمل بادئة مزود OpenRouter، ويقترح الاحتفاظ باسم مستعار LiteLLM الخاص بك منفصلاً عن معرف TokenLab.

نمط بديل لنموذج مثبت يختفي

تعامل مع البديل كنموذج مثبت ثانٍ اختبرته مسبقاً. اختره لكل موقع استدعاء، وسجل النموذج الذي قدم كل إجابة، وتحقق منه باستخدام نفس السكربت الليلي. قارن بين النموذجين قبل ربطهما:

النموذج (API حي، رُصد 2026-10-03)	الإدخال / الإخراج لكل مليون توكن	أقصى توكنات إدخال / إخراج	تنسيقات الطلبات	القدرات المدرجة
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 خارج الذروة; $1.32 / $3.96 ذروة	1,000,000 / 384,000	anthropic_messages, openai_chat_completions, openai_responses	json-mode, prompt-cache, tool-use

تم تحديث أسعار الثلاثة جميعاً آخر مرة في 2026-10-02T16:53:30.068Z. الاختلافات مهمة. لا يقبل claude-sonnet-5 تنسيق openai_responses، لذا لا يمكن للمتصل الذي يعتمد على Responses العودة إليه. لا يدرج deepseek-v4-pro الرؤية (vision) ولا الاستدلال (reasoning)، لذا فإن أي طلب يحتوي على صورة سيتعطل هناك. تعمل فترات الذروة لـ DeepSeek من 09:00 إلى 12:00 ومن 14:00 إلى 18:00 بتوقيت بكين.

إليك تقدير للتكلفة مع توضيح العمليات. افترض حملاً يومياً قدره 10 ملايين توكن إدخال و2 مليون توكن إخراج، وهو رقم توضيحي وليس قياساً:

• gpt-5.5: 10 × $1.50 + 2 × $9.00 = $15 + $18 = $33 يومياً.
• claude-sonnet-5: 10 × $0.90 + 2 × $4.50 = $9 + $9 = $18 يومياً.
• deepseek-v4-pro خارج الذروة: 10 × $0.66 + 2 × $1.98 = $6.60 + $3.96 = $10.56 يومياً.
• deepseek-v4-pro ذروة: 10 × $1.32 + 2 × $3.96 = $13.20 + $7.92 = $21.12 يومياً.

هذه تقديرات، ويتم تسعير الإدخال المخزن مؤقتاً بشكل مختلف. الكود أدناه يعود للبديل فقط عند الأخطاء التي لا يمكن لإعادة المحاولة إصلاحها. يجب أن يتبع خطأ 429 أو خطأ 5xx القابل لإعادة المحاولة قواعد إعادة المحاولة العادية بدلاً من ذلك.

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)

يقوم البديل بالتبديل مرة واحدة ولا يتسلسل. إذا فشل البديل أيضاً، ارفع الخطأ وقم بتنبيه شخص ما. سلسلة صامتة من الاستبدالات هي مشكلة الانحراف تحت اسم آخر.

قائمة مراجعة الإصدار لإيقاف دعم نماذج الذكاء الاصطناعي وإصداراتها

قم بتشغيل هذا قبل تغيير معرف نموذج في الإنتاج. إنه يعكس دليل أفضل الممارسات (تم الرصد في 2026-10-03) ويضيف فحوصات دورة الحياة.

1. ادرج كل معرف نموذج في الإنتاج وقم بتسمية موقع الاستدعاء الذي يستخدم كل واحد منها. يجب أن تجيب طبقة إعدادات واحدة على هذا في ثوانٍ.
2. قم بتشغيل سكربت دورة الحياة مقابل المعرفات الحالية والمرشحة. اقرأ deprecated_at، وretired_at، والمرحلة، والبديل.
3. تأكد من أن المرشح يقبل تنسيق الطلب الذي يرسله كودك، باستخدام accepted_request_formats من Get a Model.
4. قارن أقصى توكنات إدخال وإخراج مقابل أطول طلب حقيقي لك وسقف المخرجات الخاص بك.
5. قارن القدرات. تأكد من الرؤية، واستخدام الأدوات، ووضع JSON، والاستدلال حيث يعتمد منتجك عليها.
6. أعد حساب التكلفة من الأسعار الحالية، مع توضيح العمليات. بالنسبة لـ DeepSeek، افصل بين الذروة وخارج الذروة.
7. أعد تشغيل الطلبات التمثيلية بمعرف المرشح الدقيق والتنسيق الذي ستطلقه. قم بتضمين حالة فشل واحدة، مثل معرف غير معروف.
8. تحقق من مسار الخطأ. يجب أن يتفرع عميلك بناءً على code، ويحتفظ بمعرف الطلب، ولا يعيد محاولة 400 أو 403 أو 404.
9. أطلق التغيير كتعديل في الإعدادات مع الاحتفاظ بالمعرف القديم كقيمة تراجع موثقة.
10. تحقق من أن كل سجل استجابة يخزن النموذج الذي قدمها فعلياً.
11. أعد تشغيل السكربت الليلي بعد الإصدار. تأكد من أن معرف البديل يمر أيضاً.

حيث تكون المستندات صامتة، تكون قائمة المراجعة هي الضمان. فهي لا تعطي مهلة زمنية لإيقاف الدعم ولا قناة إشعار. تحقق من إشعارات المزود بشكل منفصل، وافحص صفحة النموذج نفسها لأي ملاحظات حول دورة الحياة.

الأسئلة الشائعة

كيف أعرف ما إذا كان نموذج TokenLab متوقفاً عن الدعم أو متقاعداً؟

اتصل بـ GET /v1/models/{model} واقرأ tokenlab.lifecycle. تحقق من المرحلة، وdeprecated_at، وretired_at، والنموذج البديل. اعتباراً من 2026-10-03، كانت النماذج الخمسة التي قرأناها جميعاً active بدون تحديد تواريخ. استعلم مرة أخرى، لأن القيمة تعكس فقط اللحظة التي سألت فيها.

ما هي حالة HTTP التي يُرجعها معرف نموذج غير معروف؟

يعتمد ذلك على نقطة النهاية. تُرجع Get a Model رمز 404 model_not_found، بينما يُرجع طلب الدردشة بنموذج سيئ 400 model_not_found. يُرجع النموذج الذي ليس له إمداد في فئة التسليم المحددة رمز 503. تفرع بناءً على حقل code.

هل يجب أن أعيد محاولة خطأ model_not_found؟

لا. تكرار نفس الطلب لن يغير النتيجة. تحقق من did_you_mean وsuggestions إذا كانت موجودة، ولكن قم بتبديل النماذج فقط عندما يمتلك منتجك إذناً بذلك بالفعل. خلاف ذلك، استخدم بديلاً معتمداً مسبقاً ونبه فريقك.

هل ستقوم TokenLab بتبديل طلبي إلى نموذج آخر إذا اختفى نموذجي؟

تقول المستندات إنها لا تستبدل النموذج الذي ترسلُه بصمت. أرسل معرفاً صريحاً وتعامل مع الخطأ بنفسك. يجب أن يكون بديلك قيمة إعدادات مختبرة، وليس افتراضاً حول المنصة.

قارن المعرفات الحالية، والحدود، والأسعار في دليل النماذج قبل تغيير نموذجك القادم.