لماذا يُعدّ LiteLLM الطبقة الناقصة في منظومات الذكاء الاصطناعي المستضافة ذاتيًا
Ollama رائع لتشغيل النماذج المحلية. ويغلّفه Open WebUI بواجهة محادثة. لكن حالما تبدأ ببناء التطبيقات — لا مجرّد المحادثة — تحتاج إلى شيء بينهما: وكيل يوحّد سطح واجهة API، ويتتبّع التكاليف لكل مشروع، ويتيح لك تبديل النماذج دون المساس بكود التطبيق. هذا بالضبط ما يفعله LiteLLM. فهو يقع بين تطبيقك وأي خلفية LLM، كاشفًا نقطة نهاية واحدة متوافقة مع OpenAI. يبقى كودك كما هو سواء وجّهت إلى Llama 3.1 على Ollama، أو Claude 3.5 Haiku، أو GPT-4o.
ما يمنحك إياه LiteLLM جاهزًا من الصندوق
- واجهة API موحّدة متوافقة مع OpenAI — تعمل مع كل حزمة SDK ومكتبة وأداة تستهدف واجهة OpenAI.
- أكثر من 100 تكامل مع مزوّدين: Ollama، Anthropic، OpenAI، Azure OpenAI، Mistral، Cohere، Bedrock وغيرها.
- مفاتيح API افتراضية بحدود إنفاق وحدود معدّل لكل مفتاح — أصدر مفاتيح للفرق واضبط سقف التكاليف الشهرية.
- لوحة تحكّم مدمجة على /ui مع تحليلات إنفاق فورية، وتفصيل لكل نموذج، وسجلّات للطلبات.
- موازنة حِمل وتجاوز تلقائي للأعطال عبر نقاط نهاية مزوّدين متعدّدة أو نسخ نماذج.
- رخصة Apache 2.0 — دون قياس عن بُعد، ودون اتصال خفي، وقابلة تمامًا للعمل معزولة عن الشبكة عند اقترانها بـ Ollama.
المتطلبات
1 غيغابايت من ذاكرة RAM على الأقل ونظام Ubuntu 22.04. مع Docker وإضافة Compose مثبّتين. المنفذ 4000 مفتوح، أو وكيل عكسي Caddy/Nginx لتفعيل HTTPS. هذا كل شيء — فـ LiteLLM نفسه وكيل بلغة Python ويحتاج نحو 256 ميغابايت؛ ويستهلك PostgreSQL معظم ما يتبقّى من ميزانية RAM. أما للفرق ذات الحركة المتزامنة، فـ 2 غيغابايت أكثر راحة.
نشر LiteLLM على خادم VPS
توفير خادم VPS
اطلب VPS Solo من ServOrbit (2 vCPU، 4 GB، Ubuntu 22.04): يكتفي LiteLLM بغيغابايت واحد، وأصغر خطة في الكتالوج تمنح ضعف ذلك. اتصل عبر SSH وثبّت Docker:
curl -fsSL https://get.docker.com | sh. إضافة Compose مُضمّنة.توليد الأسرار
نفّذ
openssl rand -hex 32لتوليد LITELLM_MASTER_KEY — فهذا يفتح لوحة التحكّم وجميع نقاط نهاية API الإدارية. أنشئ/opt/litellm/.envيتضمّن:LITELLM_MASTER_KEY،UI_USERNAME،UI_PASSWORD،DB_NAME=litellm،DB_USER=litellm،DB_PASSWORD=<strong-password>.كتابة docker-compose.yml
أنشئ
/opt/litellm/docker-compose.ymlبخدمتين:db(postgres:16-alpine، متغيّرات البيئة من .env، الحجم litellm_db) وlitellm(صورة ghcr.io/berriai/litellm مثبّتة على إصدار صريح وبصمتها@sha256:، وليس علىmain-latestأبدًا — انظر «سلسلة التوريد» أدناه —، المنفذ 4000:4000، depends_on db، DATABASE_URL + LITELLM_MASTER_KEY + UI_USERNAME + UI_PASSWORD، الحجم litellm_config:/app/data). نفّذdocker compose up -d.فتح لوحة التحكّم
انتقل إلى
http://<vps-ip>:4000/uiوسجّل الدخول بـ UI_USERNAME / UI_PASSWORD الخاصّين بك. ستصل إلى لوحة تحكّم LiteLLM. اذهب إلى Models لإضافة أول مزوّد لك. لنسخة Ollama محلية على الخادم نفسه، اضبط اسم النموذج علىollama/llama3.1وقاعدة API علىhttp://host.docker.internal:11434. أما لـ Anthropic، فالصق مفتاح API الخاص بك وأضفanthropic/claude-3-5-haiku-20241022.اختبار البوابة
من محطّة عملك، اختبر:
curl http://<vps-ip>:4000/v1/chat/completions -H "Authorization: Bearer <LITELLM_MASTER_KEY>" -H 'Content-Type: application/json' -d '{"model": "ollama/llama3.1", "messages": [{"role": "user", "content": "Hello"}]}'. ينبغي أن تستقبل ردًّا متدفّقًا — موجَّهًا عبر LiteLLM إلى Ollama لديك.إصدار مفاتيح API للفرق
في لوحة التحكّم ضمن API Keys، انقر New Key. امنحه وصفًا (مثل 'frontend-team')، واضبط
max_budget: 50(دولار أمريكي شهريًا) وtpm_limitاختياريًا. شارك هذا المفتاح مع الفريق — يوجّهون حزمة OpenAI SDK إلىhttp://<vps-ip>:4000ويستخدمون هذا المفتاح. ويُتتبَّع الإنفاق لكل مفتاح في لوحة التحكّم.إضافة HTTPS بواسطة Caddy
ثبّت Caddy:
apt install -y caddy. حرّر/etc/caddy/Caddyfile:llm.yourdomain.com { reverse_proxy localhost:4000 }. أعد التحميل:systemctl reload caddy. أغلق المنفذ 4000 في جدارك الناري — فكل الحركة تمرّ الآن عبر 443 مع TLS تلقائي.أول تسجيل دخول
افتح واجهة الإدارة على المسار /ui: يعرض LiteLLM نموذج اسم مستخدم وكلمة مرور. أدخل اسم المستخدم admin وكلمة المرور المُسلَّمة إليك، ثم أنشئ مفاتيحك الافتراضية من لوحة التحكم.
سلسلة التوريد: ثبّت، وتحقّق، وبدّل المفاتيح
تحتفظ بوابة LLM بمفاتيح جميع مزوّديك، وهذا بالضبط ما يبحث عنه سارق بيانات الاعتماد. يذكر بلاغ الأمان المفتوح في مستودع LiteLLM (القضية 47826) أن عجلات الإصدار 1.107.0 المنشورة على PyPI تضمّنت ثلاثة ملفات غريبة عن المشروع هي cook.pth وcook.py وsitecustomize.py، وُضعت في جذر site-packages: سارق بيانات اعتماد ومحمّل لتنفيذ الشيفرة يعملان عند كل تشغيل لبايثون. وضعت PyPI هذا الإصدار في الحجر. ويقول المشرفون إنهم سحبوا صور Docker الخبيثة، ويصف تقرير الحادثة لديهم اختطافًا لمسار النشر عبر رموز مطوّرين. وكان البلاغ الأول يقول إنه لم يفحص الصور؛ ثم وجد تحديث لاحق في الخيط نفسه الملفات الثلاثة في الصورة الرئيسية التي فحصها، وأوصى بمعاملة كل صور ذلك الإصدار على أنها مخترقة. لا يستطيع هذا الدليل أن يعرف ما سحبتَه في تاريخ معيّن: والفحوص الأربعة التالية تحسم ذلك على خادمك أنت.
اعرف ما يعمل فعلًا على خادمك
اقرأ بصمة الصورة
الوسم مثل
main-latestلا يقول شيئًا عمّا يُنفَّذ. نفّذdocker compose imagesثم docker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/berriai/litellm:main-latest(استبدلها بمرجع ملف compose لديك). دوّن قيمةsha256:وقارنها ببصمة إصدار تحققتَ من مصدره.ابحث عن الملفات المذكورة دون تشغيل بايثون
في بيئة مشبوهة يعيد كل تشغيل لبايثون تنفيذ الشيفرة الخبيثة، بما في ذلك
pip. ابحث إذن بأداة لا تشغّله: docker compose exec litellm find / -name 'cook.pth' -o -name 'cook.py' -o -name 'sitecustomize.py' -o -name 'litellm-1.107.0.dist-info' 2>/dev/null(إن كانت الصورة تتضمنfind). قد يكون sitecustomize.pyمنفردًا في مكان آخر من النظام سليمًا؛ أما ما يستوجب القلق فهو وجود cook.pthبجانبه فيsite-packages، أو مجلد litellm-1.107.0.dist-info. العثور على هذه الملفات يؤكد التعرّض؛ وعدم العثور على شيء لا يثبت أن البيئة سليمة.اقرأ الإصدار المثبّت
حين لا يبدو شيء مشبوهًا، يعرض
pip show litellm(داخل البيئة الافتراضية لتثبيت مباشر) أوdocker compose exec litellm pip show litellmرقم الإصدار. إن كان 1.107.0، أو إن شككتَ في صورة سُحبت في تلك الفترة، فانتقل فورًا إلى تبديل المفاتيح أدناه.ابحث عن آثار التنفيذ
يذكر البلاغ ملف قفل
/tmp/remote_code_loader.lock، وعمليةpythonيتيمة مجلدها الحالي/، وملف علامة /tmp/.pc_once_*لا يُكتب إلا بعد رفع ناجح. غيابه لا يثبت شيئًا: فالحاوية المعاد إنشاؤها تمسح/tmp. اعتبره قرينة لا حكمًا.
ثبّت بالبصمة لا بالوسم
الوسم مؤشّر يستطيع الناشر تحريكه؛ أما بصمة @sha256: فتحدّد بايتات بعينها. اكتب في docker-compose.yml السطر image: ghcr.io/berriai/litellm:<version>@sha256:<digest> مع إصدار صريح نُشر قبل الحادثة أو جرى التحقق منه بعدها، وليس latest ولا main-latest ولا main-stable أبدًا. يوصي المشرفون بتثبيت إصدار صريح، ويقترح خيط القضية استخدام البصمة. وتذكّر الحدّ: البصمة تثبت أنك تسحب دائمًا البايتات نفسها، لا من بناها. وكان يمكن تثبيت صور 1.107.0 دون أي إنذار. فالتثبيت يجمّد قرارًا اتخذتَه أنت، ولا يحلّ محلّ اتخاذه.
حدّث دون مفاجآت
- اقرأ ملاحظات الإصدار وحالة خيط الأمان قبل تغيير الإصدار، بدل ترك
docker compose pullيتبع وسمًا. - احصل على البصمة الجديدة من جهاز اختبار، وشغّل البوابة دون مفاتيح حقيقية، وافحص سلوكها، ثم انقل البصمة إلى الإنتاج.
- حين ينشر الناشر شهادات المصدر، تحقّق منها: فهي تقول من أين جاءت الصورة، وهو ما لا تقوله البصمة وحدها.
- احتفظ بالبصمة السابقة في مستودع الإعدادات: يصبح التراجع تغييرًا من سطر واحد.
- بعد أي تنبيه أمني، أعد بناء الحاويات والبيئات الافتراضية من الصفر بدل التنظيف في مكانها.
إن شُغّل 1.107.0 يومًا على خادمك: بدّل كل المفاتيح
بحسب البلاغ، إن بدأ ذلك الإصدار على مضيف يصل إلى الإنترنت فافترض أن الرفع نجح. تقرأ الشيفرة الموصوفة متغيّرات البيئة للعمليات المقروءة، وعند ضبط DATABASE_URL تستخرج الجداول التي تخزّن فيها البوابة بيانات اعتماد مزوّديها ونماذجهم، أي كل مفاتيح المنبع التي تحتفظ بها. فالتبديل يشمل كل سر كان المضيف قادرًا على بلوغه، لا المفتاح الرئيسي وحده. ألغِ المفتاح أولًا لدى المزوّد، ثم أنشئ البديل، ثم راجع استهلاك الشهر الأخير بحثًا عن استخدام لا تعرفه.
ما يجب تجديده
- كل مفاتيح المزوّدين المخزّنة في البوابة: Anthropic وOpenAI وAzure وMistral وBedrock وكل ما سواها.
LITELLM_MASTER_KEYوجميع المفاتيح الافتراضية الموزّعة على الفرق.- كلمة مرور قاعدة البيانات (
DB_PASSWORDوDATABASE_URLالذي يتضمنها)، وكذلكUI_PASSWORD. - أي سر موجود في بيئة عملية على المضيف: رموز API وكلمات مرور الخدمات المجاورة وملفات .env.
- مفاتيح SSH ورموز Git وبيانات اعتماد السحابة التي يمكن بلوغها من الخادم، إن كان المضيف يحمل شيئًا منها.
- بعد التبديل، أعد بناء الخادم أو الحاويات على الأقل من صورة موثّقة: نسخ أسرار جديدة إلى مضيف مخترق يعرّضها من جديد.
راقب حركة الخروج على الشبكة
يصف البلاغ رفعًا إلى www.litellm.dev، وهو نطاق ليس نطاق المشروع، وقراءة كل ساعة لمستودع GitHub تابع لطرف ثالث يُستخدم صندوق بريد لتعليمات جديدة. ويرى المشرفون أنفسهم أن القيد على مستوى الشبكة هو ما يهمّ، لأن الشيفرة الخبيثة تتجاهل إعدادات التطبيق. على الخادم، امنع الحركة الصادرة افتراضيًا واسمح فقط بنقاط وصول مزوّديك؛ وإن كان جدارك الناري يرشّح بالعنوان لا بالاسم، فضع وكيلًا صادرًا بقائمة سماح. وإلا فسجّل استعلامات DNS للمضيف ونبّه عند أي اسم لا مبرر لأن تتصل به البوابة.
اقرن LiteLLM بـ Ollama على الخادم نفسه للحصول على منظومة ذكاء اصطناعي معزولة تمامًا عن الشبكة. يتولّى Ollama استدلال النموذج؛ ويضيف LiteLLM طبقة البوابة — التوجيه وتحديد المعدّل وتتبّع الاستخدام. أما لأحمال العمل الحسّاسة للخصوصية (القانونية، المالية، الطبية)، فهذا يعني ألّا تغادر أي بيانات بنيتك التحتية.
الوثائق الرسمية
للإعداد المتقدّم والخيارات الخاصة بالأداة، ارجع إلى الوثائق الرسمية لـ LiteLLM. يغطّي هذا الدليل النشر على خادم VPS؛ وتبقى وثائق المُطوِّر المرجعَ للإعدادات الدقيقة والتحديثات الكبرى وحالات الاستخدام الخاصة.
