🤖 تثبيت LiteLLM — بوابة API موحّدة لأكثر من 100 مزوّد LLM
انشر LiteLLM Proxy على Ubuntu بواسطة Docker — بوابة ذاتية الاستضافة تعرض OpenAI وAnthropic وOllama وأكثر من 100 مزوّد آخر خلف واجهة API واحدة متوافقة مع OpenAI، مع مفاتيح افتراضية وميزانيات وحدود معدل.
📦 الملفات والأكواد المطلوبة
قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.
التثبيت السريع:
wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/ai/litellm/litellm-ubuntu.sh
chmod +x litellm-ubuntu.sh
sudo bash litellm-ubuntu.sh
خطوات التنفيذ
1 تحميل السكريبت
wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/ai/litellm/litellm-ubuntu.sh
2 منحه صلاحية التنفيذ
chmod +x litellm-ubuntu.sh
3 تشغيل المثبّت
يثبّت السكريبت Docker إذا لزم الأمر، يولّد مفتاحاً رئيسياً، ويشغّل حاوية LiteLLM proxy على المنفذ 4000 مع حفظ إعداداته محلياً.
sudo bash litellm-ubuntu.sh
4 الدخول إلى واجهة الويب
اختبر الـ proxy بطلب إلى نقطة نهاية النماذج المتوافقة مع OpenAI، موثّق بمفتاحك الرئيسي:
curl http://:4000/v1/models \
-H "Authorization: Bearer sk-YOUR-MASTER-KEY"
المنافذ المستخدمة
| المنفذ | الغرض |
|---|---|
| 4000 | LiteLLM API + admin UI |
| 5432 | PostgreSQL (internal, optional for key management) |
نظرة عامة
LiteLLM هو بوابة وسيط (proxy) مجانية ومفتوحة المصدر لنماذج اللغة الكبيرة تقف بين تطبيقاتك وأكثر من 100 مزوّد LLM مختلف — OpenAI وAnthropic وGoogle Gemini وAzure OpenAI وAWS Bedrock وOllama وغيرهم كثير — وتعرضهم جميعاً خلف واجهة API واحدة متوافقة مع OpenAI. بدلاً من إعادة كتابة كود التكامل لكل مزوّد أو إدارة مفاتيح API منفصلة عبر تطبيقاتك، توجّه كل شيء إلى LiteLLM proxy الخاص بك، الذي يتولى التوجيه والمصادقة وتتبع الإنفاق والتحويل عند الفشل، بينما تحتفظ أنت بالتحكم الكامل في بيانات اعتماد المزوّدين وبيانات الاستخدام.
لماذا تستخدمه
لكل مزوّد LLM واجهة برمجة مختلفة قليلاً، وحزمة SDK خاصة به، وإدارة مفاتيح خاصة به، ما يحوّل استخدام عدة مزوّدين إلى عبء تكامل وخطر أمني — إذ تنتهي مفاتيح API الخاصة بالمزوّدين مبعثرة عبر قواعد الكود وتطبيقات العميل. يُمركز LiteLLM كل ذلك خلف نقطة نهاية واحدة متوافقة مع OpenAI: تستدعي تطبيقاتك واجهة واحدة بمفتاح افتراضي واحد، ويترجم LiteLLM الطلب إلى أي مزوّد ونموذج قمت بإعداده. وبما أنه ذاتي الاستضافة، لا تغادر مفاتيح API الحقيقية للمزوّدين بنيتك التحتية أبداً، وتحصل على تتبع إنفاق مركزي وميزانيات لكل فريق أو تطبيق، ويمكنك تبديل المزوّدين أو إضافتهم دون لمس سطر واحد من كود العميل.
متى تحتاجه
- فريقك أو منتجك يستخدم عدة مزوّدي LLM وسئمت من صيانة كود تكامل منفصل لكل منهم
- تحتاج منح وصول API محدود النطاق لتطبيقات أو أعضاء فريق مختلفين دون كشف مفاتيح OpenAI أو Anthropic الحقيقية
- تريد تتبع تكلفة مركزي وميزانيات لكل فريق أو مشروع عبر كل إنفاقك على الذكاء الاصطناعي
- تحتاج تحويلاً تلقائياً عند الفشل — إذا تعطل مزوّد أو وصل لحد المعدل، يجب أن ترتد الطلبات لنموذج أو مزوّد آخر
- تُشغّل نماذج محلية بـ Ollama أو vLLM جنباً إلى جنب مع مزوّدين سحابيين وتريد واجهة API واحدة متسقة لكليهما
- تحتاج حد معدل وسقوف استخدام تُفرض مركزياً بدلاً من الثقة بأن كل تطبيق عميل سيتصرف بمسؤولية
من يحتاجه
- فرق التطوير التي تبني ميزات ذكاء اصطناعي عبر منتجات متعددة وتريد نقطة تكامل واحدة بدلاً من عدة نقاط
- مهندسو المنصات والبنية التحتية المسؤولون عن التحكم بإنفاق LLM على مستوى الشركة ومراجعته
- الشركات الناشئة والمشاريع الصغيرة التي تريد تجنّب الارتباط بمزوّد واحد والتبديل أو المزج بين مزوّدي LLM دون إعادة كتابة كود التطبيق
- مهندسو الذكاء الاصطناعي وتعلم الآلة الذين يحتاجون اختبار A/B أو موازنة الحمل بين نماذج ومزوّدين مختلفين
- المؤسسات التي تستضيف نماذج مفتوحة المصدر ذاتياً (عبر Ollama أو vLLM) وتريد عرضها بنفس واجهة الواجهات التجارية
- أي شخص يقدّم ميزات مدعومة بـ LLM لمستخدمين نهائيين ويحتاج ميزانيات وحدود معدل ورؤية استخدام لكل مستخدم
حالات الاستخدام الشائعة
- بوابة API داخلية واحدة تستدعيها كل تطبيقات الشركة، بغض النظر عن مزوّد LLM الذي يخدم الطلب خلف الكواليس
- إصدار مفاتيح افتراضية محدودة النطاق لفرق أو تطبيقات عميل مختلفة، لكل منها وصول نماذج وميزانية وحدود معدل خاصة بها
- تحويل تلقائي من مزوّد أساسي لمزوّد أو نموذج احتياطي أثناء الأعطال أو أخطاء حد المعدل
- تسجيل مركزي ولوحات إنفاق لكل طلب LLM عبر المؤسسة
- مزج نماذج مفتوحة المصدر ذاتية الاستضافة مع واجهات تجارية خلف واجهة واحدة متسقة بأسلوب OpenAI
- موازنة حمل الطلبات عبر عدة مفاتيح API أو عمليات نشر لنفس المزوّد لزيادة الإنتاجية
الميزات الرئيسية
- واجهة API متوافقة مع OpenAI لأكثر من 100 مزوّد LLM، منها OpenAI وAnthropic وGoogle Gemini وAzure OpenAI وAWS Bedrock وCohere وOllama وvLLM
- مفاتيح API افتراضية بقيود وصول للنماذج لكل مفتاح، وميزانيات إنفاق، وتواريخ انتهاء صلاحية، وحدود معدل (RPM/TPM)
- واجهة ويب إدارية ولوحة تحكم لإدارة المفاتيح والفرق والنماذج ومشاهدة الاستخدام والإنفاق
- إعادة محاولة تلقائية وتوجيه احتياطي بين النماذج أو المزوّدين عند الفشل أو تجاوز حد المعدل
- موازنة حمل عبر عمليات نشر متعددة أو مفاتيح API متعددة لنفس النموذج
- تسجيل مركزي مع تكاملات لأدوات مراقبة مثل Langfuse وHelicone وغيرهما
- تتبع تكلفة لكل مفتاح أو فريق أو مستخدم، مع دعم تسعير مخصص للنماذج ذاتية الاستضافة
- دعم Redis لفرض الميزانيات وحدود المعدل بشكل متسق عبر عدة نسخ من الـ proxy
كيفية الاستخدام بعد التثبيت
- احفظ المفتاح الرئيسي المُولَّد بأمان — فهو يمنح صلاحية إدارية كاملة على الـ proxy ويجب ألا يُشارَك أبداً مع تطبيقات العميل
- افتح واجهة الإدارة على http://your-server-ip:4000/ui وسجّل الدخول بالمفتاح الرئيسي لاستكشاف لوحة التحكم
- أضف مفاتيح API لمزوّدي LLM الخاصين بك (OpenAI، Anthropic، إلخ) إلى إعدادات الـ proxy حتى يتمكن من توجيه الطلبات إليهم
- أنشئ مفاتيح افتراضية لكل تطبيق أو فريق، وحدّد نطاقها بنماذج وميزانيات وحدود معدل معينة
- وجّه تطبيقاتك إلى نقطة نهاية الـ proxy المتوافقة مع OpenAI (http://your-server-ip:4000/v1) باستخدام مفتاح افتراضي بدلاً من مفتاح المزوّد الحقيقي
- اضبط التوجيه الاحتياطي حتى تُعيد الطلبات المحاولة تلقائياً على نموذج أو مزوّد احتياطي إذا فشل الأساسي
- اربط أداة مراقبة مثل Langfuse إذا أردت تسجيلاً وتتبعاً تفصيلياً للطلبات يتجاوز لوحة التحكم المدمجة
- أعدّ وكيلاً عكسياً بـ HTTPS قبل كشف الـ proxy خارج شبكتك المحلية، لأن مفاتيح API تُنقل مع كل طلب
أفضل ممارسات الأمان
- تعامل مع المفتاح الرئيسي كبيانات اعتماد جذرية — خزّنه في مدير أسرار، ولا تضعه أبداً في نظام التحكم بالإصدار أو كود العميل
- أصدر مفاتيح افتراضية محدودة النطاق لكل تطبيق وفريق بدلاً من توزيع المفتاح الرئيسي أو مفاتيح المزوّدين الحقيقية
- اضبط ميزانيات إنفاق وحدود معدل على كل مفتاح افتراضي لاحتواء الضرر إذا تسرّب مفتاح أو أُسيء استخدامه
- ضع الـ proxy خلف وكيل عكسي بـ HTTPS — تحمل الطلبات مفاتيحك الافتراضية ومحتوى الطلبات والردود الكامل
- دوّر المفاتيح الافتراضية دورياً وألغِ أي مفتاح فوراً إذا لم يعد تطبيق أو عضو فريق يحتاج الوصول
- أبقِ قاعدة بيانات PostgreSQL المستخدمة لإدارة المفاتيح داخلية ضمن شبكة Docker ولا تكشف المنفذ 5432 خارجياً أبداً
- حافظ على تحديث صورة Docker لـ LiteLLM لتلقي رقع الأمان، لأنها تتعامل مع بيانات اعتماد حساسة للمزوّدين
المنافذ وإعدادات جدار الحماية
تستمع واجهة API وواجهة الإدارة في LiteLLM على المنفذ 4000، الذي يجب أن يكون متاحاً لأي تطبيق أو مستخدم يستدعي البوابة. قاعدة بيانات PostgreSQL الاختيارية المستخدمة لإدارة المفاتيح الافتراضية وتتبع الإنفاق تستمع على المنفذ 5432 ويجب أن تبقى داخلية بشكل صارم ضمن شبكة Docker — فهي تخزّن مفاتيح مُجزّأة وبيانات استخدام ويجب ألا تُكشف أبداً للمضيف أو الإنترنت. إذا كنت تشغّل عدة نسخ من الـ proxy مع Redis لحدود معدل موزعة، يجب أن يبقى Redis داخلياً أيضاً. لأي نشر يتجاوز الاختبار المحلي، ضع المنفذ 4000 خلف وكيل عكسي بشهادة TLS صالحة، لأن كل طلب إليه يتضمن مفتاح API وغالباً محتوى طلب حساس.
النسخ الاحتياطي والصيانة
- انسخ قاعدة بيانات PostgreSQL احتياطياً إذا كنت تستخدم إدارة المفاتيح الافتراضية — فهي تحتوي كل مفتاح وفريق وميزانية وسجل إنفاق
- انسخ ملف config.yaml احتياطياً، فهو يحدد كل مزوّد ونموذج مُعرَّف وقاعدة توجيه
- خزّن مفاتيح API لمزوّديك والمفتاح الرئيسي لـ LiteLLM في مدير أسرار، منسوخ احتياطياً بشكل منفصل عن بيانات التطبيق
- انسخ docker-compose.yml ومتغيرات البيئة احتياطياً حتى يمكن إعادة إنشاء الـ proxy بشكل مطابق على مضيف جديد
- صدّر تقارير الاستخدام والإنفاق دورياً إذا احتجت بيانات فوترة تاريخية تتجاوز ما تحتفظ به لوحة التحكم
- اختبر استعادة كاملة على تثبيت منفصل للتأكد أن المفاتيح والميزانيات وقواعد التوجيه تعود بشكل صحيح
الأخطاء الشائعة
- استخدام المفتاح الرئيسي مباشرة في تطبيقات العميل بدلاً من إصدار مفاتيح افتراضية محدودة النطاق
- عدم ضبط ميزانيات إنفاق على المفاتيح الافتراضية، ما يسمح لمفتاح واحد متسرّب بتوليد تكاليف مزوّد غير محدودة
- كشف المنفذ 4000 مباشرة للإنترنت بدون وكيل عكسي وTLS
- كشف منفذ PostgreSQL (5432) المستخدم لإدارة المفاتيح خارج شبكة Docker
- نسيان إعداد نماذج احتياطية، فيؤدي عطل مزوّد واحد لتعطيل كل تطبيق يستخدم الـ proxy
- تخزين مفاتيح API للمزوّدين في متغيرات بيئة عادية داخل نظام التحكم بالإصدار بدلاً من مدير أسرار
- تشغيل نسخة واحدة من الـ proxy لحركة إنتاج بدون Redis، ما يسبب فرضاً غير متسق لحدود المعدل تحت الحمل
استكشاف الأخطاء وإصلاحها
- أخطاء 401 غير مصرّح — تأكد أن المفتاح الافتراضي أو الرئيسي مُضمَّن بشكل صحيح في ترويسة Authorization: Bearer
- فشل طلبات لمزوّد معين — تحقق أن مفتاح API لذلك المزوّد مضبوط بشكل صحيح في config.yaml وأن الحساب يملك حصة متاحة
- إدارة المفاتيح الافتراضية لا تعمل — تأكد أن متغيّر البيئة DATABASE_URL يشير إلى نسخة PostgreSQL تعمل ويمكن الوصول إليها
- حدود المعدل لا تُفرض بشكل متسق عبر النسخ — أعدّ Redis واضبط REDIS_HOST حتى تُشارَك عدادات الميزانية وحد المعدل
- زمن استجابة مرتفع للطلبات — تحقق ما إذا كان الـ proxy يعيد المحاولة مع مزوّد بطيء أو محدود المعدل قبل التحويل الاحتياطي، وراجع ترتيب التحويل الاحتياطي
- واجهة الإدارة لا تُحمَّل — تأكد أنك تستخدم المفتاح الرئيسي لتسجيل الدخول وأن المنفذ 4000 متاح من متصفحك
- تكاليف غير متوقعة — راجع لوحة الإنفاق لكل مفتاح وفريق، وتأكد أن الميزانيات وحدود المعدل مُطبَّقة فعلياً على المفاتيح المستخدمة
البدائل
OpenRouter بوابة API مستضافة متعددة المزوّدين بمفهوم مشابه لواجهة واحدة لعدة نماذج، لكنها خدمة طرف ثالث وليست شيئاً تشغّله بنفسك، وتمر حركة مرورك عبر بنيتهم التحتية. Portkey وHelicone يقدمان ميزات بوابة LLM مستضافة أو ذاتية الاستضافة مع تركيز أساسي على المراقبة. لاحتياجات أبسط، يقدم بعض المزوّدين حزم SDK رسمية بمنطق إعادة محاولة مدمج، لكن لا شيء منها يوحّد أكثر من 100 مزوّد خلف واجهة واحدة بميزانيات ومفاتيح افتراضية كما يفعل LiteLLM. إذا كنت تحتاج فقط استضافة نماذج مفتوحة المصدر ذاتياً بدون أي توجيه لمزوّدين سحابيين، فأدوات مثل Ollama أو vLLM وحدها أبسط، لكنها لا توفر طبقة تجريد متعددة المزوّدين التي يضيفها LiteLLM فوقها. كبوابة ذاتية الاستضافة ومفتوحة المصدر ومحايدة تجاه المزوّد بميزانيات وتحكم في الوصول، LiteLLM من أكثر الخيارات اكتمالاً.
متى لا تستخدمه
إذا كنت تستدعي دائماً مزوّد LLM واحداً فقط ولا تحتاج ميزانيات أو مفاتيح افتراضية أو تحويلاً احتياطياً، فإضافة طبقة proxy تعقيد غير ضروري — استدعِ SDK المزوّد مباشرة. يفترض LiteLLM أيضاً أنك مرتاح لتشغيل قطعة صغيرة من البنية التحتية الإنتاجية (Docker، واختيارياً PostgreSQL وRedis، وTLS) — إذا كنت تريد عدم إدارة أي بنية تحتية إطلاقاً، فخدمة بوابة مستضافة تتنازل عن بعض التحكم مقابل الراحة. إذا كانت حاجتك الأساسية مراقبة وتتبع عميق على مستوى الطلب بدلاً من التوجيه والتحكم بالتكلفة، فقد تخدمك أداة مراقبة مخصصة مدمجة مباشرة في تطبيقك بشكل أفضل، حتى لو زاوجتها مع LiteLLM للتوجيه. وللمشاريع الشخصية منخفضة حركة المرور جداً، قد يفوق العبء التشغيلي لتشغيل بوابة وتأمينها الفائدة مقارنة باستدعاء واجهة مزوّد واحد مباشرة.
هل تحتاج مساعدة احترافية؟
توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.
- التثبيت وتجهيز السيرفر
- الإعداد المتقدم وإعداد التوجيه
- تصليب الأمان وتحسين جدار الحماية
- إعداد شهادات SSL/TLS مع Let's Encrypt
- ربط النطاق المخصص والوكيل العكسي
- جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
- المراقبة الفورية وتنبيهات الجاهزية
- الترحيل من المنصات القائمة
- استكشاف مشكلات الاتصال والأداء وإصلاحها
- سكريبتات أتمتة مخصصة وعقود دعم مستمر
الأسئلة الشائعة
ما الذي يفعله LiteLLM بالضبط؟
إنه proxy ذاتي الاستضافة يقف بين تطبيقاتك وأكثر من 100 مزوّد LLM، ويعرضهم جميعاً عبر واجهة API واحدة متوافقة مع OpenAI. تستدعي تطبيقاتك نقطة نهاية واحدة بمفتاح افتراضي واحد، ويوجّه LiteLLM الطلب إلى أي مزوّد ونموذج قمت بإعداده، بينما يتتبع الإنفاق ويفرض الميزانيات وحدود المعدل.
هل استضافة LiteLLM ذاتياً مجانية؟
نعم. LiteLLM proxy الأساسي مفتوح المصدر برخصة MIT، واستضافته ذاتياً تمنحك إدارة مفاتيح افتراضية وميزانيات وحدود معدل وتسجيلاً بدون تكلفة. توجد باقة Enterprise مدفوعة منفصلة لميزات متقدمة مثل SSO والدعم المخصص، لكنها غير مطلوبة لبوابة ذاتية الاستضافة كاملة الوظائف.
هل أحتاج PostgreSQL لتشغيل LiteLLM؟
فقط إذا أردت إدارة مفاتيح افتراضية وتتبع إنفاق وميزانيات — يمكن لـ LiteLLM العمل بدون قاعدة بيانات للتوجيه الأساسي، لكن إعداد Docker الافتراضي يتضمن PostgreSQL لأن معظم عمليات النشر تستخدم هذه الميزات. يجب أن تبقى قاعدة البيانات داخلية ضمن شبكة Docker ولا تُكشف أبداً للعموم.
هل يخزّن LiteLLM أو يرى مفاتيح API الحقيقية لمزوّديّ؟
تُخزَّن مفاتيح API لمزوّديك في إعدادات أو قاعدة بيانات الـ proxy نفسها، وليست مكشوفة لتطبيقات العميل التي تستدعيه. تستخدم التطبيقات مفاتيح افتراضية محدودة النطاق بدلاً من ذلك، فتسرّب مفتاح افتراضي لا يكشف بيانات اعتماد OpenAI أو Anthropic أو أي مزوّد آخر الحقيقية.
هل يمكن لـ LiteLLM التحويل تلقائياً لمزوّد آخر إذا تعطل أحدهم؟
نعم. يمكنك ضبط نماذج أو مزوّدين احتياطيين في إعدادات التوجيه، فإذا فشل طلب للنموذج الأساسي أو وصل لحد المعدل، يعيد LiteLLM المحاولة تلقائياً على نموذج احتياطي دون أي تغيير مطلوب في كود تطبيقك.
