استخدام واجهة برمجة تطبيقات OpenRouter للوصول إلى نماذج الذكاء الاصطناعي عبر بايثون

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

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

يُتيح لك OpenRouter الوصول إلى آلاف النماذج من مزودين رائدين مثل OpenAI وAnthropic وMistral وGoogle وMeta. يمكنك التبديل بينها دون تغيير كود تطبيقك.

المتطلبات الأساسية

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

الخطوة 1: الاتصال بواجهة برمجة تطبيقات OpenRouter

قبل استخدام OpenRouter، ستحتاج إلى إنشاء حساب وتوليد مفتاح API. تتطلب بعض الطرازات رصيدًا مدفوعًا مسبقًا للوصول، ولكن يمكنك البدء بوصول مجاني لاختبار واجهة برمجة التطبيقات والتأكد من أن كل شيء يعمل بشكل صحيح.

لإنشاء مفتاح API:

• أنشئ حسابًا على OpenRouter.ai أو قم بتسجيل الدخول إذا كان لديك حساب بالفعل.
• حدد “المفاتيح” من القائمة المنسدلة وقم بإنشاء مفتاح API.
• أدخل الاسم، شيء مثل اختبار OpenRouter.
• اترك الإعدادات الافتراضية المتبقية وانقر على “إنشاء”.

انسخ المفتاح المُنشأ واحتفظ به في مكان آمن. بعد قليل، ستخزنه كمتغير بيئي بدلاً من تضمينه مباشرةً في التعليمات البرمجية الخاصة بك.

لاستدعاء نماذج ذكاء اصطناعي متعددة من خلال برنامج بايثون واحد، ستستخدم واجهة برمجة تطبيقات OpenRouter. ستستخدم مكتبة requests لإجراء استدعاءات HTTP، مما يمنحك تحكمًا كاملاً في تفاعلات واجهة برمجة التطبيقات دون الحاجة إلى حزمة تطوير برمجية (SDK) محددة. يعمل هذا الأسلوب مع أي عميل HTTP، ويحافظ على بساطة وشفافية الكود.

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

$ mkdir openrouter-project/
$ cd openrouter-project/
$ python -m venv venv/

الآن، يمكنك تفعيل البيئة الافتراضية:

PS> venv\Scripts\activate

ستظهر لك (venv) في موجه الأوامر عندما يكون نشطًا. الآن أنت جاهز لتثبيت حزمة requests لإجراء استدعاءات HTTP بسهولة.

(venv) $ python -m pip install requests

الآن، اجمع مفتاح API الذي أنشأته سابقًا وقم بتعيينه كمتغير بيئة OPENROUTER_API_KEY في جلسة الطرفية الخاصة بك:

PS> $env:OPENROUTER_API_KEY="your-api-key-here"

استبدل your-api-key-here بمفتاح API الفعلي الخاص بك من إعدادات OpenRouter. يُحافظ تخزين البيانات الحساسة، مثل مفتاح API، في متغيرات البيئة على بيانات الاعتماد بعيدًا عن مستودعك، ويُقلل من خطر التسريبات العرضية، ويُسهّل استخدام مفاتيح مختلفة عبر بيئات متعددة.

بعد ذلك، ستقوم بإنشاء برنامج نصي للتحقق من أن كل شيء يعمل بشكل صحيح. أنشئ ملفًا باسم get_models.py:

import os
import requests

OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models"

api_key = os.getenv("OPENROUTER_API_KEY")

headers = {"Authorization": f"Bearer {api_key}"}
response = requests.get(OPENROUTER_MODELS_URL, headers=headers)
data = response.json()

models = data.get("data", [])
print(f"Success! Found {len(models)} models via OpenRouter.")
print(f"Examples: {', '.join(m['id'] for m in models[:5])}")

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

عند تشغيل ملف get_models.py، سترى العدد الإجمالي للنماذج بالإضافة إلى بعض أسماء النماذج كمثال:

(venv) $ python get_models.py

Success! Found 345 models via OpenRouter.
Examples: writer/palmyra-x5, liquid/lfm-2.5-1.2b-thinking:free,
liquid/lfm-2.5-1.2b-instruct:free, openai/gpt-audio, openai/gpt-audio-mini

في هذه المرحلة، تكون قد تأكدت من أن مفتاح واجهة برمجة التطبيقات (API) يعمل وأن بيئة بايثون الخاصة بك قادرة على التواصل بنجاح مع OpenRouter. بعد إتمام الأساسيات، يمكنك الآن تجاوز مجرد عرض النماذج والبدء في التحكم في كيفية توجيه الطلبات بين مزودي الخدمة.

الخطوة الثانية: توجيه الطلبات إلى مزودي الذكاء الاصطناعي المحددين

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

أولاً، أنشئ ملفًا جديدًا باسم ask_auto_model.py. استخدم ملف get_models.py كنقطة بداية، ولكن عدّله لإرسال طلب إكمال المحادثة بدلاً من جلب قائمة النماذج.

البنية متطابقة تقريبًا: تقوم بتحميل مفتاح واجهة برمجة التطبيقات، وإعداد رؤوس الطلب، ثم إرسال طلب HTTP. يكمن الاختلاف الرئيسي في أنك ستستخدم نقطة نهاية إكمال المحادثات، وترسل طلب POST، وتتضمن حمولة JSON مع موجه.

import os
import requests

OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions"

api_key = os.getenv("OPENROUTER_API_KEY")

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
payload = {
    "model": "openrouter/auto",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
}
response = requests.post(OPENROUTER_API_URL, headers=headers, json=payload)
data = response.json()

print(f"Model: {data.get('model')}")
print(f"Response: {data['choices'][0]['message']['content']}")

التغييرات في ملف get_models.py طفيفة ومقتصرة على بضعة أسطر:

• السطر 4: انتقل إلى رابط إكمال المحادثة
• السطر 10: أضف Content-Type: application/json إلى الترويسات
• السطر 12: إنشاء حمولة JSON تحتوي على النموذج والرسائل
• السطر 16: استدعِ ()requests.post بدلاً من ()requests.get

بتعيين “model”: “openrouter/auto”، فإنك تسمح لـ OpenRouter باختيار كلٍ من النموذج ومزود الخدمة نيابةً عنك. عند تشغيل ask_auto_model.py كما هو موضح في المثال أدناه، فإنه يُعيد استجابةً من النموذج الذي يختاره OpenRouter.

(venv) $ python ask_auto_model.py

Model: mistralai/mistral-nemo
Response: Hello! It's great to meet you, how can I help you today?

قد لا ترغب دائمًا في أن يختار OpenRouter النموذج نيابةً عنك. عندما تحتاج إلى نموذج مُحدد، مثل gpt-3.5-turbo من OpenAI، يمكنك استهدافه مباشرةً. أنشئ ملف ask_specific_model.py باستخدام الكود أدناه، وهو مطابق لملف ask_auto_model.py باستثناء سطر واحد وإضافة شرط بسيط في النهاية.

import os
import requests

OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions"

api_key = os.getenv("OPENROUTER_API_KEY")

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
payload = {
    "model": "openai/gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
}
response = requests.post(OPENROUTER_API_URL, headers=headers, json=payload)
data = response.json()

if model := data.get('model'):
    print(f"Model: {model} by {data['provider']}")
    print(f"Response: {data['choices'][0]['message']['content']}")
else:
    print("No model found in the response.")
    print(f"Response: {data}")

في السطر 13، يمكنك تحديد النموذج الذي تختاره عن طريق تعيين حقل “model” إلى “openai/gpt-3.5-turbo” بدلاً من استخدام “openrouter/auto”.

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

عند تشغيل ملف ask_specific_model.py، يقوم OpenRouter بتوجيه طلبك إلى النموذج الذي تختاره ويعيد الموفر الذي قام بتلبية الطلب:

(venv) $ python ask_specific_model.py

Model: openai/gpt-3.5-turbo by OpenAI
Response: Hello, how are you today?

يتميز كل مزود خدمة بخصائص مختلفة، مثل التكلفة والسرعة والسعة. فعند طلب نموذج مثل openai/gpt-3.5-turbo، قد يقدمه عدة مزودين بأسعار وسرعات وسعات متفاوتة.

بدلاً من اختيار مزود الخدمة يدويًا، يمكنك إخبار OpenRouter بما يهمك أكثر من خلال إعدادات مزود الخدمة، وسيقوم تلقائيًا بتوجيه طلبك إلى الخيار الأفضل.

يدعم OpenRouter ثلاث استراتيجيات توجيه لتحديد أولويات مزودي الخدمة:

تعتمد استراتيجية التوجيه التي تختارها على احتياجات تطبيقك. إليك كيفية استخدامها عمليًا: أنشئ ملفًا باسم route_requests.py يحتوي على دالة قابلة لإعادة الاستخدام وطلب أولي مُحسَّن من حيث التكلفة.

import os
import requests

OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions"

api_key = os.getenv("OPENROUTER_API_KEY")

def make_request(model, messages, provider_config=None):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    payload = {"model": model, "messages": messages}
    if provider_config:
        payload["provider"] = provider_config

    response = requests.post(OPENROUTER_API_URL, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()

data = make_request(
    model="meta-llama/llama-3.1-70b-instruct",
    messages=[{"role": "user", "content": "Explain AI in one sentence."}],
    provider_config={"sort": "price"}
)

if model := data.get('model'):
    print(f"Model: {model} by {data['provider']}")
    print(f"Response: {data['choices'][0]['message']['content']}")
else:
    print("No model found in the response.")
    print(f"Response: {data}")

ترسل الدالة make_request طلب POST إلى نقطة نهاية إكمال المحادثات، وتضيف اختياريًا مفتاح المزوّد إلى الحمولة عند توفير provider_config. تمرر الدالة ()make_request الوسيط {“sort”: “price”}، لذا يختار OpenRouter المزوّد الأرخص لـ meta-llama/llama-3.1-70b-instruct.

عند تشغيل ملف route_requests.py الآن، يمكنك معرفة مزود الخدمة الذي يختاره OpenRouter:

(venv) $ python route_requests.py

Model: meta-llama/llama-3.1-70b-instruct by Hyperbolic
Response: Artificial Intelligence (AI) is a computer system designed
to perform tasks that typically require human intelligence ...

عندما تقوم بمعالجة كميات كبيرة من الطلبات ويكون الحفاظ على انخفاض التكاليف هو الأهم، فمن الجيد إعطاء الأولوية للسعر.

يمكنك تعديل قيمة “sort” في إعدادات مزود الخدمة (provider_config) حسب معدل النقل أو زمن الاستجابة. يستخدم كل طلب نفس النموذج، لكن OpenRouter يختار مزودي خدمة مختلفين بناءً على أولوياتك: التكلفة، أو معدل النقل، أو زمن الاستجابة. لمعرفة المزيد حول خيارات تكوين مزود الخدمة، راجع وثائق توجيه مزودي الخدمة في OpenRouter.

الخطوة 3: تطبيق نماذج احتياطية لضمان الموثوقية

الآن بعد أن أصبح بإمكانك توجيه الطلبات بذكاء، يمكنك إضافة موثوقية إلى تطبيقك.

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

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

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

إليك كيفية تطبيق خيارات احتياطية باستخدام واجهة برمجة تطبيقات OpenRouter التي تستهدف نماذج محددة. ستنشئ دالة تقبل قائمة بالنماذج مرتبة حسب الأولوية. أنشئ ملفًا باسم fallback_models.py:

import os
import requests

OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions"

api_key = os.getenv("OPENROUTER_API_KEY")

def make_request_with_fallback(models_list, messages):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    payload = {"models": models_list, "messages": messages}

    return requests.post(OPENROUTER_API_URL, headers=headers, json=payload)

response = make_request_with_fallback(
    models_list=[
        "openai/gpt-5",
        "openai/gpt-3.5-turbo",
        "openai/gpt-3.5-turbo-16k"
    ],
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)

data = response.json()
if model := data.get('model'):
    print(f"Model: {model} by {data['provider']}")
    print(f"Response: {data['choices'][0]['message']['content']}")
else:
    print("No model found in the response.")
    print(f"Response: {data}")

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

من خلال تشغيل ملف fallback_models.py، يمكنك أن ترى أن OpenRouter يجتاز قائمة النماذج في قائمة النماذج الاحتياطية الخاصة بك حتى يستجيب openai/gpt-3.5-turbo بنجاح:

(venv) $ python fallback_models.py

Model: openai/gpt-3.5-turbo by OpenAI
Response: Paris

ضع هذه الاستراتيجيات في اعتبارك عند ترتيب خططك الاحتياطية:

• على أساس الجودة: جرب النموذج الأفضل أولاً ثم ارجع إلى البدائل الأرخص إذا لزم الأمر. يعمل هذا الأسلوب بشكل جيد عندما تكون الجودة هي أولويتك القصوى ولكنك لا تزال تريد نسخًا احتياطية فعالة من حيث التكلفة.
• تنويع مزودي الخدمة: استخدم أكثر من مزود خدمة لتجنب نقاط الضعف الفردية. وزّع حلول الدعم الاحتياطية على مزودين مختلفين حتى لا يؤثر انقطاع الخدمة لدى مزود واحد على تطبيقك. هذا أمر بالغ الأهمية لأنظمة الإنتاج حيث الموثوقية أساسية.
• تحسين التكاليف: ابدأ بالنماذج ذات التكلفة المنخفضة، ولا تستخدم النماذج باهظة الثمن إلا عند الضرورة. تنجح هذه الاستراتيجية عندما تكون التكلفة هي الشاغل الرئيسي، ولكن يجب أن تبقى الخيارات المتميزة متاحة كخيارات احتياطية.
• الأداء هو المعيار: إعطاء الأولوية للسرعة مع ضمان وجود نسخ احتياطية موثوقة. يناسب هذا النهج التطبيقات التي يكون فيها وقت الاستجابة مهمًا، ولكن لا يمكنك تحمل أي عطل كامل.

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

الخطوات التالية

أصبح لديك الآن أساسيات واجهة برمجة تطبيقات OpenRouter جاهزة للعمل. إليك بعض المواضيع الإضافية التي يمكنك استكشافها أثناء بناء تطبيقات أكثر تطوراً:

حدود معدل النقل: يتعامل OpenRouter مع نوعين من الحدود: حدود حسابك، والتي يمكنك مراجعتها في لوحة التحكم، وحدود مزود الخدمة. عندما يصل مزود الخدمة إلى حده الأقصى، يقوم OpenRouter تلقائيًا بتوجيه الطلبات إلى مزودي الخدمة المتاحين أو وضعها في قائمة الانتظار.

نقاط نهاية أخرى: يدعم OpenRouter إنشاء الصور، وتضمينها، وتحويل الصوت إلى نص، واستدعاء الدوال. راجع وثائق واجهة برمجة تطبيقات OpenRouter للاطلاع على تفاصيل نقاط النهاية ومعاييرها.

مع وجود هذه الأدوات والمفاهيم، ستكون جاهزًا لبناء تطبيقات أكثر مرونة وقدرة على الصمود مدعومة بالذكاء الاصطناعي.

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

الآن بعد أن اكتسبت بعض الخبرة في استخدام واجهة برمجة تطبيقات OpenRouter في بايثون، يمكنك استخدام الأسئلة والأجوبة أدناه للتحقق من فهمك ومراجعة ما تعلمته.

تتعلق هذه الأسئلة الشائعة بأهم المفاهيم التي تناولتها في هذا الدليل. انقر على زر إظهار/إخفاء بجوار كل سؤال لعرض الإجابة.