وابستگی مستقیم به یک ارائهدهندهی مدل زبانی، هزینه‌ی توسعه را بالا می‌برد و با کوچک‌ترین اختلال در سرویس‌دهنده، سامانه‌ی شما را با قطعی مواجه میکند. از سوی دیگر، تمام درخواستها به پیشرفته‌ترین و گران‌ترین مدل بازار نیاز ندارند و می‌توان وظایف ساده‌تر را به گزینه‌های سریع‌تر و اقتصادی‌تر سپرد.
گیت‌وی‌های مسیریابی (Routing Gateways) این چالش را با یک رابط واحد سازگار با استاندارد OpenAI حل می‌کنند؛ این ابزارها امکاناتی نظیر تغییر مسیر خودکار هنگام خرابی (Failover)، ردیابی هزینه‌ی توکن‌ها، کش معنایی (Semantic Caching) و اعمال گاردریل‌ها را فراهم می‌آورند. در این درس با معماری این لایه و تفاوت‌های سه راهکار LiteLLM، OpenRouter و Portkey آشنا می‌شوید و یک گیتوی اختصاصی پیاده‌سازی می‌کنید.
برای توسعه‌دهندگان در ایران که کارت‌های بانکی بین‌المللی برای پرداخت مستقیم به پلتفرم‌هایی نظیر OpenAI یا Anthropic در اختیار ندارند و با محدودیت‌های دسترسی یا نوسان اتصال به APIهای ابری مواجه هستند، استفاده از یک پروکسی داخلی یا گزینه‌های خودمیزبان مثل LiteLLM امکان مدیریت یکپارچه‌ی کلیدها، استفاده از گیت‌وی‌های واسط و مدیریت مصرف ارزی را با کمترین تغییر در کدهای کلاینت مهیا می‌سازد.
وابستگی به یک ارائه‌دهنده (Vendor lock-in) گران تمام می‌شود. هر حجم کاری در فراخوانی ابزار (tool-calling) با مدل متفاوتی سازگار است. گیت‌وی‌های مسیریابی (Routing gateways) یک رابط API یکپارچه، تلاش مجدد (retry)، تغییر مسیر خودکار هنگام خرابی (failover)، ردیابی هزینه و گاردریل‌ها (guardrails) را فراهم می‌کنند. در سال 2026 سه الگوی اصلی بر بازار مسلط هستند: LiteLLM (متنباز و خودمیزبان)، OpenRouter (سرویس SaaS مدیریتشده) و Portkey (در سطح پروداکشن، که در مارس 2026 متنباز شد). این درس معیارهای تصمیم‌گیری را مشخص میکند و پیاده‌سازی یک گیتوی مسیریابی با کتابخانه‌ی استاندارد را گام‌به‌گام نشان میدهد.
اهداف یادگیری
- تمایز بین گزینه‌های مسیریابی خودمیزبان، مدیریتشده و سطح پروداکشن.
- پیاده‌سازی زنجیرهی مدلهای جایگزین (fallback chain) برای تلاش مجدد هنگام خطای ارائه‌دهنده با ترتیبی مشخص از اولویت‌ها.
- ردیابی هزینه و مصرف توکن به ازای هر درخواست در میان ارائه‌دهندگان مختلف.
- تصمیم‌گیری آگاهانه میان LiteLLM، OpenRouter و Portkey با توجه به محدودیت‌های پروداکشن مفروض.
صورت‌مسئله
سناریوهایی که مسیریابی ارائه‌دهندگان در آن‌ها اهمیت دارد:
-
هزینه. هزینه‌ی Claude Sonnet سه برابر Haiku است. برای وظیفه‌ی تریاژ، Haiku کفایت میکند؛ اما برای سنتز و ترکیب اطلاعات، Sonnet ارزش هزینه‌اش را دارد. مسیر را برای هر درخواست جداگانه تعیین کنید.
-
تغییر مسیر خودکار هنگام خرابی (Failover). OpenAI به مدت یک ساعت دچار اختلال می‌شود و همه‌ی درخواستها با خطا مواجه می‌شوند. در این حالت می‌خواهید بدون نیاز به دیپلوی دوباره، ترافیک خودکار به سمت Anthropic هدایت شود.
-
تاخیر (Latency). رابط کاربری یک چت زنده به زمان ارسال اولین توکن (time-to-first-token) بسیار سریعی نیاز دارد، اما سیستم خلاصه‌ساز دسته‌ای (batch summarizer) چنین نیازی ندارد. ترافیک را بر اساس توافق‌نامه‌ی سطح خدمات (SLA) تاخیر هدایت کنید.
-
انطباق با قوانین (Compliance). داده‌های کاربران اتحادیه‌ی اروپا باید در مناطق سروری همین اتحادیه باقی بماند. درخواستها را بر اساس منطقه هدایت کنید.
-
آزمایش. اجرای آزمون A/B روی دو مدل برای یک بار کاری یکسان. مسیر را بر اساس دسته‌ی آزمایشی مشخص کنید.
کدنویسی دستی همه‌ی این منطق‌ها برای هر اتصال کاری تکراری است. یک گیتوی مسیریابی، یک API سازگار با ساختار OpenAI در اختیارتان می‌گذارد و باقی کارها را خودش مدیریت میکند.
مفهوم
ساختار پروکسی سازگار با OpenAI
امروزه همه‌ی سیستم‌ها با فرمت OpenAI صحبت می‌کنند. گیتوی مسیریابی مسیر /v1/chat/completions را در معرض استفاده قرار میدهد، اسکیمای OpenAI را می‌پذیرد و درون خود به عنوان پروکسی به سمت Anthropic، Gemini، Cohere، Ollama یا هر سرویس دیگری هدایت میکند؛ در این فرایند برای کلاینت هیچ فرقی ندارد.
نام‌های مستعار مدل‌ها (Model aliases)
به جای نوشتن شناسه‌ی ثابت یک اسنپ‌شات در کد، نامی مثل our_smart_model را به کار می‌برید. گیتوی این نام‌های مستعار را به مدلهای واقعی نگاشت میکند. وقتی ارائه‌دهنده‌ای نسل جدیدی از مدلش را عرضه کرد، شما نام مستعار را فقط در سمت سرور تغییر می‌دهید و دست به کدهای برنامه‌تان نمی‌زنید.
زنجیره‌های مدلهای جایگزین (Fallback chains)
primary: openai/gpt-4o
on 5xx: anthropic/claude-3-5-sonnet
on 5xx: google/gemini-1.5-pro
on 5xx: refuseگیت‌وی‌ها این رفتار را در یک فایل کانفیگ تعریف می‌کنند. تلاش‌های مجدد در چارچوب یک بودجه‌ی مشخص شمرده می‌شوند تا آبشاری شدن گزینه‌های جایگزین هزینه‌ها را منفجر نکند.
کش معنایی (Semantic caching)
پرامپت‌های کاملاً یکسان یا بسیار نزدیک به هم، به جای رفتن به سمت ارائه‌دهنده، به کش برخورد می‌کنند. این سازوکار در حلقه‌های مکرر ایجنت، هزینه‌ها را 30 تا 60 درصد کاهش میدهد. کلیدها بر اساس امبدینگ ساخته می‌شوند و پرامپت‌های بسیار نزدیک در یک خانه‌ی کش شریک می‌شوند.
گاردریل‌ها (Guardrails)
سازوکارهای ایمنی در سطح گیتوی:
- پاک‌سازی اطلاعات هویتی حساس (PII redaction). عبور پرامپت‌ها از فیلتر Regex یا مدلهای یادگیری ماشین پیش از ارسال.
- بررسی نقض قوانین (Policy violations). رد کردن پرامپت‌های حاوی محتوای ممنوعه.
- فیلترهای خروجی. پالایش خروجی‌های تکمیل‌شده برای جلوگیری از نشت اطلاعات.
ابزارهای Portkey و Kong گاردریل‌ها را به‌صورت سفت‌وسخت و پیش‌فرض ارائه می‌دهند؛ اما LiteLLM فعال‌سازی آن‌ها را اختیاری گذاشته است.
محدودیت نرخ بر اساس کلید (Per-key rate limits)
یک کلید API برای هر تیم. تعیین بودجه به ازای هر کلید جلوی این را می‌گیرد که یک تیم کل سهمیه‌ی اشتراکی را مصرف کند. بیشتر گیت‌وی‌ها از این قابلیت پشتیبانی می‌کنند.
مقایسه‌ی سیستم‌های خودمیزبان و سرویس‌های مدیریتشده
| فاکتور | LiteLLM (خودمیزبان) | OpenRouter (مدیریتشده) | Portkey (پروداکشن) |
|---|---|---|---|
| کد | متنباز، Python | سرویس SaaS مدیریتشده | متنباز (مارس 2026) + مدیریتشده |
| راه‌اندازی | استقرار یک پروکسی | ثبت‌نام | هر دو حالت |
| ارائه‌دهندگان | بیش از 100 | بیش از 300 | بیش از 100 |
| پرداخت و صورتحساب | کلیدهای اختصاصی خودتان | شارژ اعتباری OpenRouter | کلیدهای اختصاصی خودتان |
| مشاهده‌پذیری | از طریق OpenTelemetry | داشبورد | پشتیبانی کامل از OTel + پاک‌سازی PII |
| مناسب برای | تیم‌هایی که کنترل کامل داده را می‌خواهند | نمونه‌سازی سریع | پروداکشن نیازمند استانداردهای قانونی |
اگر تیم SRE دارید و حاکمیت داده‌ها برایتان حیاتی است، LiteLLM گزینه‌ی اول است. اگر اشتراکی واحد و بدون دردسرهای زیرساختی می‌خواهید، OpenRouter برنده است. در نهایت، اگر به گاردریل‌های آماده و انطباق با قوانین در محیط پروداکشن نیاز دارید، Portkey انتخاب نهایی است.
ردیابی هزینه
هر درخواست حامل مقادیر provider، model، input_tokens و output_tokens است. این مقادیر در قیمت هر توکن برای مدل مربوطه (که از فهرست قیمت‌های نگهداری‌شده در گیتوی خوانده می‌شود) ضرب می‌شوند. سپس هزینه‌ها را می‌توان به تفکیک کاربر، تیم یا پروژه تجمیع کرد.
ترکیب مسیریابی با MCP
گیتوی می‌تواند هم فراخوانی‌های LLM و هم درخواستهای نمونه‌گیری (sampling) پروتکل کانتکست مدل (MCP) را هدایت کند. وقتی در گزینه‌ی modelPreferences یک درخواست نمونه‌گیری، مدلی خاص ترجیح داده شده باشد، گیتوی آن را به بک‌اند درست ترجمه میکند. این نقطه‌ای است که فاز 13 · 17 (گیتوی MCP) و گیتوی مسیریابی این درس گاهی درون یک سرویس واحد merge می‌شوند.
استراتژی‌های مسیریابی
- اولویت ایستا (Static priority). انتخاب اولین مدل لیست؛ سوئیچ به بعدی در صورت خطا.
- توازن بار (Load balancing). الگوریتم نوبت‌گردشی (Round-robin) یا وزن‌دار.
- حساس به هزینه (Cost-aware). انتخاب ارزان‌ترین مدلی که با حداقل کیفیت و تاخیر مدنظر همخوانی دارد.
- حساس به تاخیر (Latency-aware). انتخاب سریع‌ترین مدل در N دقیقه‌ی گذشته.
- حساس به وظیفه (Task-aware). استفاده از طبقه‌بند پرامپت برای هدایت کارهای کدنویسی به یک مدل و خلاصه‌سازی به مدلی دیگر.
استفاده در عمل
فایل code/main.py یک گیتوی مسیریابی را در حدود 150 خط کد پیاده‌سازی میکند: درخواستهای سازگار با OpenAI را می‌پذیرد، آن‌ها را به استاب‌های اختصاصی هر ارائه‌دهنده تبدیل میکند، زنجیرهی مدلهای جایگزینِ اولویت‌دار را به اجرا درمی‌آورد، هزینه‌ی هر درخواست را می‌سنجد و لایه‌ی پاک‌سازی اطلاعات هویتی (PII) را روی ورودی‌ها اعمال میکند. برنامه را با سه سناریو اجرا کنید: درخواست عادی، قطعی ارائهدهندهی اصلی که زنجیرهی جایگزین را فعال میکند، و نشت اطلاعات هویتی که توسط فیلتر مهار می‌شود.
بخش‌هایی که باید بررسی کنید:
- دیکشنری
ROUTES: نگاشت نام مستعار به فهرستی از ارائه‌دهندگانِ مشخص بر اساس اولویت. - حلقه‌ی مدلهای جایگزین که با خطای 5xx دوباره تلاش میکند.
- ردیاب هزینه که مصرف توکن را در نرخ ویژه‌ی هر مدل ضرب میکند.
- پاک‌ساز PII که الگوهای شبیه به کد ملی و شماره‌ی بیمه (SSN) را پیش از فوروارد کردن ماسک میکند.
تحویل پروژه
خروجی این درس فایل outputs/skill-routing-config-designer.md خواهد بود. این مهارت با گرفتن پروفایل بار کاری (تاخیر، هزینه، انطباق با قوانین)، از بین LiteLLM، OpenRouter یا Portkey گزینه‌ی درست را برمی‌گزیند و کانفیگ مسیریابی آن را تولید میکند.
تمرین‌ها
-
اسکریپت
code/main.pyرا اجرا کنید. سناریوی قطعی را تحریک کنید؛ بررسی کنید که آیا درخواست به ارائهدهندهی دوم منتقل می‌شود و هزینه به درستی محاسبه می‌گردد یا خیر. -
کش معنایی را پیاده‌سازی کنید: رشته‌ی SHA256 پرامپت را کلید جست‌وجو قرار دهید؛ طوری که در صورت کش‌هیت شدن، پاسخ فوراً بازگردانده شود. کاهش هزینه‌ها را در فراخوانی‌های مکرر بسنجید.
-
یک طبقه‌بند پرامپت اضافه کنید که پرامپت‌های با مضمون «... code» را به نام مستعاری با هوشمندی بالاتر، و پرامپت‌های با مضمون «... summarize» را به نام مستعاری متمرکز بر سرعت هدایت کند.
-
بودجه‌بندی تیمی را پیاده کنید: هر تیم سقف مشخصی برای هزینه‌ی ماهانه دارد؛ گیتوی پس از پر شدن سقف، درخواستها را رد میکند. سطح سخت‌گیری را تعیین کنید (به ازای هر درخواست یا در پنجره‌های زمانی دوره‌ای).
-
مستندات LiteLLM، OpenRouter و Portkey را کنار هم بررسی کنید. برای هر کدام، یک قابلیت شاخص نام ببرید که دوتای دیگر فاقد آن هستند.
اصطلاحات کلیدی
| اصطلاح | چیزی که معمولاً گفته می‌شود | معنای دقیق فنی |
|---|---|---|
| Routing gateway | «پروکسی LLM» | لایه‌ای با سطح API یکپارچه در برابر چندین ارائه‌دهنده |
| OpenAI-compatible | «با اسکیمای OpenAI کار میکند» | دریافت درخواستها با الگوی /v1/chat/completions و ترجمه‌ی آن به هر بک‌اندی |
| Model alias | «our_smart_model» | نامی در کد شما که گیتوی آن را به یک مدل مشخص نگاشت میکند |
| Fallback chain | «لیست تلاش مجدد» | فهرستی مرتب از ارائه‌دهندگان که در صورت بروز خطا به ترتیب امتحان می‌شوند |
| Semantic caching | «کش امبدینگ پرامپت» | کلیدی از جنس امبدینگ پرامپت؛ ورودی‌های بسیار نزدیک در یک خانه‌ی کش مشترک می‌شوند |
| Guardrails | «فیلترهای ورودی و خروجی» | ماسک کردن PII و رد درخواستهای ناقض خط‌مشی |
| Per-key rate limit | «بودجه‌ی تیمی» | تعیین سهمیه‌ی مصرف در دامنه‌ی یک کلید API خاص |
| Cost tracking | «هزینه‌ی هر درخواست» | مجموع مصرف توکن ضربدر قیمت هر مدل |
| LiteLLM | «پروکسی متنباز» | گیتوی مسیریابی متنباز با قابلیت میزبانی شخصی |
| OpenRouter | «سرویس SaaS مدیریتشده» | گیتوی میزبانی‌شده با مدل پرداخت بر پایه‌ی اعتبار |
| Portkey | «گزینه‌ی پروداکشن» | پلتفرم متنباز و مدیریتشده با گاردریل‌های داخلی و آماده |
برای مطالعه‌ی بیشتر
- LiteLLM — مستندات — گیتوی مسیریابی متنباز و خودمیزبان
- OpenRouter — شروع سریع — سرویس SaaS مدیریتشده برای مسیریابی
- Portkey — مستندات — مسیریابی در سطح پروداکشن مجهز به گاردریل‌ها
- TrueFoundry — مقایسه‌ی LiteLLM و OpenRouter — راهنمای تصمیم‌گیری
- Relayplane — مقایسه‌ی گیت‌وی‌های LLM در سال 2026 — ارزیابی ارائه‌دهندگان مختلف