كيفية بناء تطبيقات ذكاء اصطناعي لا تعتمد على مزوّد واحد

الارتهان للمزوّد في تطبيقات الذكاء الاصطناعي لا يحدث عادةً دفعةً واحدة. إنه يتسلّل — هنا import openai مباشر، وهناك اسم نموذج مُضمَّن صراحةً، وحقل في الاستجابة تقوم بتحليله من دون التحقق مما إذا كان المزوّدون الآخرون يُرجعون الشيء نفسه. بعد ستة أشهر، يصبح تبديل المزوّدين معناه إعادة كتابة نصف الواجهة الخلفية لديك.

الطرق الأربع التي يتسلّل بها الارتهان

معظم المطورين يظنون أن الارتهان يعني "أنا أستخدم SDK الخاص بـ OpenAI". هذا هو النوع الأقل خطورة. الفخاخ الحقيقية أكثر خفاءً:

ليس الهدف القضاء على كل ما سبق — فبعضها مقايضات مقبولة. الهدف هو أن تعرف أيّها تتبنّاه عن قصد.

استخدم نقطة نهاية متوافقة مع OpenAI كطبقة تجريد

أنظف طريقة لتجنّب الارتهان للـ SDK هي استخدام نقطة نهاية واحدة متوافقة مع OpenAI تُوجِّه الطلبات إلى مزوّدين متعددين. تحتفظ بـ SDK الخاص بـ OpenAI، لكن الواجهة الخلفية يمكن أن تكون أي مزوّد.

CometAPI تفعل ذلك — نقطة نهاية واحدة، مفتاح واحد، وأكثر من 500 نموذج عبر OpenAI وAnthropic وGoogle وDeepSeek وxAI وغيرها:

import osfrom openai import OpenAIfrom dotenv import load_dotenv​load_dotenv()​api_key = os.environ.get("AI_API_KEY")if not api_key:    raise ValueError("AI_API_KEY environment variable is not set")​client = OpenAI(    base_url=os.environ.get("AI_BASE_URL", "https://api.cometapi.com/v1"),    api_key=api_key,)

التبديل من GPT إلى Claude إلى Gemini يتطلب تغيير سطر واحد:

# Beforeresponse = client.chat.completions.create(model="gpt-5.4", messages=[...])​# After — same code, different modelresponse = client.chat.completions.create(model="claude-sonnet-4-6", messages=[...])

ملاحظة: أسماء النماذج مثل gpt-5.4 وclaude-sonnet-4-6 هي معرّفات منصة CometAPI — تعمل فقط عبر https://api.cometapi.com/v1، ولا تعمل مباشرة عبر واجهات OpenAI أو Anthropic. اطّلع على قائمة النماذج الكاملة للاطلاع على الكتالوج الكامل والتسعير.

أبقِ أسماء النماذج خارج منطق الأعمال لديك

تبعثر أسماء النماذج في الشيفرة هو الشكل الأكثر شيوعاً من الارتهان. الحل هو إعداد مركزي يقرأ من متغيرات البيئة:

# config.py — one place to change model assignmentsimport os​MODEL_CONFIG = {    "summarize": os.environ.get("MODEL_SUMMARIZE", "claude-opus-4-7"),    "code":      os.environ.get("MODEL_CODE",      "gpt-5.4"),    "classify":  os.environ.get("MODEL_CLASSIFY",  "claude-haiku-4-5"),    "chat":      os.environ.get("MODEL_CHAT",       "gpt-5.4-mini"),}​# Validate at startup — fail fast rather than getting mysterious API errorsfor task, model in MODEL_CONFIG.items():    if not model:        raise ValueError(f"Model config for '{task}' is not set")

لا يشير منطق الأعمال لديك مباشرةً إلى اسم نموذج:

from config import MODEL_CONFIG​def summarize(text: str) -> str:    response = client.chat.completions.create(        model=MODEL_CONFIG["summarize"],        messages=[{"role": "user", "content": f"Summarize: {text}"}],        max_tokens=300  # move to config in production    )    return response.choices[0].message.content

لتبديل نموذج التلخيص في كامل تطبيقك، غيّر متغير بيئة واحداً فقط. لا حاجة إلى grep ولا إلى الاستبدال عبر البحث.

لفّ الاستجابة بحيث لا يعتمد كودك على حقول خاصة بمزوّد

المزوّدون المختلفون يُرجعون بنى استجابة تختلف قليلاً. إذا قمت بتحليل الاستجابات الخام عبر أرجاء الشيفرة، فأنت مرتبط بصيغة ذلك المزوّد.

لفّها ضمن فئة بيانات موحّدة:

from dataclasses import dataclassfrom typing import Optionalfrom openai import OpenAI, APIStatusError, APIConnectionError, APITimeoutErrorfrom openai.types.chat import ChatCompletionimport logging​@dataclassclass AIResponse:    content: str    model: str    input_tokens: int    output_tokens: int​def call_model(task: str, messages: list, **kwargs) -> AIResponse:    """    Single entry point for all LLM calls.    Returns a normalized AIResponse regardless of which model handled it.    Raises on 4xx (client errors). Logs and re-raises on 5xx/network errors.    """    model = MODEL_CONFIG.get(task, "gpt-5.4-mini")    if not model:        raise ValueError(f"No model configured for task '{task}'")​    try:        response: ChatCompletion = client.chat.completions.create(            model=model,            messages=messages,            **kwargs        )    except APIStatusError as e:        logging.error(f"API error for task={task} model={model}: {e.status_code} {e.message}")        raise    except (APIConnectionError, APITimeoutError) as e:        logging.error(f"Network error for task={task} model={model}: {e}")        raise​    # content is None when the model triggers a tool call instead of returning text    content = response.choices[0].message.content or ""​    # usage is None in streaming mode — default to 0 if not available    usage = response.usage    input_tokens = usage.prompt_tokens if usage else 0    output_tokens = usage.completion_tokens if usage else 0​    logging.info(        f"task={task} model={model} "        f"input_tokens={input_tokens} output_tokens={output_tokens}"    )​    return AIResponse(        content=content,        model=response.model,        input_tokens=input_tokens,        output_tokens=output_tokens,    )

الآن يعمل منطق الأعمال لديك مع كائنات AIResponse، وليس الاستجابات الخام للواجهة البرمجية. إذا غيّر مزوّد صيغة استجابته، تُصلِح ذلك في موضع واحد.

أضِف دعم البثّ إلى الغلاف

بالنسبة لواجهات المحادثة، ستحتاج إلى البثّ. يتعامل الغلاف معه كمسار منفصل:

from typing import Iterator​def stream_model(task: str, messages: list, **kwargs) -> Iterator[str]:    """    Stream tokens from the routed model.    Note: streaming doesn't return usage data.    Fallback is not supported in streaming mode — you've already    started yielding tokens before you know if the full request succeeds.    """    model = MODEL_CONFIG.get(task, "gpt-5.4-mini")    if not model:        raise ValueError(f"No model configured for task '{task}'")​    stream = client.chat.completions.create(        model=model,        messages=messages,        stream=True,        **kwargs    )​    for chunk in stream:        delta = chunk.choices[0].delta.content        if delta:            yield delta​# Usagefor token in stream_model("chat", [{"role": "user", "content": "Hello"}]):    print(token, end="", flush=True)

اعرف أيّ المعاملات تُولّد الارتهان

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

إذا كنت تستخدم logprobs لتسجيل الثقة، فأنت مرتبط بـ GPT لهذه الميزة. هذه مقايضة معقولة — فقط وثّقها كي يعرف المطور التالي السبب.

اجعل نقطة نهاية المزوّد قابلة للتهيئة

تضمين base_url="https://api.cometapi.com/v1" بشكل صريح لا يزال شكلاً من الارتهان. اجعله متغير بيئة:

# .env — using CometAPIAI_BASE_URL=https://api.cometapi.com/v1AI_API_KEY=your_cometapi_key​# To switch to OpenAI directly, change two lines:# AI_BASE_URL=https://api.openai.com/v1# AI_API_KEY=your_openai_key

تهيئة العميل من الخطوة 1 تقرأ بالفعل هذه المتغيرات. أصبح التبديل بين CometAPI والاتصال المباشر بمزوّد مجرد تغيير إعداد، لا تغيير شيفرة.

إصدار Node.js

import OpenAI from 'openai';​const apiKey = process.env.AI_API_KEY;if (!apiKey) throw new Error('AI_API_KEY is not set');​const client = new OpenAI({  baseURL: process.env.AI_BASE_URL ?? 'https://api.cometapi.com/v1',  apiKey,});​// Model IDs are CometAPI platform identifiers — see cometapi.com/modelsconst MODEL_CONFIG = {  summarize: process.env.MODEL_SUMMARIZE ?? 'claude-opus-4-7',  code:      process.env.MODEL_CODE      ?? 'gpt-5.4',  classify:  process.env.MODEL_CLASSIFY  ?? 'claude-haiku-4-5',  chat:      process.env.MODEL_CHAT      ?? 'gpt-5.4-mini',};​// Validate at startupfor (const [task, model] of Object.entries(MODEL_CONFIG)) {  if (!model) throw new Error(`Model config for '${task}' is not set`);}​/** * Single entry point for all LLM calls. * Returns normalized response. Raises on 4xx, logs and re-raises on 5xx/network. */async function callModel(task, messages, options = {}) {  const model = MODEL_CONFIG[task] ?? 'gpt-5.4-mini';​  let response;  try {    response = await client.chat.completions.create({      model,      messages,      ...options,    });  } catch (err) {    // Don't swallow errors — log and re-raise    console.error(`API error task=${task} model=${model}:`, err.message);    throw err;  }​  // content is null when model triggers a tool call  const content = response.choices[0].message.content ?? '';​  // usage may be absent in some configurations  const inputTokens  = response.usage?.prompt_tokens     ?? 0;  const outputTokens = response.usage?.completion_tokens ?? 0;​  console.log(`task=${task} model=${model} input=${inputTokens} output=${outputTokens}`);​  return { content, model: response.model, inputTokens, outputTokens };}​/** * Stream tokens from the routed model. * Usage data is not available in streaming mode. */async function* streamModel(task, messages, options = {}) {  const model = MODEL_CONFIG[task] ?? 'gpt-5.4-mini';​  const stream = await client.chat.completions.create({    model,    messages,    stream: true,    ...options,  });​  for await (const chunk of stream) {    const delta = chunk.choices[0]?.delta?.content;    if (delta) yield delta;  }}​// Usage — blockingconst result = await callModel('classify', [  { role: 'user', content: 'Positive or negative? "Loved it!"' }]);console.log(result.content);​// Usage — streamingfor await (const token of streamModel('chat', [  { role: 'user', content: 'Hello' }])) {  process.stdout.write(token);}

ما الارتهان المقبول

ليس كل ارتهان يستحق المقاومة. بعض المقايضات منطقية:

• استخدام OpenAI SDK — إنه المعيار الواقعـي المتعارف عليه. يدعمه معظم المزوّدين. ارتهان منخفض المخاطر.
• ميزات خاصة بمزوّد تحتاجها فعلاً — إذا كنت بحاجة إلى logprobs، فاستخدمها. اعزل ذلك الكود بحيث يسهل العثور عليه واستبداله لاحقاً.
• نماذج مخصّصة بالتدريب — النموذج المخصّص بطبيعته مرتبط بمزوّد واحد. هذا متوقع.

الارتهان الذي يستحق التجنّب هو ذلك العرضي — أسماء نماذج في منطق الأعمال، تحليل الاستجابات الخام موزّع عبر الملفات، مفاتيح API مضمنة داخل الشيفرة.

ما التالي

بات لديك الآن طبقة تجريد تُبقي تفاصيل المزوّد خارج منطق الأعمال لديك. تغطي المقالة الأخيرة في هذه السلسلة ما يحدث عندما تسوء الأمور: كيفيّة تصحيح الإخفاقات في التوليد، وتفسير رموز الأخطاء، وبناء معالجة أخطاء تُخبرك فعلاً بما تعطل.

التالي: كيفية تصحيح عمليات توليد واجهات برمجة تطبيقات الذكاء الاصطناعي الفاشلة

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

س: ما الفرق بين الارتهان للـ SDK والارتهان للنموذج؟

الارتهان للـ SDK يعني أن شيفرتك تستورد مكتبة محددة وستحتاج إلى تعديلها إذا بدّلت الـ SDK. الارتهان للنموذج يعني أن أسماء النماذج مبعثرة في منطق الأعمال الخاص بك. الارتهان للـ SDK أقل خطورة لأن معظم المزوّدين يدعمون الآن صيغة SDK الخاصة بـ OpenAI. الارتهان للنموذج أكثر خفاءً لأنه أصعب في العثور عليه وإصلاحه.

س: إذا استخدمت CometAPI، أأكون بذلك أستبدل ارتهاناً بـ OpenAI بارتهانٍ إلى CometAPI؟

جزئياً. أنت تستبدل الارتباط المباشر بمزوّد بطبقة وكيل. الميزة: مفتاح واحد، نقطة نهاية واحدة، وتبديل النماذج بسهولة. المخاطرة: إذا تعرّضت CometAPI لانقطاع، فستتوقف جميع مزوّديك معاً. التخفيف مذكور بالفعل في الشيفرة أعلاه — AI_BASE_URL متغير بيئة. إذا احتجت لتجاوز CometAPI والاتصال بمزوّد مباشرة، فالأمر مجرد تغيير إعداد لا تغيير شيفرة.

س: هل يمكنني استخدام التفكير الموسّع في Claude أو OpenAI reasoning_effort من خلال هذا النمط؟

نعم، مرّرها كـ **kwargs إلى call_model. فقط اعلم أنه إذا وجّهت هذا العمل إلى نموذج مختلف، فسيتم تجاهل تلك المعاملات أو ستتسبب في خطأ. وثّق المهام التي تستخدم مزايا خاصة بمزوّد حتى يعرف المطور التالي السبب.

س: كيف أتعامل مع حد temperature لدى Claude عند 1.0 عند التوجيه بين Claude و GPT**?****

أبقِ temperature عند 1.0 أو أقل للبقاء ضمن النطاق الآمن لكليهما. إذا كنت بحاجة إلى درجة حرارة أعلى للمهام الإبداعية على GPT تحديداً، فقم بتوجيه تلك المهام إلى GPT صراحةً في MODEL_CONFIG بدلاً من تركها تمر عبر الموجّه العام.

س: هل يجب أن أجرّد واجهات توليد الصور والفيديو بالطريقة نفسها؟

تنطبق المبادئ نفسها — إعداد مركزي، غلاف استجابة موحّد، ولا حقول خاصة بمزوّد في منطق الأعمال. واجهات الصور والفيديو لديها فروق بنيوية أكبر (متزامن مقابل غير متزامن، مجموعات معاملات مختلفة) لذا تتطلب طبقة التجريد قدراً أكبر من العمل. ابدأ بالنص، ثم وسّع النمط بعد إثبات البنية.

س: ماذا عن فروق context window بين النماذج؟

هذا خطر حقيقي عند التوجيه. لدى GPT-5.5 نافذة سياق بحجم 1M من الرموز، وتدعم نماذج Claude حتى 200K، وGemini 3.5 Flash يدعم حتى 1M. إذا وجّهت مهمة تتطلب مستنداً طويلاً إلى نموذج ذي نافذة سياق أقصر، فسيتم اقتطاع الإدخال بصمت. أضِف فحص طول السياق قبل التوجيه إن كانت مهامك تتضمن مدخلات طويلة — أو وجّه مهام السياق الطويل دائماً إلى نموذج محدد في MODEL_CONFIG بدلاً من تركها تمر إلى الإعداد الافتراضي.