استضافة LiteLLM كبوابة موحّدة لنماذج الذكاء الاصطناعي

ما الذي يفعله بوّاب LLM مستضاف ذاتياً

LiteLLM هو بوّاب LLM مفتوح المصدر تستضيفه بنفسك: نقطة نهاية HTTP واحدة تستدعيها جميع تطبيقاتك، ثم يمرّر كل طلب إلى المزوّد المناسب لمعالجته. يشير LLM إلى نموذج لغوي كبير. يتحدث البوّاب باستخدام واجهة برمجة التطبيقات لإكمالات المحادثة في OpenAI، لذلك تعمل معه أي مكتبة عميلة تتصل بـOpenAI مسبقاً بعد تغييرين فقط: عنوان URL الأساسي والمفتاح.

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

بعد تشغيله، ستحصل على ما يلي:

• نقطة نهاية واحدة. تستهدف التطبيقات https://gateway.example.com/v1 وتطلب اسم نموذج اخترعته، مثل bulk أو strong.
• مفاتيح افتراضية. يحصل كل تطبيق على مفتاحه الخاص، وقائمة النماذج المسموح بها، وحد الإنفاق الخاص به. ويمكنك إبطال مفتاح واحد دون المساس بالمفاتيح الأخرى.
• بدائل تلقائية. يُعاد إرسال الطلب الفاشل أو الطلب ذي المحث الكبير إلى نموذج مختلف تلقائياً.
• سجل مسجّل. يكتب كل طلب سجلاً يتضمن تكلفته، لذلك يمكن معرفة إجابة سؤال «أي تطبيق أنفق ذلك؟».

لماذا تشغّل البوابة بنفسك

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

ما تحتاج إليه

• خادم VPS ‏(خادم افتراضي خاص) يعمل بنظام Ubuntu 24.04، مع تثبيت Docker وإضافة Compose.
• اسم نطاق يشير إلى الخادم، إذا كانت الأجهزة خارج الخادم ستصل إلى البوابة عبر TLS ‏(أمان طبقة النقل).
• مفتاح API واحد على الأقل لأحد المزوّدين.

لا تجري البوابة أي استدلال. فهي تمرّر الطلبات وتعيد بث الإجابات، لذلك يرتبط حمل CPU بحجم الطلبات لا بحجم النموذج. يستطيع خادم مزوّد بـ1 vCPU تشغيل عدد محدود من التطبيقات الداخلية دون مشاكل. أما ما ينمو فهو قاعدة البيانات، لأن البوابة تكتب صفاً للمصروفات لكل طلب.

اكتب 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
  allowed_fails: 3
  cooldown_time: 30
  json_logs: true
  set_verbose: false

router_settings:
  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 في مستودعك.

يتشارك إدخالان الاسم strong عن قصد. عندما تحمل أكثر من عملية نشر القيمة نفسها model_name، يتعامل معها الموجّه كعمليات قابلة للتبادل، ويحاول العملية الأخرى عند فشل الأولى. بهذه الطريقة يستمر strong في العمل إذا واجه أحد المورّدين مشكلة مؤقتة.

يعيد num_retries: 2 محاولة عملية النشر نفسها عند حدوث خطأ قابل لإعادة المحاولة. لا يعمل البديل إلا بعد استنفاد هذه المحاولات. يؤدي allowed_fails: 3 مع cooldown_time: 30 إلى إخراج عملية النشر من التناوب لمدة 30 ثانية بعد فشلها 3 مرات، لذلك يتوقف المورّد الذي يعيد أخطاء 500 عن تلقي محاولة في كل طلب.

يملك fallbacks وcontext_window_fallbacks محفزات مختلفة، والثاني هو المفيد الذي يتجاهله الناس عادةً.

• يعمل fallbacks عند فشل الطلب الأساسي.
• يعمل context_window_fallbacks عندما يرفض المورّد الطلب لأنه أطول من نافذة السياق الخاصة بذلك النموذج، ولذلك يُرسل الطلب الكبير إلى نموذج يملك مساحة كافية بدلاً من إعادة خطأ إلى المستدعي.

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

نشر LiteLLM على VPS باستخدام Docker Compose

أنشئ دليلاً يحتوي على ثلاثة ملفات: config.yaml وdocker-compose.yml و.env. تسحب خطوات البدء السريع من upstream الوسم latest. ثبّت وسم إصدار بدلاً منه، حتى يمنحك docker compose up -d في الشهر المقبل البوابة نفسها التي يمنحك إياها اليوم، ويصبح التراجع إلى إصدار سابق أمراً من سطر واحد.

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 هو الإصدار الحالي في August 2026. تحقّق من صفحة إصدارات المشروع وثبّت الإصدار الحالي عند النشر. ينشر كل إصدار توقيعاً، لذلك يمكنك التحقق من الصورة قبل الوثوق بها:

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 بدلاً منه، فستصبح بوابتك متاحة من الإنترنت بالكامل، لأن Docker يضيف قواعده الخاصة إلى سلسلة FORWARD في iptables، وتُقيَّم هذه القواعد قبل قواعد ufw، لذلك لا يمنعها ufw deny 4000. هذه هي الطريقة الأكثر شيوعاً لانكشاف بوابة مستضافة ذاتياً على الإنترنت: راجع كيفية نشر Docker لمنفذ حاوية مباشرةً متجاوزاً ufw. تصل حركة الشبكة من الخارج عبر reverse proxy بدلاً من ذلك.

أبقِ مفاتيح المزوّد خارج الصورة

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

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 بيانات اعتماد المسؤول. يُستخدم لمصادقة Management API، وهو كلمة المرور الخاصة بواجهة Admin UI على /ui. يجب ألا تحتفظ به أيٌّ من التطبيقات مطلقاً.

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

يتيح لك STORE_MODEL_IN_DB=True إضافة النماذج وتعديلها من Admin UI دون تعديل config.yaml. هذا مريح، لكنه يقسم مصدر الحقيقة إلى جزأين. حدّد المصدر المعتمد، وسجّل هذا القرار بجانب ملف الإعداد.

المنطق الذي يبرر إبقاء المفاتيح خارج ملف الإعداد هو نفسه الذي يبرر إبقاءها خارج الأدوات التي تمنحها لوكيل. يشرح إبقاء أسرار المزوّد خارج وكلاء الذكاء الاصطناعي هذا النمط، بينما يشرح ملفات البيئة والأسرار في Docker Compose الجوانب العملية.

شغّل الخدمة وراقب الإقلاع الأول:

docker compose up -d
docker compose logs -f litellm

تحقّق من عمله فعلياً

هناك فحصان دون مصادقة وفحص واحد يتطلب المصادقة، وتفشل هذه الفحوص لأسباب مختلفة.

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!" ما دام process قيد التشغيل. ولا يحتاج /health/readiness إلى مصادقة أيضاً. ويعيد كائن JSON يحتوي على "status": "healthy" وحقل db، أو يعيد 503 عندما يتعذر الوصول إلى قاعدة البيانات. وجّه نظام المراقبة إلى readiness، لأن liveliness يبقى بحالة خضراء على gateway لا يستطيع البحث عن virtual key واحدة.

الفحص الذي يتحدث إلى providers هو الفحص الذي يتطلب المصادقة:

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

يستجيب بمصفوفتَي healthy_endpoints وunhealthy_endpoints. إذا ظهر model في unhealthy_endpoints مع خطأ مصادقة، فهذا يعني أن provider key في .env غير صحيحة أو مفقودة. وهذا هو العطل الذي تريد اكتشافه الآن. وبما أن background_health_checks: true مضبوط، يشغّل proxy هذه الفحوص تلقائياً كل health_check_interval ثانية، ويعيد /health آخر نتيجة، لذلك لا يؤدي استقصاؤه إلى إرسال طلب اختبار إلى providers في كل مرة.

المفاتيح الافتراضية والميزانيات لكل مفتاح

يحصل كل تطبيق على مفتاح خاص به، ويُنشأ هذا المفتاح باستخدام المفتاح الرئيسي.

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 قائمة سماح تحدد ما يمكن لهذا المفتاح طلبه. يمكن للمفتاح أعلاه طلب bulk فقط، ولا شيء غيره.
• max_budget: 5 مع budget_duration: "30d" يحددان ميزانية قدرها خمسة دولارات أمريكية لكل 30 يوماً متحركة، ثم يتوقف المفتاح عن العمل.
• rpm_limit وtpm_limit يحددان الحد الأقصى للطلبات في الدقيقة والرموز في الدقيقة لهذا المفتاح وحده.
• key_alias هي القيمة التي ستتعرف عليها في سجل الإنفاق بعد ستة أسابيع. عيّنها دائماً.

عند نفاد الميزانية، يفشل الطلب مع HTTP 401 ويكون نص الاستجابة على النحو الآتي:

ExceededBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07

رمز الحالة هو ما يجعل هذه المشكلة مربكة. تبلغ مكتبة العميل عن 401 باعتباره مشكلة مصادقة، لذلك يبدأ المطور الذي يقرأ تتبع المكدس بالتحقق مما إذا كان المفتاح صالحاً. سجّل نص الاستجابة بجانب رمز الحالة، وإلا فسيبدو نفاد الميزانية في كل مرة كأنه بيانات اعتماد معطّلة.

افحص المفاتيح واضبطها باستخدام واجهة الإدارة البرمجية نفسها:

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}'

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

إرسال الأعمال المجمّعة إلى نموذج منخفض التكلفة

وجّه العميل إلى البوابة. عنوان 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 بالطريقة نفسها: اضبط base_url على https://gateway.example.com/v1، واضبط api_key على المفتاح الافتراضي.

تُطبَّق الآن سياسة التوجيه من config.yaml دون أن يعرف المستدعي ذلك. يذهب الطلب إلى bulk إلى النموذج منخفض التكلفة. إذا فشل هذا الاستدعاء بعد إعادة المحاولة المحددة له، يُعاد إرسال الطلب إلى strong. وإذا كان الـprompt طويلاً جداً بالنسبة إلى bulk، يرسله context_window_fallbacks إلى strong بدلاً من إرجاع خطأ. تُنفَّذ الأعمال المجمّعة، مثل تمريرة تصنيف أو تراكم ملخصات، باستخدام النموذج منخفض التكلفة افتراضياً، ولا تتكلف الطلبات الصعبة مبلغاً أكبر إلا عند الحاجة.

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

كيف تعرف أن التحويل الاحتياطي حدث؟

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

الأدلة موجودة في ترويسات الاستجابة. اطلبها:

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 هو ما طلبه العميل. x-litellm-model-id هو النشر الذي أجاب. عندما يختلف هذان الحقلان، يكون التحويل الاحتياطي قد حدث.
• x-litellm-attempted-fallbacks وx-litellm-attempted-retries يعدّان مرات حدوثه. في الطلب السليم تكون قيمة كل منهما 0.
• x-litellm-response-cost هي تكلفة ذلك الطلب الواحد بالدولار الأمريكي.
• x-litellm-call-id هو المعرّف الذي تستخدمه للعثور على الطلب نفسه في سجلاتك.

سجّل x-litellm-attempted-fallbacks في كل طلب، وأطلق تنبيهاً عندما تتوقف قيمته عن كونها 0. هذا الرقم الواحد هو الفارق بين سياسة توجيه تعمل كما ينبغي وسياسة توجيه تحولت بصمت إلى «استخدم النموذج الأغلى دائماً».

النسخة الكاملة من ذلك هي التتبّع، وهي تستحق إعداداً مستقلاً: Langfuse مستضاف ذاتياً لتتبّع استدعاءات الوكلاء. يوفّر LiteLLM دالة الاستدعاء، لذا لا يتطلب ربطها سوى سطرين وبيانات الاعتماد.

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.com

اضبط failure_callback وsuccess_callback أيضاً. إذا تخطيت ذلك، فلن تحتفظ إلا بالتتبعات التي لم يحدث فيها خطأ. وبصرف النظر عن ذلك، يكتب LiteLLM صفاً عن الإنفاق لكل طلب في Postgres، وتقرأ واجهة الإدارة في /ui ذلك الجدول. يزداد حجمه مع ازدياد حركة الشبكة، لذا راقبه إذا كانت مساحة القرص محدودة.

ضع البوابة خلف 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 لأن الاستجابة المتدفقة تتكون من أحداث يرسلها الخادم، وعندما يكون التخزين المؤقت مفعّلاً، يحتفظ nginx بالكتل حتى تنتهي الاستجابة. عندها لا يرى العميل أي بيانات، ثم يتلقى كل شيء دفعة واحدة. ويهم proxy_read_timeout 600s لأن التوليد الطويل يتجاوز المهلة الافتراضية البالغة 60 ثانية في nginx. عند حدوث ذلك، يتلقى العميل الخطأ 504، ويسجل سجل الأخطاء upstream timed out (110: Connection timed out) while reading response header from upstream.

بالنسبة إلى الشهادة، فإن Certbot مع Let's Encrypt على nginx هو المسار الأقصر. وإذا كان الخادم يشغّل عدة حاويات بالفعل، فإن Traefik أمام عدة تطبيقات Compose يتولى التوجيه والشهادات في مكان واحد.

البوابة الآن نقطة فشل واحدة

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

• يؤدي الإعداد السيئ إلى إيقاف كل شيء دفعة واحدة. يعيد restart: unless-stopped تشغيل الحاوية بعد تعطلها، ويعيد تشغيل الحاوية التي لا تستطيع تحليل config.yaml مراراً. اقرأ docker compose logs litellm بعد كل تغيير في الإعداد، وأجرِ تغييرات الإعداد عندما يتوفر لديك وقت لمراقبتها.
• توجد Postgres في مسار الطلبات. يستخدمها كل من البحث عن المفتاح الافتراضي وتسجيل الإنفاق. يشير إرجاع /health/readiness لحالة 503 إلى أن البوابة تعمل، لكنها عاجزة عن تنفيذ أي من العمليتين.
• وسّع الخدمة بإضافة مثيلات، لا بجعل مثيل واحد أكبر. توصي إرشادات المشروع نفسها باستخدام عامل واحد لكل مثيل (--num_workers 1)، مع مشاركة عدة مثيلات لقاعدة بيانات واحدة. يؤدي وضع بوابتين صغيرتين خلف موازن حمل إلى إزالة الحاوية الوحيدة من نقطة الفشل. لكنه لا يزيل قاعدة البيانات.
• انسخ احتياطياً ما لا يمكنك إعادة إنشائه. يشمل ذلك config.yaml و.env، إلى جانب pg_dump لقاعدة البيانات. يؤدي فقدان LITELLM_SALT_KEY إلى جعل بيانات اعتماد الموفر المشفرة داخل ذلك التفريغ عديمة الفائدة، لذلك يجب أن ينتمي ملف البيئة والتفريغ إلى مهمة النسخ الاحتياطي نفسها: نسخ restic الاحتياطية إلى تخزين خارج الخادم.

تتم الترقية بتعديل وسم الصورة وتشغيل docker compose up -d. يشغّل LiteLLM prisma migrate deploy عند بدء التشغيل افتراضياً، لذلك ترحّل الحاوية الجديدة مخطط قاعدة البيانات عند إقلاعها الأول. أنشئ التفريغ قبل تغيير الوسم، لأن إعادة الصورة القديمة لا تلغي عملية ترحيل نُفذت بالفعل.

FAQ

هل يضيف LiteLLM زمن استجابة ملحوظاً إلى كل استدعاء؟

ينشر المشروع رقماً قدره 8 ms عند النسبة المئوية 95 وبمعدل 1000 طلب في الثانية، وفقاً لما ورد في README في August 2026. تعامل مع هذا الرقم على أنه رقم صادر عن المورّد. العامل الذي يغيّر زمن الاستجابة لديك فعلياً هو المسافة الشبكية بين تطبيقاتك والبوابة، لأنك أضفت دورة ذهاب وإياب واحدة إلى كل استدعاء. شغّل البوابة في المنطقة نفسها التي توجد فيها التطبيقات التي تستدعيها، ثم قِس الحمل الإضافي الفعلي لديك باستخدام الرأس x-litellm-overhead-duration-ms في استجابة حقيقية.

لماذا توقف البث بعد أن وضعت nginx أمام الخدمة؟

لأن nginx يخزّن استجابات الخدمات الخلفية مؤقتاً افتراضياً، ولأن الاستجابة المتدفقة تكون سلسلة من server-sent events. عند تفعيل proxy_buffering، يجمع nginx الأجزاء ولا يرسلها إلا بعد اكتمال الاستجابة، لذلك ينتظر العميل دون بيانات ثم يتلقى الإجابة كاملة دفعة واحدة. عيّن proxy_buffering off; في كتلة location. ارفع قيمة proxy_read_timeout في الكتلة نفسها، لأن عملية التوليد الطويلة ستتجاوز افتراض nginx البالغ 60 ثانية، ويحصل العميل عندها على 504.

ماذا يحدث عندما تنفد ميزانية مفتاح افتراضي؟

يفشل الاستدعاء مع HTTP 401، ويكون نص الاستجابة على شكل ExceededBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07. تكمن المشكلة في رمز 401: إذ تعرضه مكتبة العميل على أنه فشل في المصادقة، فيبدأ المستخدمون بالتحقق من صلاحية المفتاح بدلاً من قراءة الرسالة. سجّل نص الاستجابة إلى جانب رمز الحالة. أكّد الموضع الفعلي للمفتاح باستخدام /key/info?key=sk-... مقابل المفتاح الرئيسي، وارفع الحد باستخدام /key/update إذا كانت الميزانية مضبوطة على قيمة منخفضة جداً.

هل يمكن للبوابة التوجيه إلى نموذج محلي وإلى نماذج مستضافة أيضاً؟

نعم، ويكون ذلك إدخالاً إضافياً في model_list. استخدم البادئة ollama_chat/ مع api_base، مثلاً model: ollama_chat/llama3.1 إلى جانب api_base: http://ollama:11434. من داخل حاوية، تشير localhost إلى تلك الحاوية نفسها، لذلك استخدم اسم خدمة Compose أو عنوان المضيف على شبكة Docker، ولا تستخدم 127.0.0.1 مطلقاً. تشغيل النموذج المحلي مهمة منفصلة؛ راجع استضافة LLM ذاتياً باستخدام Ollama على VPS.