SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

آموزش راه‌اندازی LiteLLM به‌عنوان گیت‌وی LLM

با LiteLLM یک endpoint سازگار با OpenAI روی VPS بسازید؛ کلید مجازی، بودجه جداگانه برای هر کلید، fallback بین ارائه‌دهندگان و imageهای ثابت را مدیریت کنید.

گیت‌وی LLM خودمیزبان چه کاری انجام می‌دهد

LiteLLM یک گیت‌وی متن‌باز برای LLM است که خودتان آن را میزبانی می‌کنید: یک endpoint واحد HTTP که تمام برنامه‌های شما با آن در ارتباط هستند و درخواست‌ها را به ارائه‌دهنده‌ای که باید پاسخگو باشد، هدایت می‌کند. LLM مخفف مدل زبانی بزرگ (Large Language Model) است. این گیت‌وی از API (رابط برنامه‌نویسی اپلیکیشن) چت کامپلیشن OpenAI پشتیبانی می‌کند، بنابراین هر کتابخانه کلاینتی که پیش‌تر با OpenAI کار می‌کرده، پس از دو تغییر در base URL و کلید، با آن سازگار می‌شود.

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

پس از راه‌اندازی، امکانات زیر را در اختیار دارید:

  • یک endpoint واحد. برنامه‌ها به https://gateway.example.com/v1 متصل می‌شوند و نام مدلی که خودتان تعریف کرده‌اید، مانند bulk یا strong را درخواست می‌کنند.
  • کلیدهای مجازی. هر برنامه کلید اختصاصی خود را با لیست مجاز مدل‌ها و سقف بودجه مشخص دریافت می‌کند. می‌توانید بدون تأثیر بر سایر برنامه‌ها، دسترسی یکی را لغو کنید.
  • جایگزین‌های خودکار (Fallbacks). فراخوانی‌های ناموفق یا پرامپت‌های بیش از حد بزرگ، به‌طور خودکار با یک مدل دیگر دوباره تلاش می‌شوند.
  • ثبت لاگ. هر درخواست، ردیفی شامل هزینه مربوطه را ثبت می‌کند، بنابراین پاسخ به این سؤال که «کدام برنامه آن هزینه را ایجاد کرده» همیشه در دسترس است.

چرا باید گیت‌وی را خودتان اجرا کنید

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

پیش‌نیازها

  • یک سرور مجازی (VPS) با سیستم‌عامل Ubuntu 24.04 که Docker و افزونه Compose روی آن نصب شده باشد.
  • یک نام دامنه که به سرور اشاره می‌کند، در صورتی که قرار است ماشین‌های خارج از شبکه از طریق TLS (امنیت لایه انتقال) به gateway دسترسی داشته باشند.
  • حداقل یک کلید API از ارائه‌دهنده سرویس.

این gateway هیچ پردازش استنتاجی (inference) انجام نمی‌دهد. وظیفه آن ارسال درخواست‌ها و بازگرداندن پاسخ‌ها به صورت stream است، بنابراین بار پردازنده (CPU) آن متناسب با حجم درخواست‌ها تغییر می‌کند، نه اندازه مدل. یک سرور با 1 هسته پردازنده (vCPU) می‌تواند چندین برنامه داخلی را بدون مشکل مدیریت کند. آنچه با گذشت زمان افزایش می‌یابد، حجم پایگاه داده است، زیرا gateway برای هر درخواست یک ردیف هزینه (spend row) ثبت می‌کند.

ابتدا فایل config.yaml را بنویسید

فایل پیکربندی تعیین می‌کند که کلاینت‌ها مجاز به درخواست کدام مدل‌ها هستند. چهار بخش سطح بالا اهمیت دارند: model_list، litellm_settings، router_settings و general_settings.

model_list:
  - model_name: bulk
    litellm_params:
      model: anthropic/claude-haiku-4-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: openai/gpt-5.5
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  num_retries: 2
  request_timeout: 120
  json_logs: true
  set_verbose: false

router_settings:
  allowed_fails: 3
  cooldown_time: 30
  fallbacks: [{"bulk": ["strong"]}]
  context_window_fallbacks: [{"bulk": ["strong"]}]

general_settings:
  background_health_checks: true
  health_check_interval: 300

model_name نامی است که کلاینت‌های شما ارسال می‌کنند. litellm_params.model مدل واقعی است که به صورت provider/model نوشته می‌شود. مدل‌های خود را بر اساس وظیفه نام‌گذاری کنید، نه بر اساس فروشنده. برنامه‌ای که درخواست bulk را می‌دهد، زمانی که ماه آینده تصمیم بگیرید bulk باید مدل متفاوتی باشد، همچنان به کار خود ادامه می‌دهد.

api_key: os.environ/ANTHROPIC_API_KEY به LiteLLM می‌گوید که آن متغیر را در زمان اجرا بخواند. کلید واقعی هرگز در فایل ظاهر نمی‌شود، که این موضوع اهمیت دارد زیرا config.yaml فایلی است که شما commit می‌کنید.

دو ورودی به عمد نام strong را به اشتراک می‌گذارند. هنگامی که بیش از یک deployment دارای model_name یکسان باشد، روتر با آن‌ها به عنوان موارد قابل جایگزینی رفتار می‌کند و درخواست‌های آن نام را بین آن‌ها توزیع می‌کند. این‌گونه است که strong از خرابی یک ارائه‌دهنده در یک بازه زمانی بد جان سالم به در می‌برد: هنگامی که یک deployment در وضعیت cooldown (پایین) قرار می‌گیرد، درخواست‌های جدید برای strong به دیگری ارسال می‌شوند.

num_retries: 2 خطای قابل‌تکرار را تا دو بار مجدداً تلاش می‌کند. آن تلاش‌های مجدد می‌توانند deployment در دسترس دیگری را در همان گروه مدل انتخاب کنند: مستندات معماری LiteLLM، که در تاریخ 2026-10-29 بررسی شد، تلاش‌های مجدد درون گروهی و fallbackهای بین‌گروهی را به عنوان مراحل جداگانه توصیف می‌کنند. بنابراین، یک تلاش مجدد برای strong می‌تواند بدون فعال‌سازی weighted failover به ارائه‌دهنده دیگر برسد. یک fallback تنها پس از اتمام آن تلاش‌های مجدد اجرا می‌شود.

allowed_fails و cooldown_time گزینه‌های روتر هستند، بنابراین در زیر router_settings قرار می‌گیرند. پروکسی روتر خود را از آن بخش می‌سازد و در نسخه v1.95.0، یک cooldown_time که در زیر litellm_settings نوشته شده باشد هرگز به آن نمی‌رسد، بنابراین cooldownها بی‌سروصدا روی مقدار پیش‌فرض 5 ثانیه باقی می‌مانند. cooldown_time: 30 تعیین می‌کند که یک deployment پس از خنک شدن (cooldown)، چه مدت از چرخه خارج بماند. مرجع پیکربندی، allowed_fails را به عنوان تعداد خطایی توصیف می‌کند که یک deployment باید در مدت cooldown_time از آن فراتر رود تا خنک شود. در سورس v1.95.0، allowed_fails: 3 مقدار پیش‌فرض است و در حالت پیش‌فرض، روتر به آن محرک‌های داخلی پایبند می‌ماند؛ تعداد خطا تنها زمانی جایگزین می‌شود که شما عدد متفاوتی را تنظیم کنید. آن محرک‌ها شامل cooldown فوری در پاسخ 429 برای گروهی با بیش از یک deployment، بیش از 50% خطا در دقیقه جاری پس از حداقل 5 درخواست برای چنین گروهی، و خطاهایی که روتر دوباره تلاش نمی‌کند (مانند 401 از یک کلید نامعتبر) هستند. یک محرک جداگانه نیز زمانی که تمام درخواست‌ها در دقیقه جاری شکست بخورند و ترافیک به SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD برسد (که پیش‌فرض آن 1000 درخواست است)، یک deployment تکی را خنک می‌کند. بنابراین برای strong که دو deployment دارد، ارائه‌دهنده‌ای که در یک بازه زمانی پاسخ‌های 500 برمی‌گرداند، در هر درخواست تکی دیگر امتحان نمی‌شود، در حالی که یک خطای 500 پراکنده در هر چند دقیقه هرگز باعث فعال شدن cooldown نمی‌شود. bulk تنها یک deployment دارد، بنابراین محرک نرخ خطا برای آن اعمال نمی‌شود: یک انفجار از خطاهای 500 که زیر 1000 درخواست در دقیقه باقی بماند، آن را در چرخه نگه می‌دارد و آنچه تماس‌گیرندگانش را محافظت می‌کند، num_retries و به دنبال آن fallback به strong است.

fallbacks و context_window_fallbacks محرک‌های متفاوتی دارند و دومی همان مورد مفیدی است که افراد از آن صرف‌نظر می‌کنند.

  • fallbacks زمانی فعال می‌شود که تماس اصلی شکست بخورد.
  • context_window_fallbacks زمانی فعال می‌شود که ارائه‌دهنده درخواست را به دلیل طولانی‌تر بودن از پنجره کانتکست (context window) آن مدل رد کند، بنابراین یک پرامپت بیش‌ازحد بزرگ به جای بازگرداندن خطا به تماس‌گیرنده، به مدلی با فضای کافی برای آن ارسال می‌شود.

همچنین content_policy_fallbacks وجود دارد که برای ارائه‌دهنده‌ای است که به دلایل سیاست محتوا (content policy) درخواست را رد می‌کند. آن را فقط در صورتی تنظیم کنید که جای مناسبی برای ارسال آن تماس‌ها داشته باشید.

استقرار LiteLLM روی یک VPS با Docker Compose

یک دایرکتوری بسازید که شامل سه فایل config.yaml، docker-compose.yml و .env باشد. راهنمای شروع سریع پروژه، تگ latest را دریافت می‌کند. به‌جای آن، یک تگ نسخه (release tag) را ثابت کنید تا ارتقا فقط زمانی انجام شود که فایل را ویرایش می‌کنید و بازگشت به نسخه قبلی (rollback) تنها با تغییر یک خط امکان‌پذیر باشد. تگ به‌تنهایی تضمین‌کننده محتوای یکسان نیست، زیرا تگ‌های ایمیج تغییرپذیرند و ناشر می‌تواند آن را به ایمیج جدیدی اشاره دهد. اگر قرار است docker compose up -d در ماه آینده دقیقاً همان gateway امروز را به شما بدهد، digest ایمیج را نیز به فرمت ghcr.io/berriai/litellm:v1.95.0@sha256:<digest> اضافه کنید؛ دستور docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 آن را چاپ می‌کند.

services:
  litellm:
    image: ghcr.io/berriai/litellm:v1.95.0
    restart: unless-stopped
    command: ["--config", "/app/config.yaml", "--num_workers", "1"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file: .env
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: litellm
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

در اینجا Compose فایل .env را دو بار می‌خواند. یک بار برای جایگذاری ${POSTGRES_PASSWORD} در داخل خود فایل compose، و یک بار از طریق env_file برای انتقال تمام متغیرها به داخل کانتینر.

v1.95.0 نسخه جاری در آگوست 2026 بود. صفحه releases پروژه را بررسی کنید و هنگام استقرار، نسخه جاری را ثابت (pin) کنید. هر نسخه یک امضا منتشر می‌کند، بنابراین می‌توانید پیش از اعتماد به ایمیج، آن را بررسی کنید:

cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0

خط پورت به صورت 127.0.0.1:4000:4000 است که پورت را فقط روی اینترفیس loopback منتشر می‌کند. اگر به‌جای آن 4000:4000 بنویسید، gateway شما از کل اینترنت در دسترس خواهد بود، زیرا Docker قوانین خاص خود را در زنجیره iptables FORWARD اضافه می‌کند و این قوانین پیش از قوانین ufw ارزیابی می‌شوند، بنابراین ufw deny 4000 مانع آن نمی‌شود. این رایج‌ترین روشی است که یک gateway خود-میزبانی‌شده (self-hosted) به‌طور ناخواسته در دسترس عموم قرار می‌گیرد: به نحوه انتشار پورت کانتینر توسط Docker که ufw را دور می‌زند مراجعه کنید. ترافیک از خارج باید از طریق reverse proxy وارد شود.

کلیدهای ارائه‌دهنده را خارج از ایمیج نگه دارید

فایل .env تمام اسرار را در خود جای می‌دهد. این فایل در زمان اجرا به عنوان متغیر محیطی (environment) تزریق می‌شود، بنابراین هرگز در ایمیج نهایی قرار نمی‌گیرد و در مخزن کد (commit) ذخیره نمی‌شود.

LITELLM_MASTER_KEY=sk-REPLACE_ME
LITELLM_SALT_KEY=sk-REPLACE_ME_TOO
POSTGRES_PASSWORD=REPLACE_ME_AS_WELL
DATABASE_URL=postgresql://litellm:REPLACE_ME_AS_WELL@db:5432/litellm
STORE_MODEL_IN_DB=True
LITELLM_MODE=PRODUCTION
LITELLM_LOG=ERROR
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...

دو کلید LiteLLM را با تصادفی‌سازی واقعی تولید کنید و سپس دسترسی به فایل را محدود نمایید:

printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .env

LITELLM_MASTER_KEY اعتبارنامه مدیریت است. این کلید، API مدیریت را احراز هویت می‌کند و رمز عبور برای رابط کاربری Admin در /ui است. هیچ برنامه‌ای نباید آن را در اختیار داشته باشد.

LITELLM_SALT_KEY اعتبارنامه‌های ارائه‌دهنده ذخیره‌شده در دیتابیس را رمزنگاری می‌کند. آن را یک‌بار تنظیم کنید و دیگر تغییر ندهید. اگر بعداً آن را تغییر دهید، اعتبارنامه‌های ذخیره‌شده قبلی قابل رمزگشایی نخواهند بود؛ در نتیجه، گیت‌وی به‌طور عادی بالا می‌آید اما تمام فراخوانی‌ها به آن ارائه‌دهندگان در مرحله احراز هویت با شکست مواجه می‌شوند.

STORE_MODEL_IN_DB=True به شما امکان می‌دهد مدل‌ها را از طریق رابط کاربری Admin اضافه یا ویرایش کنید، بدون اینکه نیازی به دستکاری فایل config.yaml باشد. این کار راحت است، اما باعث می‌شود منبع حقیقت (source of truth) شما به دو بخش تقسیم شود. تصمیم بگیرید کدام‌یک مرجع اصلی است و این تصمیم را در کنار فایل پیکربندی یادداشت کنید.

استدلالی که باعث می‌شود کلیدها را خارج از فایل پیکربندی نگه داریم، همان استدلالی است که آن‌ها را از ابزارهایی که به یک عامل (agent) می‌دهید، دور نگه می‌دارد. دور نگه داشتن اسرار ارائه‌دهنده از عامل‌های هوش مصنوعی این الگو را پوشش می‌دهد و فایل‌های env و اسرار در Docker Compose جزئیات فنی آن را توضیح می‌دهد.

سرویس را بالا بیاورید و اولین بوت را نظارت کنید:

docker compose up -d
docker compose logs -f litellm

بررسی عملکرد صحیح

دو کاوشگر (probe) بدون احراز هویت و یک کاوشگر با احراز هویت وجود دارند که به دلایل متفاوتی با شکست مواجه می‌شوند.

curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness

/health/liveliness به احراز هویت نیاز ندارد و تا زمانی که پردازش در حال اجرا باشد، پاسخ "I'm alive!" را برمی‌گرداند. /health/readiness نیز به احراز هویت نیاز ندارد. این کاوشگر یک شیء JSON شامل "status": "healthy" و فیلد db برمی‌گرداند، یا در صورتی که دیتابیس در دسترس نباشد، کد خطای 503 را ارسال می‌کند. مانیتورینگ خود را روی readiness تنظیم کنید، زیرا liveliness در gatewayای که قادر به جستجوی یک کلید مجازی نیست، همچنان سبز باقی می‌ماند.

بررسی احراز هویت‌شده، همان کاوشگری است که با ارائه‌دهندگان (providers) ارتباط برقرار می‌کند:

curl -s http://127.0.0.1:4000/health \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

این کاوشگر با آرایه‌های healthy_endpoints و unhealthy_endpoints پاسخ می‌دهد. قرار گرفتن یک مدل در وضعیت unhealthy_endpoints همراه با خطای احراز هویت، به این معنی است که کلید ارائه‌دهنده در .env اشتباه است یا وجود ندارد؛ این همان خطایی است که اکنون باید شناسایی کنید. از آنجا که background_health_checks: true تنظیم شده است، پروکسی این کاوشگرها را هر health_check_interval ثانیه به‌طور خودکار اجرا می‌کند و /health آخرین نتیجه را برمی‌گرداند؛ بنابراین، polling کردن آن باعث نمی‌شود که هر بار یک درخواست تست به ارائه‌دهندگان شما ارسال شود.

کلیدهای مجازی و بودجه‌های اختصاصی برای هر کلید

هر برنامه کلید مخصوص به خود را دریافت می‌کند که بر اساس کلید اصلی (master key) صادر شده است.

curl -s http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "key_alias": "nightly-summariser",
    "models": ["bulk"],
    "max_budget": 5,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 200000
  }'

پاسخ شامل فیلد key است که با sk- شروع می‌شود. آن رشته همان چیزی است که برنامه دریافت می‌کند و تنها چیزی است که برنامه در اختیار خواهد داشت.

  • models یک لیست مجاز (allowlist) از درخواست‌هایی است که این کلید می‌تواند ارسال کند. کلید بالا فقط می‌تواند درخواست bulk را ارسال کند و هیچ چیز دیگری مجاز نیست.
  • max_budget: 5 با مقدار budget_duration: "30d" معادل پنج دلار آمریکا در هر ماه تقویمی است. LiteLLM بودجه 30d را در روز اول هر ماه در نیمه‌شب به وقت UTC بازنشانی می‌کند (مگر اینکه timezone را در بخش litellm_settings تنظیم کرده باشید)؛ این بازنشانی به جای بازه 30 روزه متغیر، در زمان مشخص انجام می‌شود. بنابراین، هنگامی که کلید پنج دلار را مصرف کرد، تا روز اول ماه بعد از کار می‌افتد.
  • rpm_limit و tpm_limit سقف تعداد درخواست در دقیقه و تعداد توکن در دقیقه را فقط برای همین کلید تعیین می‌کنند.
  • key_alias نامی است که شش هفته بعد در لاگ هزینه‌ها مشاهده خواهید کرد. همیشه آن را تنظیم کنید.

هنگامی که بودجه تمام شود، فراخوانی با خطای نوع budget_exceeded و پیامی به شکل زیر شکست می‌خورد:

Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>

کد وضعیت به نسخه (release) بستگی دارد. در نسخه ثابت v1.95.0، این کد HTTP 429 است. از نسخه v1.104.0 به بعد، مقدار پیش‌فرض HTTP 422 است و تنظیم budget_exceeded_status_code: 429 در بخش litellm_settings، کد قبلی را بازمی‌گرداند. موارد واقعی rpm_limit و tpm_limit در هر دو نسخه همچنان کد 429 را برمی‌گردانند. پس از هر ارتقا، بررسی کنید که کدام کد را دریافت می‌کنید.

کد وضعیت باعث سردرگمی می‌شود، زیرا هیچ‌کدام از این کدها مستقیماً به معنای «اتمام بودجه» نیستند. کتابخانه کلاینت، کد 429 را به عنوان محدودیت نرخ (rate limit) گزارش می‌دهد و ممکن است با مکانیزم backoff دوباره تلاش کند، در حالی که بودجه تا زمان بازنشانی برنمی‌گردد. همچنین کد 422 را به عنوان درخواستی که قابل پردازش نبوده گزارش می‌دهد. بدنه پاسخ را در کنار کد وضعیت لاگ کنید، در غیر این صورت اتمام بودجه هر بار به شکل خطای متفاوتی به نظر می‌رسد.

کلیدها را از طریق همان API مدیریتی بررسی و تنظیم کنید:

curl -s "http://127.0.0.1:4000/key/info?key=sk-..." \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

curl -s -X POST http://127.0.0.1:4000/key/update \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"key": "sk-...", "max_budget": 25}'

بودجه‌ای که در gateway اعمال می‌شود، حتی زمانی که مشکل از خود عامل (agent) باشد نیز معتبر باقی می‌ماند؛ به همین دلیل است که این قابلیت ستون فقرات کنترل هزینه برای عامل‌های هوش مصنوعی روی VPS محسوب می‌شود.

ارسال کارهای حجیم به یک مدل ارزان

کلاینت خود را به سمت gateway هدایت کنید. Base URL، کلید و نام مدل را تنظیم کنید:

curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bulk",
    "messages": [{"role": "user", "content": "Say hello in five words."}]
  }'

هر کتابخانه کلاینت OpenAI به همین روش کار می‌کند، اگرچه نام گزینه‌ها در زبان‌های مختلف متفاوت است. در کلاینت Python، مقدار base_url را روی https://gateway.example.com/v1 و api_key را روی کلید مجازی تنظیم کنید. کلاینت‌های JavaScript و TypeScript از همین دو گزینه با نام‌های baseURL و apiKey استفاده می‌کنند.

سیاست مسیریابی تعریف‌شده در config.yaml اکنون بدون اطلاع فراخواننده اعمال می‌شود. یک درخواست برای bulk به مدل ارزان ارسال می‌شود. اگر آن فراخوانی پس از تلاش‌های مجدد (retries) با شکست مواجه شود، درخواست مجدداً علیه strong امتحان می‌شود. اگر طول prompt برای bulk بیش از حد باشد، context_window_fallbacks به‌جای بازگرداندن خطا، آن را به strong می‌فرستد. کارهای حجیم مانند دسته‌بندی یا خلاصه‌سازی backlog به‌صورت پیش‌فرض با هزینه کم اجرا می‌شوند و تنها درخواست‌های دشوار هزینه بیشتری خواهند داشت.

اینجاست که یک gateway در کار با ایجنت‌های دارای ابزار (tool-using agents) ارزش خود را نشان می‌دهد. یک سرور MCP (پروتکل زمینه مدل) روی همان VPS و ایجنتی که آن را هدایت می‌کند، هر دو می‌توانند به یک endpoint اشاره کنند؛ بنابراین مدل پشت آن‌ها بدون نیاز به redeploy کردن هیچ‌کدام، تغییر می‌کند.

چگونه متوجه شویم که fallback رخ داده است؟

این همان حالت شکستی است که هزینه مالی به همراه دارد، زیرا در ظاهر هیچ‌چیز خراب به نظر نمی‌رسد. یک fallback موفق، کد وضعیت HTTP 200 را به همراه یک بدنه پاسخ معمولی برمی‌گرداند. مدل ارزان‌قیمت شما ممکن است یک روز کامل از دسترس خارج باشد و هر درخواست به‌آرامی توسط مدل گران‌قیمت پاسخ داده شود؛ در این صورت، اولین نشانه از این اتفاق، صورت‌حساب شما خواهد بود.

شواهد این اتفاق در هدرهای پاسخ (response headers) موجود است. آن‌ها را بررسی کنید:

curl -s -D - -o /dev/null http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{"model":"bulk","messages":[{"role":"user","content":"ping"}]}' \
  | grep -i '^x-litellm'
  • x-litellm-model-group نام مدلی است که درخواست تحت آن مسیریابی شده است، مانند bulk. x-litellm-model-id شناسه deployment پاسخ‌دهنده است که می‌توانید آن را با /v1/model/info?litellm_model_id=... جستجو کنید. زمانی که این شناسه جزو bulkهای شما نباشد، یعنی یک fallback رخ داده است.
  • x-litellm-attempted-fallbacks و x-litellm-attempted-retries تعداد این موارد را می‌شمارند. در یک فراخوانی سالم، هیچ‌کدام عددی بزرگ‌تر از 0 را نشان نمی‌دهند.
  • x-litellm-response-cost هزینه همان یک فراخوانی خاص به دلار آمریکا است.
  • x-litellm-call-id شناسه‌ای است که برای یافتن همان فراخوانی در لاگ‌های خود از آن استفاده می‌کنید.

مقدار x-litellm-attempted-fallbacks را در هر درخواست ثبت کنید و هر زمان که مقدار آن بالای 0 بود، هشدار دریافت کنید. همین یک عدد، تفاوت بین یک سیاست مسیریابی کارآمد و سیاستی است که به‌طور خاموش به «همیشه از مدل گران استفاده کن» تبدیل شده است.

نسخه کامل این قابلیت، tracing است که نیاز به راه‌اندازی اختصاصی دارد: میزبانی شخصی Langfuse برای ردیابی فراخوانی‌های agent. ابزار LiteLLM این callback را ارائه می‌دهد، بنابراین اتصال آن تنها به دو خط کد به اضافه اعتبارنامه‌ها نیاز دارد.

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.com

برای Langfuse نسخه 3 و بالاتر، صفحه Langfuse در LiteLLM اکنون استفاده از preset langfuse_otel را توصیه می‌کند؛ callback مربوط به langfuse که در بالا ذکر شد همچنان مستند است. متغیرهای failure_callback و همچنین success_callback را تنظیم کنید. اگر این کار را انجام ندهید، تنها ردیابی‌هایی را نگه می‌دارید که در آن‌ها هیچ خطایی رخ نداده است. جدا از تمام این موارد، LiteLLM به ازای هر درخواست یک ردیف هزینه در Postgres می‌نویسد و رابط کاربری Admin در /ui آن جدول را می‌خواند. این جدول با افزایش ترافیک رشد می‌کند، بنابراین آن را روی یک دیسک کوچک زیر نظر داشته باشید.

Gateway را پشت یک reverse proxy قرار دهید

هیچ چیزی خارج از سرور نباید به پورت 4000 دسترسی داشته باشد. TLS را در nginx یا Caddy خاتمه دهید و درخواست‌ها را به آدرس loopback ارسال کنید.

location / {
    proxy_pass http://127.0.0.1:4000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 600s;
}

این دو خط معمولاً حذف می‌شوند. proxy_buffering off مهم است، چون یک streaming completion مجموعه‌ای از server-sent eventهاست و وقتی buffering در nginx فعال باشد، nginx قطعه‌ها را پیش از ارسال به client در bufferها جمع می‌کند و تحویل را به تأخیر می‌اندازد. proxy_read_timeout 600s نیز مهم است، چون مقدار پیش‌فرض 60 ثانیه در nginx، بیشترین فاصله‌ای است که nginx بین دو read از gateway منتظر می‌ماند، نه محدودیت کل response. یک completion غیر-streamed تا پایان generation هیچ داده‌ای ارسال نمی‌کند؛ بنابراین اگر generation طولانی باشد، بیش از 60 ثانیه بدون رسیدن حتی یک byte ادامه پیدا می‌کند و client با خطای 504 مواجه می‌شود، درحالی‌که error log مقدار upstream timed out (110: Connection timed out) while reading response header from upstream را ثبت می‌کند. یک completion streamed که همچنان chunk ارسال می‌کند، می‌تواند بسیار بیشتر از 60 ثانیه ادامه داشته باشد؛ این completion فقط زمانی باعث فعال‌شدن timeout می‌شود که model برای این مدت ساکت بماند.

برای certificate، استفاده از Certbot با Let's Encrypt در nginx کوتاه‌ترین مسیر است. اگر این سرور از قبل چند container را ارائه می‌کند، استفاده از Traefik در برابر چند برنامه Compose مسیریابی و certificateها را در یک نقطه مدیریت می‌کند.

دروازه اکنون یک نقطهٔ شکست واحد است

دربارهٔ چیزی که ساخته‌اید صادق باشید. اکنون هر برنامه‌ای که در اختیار دارید به یک container روی یک VPS وابسته است. تا زمانی که این container از کار افتاده است، هیچ‌چیز نمی‌تواند هیچ مدلی را فراخوانی کند؛ حتی providerهایی که کاملاً سالم‌اند. نتیجهٔ این وضعیت چهار نکته است.

  • یک پیکربندی نادرست همه‌چیز را هم‌زمان از کار می‌اندازد. restart: unless-stopped پس از crash، سرویس را restart می‌کند و containerی را که نمی‌تواند config.yaml را parse کند، پیوسته restart می‌کند. پس از هر تغییر پیکربندی، docker compose logs litellm را بخوانید و تغییرات پیکربندی را زمانی انجام دهید که فرصت monitor کردن آن‌ها را دارید.
  • در صورت cache miss، Postgres در مسیر درخواست قرار می‌گیرد. جست‌وجوی کلید مجازی وقتی کلید cache نشده باشد از آن استفاده می‌کند؛ ثبت هزینه پس از ارسال پاسخ به‌صورت asynchronous اجرا می‌شود. بازگشت /health/readiness با کد 503 هشداری است که gateway در حال اجراست، اما هیچ‌یک از این دو کار را نمی‌تواند انجام دهد.
  • ابتدا از هسته‌ها استفاده کنید، سپس instance اضافه کنید. راهنمای production پروژه دربارهٔ یک worker برای هر instance (--num_workers 1) برای Kubernetes یا autoscaler دیگری است که podها را به‌طور خودکار اضافه می‌کند. برای یک VM یا container مستقل مانند این مورد، توصیه برعکس است: تعداد workerها را برابر تعداد vCPUهای ماشین قرار دهید. در ماشین 1 vCPU بالا، این مقدار همچنان --num_workers 1 است؛ در ماشین بزرگ‌تر آن را افزایش دهید و به خاطر داشته باشید که هر worker حافظهٔ مخصوص خود را مصرف می‌کند. اجرای gateway دوم پشت load balancer، وابستگی به یک container واحد را از بین می‌برد. اما وابستگی به database همچنان باقی می‌ماند.
  • از چیزهایی که نمی‌توانید دوباره تولید کنید backup بگیرید. این موارد شامل config.yaml و .env، به‌همراه یک pg_dump از database هستند. از دست دادن LITELLM_SALT_KEY باعث می‌شود credentialهای رمزگذاری‌شدهٔ provider درون آن dump بی‌استفاده شوند؛ بنابراین فایل env و dump باید در یک backup job قرار داشته باشند: backupهای restic در storage خارج از سرور

برای upgrade، tag مربوط به image را ویرایش کنید و docker compose up -d را اجرا کنید. LiteLLM به‌طور پیش‌فرض هنگام startup، prisma migrate deploy را اجرا می‌کند؛ بنابراین container جدید در نخستین boot، schema مربوط به database را migrate می‌کند. پیش از تغییر tag، dump بگیرید؛ زیرا بازگرداندن image قدیمی، migrationای را که قبلاً اجرا شده است برنمی‌گرداند.

یادداشت‌های release مربوط به همهٔ versionهایی را که رد می‌کنید بخوانید، نه فقط versionی را که در نهایت نصب می‌کنید. انتقال از v1.95.0 به v1.104.0 یا نسخه‌های جدیدتر، از چند breaking change عبور می‌کند: status code مربوط به budget که در بالا گفته شد، proxyای که با master key تنظیم‌نشده، خالی یا عمومی‌شده شروع نمی‌شود، و proxyای که هنگام شکست setup مربوط به database در startup خارج می‌شود؛ این وضعیت در restart: unless-stopped به‌صورت restart loop دیده می‌شود. اگر از v1.102.x یا نسخه‌های قدیمی‌تر می‌آیید، یادداشت‌های v1.104.0 همچنین از شما می‌خواهند دو index از نوع LiteLLM_SpendLogs را خودتان ایجاد کنید.

FAQ

آیا LiteLLM تأخیر محسوسی به هر فراخوانی اضافه می‌کند؟

این پروژه در فایل README خود در نوامبر 2026، عدد 8 میلی‌ثانیه را در صدک 95 برای 1000 درخواست در ثانیه اعلام کرده است. این عدد را به عنوان یک آمار تبلیغاتی از سوی سازنده در نظر بگیرید. عددی که در واقع تأخیر شما را تغییر می‌دهد، فاصله شبکه بین برنامه‌های شما و gateway است، زیرا شما یک رفت‌وبرگشت (round trip) به هر فراخوانی اضافه کرده‌اید. gateway را در همان منطقه‌ای (region) اجرا کنید که برنامه‌های فراخواننده در آن قرار دارند، سپس سربار اختصاصی خود را با استفاده از هدر x-litellm-overhead-duration-ms در یک پاسخ واقعی اندازه‌گیری کنید.

چرا پس از قرار دادن nginx در مقابل سرویس، قابلیت streaming از کار افتاد؟

زیرا nginx به‌صورت پیش‌فرض پاسخ‌های upstream را بافر می‌کند و یک completion در حالت streaming، مجموعه‌ای از رویدادهای ارسالی از سمت سرور (server-sent events) است. با فعال بودن proxy_buffering، nginx تکه‌ها را در بافر جمع‌آوری می‌کند و پیش از ارسال به کلاینت، آن‌ها را نگه می‌دارد که باعث تأخیر در تحویل می‌شود. مقدار proxy_buffering off; را در بلاک location تنظیم کنید. همچنین مقدار proxy_read_timeout را در همان بلاک افزایش دهید. nginx به‌صورت پیش‌فرض پس از 60 ثانیه بدون دریافت داده از gateway، اتصال را قطع می‌کند؛ این زمان در تولید محتوای طولانی (غیر streaming) به‌راحتی سپری می‌شود و کلاینت خطای 504 دریافت می‌کند.

وقتی بودجه یک کلید مجازی (virtual key) تمام می‌شود چه اتفاقی می‌افتد؟

فراخوانی با خطایی از نوع budget_exceeded و پیامی با فرمت Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget> شکست می‌خورد. در نسخه v1.95.0، وضعیت HTTP 429 است؛ از نسخه v1.104.0 به بعد، وضعیت پیش‌فرض به HTTP 422 تغییر یافته است. هیچ‌کدام از این کدها مستقیماً به مفهوم «بودجه» اشاره نمی‌کنند و این همان دام است: کتابخانه‌های کلاینت کد 429 را به عنوان محدودیت نرخ (rate limit) گزارش می‌دهند و ممکن است تلاش مجدد (retry) انجام دهند، بنابراین افراد به‌جای خواندن متن پیام، به دنبال رفع مشکل throttling می‌روند. بدنه پاسخ را در کنار کد وضعیت لاگ کنید. موقعیت واقعی کلید را با استفاده از /key/info?key=sk-... در برابر کلید اصلی (master key) بررسی کنید و اگر بودجه خیلی کم تعیین شده است، سقف آن را با /key/update افزایش دهید.

آیا gateway می‌تواند علاوه بر مدل‌های میزبانی‌شده، به یک مدل محلی نیز درخواست ارسال کند؟

بله، این مورد تنها یک ورودی دیگر در model_list است. از پیشوند ollama_chat/ به همراه یک api_base استفاده کنید، برای مثال model: ollama_chat/llama3.1 در کنار api_base: http://ollama:11434. در شبکه پیش‌فرض Compose، عبارت localhost داخل یک container به معنای همان container است، بنابراین از نام سرویس Compose یا آدرس میزبان در شبکه Docker استفاده کنید و هرگز از 127.0.0.1 استفاده نکنید. شبکه میزبان (Host networking)، که در آن container از stack شبکه میزبان استفاده می‌کند، یک استثنا است. راه‌اندازی مدل محلی یک وظیفه جداگانه است: به میزبانی مدل LLM با Ollama روی VPS مراجعه کنید.

آیا این مقاله مفید بود؟