آموزش OpenRouter ؛ راهنمای جامع اتصال و برنامه نویسی با صدها مدل هوش مصنوعی

در دنیای پرشتاب توسعه نرم افزار و هوش مصنوعی، اتکا به یک ارائه دهنده واحد می تواند ریسک های عملیاتی سنگین و هزینه های غیر قابل کنترلی ایجاد کند. آموزش OpenRouter به عنوان یک درگاه یکپارچه ابری، مطمئن ترین و اقتصادی ترین مسیر را برای دسترسی همزمان به صدها مدل زبانی بزرگ از طریق یک کلید واحد هموار می سازد. در این راهنمای جامع و کاربردی از وبلاگ طراحان نوین، گام های فنی اتصال، معماری بدون قطعی، اتصال به کلاینت ها، استراتژی های روتینگ هوشمند و شیوه های بهینه سازی هزینه ها را با کدهای اجرایی بررسی می کنیم.

۱. معرفی فنی و مزیت رقابتی پلتفرم OpenRouter

اتصال مجزا به زیرساخت های اختصاصی شرکت هایی نظیر OpenAI، Anthropic، Google یا Mistral مستلزم نگهداری ده ها کلید امنیتی، مواجهه با پنل های مالی پیچیده و پیاده سازی ساختارهای ناهمگون است. پلتفرم OpenRouter به عنوان یک تجمیع کننده پیشرفته (LLM Aggregator)، تمام این سرویس ها را زیر چتر یک استاندارد واحد گرد هم آورده است.

تفاوت اساسی OpenRouter با اتصال مستقیم به شرکت های هوش مصنوعی

در سناریوی اتصال مستقیم، نرم افزار شما به طور صلب به یک تامین کننده وابسته می شود. این وابستگی فنی (Vendor Lock-in) فرآیند مهاجرت یا تغییر مدل را بسیار دشوار و پرهزینه می کند. در نقطه مقابل، پلتفرم OpenRouter به عنوان یک لایه انتزاعی هوشمند (Smart Abstraction Layer) عمل می کند و تفاوت های زیرساختی را محو می نماید:

• یکپارچگی مالی و اداری: به جای پرداخت فاکتورهای متعدد ارزی به ده ها شرکت با خطرات مسدودی حساب، تمام شارژها در یک کیف پول متمرکز انجام می گیرد.
• استانداردسازی کامل فرمت درخواست ها: تمامی مدل های پردازشی، اعم از مدل های انحصاری و متن باز، با ساختار استاندارد و جهانی OpenAI Chat Completions قابل فراخوانی هستند.
• انعطاف پذیری در تغییر مدل: جایگزینی یک مدل قدرتمند تجاری نظیر Claude 3.5 Sonnet با مدلی اقتصادی نظیر DeepSeek V3 بدون کوچک ترین دستکاری در منطق نرم افزار و تنها با تغییر نام مدل محقق می گردد.

معماری Universal API و پایداری عملیاتی

معماری OpenRouter بر بستر یک اندپوینت واحد (https://openrouter.ai/api/v1) پایه ریزی شده است. سیستم روتینگ هوشمند این پلتفرم ترافیک ارسالی شما را به صورت خودکار به پایدارترین و کم تاخیرترین مرکز داده ابری هدایت می کند.

اگر یکی از تامین کنندگان با اختلال موقت شبکه (Downtime) یا محدودیت سقف ترافیک (Rate Limit) روبه رو شود، سیستم روتینگ درخواست را به تامین کننده دیگر همان مدل یا به مدل پشتیبان (Fallback) هدایت می نماید. این پایداری ساختاری شباهت کاملی با مفاهیم مطرح شده در مقاله معماری AI Harness و لایه های انتزاعی دارد که بقای سیستم های مدرن را در شرایط قطعی تضمین می کند.

مزایای اقتصادی و دسترسی به مدل های متن باز

پلتفرم OpenRouter علاوه بر پرچمداران تجاری، میزبان برترین مدل های بازمتن (Open Source) نظیر سری های Llama 3.3، Qwen 2.5، Mistral Large و مدل های استدلالی انقلابی DeepSeek R1 است. هزینه پردازش این مدل ها تا ده برابر کمتر از مدل های انحصاری است. افزون بر این، مدل های رایگان با پسوند :free محیطی بی نظیر برای اجرای آزمایش های تستی و مراحل استقرار اولیه فراهم می سازند.

۲. شروع کار و پیکربندی حساب کاربری (مرحله به مرحله)

فرآیند راه اندازی حساب در OpenRouter بدون پیچیدگی های تایید هویت سنتی و بدون نیاز به شماره تلفن های خارجی انجام می پذیرد.

گام اول: ثبت نام و ورود به پنل کاربری

جهت ساخت حساب کاربری، مراحل زیر را طی نمایید:

1. به وبسایت رسمی openrouter.ai مراجعه کنید.
2. روی دکمه Sign In در نوار بالایی صفحه کلیک فرمایید.
3. شیوه احراز هویت مدنظر خود را برگزینید:
   • ورود با گوگل (Google Account): ساده ترین و سریع ترین روش ورود.
   • ورود با گیت هاب (GitHub): گزینه ای عالی برای توسعه دهندگان نرم افزار و تیم های فنی.
   • ورود با کیف پول وب ۳ (Web3 Wallet / MetaMask): مناسب برای حفظ حریم خصوصی بدون ثبت ایمیل.

گام دوم: ساخت API Key و اعمال سقف مصرف (Credit Limit)

یکی از ارزشمندترین قابلیت های امنیتی OpenRouter، توانایی ایجاد سقف هزینه مجزا برای هر کلید ارتباطی است تا از هدررفت بودجه بر اثر خطاهای نرم افزاری جلوگیری شود:

1. از منوی پروفایل کاربری به بخش تنظیمات کلیدها (Keys) بروید.
2. بر روی دکمه Create Key کلیک نمایید.
3. در کادر باز شده، یک نام توصیفی در فیلد Name وارد کنید (برای مثال: Chatbot-Production یا VSCode-Continue).
4. در فیلد Credit Limit، سقف مجاز مصرف را بر حسب دلار تعیین کنید (مثلا عدد 5 مشخص می کند این کلید حداکثر مجاز به مصرف ۵ دلار اعتبار است). اگر مایل به مصرف نامحدود از کل موجودی هستید، این بخش را خالی بگذارید.
5. دکمه Create را فشرده و کلید تولید شده را کپی کنید. کلیدها با پیشوند sk-or-v1- آغاز می شوند و تنها یک بار نمایش داده خواهند شد.

گام سوم: شارژ اعتبار و مدل مالی Pay-as-you-go

مدل مالی OpenRouter کاملا شفاف و به صورت پرداخت به ازای مصرف دقیق توکن ها (Pay-as-you-go) طراحی شده است. هیچ گونه آبونمان ماهانه ثابت به کاربران تحمیل نمی شود.

جهت شارژ حساب کاربری:

• وارد تب Credits در منوی کاربری شوید.
• روی دکمه Add Credit کلیک فرمایید.
• شیوه پرداخت را تعیین کنید: پرداخت بین المللی با استرایپ (Stripe) یا پرداخت از طریق رمزارز (Coinbase Commerce با پشتیبانی از تتر USDT، بیت کوین، اتریوم و یو اس دی کوین USDC).
• موجودی شارژ شده تاریخ انقضا ندارد و متناسب با توکن های ورودی (Prompt Tokens) و خروجی (Completion Tokens) کسر می گردد.

۳. آشنایی با داشبورد و ابزارهای کلیدی

پنل مدیریتی OpenRouter ابزارهای دقیقی را برای ارزیابی کیفی، بررسی مالی و رصد عملکرد مدل ها در اختیارتان قرار می دهد.

بخش Playground و مقایسه رو در روی مدل ها

محیط تعاملی Playground فضایی ایده آل برای تست سریع مدل ها بدون نوشتن کد است:

• مقایسه همزمان (Side-by-Side Comparison): با انتخاب همزمان دو یا چند مدل، می توانید پاسخ یک پرامپت یکسان را به صورت بلادرنگ مشاهده کرده و کیفیت، سرعت تولید و تفاوت هزینه های آنها را بسنجید.
• تنظیم پارامترهای استنتاج:
  • System Prompt: تدوین هویت، زمینه و دستورالعمل های اساسی مدل.
  • Temperature (دما): عددی بین ۰ تا ۲؛ مقادیر کمتر (مثلا ۰.۲) برای کدنویسی و پاسخ های قطعی و مقادیر بالاتر (مثلا ۰.۸) برای ایده پردازی های خلاقانه مناسب است.
  • Top-P: نمونه برداری هسته ای برای کنترل گستردگی انتخاب واژگان محتمل.
  • Max Tokens: تعیین سقف تولید توکن برای جلوگیری از پاسخ های بیش از حد طولانی.

بخش Activity & Analytics برای تحلیل مصارف و لاگ خطاها

تب Activity مرکز کنترل و مانیتورینگ منابع مصرفی به شمار می رود:

• ردیابی توکن ها: نمایش نمودارهای حجمی به تفکیک توکن های پرامپت و توکن های پاسخ.
• گزارش هزینه ها: فیلتر کردن هزینه ها بر اساس کلید های فعال یا مدل های پرمصرف جهت محاسبه بهای تمام شده پروژه ها.
• لاگ ترافیک و خطاها: مشاهده وضعیت سلامت درخواست ها به همراه زمان پاسخ دهی (Latency بر حسب میلی ثانیه) و کدهای خطای احتمالی شبکه.

رنکینگ و کاتالوگ جامع مدل ها (Models Catalog)

در صفحه کاتالوگ مدل های OpenRouter، امکان جستجو در میان صدها مدل هوش مصنوعی با فیلترهای زیر تعبیه شده است:

• فیلتر هزینه: مرتب سازی بر اساس کمترین قیمت یا مدل های کاملا رایگان.
• اندازه پنجره زمینه (Context Window): انتخاب مدل هایی از ۸ هزار توکن تا کانتکست های غول آسا (بیش از ۱ میلیون توکن) برای پردازش اسناد حجیم و پایگاه های کد.
• نرخ توان عملیاتی (Throughput): فیلتر بر اساس سرعت تولید توکن بر ثانیه جهت کاربردهای بلادرنگ و چت بات های حساس به سرعت.
• میزان محبوبیت (Most Used): رصد حجم توکن های پردازش شده در سطح جهانی برای شناسایی مدل های باثبات و پرطرفدار.

۴. راهنمای ادغام و برنامه نویسی (Implementation Guide)

از آنجا که OpenRouter از استانداردهای رسمی OpenAI تبعیت می کند، توسعه دهندگان پایتون و جاوا اسکریپت می توانند بدون نیاز به نصب بسته های جانبی غیر رسمی، از کلاینت های استاندارد استفاده کنند.

پیکربندی اولیه با کلاینت رسمی OpenAI

کتابخانه رسمی را از طریق مدیریت پکیج پایتون نصب نمایید:

pip install openai

جهت اتصال به OpenRouter، کافی است دو متغیر را تغییر دهید:

1. آدرس پایه سرور: base_url="https://openrouter.ai/api/v1"
2. کلید دسترسی: api_key="sk-or-v1-..."

نمونه کد کامل پایتون: استریمینگ، مدیریت خطا، هدرهای آماری و مدل های پشتیبان (Fallback)

کد زیر یک الگوی سازمانی کامل است که ویژگی های استریم پیوسته، سوئیچ خودکار بین مدل ها در زمان بروز خطا، ارسال هدرهای رهگیری و مدیریت انواع خطاهای سرور را به تصویر می کشد:

# -*- coding: utf-8 -*-
import sys
import os
from openai import OpenAI, APIConnectionError, RateLimitError, AuthenticationError, APIStatusError

# دریافت کلید اختصاصی از متغیرهای محیطی سیستم
OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY", "sk-or-v1-your-key-here")
OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"

# مقداردهی کلاینت رسمی با تنظیم هدرهای پیشنهادی پلتفرم OpenRouter
client = OpenAI(
    base_url=OPENROUTER_BASE_URL,
    api_key=OPENROUTER_API_KEY,
    default_headers={
        # آدرس سایت شما جهت نمایش نام پروژه در رتبه بندی های پلتفرم
        "HTTP-Referer": "https://tarahanenovin.ir",
        # نام شناسه پروژه شما در لاگ های مانیتورینگ
        "X-Title": "Tarahanenovin AI Client",
    }
)

def stream_ai_completion_with_fallback(prompt_text):
    # تعریف اولویت مدل ها: در صورت قطعی مدل اول، به مدل بعدی سوئیچ می شود
    models_fallback_list = [
        "deepseek/deepseek-r1",
        "anthropic/claude-3.5-sonnet",
        "meta-llama/llama-3.3-70b-instruct"
    ]

    print(f"ارسال درخواست پردازش به مدل های هوش مصنوعی: {prompt_text}\n")
    print("دریافت پاسخ زنده:\n" + "=" * 45)

    try:
        # فراخوانی متد گفتگو با تنظیم قابلیت روتینگ هوشمند
        response_stream = client.chat.completions.create(
            # مدل اولویت نخست
            model=models_fallback_list[0],
            messages=[
                {"role": "system", "content": "شما یک دستیار فنی دقیق و حرفه ای در حوزه نرم افزار هستید."},
                {"role": "user", "content": prompt_text}
            ],
            # فعال سازی خروجی پیوسته و استریم
            stream=True,
            temperature=0.3,
            # فعال سازی قابلیت سوییچ خودکار در سرور OpenRouter
            extra_body={
                "models": models_fallback_list,
                "route": "fallback"
            }
        )

        # دریافت قطعات متنی به محض تولید در سرور
        for chunk in response_stream:
            if chunk.choices and chunk.choices[0].delta.content:
                sys.stdout.write(chunk.choices[0].delta.content)
                sys.stdout.flush()

        print("\n" + "=" * 45 + "\nپردازش با موفقیت کامل انجام شد.")

    except AuthenticationError:
        print("\n[خطای ۴۰۱]: کلید ارتباطی نامعتبر است. مقدار API Key را بازبینی فرمایید.")
    except RateLimitError:
        print("\n[خطای ۴۲۹]: سقف مجاز فراخوانی در دقیقه تکمیل شده است. کمی صبر کنید.")
    except APIStatusError as status_err:
        # تفکیک خطای اتمام اعتبار کیف پول با کد ۴۰۲
        if status_err.status_code == 402:
            print("\n[خطای ۴۰۲]: اعتبار حساب یا سقف مجاز این کلید تمام شده است.")
        else:
            print(f"\n[خطای وضعیت سرور {status_err.status_code}]: {status_err.message}")
    except APIConnectionError:
        print("\n[خطای اتصال]: عدم امکان برقراری ارتباط پایدار با سرور OpenRouter.")
    except Exception as unexpected_error:
        print(f"\n[خطای سیستمی]: {str(unexpected_error)}")

if __name__ == "__main__":
    sample_query = "معماری میکروسرویس چیست و چه کاربردی در سیستم های توزیع شده دارد؟ در ۳ خط توضیح بده."
    stream_ai_completion_with_fallback(sample_query)

نمونه کد در جاوا اسکریپت و تایپ اسکریپت (Node.js)

توسعه دهندگان محیط های تحت وب و Node.js می توانند به سادگی از پکیج رسمی جاوا اسکریپت بهره ببرند:

import OpenAI from "openai";

const openRouterClient = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": "https://tarahanenovin.ir",
    "X-Title": "Tarahanenovin Production Service",
  },
});

async function requestCompletion() {
  try {
    const response = await openRouterClient.chat.completions.create({
      model: "meta-llama/llama-3.3-70b-instruct",
      messages: [
        { role: "system", content: "شما یک مهندس ارشد نرم افزار هستید." },
        { role: "user", content: "مزیت استفاده از TypeScript در مقایسه با JavaScript چیست؟" },
      ],
    });

    console.log("پاسخ مدل:", response.choices[0].message.content);
  } catch (error) {
    console.error("خطا در پردازش درخواست:", error);
  }
}

requestCompletion();

استفاده از خروجی ساختاریافته (Structured Outputs) و حالت JSON Mode

در سناریوهایی که نیاز به استخراج فیلدهای مشخص برای ذخیره سازی در دیتابیس یا پاسخ به API های داخلی دارید، حالت ساختاریافته مانع از تولید متن های حاشیه ای می شود:

structured_response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[
        {
            "role": "system",
            "content": "مشخصات فنی سرور را استخراج کرده و تنها در قالب یک آبجکت استاندارد JSON با کلیدهای cpu و ram و storage ارائه بده."
        },
        {
            "role": "user",
            "content": "سرور اختصاصی ابری مجهز به پردازنده ۳۲ هسته ای زئون با ۶۴ گیگابایت رم و ۲ ترابایت حافظه ان وی ام ای."
        }
    ],
    # فعال سازی تولید تضمین شده جی سان
    response_format={"type": "json_object"}
)

print(structured_response.choices[0].message.content)

۵. سناریوهای پیشرفته و کاربردهای خاص

پلتفرم OpenRouter قابلیت اتصال سریع به صدها نرم افزار آماده و ابزارهای دستیار مهندسی را فراهم می سازد.

اتصال به کلاینت های آماده و رابط های چت متن باز

اگر قصد استقرار یک پایگاه چت سازمانی یا فردی را دارید، نیازی به طراحی فرانت اند از صفر نیست:

• نرم افزار LibreChat: یک کلاینت بی نظیر متن باز با قابلیت های غنی. با تعریف متغیر OPENROUTER_KEY در فایل .env این پروژه، صدها مدل با قابلیت های ضمیمه فایل و ابزارها برای تمامی اعضای تیم فعال می شوند.
• نرم افزار NextChat (ChatGPT-Next-Web): در منوی تنظیمات این نرم افزار، آدرس Custom Endpoint را برابر https://openrouter.ai/api/v1 قرار داده و کلید امنیتی خود را درج نمایید.
• نرم افزار TypingMind: در صفحه تنظیمات API Keys گزینه OpenRouter را برگزینید تا تمامی مدل ها با دسته بندی تخصصی همگام سازی شوند.

اتصال به افزونه های کدنویسی در محیط VS Code

برای تبدیل محیط برنامه نویسی خود به یک استودیوی هوش مصنوعی قدرتمند بدون پرداخت آبونمان های سنگین:

• افزونه Continue.dev: این اکستنشن متن باز امکان انتخاب مدل های OpenRouter را در ویرایشگر فراهم می کند. کافی است در تنظیمات افزونه مدل هایی نظیر deepseek/deepseek-coder یا claude-3.5-sonnet را متصل سازید.
• افزونه Roo Code یا Cline: این ابزارهای پیشرفته فایل های ساختار پروژه را تحلیل کرده و مستقیما به اصلاح باگ ها می پردازند. همان گونه که در بررسی های ۵ ابزار هوش مصنوعی انقلابی در سال ۲۰۲۶ و معرفی جایگزین های رایگان Claude Code اشاره کردیم، اتصال این عامل ها به درگاه های یکپارچه، بالاترین بازدهی کاری را رقم می زند.

بهره گیری از مدل های رایگان با پیشوند free برای محیط تست

پلتفرم OpenRouter فهرستی از مدل های کارآمد را با پیشوند :free عرضه می کند (نظیر meta-llama/llama-3.3-70b-instruct:free یا google/gemini-2.0-flash-exp:free). فراخوانی این مدل ها هزینه ای ندارد و برای تست های مداوم (CI/CD)، دانشجویان، پروژه های دانشگاهی و ارزیابی پرامپت ها فوق العاده است. تنها تفاوت این مدل ها، وجود محدودیت سقف درخواست در دقیقه است.

استراتژی هوشمندانه بهینه سازی هزینه ها (Prompt Routing)

ارسال تمامی پرسش ها به مدل های گران قیمت تصمیمی غیراقتصادی است. معماری استاندارد بر پایه تفکیک درخواست ها شکل می گیرد:

1. پرامپت های کوتاه، دسته بندی و استخراج داده: این درخواست ها را به مدل های سریع و کم مصرف مانند google/gemini-2.0-flash یا meta-llama/llama-3.1-8b-instruct ارسال کنید.
2. استدلال های پیچیده، معماری کد و محاسبات سنگین: این پرامپت ها را به مدل های قدرتمندی مانند deepseek/deepseek-r1 یا anthropic/claude-3.5-sonnet ارجاع دهید.
3. با به کارگیری این استراتژی، هزینه زیرساخت هوش مصنوعی سیستم شما بین ۷۰ تا ۹۰ درصد کاهش پیدا می کند.

۶. پرسش های متداول، عیب یابی و حریم خصوصی

شناخت کدهای خطای وب و اصول محافظت از داده ها، پایداری استقرار پروژه های تجاری را تضمین می کند.

حل خطاهای متداول در کار با OpenRouter

• خطای ۴۰۱ (Authentication Error): کلید ارتباطی اشتباه است یا پیشوند sk-or-v1- به طور ناقص کپی شده است. همچنین وضعیت فعال بودن کلید در پنل را بازبینی نمایید.
• خطای ۴۰۲ (Insufficient Credits): اعتبار کیف پول به اتمام رسیده است یا مصرف کلید به سقف مشخص شده (Credit Limit) برخورد کرده است.
• خطای ۴۲۹ (Rate Limit Exceeded): ارسال درخواست بیش از حد مجاز در ثانیه یا دقیقه؛ این حالت در مدل های رایگان رخ می دهد و با پیاده سازی وقفه تدریجی (Exponential Backoff) یا سوئیچ به مدل های پولی برطرف می گردد.
• خطای ۵۰۲ و ۵۰۳ (Upstream Provider Error): سرور تامین کننده اصلی مدل دچار اختلال مقطعی شده است. با فعال سازی پارامتر fallback، درخواست به صورت خودکار به هاستینگ های سالم هدایت خواهد شد.

وضعیت حریم خصوصی و امنیت داده ها (Data Privacy & Compliance)

آیا پرامپت های کاربران برای آموزش هوش مصنوعی ضبط می شوند؟

• تنظیمات Data Privacy: در پنل کاربری بخش Settings به قسمت Privacy مراجعه کنید. می توانید گزینه های ممانعت از ثبت پرامپت ها توسط هاستینگ ها را فعال نمایید تا داده ها ذخیره نشوند.
• مدل های تجاری پولی: تامین کنندگان متعهد هستند که داده های ارسالی به مدل های پولی تجاری را ذخیره نکرده و برای آموزش استفاده نکنند.
• مدل های رایگان: برخی از تامین کنندگان مدل های رایگان ممکن است از ورودی های ناشناس برای بهبود الگوهای خود استفاده نمایند. بنابراین برای داده های بسیار حساس، بهره گیری از کلیدهای شارژ شده و مدل های پولی توصیه می شود.

بهره گیری هدفمند از فناوری های پردازش زبان طبیعی و زیرساخت های ابری، عاملی حیاتی در ارتقای راندمان کسب و کارها به شمار می رود. اگر در مسیر هوشمندسازی فرآیندها، توسعه وبسایت های مقیاس پذیر یا پیاده سازی دستیارهای تجاری به مشاوره مهندسی نیاز دارید، می توانید جهت بهره مندی از خدمات فنی و طراحی سایت و پیاده سازی هوش مصنوعی توسط طراحان نوین با کارشناسان متخصص ما در تماس باشید.