دليل OpenRouter لتطوير الذكاء الاصطناعي

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

ما هو OpenRouter؟

يتيح لك OpenRouter الوصول إلى العديد من نماذج الذكاء الاصطناعي باستخدام واجهة برمجة تطبيقات واحدة. لا تحتاج إلى إعداد كل مزود على حدة. يمكنك الاتصال مرة واحدة، واستخدام مفتاح API واحد، وكتابة مجموعة واحدة من التعليمات البرمجية. يتعامل OpenRouter مع الباقي، مثل المصادقة وتنسيق الطلب والفوترة. وهذا يجعل من السهل تجربة نماذج مختلفة. يمكنك التبديل بين نماذج مثل GPT-5، أو Claude 4.6، أو Gemini 3.1 Pro، أو Llama 4 عن طريق تغيير معلمة واحدة فقط في التعليمات البرمجية الخاصة بك. يساعدك هذا على اختيار النموذج المناسب بناءً على التكلفة أو السرعة أو الميزات مثل التفكير وفهم الصورة.

كيف يعمل OpenRouter؟

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

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

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

الشروع في العمل: أول استدعاء لواجهة برمجة التطبيقات (API).

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

الخطوة 1: إنشاء حساب والحصول على الاعتمادات:

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

الخطوة 2: إنشاء مفتاح API

انتقل إلى قسم “المفاتيح” في لوحة تحكم حسابك. انقر فوق “إنشاء مفتاح”، وقم بتسميته، وانسخ المفتاح بشكل آمن. للحصول على أفضل الممارسات، استخدم مفاتيح منفصلة لبيئات مختلفة (على سبيل المثال، dev، prod) وقم بتعيين حدود الإنفاق للتحكم في التكاليف.

الخطوة 3: تكوين بيئتك

قم بتخزين مفتاح API الخاص بك في متغير بيئة لتجنب كشفه في التعليمات البرمجية الخاصة بك.

الخطوة 4: الإعداد المحلي باستخدام متغير البيئة:

لنظام التشغيل MacOS أو Linux:

export OPENROUTER_API_KEY="your-secret-key-here"

لنظام التشغيل Windows (باورشيل):

setx OPENROUTER_API_KEY "your-secret-key-here"

تقديم طلب على OpenRouter

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

مثال بايثون باستخدام OpenAI SDK

# First, ensure you have the library installed:
# pip install openai

import os
from openai import OpenAI

# Initialize the client, pointing it to OpenRouter's API
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ.get("OPENROUTER_API_KEY"),
)

# Send a chat completion request to a specific model
response = client.chat.completions.create(
    model="openai/gpt-4.1-nano",
    messages=(
        {
            "role": "user",
            "content": "Explain AI model routing in one sentence."
        },
    ),
)

print(response.choices(0).message.content)

الإخراج:

استكشاف النماذج والتوجيه المتقدم

يُظهر OpenRouter قوته الحقيقية بما يتجاوز الطلبات البسيطة. تدعم منصتها توجيه نماذج الذكاء الاصطناعي الديناميكي والذكي.

اكتشاف النماذج برمجيا

نظرًا لأنه تتم إضافة النماذج أو تحديثها باستمرار، ليس من المفترض أن تقوم بترميز أسماء النماذج في أحد تطبيقات الإنتاج لديك، وبدلاً من ذلك، يحتوي openrouter على نقطة نهاية /models التي تعرض قائمة بجميع النماذج المتاحة مع الأسعار المقترحة وحدود السياق والإمكانيات.

import os
import requests

# Fetch the list of available models
response = requests.get(
    "https://openrouter.ai/api/v1/models",
    headers={
        "Authorization": f"Bearer {os.environ.get('OPENROUTER_API_KEY')}"
    },
)

if response.status_code == 200:
    models = response.json()("data")

    # Filter for models that support tool use
    tool_use_models = (
        m for m in models
        if "tools" in (m.get("supported_parameters") or ())
    )

    print(f"Found {len(models)} total models.")
    print(f"Found {len(tool_use_models)} models that support tool use.")
else:
    print(f"Error fetching models: {response.text}"

الإخراج:

التوجيه الذكي والتراجعات

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

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

فيما يلي مثال بايثون يوضح سلسلة احتياطية:

# The primary model is 'openai/gpt-4.1-nano'
# If it fails, OpenRouter will try 'anthropic/claude-3.5-sonnet',
# then 'google/gemini-2.5-pro'

response = client.chat.completions.create(
    model="openai/gpt-4.1-nano",
    extra_body={
        "models": (
            "anthropic/claude-3.5-sonnet",
            "google/gemini-2.5-pro"
        )
    },
    messages=(
        {
            "role": "user",
            "content": "Write a short poem about space."
        }
    ),
)

print(f"Model used: {response.model}")
print(response.choices(0).message.content)

الإخراج:

إتقان القدرات المتقدمة

يمكن استخدام نفس واجهة برمجة تطبيقات إكمال الدردشة لإرسال الصور إلى أي نموذج قادر على الرؤية لتحليلها. كل ما هو مطلوب هو إضافة الصورة كعنوان URL، أو سلسلة مشفرة بـ base64 إلى مجموعة رسائلك.

المخرجات المنظمة (وضع JSON)

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

# Requesting a structured JSON output

response = client.chat.completions.create(
    model="openai/gpt-4.1-nano",
    messages=(
        {
            "role": "user",
            "content": "Extract the name and age from this text: 'John is 30 years old.' in JSON format."
        }
    ),
    response_format={
        "type": "json_object",
        "json_schema": {
            "name": "user_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"}
                },
                "required": ("name", "age"),
            },
        },
    },
)

print(response.choices(0).message.content)

الإخراج:

المدخلات متعددة الوسائط: العمل مع الصور

يمكنك استخدام نفس واجهة برمجة تطبيقات إكمال الدردشة لإرسال الصور إلى أي نموذج قادر على الرؤية لتحليلها. ما عليك سوى إضافة الصورة كعنوان URL أو سلسلة مشفرة بـ base64 إلى مجموعة رسائلك.

# Sending an image URL for analysis

response = client.chat.completions.create(
    model="openai/gpt-4.1-nano",
    messages=(
        {
            "role": "user",
            "content": (
                {
                    "type": "text",
                    "text": "What is in this image?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRmqgVW-371UD3RgE3HwhF11LYbGcVfn9eiTYqiw6a8fK51Es4SYBK0fNVyCnJzQit6YKo9ze3vg1tYoWlwqp3qgiOmRxkTg1bxPwZK3A&s=10"
                    }
                },
            ),
        }
    ),
)

print(response.choices(0).message.content)

الإخراج:

وكيل مدرك للتكلفة ومتعدد الموفرين

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

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

منطق “الرخيص إلى الذكي”.

سيتبع وكيلنا الخطوات التالية:

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

يضمن هذا الأسلوب عدم دفع مبالغ زائدة مقابل الطلبات البسيطة مع الاستمرار في التمتع بقوة النماذج عالية المستوى عند الطلب.

تنفيذ بايثون

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

from openai import OpenAI
import os
import json

# Initialize the client for OpenRouter
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ.get("OPENROUTER_API_KEY"),
)


def run_cheap_to_smart_agent(prompt: str):
    """
    Runs a prompt first through a cheap model, then escalates to a
    smarter model if confidence is low.
    """

    cheap_model = "mistralai/mistral-7b-instruct"
    smart_model = "openai/gpt-4.1-nano"

    # Define the desired JSON structure for the response
    json_schema = {
        "type": "object",
        "properties": {
            "answer": {"type": "string"},
            "confidence": {
                "type": "integer",
                "description": "A score from 1-100 indicating confidence in the answer.",
            },
        },
        "required": ("answer", "confidence"),
    }

    # First, try the cheap model
    print(f"--- Attempting with cheap model: {cheap_model} ---")

    try:
        response = client.chat.completions.create(
            model=cheap_model,
            messages=(
                {
                    "role": "user",
                    "content": f"Answer the following prompt and provide a confidence score from 1-100. Prompt: {prompt}",
                }
            ),
            response_format={
                "type": "json_object",
                "json_schema": {
                    "name": "agent_response",
                    "schema": json_schema,
                },
            },
        )

        # Parse the JSON response
        result = json.loads(response.choices(0).message.content)
        answer = result.get("answer")
        confidence = result.get("confidence", 0)

        print(f"Cheap model confidence: {confidence}")

        # If confidence is below a threshold (e.g., 70), escalate
        if confidence < 70:
            print(f"--- Confidence low. Escalating to smart model: {smart_model} ---")

            # Use a simpler prompt for the smart model
            smart_response = client.chat.completions.create(
                model=smart_model,
                messages=(
                    {
                        "role": "user",
                        "content": prompt,
                    }
                ),
            )

            final_answer = smart_response.choices(0).message.content
        else:
            final_answer = answer

    except Exception as e:
        print(f"An error occurred with the cheap model: {e}")
        print(f"--- Falling back directly to smart model: {smart_model} ---")

        smart_response = client.chat.completions.create(
            model=smart_model,
            messages=(
                {
                    "role": "user",
                    "content": prompt,
                }
            ),
        )

        final_answer = smart_response.choices(0).message.content

    return final_answer


# --- Test the Agent ---

# 1. A simple prompt that the cheap model can handle
simple_prompt = "What is the capital of France?"
print(f"Final Answer for Simple Prompt:\n{run_cheap_to_smart_agent(simple_prompt)}\n")

# 2. A complex prompt that will likely require escalation
complex_prompt = "Provide a detailed comparison of the transformer architecture and recurrent neural networks, focusing on their respective advantages for sequence processing tasks."
print(f"Final Answer for Complex Prompt:\n{run_cheap_to_smart_agent(complex_prompt)}")

الإخراج:

يتجاوز هذا المثال العملي استدعاء API البسيط ويعرض كيفية تصميم نظام أكثر ذكاءً وفعالية من حيث التكلفة باستخدام نقاط القوة الأساسية لـ OpenRouter: تنوع النماذج والمخرجات المنظمة.

الرصد والملاحظة

يعد فهم أداء تطبيقك وتكاليفه أمرًا بالغ الأهمية. يوفر OpenRouter أدوات مدمجة للمساعدة.

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

خاتمة

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

الأسئلة المتداولة