دليل تشغيل LiteLLM Proxy للإنتاج: LLM Gateway في ٢٠٢٦

ملخص. يقوم هذا البرنامج التعليمي بنشر LiteLLM Proxy جاهز للإنتاج باستخدام Docker Compose، وPostgres، ومفاتيح افتراضية، وميزانيات لكل فريق، وتوجيه تلقائي للاحتياطي (fallback) عبر Claude Sonnet 4.6 وGPT-5.4 وGemini 2.5 Pro. كل كتلة برمجية قابلة للتشغيل كما هي مكتوبة. نقوم بتثبيت صورة الحاوية على v1.85.0 ونشرح السبب بدقة — فحوادث سلسلة التوريد في مارس 2026 هي نوع من الملاحظات الهامشية التي تحول البرنامج التعليمي من "مجرد نسخ لمدونة" إلى "هذا ما نقوم بتشغيله فعلياً يوم الاثنين".¹² الوقت الإجمالي: ~40 دقيقة.

LiteLLM Proxy هو بوابة LLM مستضافة ذاتياً ومرخصة بموجب MIT، تعرض أكثر من 100 واجهة برمجة تطبيقات للمزودين (OpenAI، Anthropic، Google، AWS Bedrock، Azure، vLLM، Ollama، والمزيد) خلف نقطة نهاية واحدة متوافقة مع OpenAI، مع مفاتيح افتراضية، وميزانيات لكل فريق، وتتبع التكاليف، واحتياطيات تلقائية، وواجهة إدارة مدمجة.³ تقوم بتشغيله على بنيتك التحتية الخاصة — فقط مزودو النماذج يرون مطالباتك (prompts)، وفقط حاملو مفاتيحك الافتراضية يرون بيانات اعتماد المزود الخاصة بك.

ما ستتعلمه

• كيفية نشر LiteLLM Proxy باستخدام Docker Compose وPostgres، مع تثبيته على وسم صورة موقع ومحصن.
• كيفية كتابة ملف config.yaml يعرض Claude Sonnet 4.6 وGPT-5.4 وGPT-5.4 mini وGemini 2.5 Pro من خلال نقطة نهاية واحدة بتنسيق OpenAI.
• كيفية إنشاء مفاتيح افتراضية بميزانيات، وحدود معدل الطلبات، وقوائم نماذج مسموح بها عبر API /key/generate.
• كيفية تكوين توجيه الاحتياطي (fallback routing) بحيث تنجو الطلبات من انقطاع خدمة المزود أو تجاوز نافذة السياق (context-window).
• كيفية قراءة تتبع التكاليف من نقطة نهاية /global/spend/report ولوحة تحكم المسؤول /ui.
• كيف يختلف LITELLM_MASTER_KEY عن LITELLM_SALT_KEY وأيهما لا يمكنك تدويره أبداً.
• كيفية التحقق من توقيع الحاوية وتجنب الأوسمة المتغيرة (rolling tags) التي شحنت ثغرة خلفية مؤخراً.

المتطلبات الأساسية

• Docker Desktop 4.30+ أو مضيف Linux مع Docker Engine 25+ وإضافة Compose v2.
• openssl (مثبت مسبقاً على macOS ومعظم توزيعات Linux).
• مفتاح API لـ Anthropic، ومفتاح API لـ OpenAI، ومفتاح API لـ Google AI Studio. لست بحاجة ماسة للثلاثة معاً للمتابعة — الطلبات للمزودين الذين تفتقد مفاتيحهم ستعيد خطأ 401، لكن الوكيل سيعمل على أي حال وأي نموذج يتوفر مفتاحه سيعمل. (خطوة الاحتياطيات تظهر فائدتها القصوى عندما يكون لديك Anthropic + واحد على الأقل من الاثنين الآخرين.)
• حوالي 2 جيجابايت من ذاكرة الوصول العشوائي (RAM) المتوفرة على المضيف (Postgres + LiteLLM خفيفان، لكن المساحة الإضافية مهمة عندما يقوم الوكيل بتسجيل السجلات).
• 40 دقيقة.

الخطوة 1 — إنشاء دليل المشروع وتوليد المفاتيح

mkdir -p ~/llm-gateway && cd ~/llm-gateway

قم بتوليد المفتاحين التشفيريين اللذين يحتاجهما LiteLLM. المفتاح الرئيسي (master key) يصرح لنقاط نهاية المسؤول ويبدأ بالبادئة الحرفية sk-. مفتاح الملح (salt key) يشفر مفاتيح API الخاصة بالمزودين التي تخزنها في Postgres.⁴

echo "LITELLM_MASTER_KEY=sk-$(openssl rand -hex 24)" > .env
echo "LITELLM_SALT_KEY=$(openssl rand -base64 32)" >> .env

تحقق من الملف:

cat .env
# LITELLM_MASTER_KEY=sk-9f6c... (48 hex chars after the sk- prefix)
# LITELLM_SALT_KEY=<base64-encoded 32 random bytes>

تحذير — اقرأ هذا مرة واحدة. إن LITELLM_SALT_KEY هو المفتاح المستخدم لتشفير كل بيانات اعتماد مزود يكتبها الوكيل في Postgres. إذا قمت بتغييره بعد إضافة نموذج واحد حتى، فسيصبح كل صف مشفر عديم الفائدة وسيفشل الوكيل في البدء مع خطأ Error decrypting value.⁵ اختره مرة واحدة، وقم بنسخه احتياطياً في مدير كلمات المرور الخاص بك، ولا تقم بتدويره أبداً طوال عمر قاعدة البيانات هذه. المفتاح الرئيسي، على النقيض من ذلك، يمكن تدويره وهناك تدفق تدوير موثق.

أضف مفاتيح API الثلاثة للمزودين (استبدل العناصر النائبة بالقيم الحقيقية؛ إذا كان لديك مفتاح مزود واحد فقط، فاترك الاثنين الآخرين فارغين — الطلبات الموجهة لتلك النماذج ستعيد خطأ مصادقة، لكن الوكيل سيظل يبدأ ويخدم المزودين المتوفرين لديك):

cat <<'EOF' >> .env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=AIza...
EOF

الخطوة 2 — كتابة config.yaml مع توجيه متعدد المزودين

يقرأ LiteLLM Proxy تكوين YAML الذي يعلن عن النماذج التي تعرضها البوابة، وكيفية تعيينها للمزودين الأساسيين، وكيفية عمل التوجيه/الاحتياطيات/الحدود. أنشئ config.yaml في نفس الدليل:

# config.yaml — LiteLLM Proxy v1.85.0
model_list:
  # ---- Anthropic ----
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_key: os.environ/ANTHROPIC_API_KEY

  # ---- OpenAI ----
  - model_name: gpt-5.4
    litellm_params:
      model: openai/gpt-5.4
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-5.4-mini
    litellm_params:
      model: openai/gpt-5.4-mini
      api_key: os.environ/OPENAI_API_KEY

  # ---- Google Gemini (AI Studio, NOT Vertex) ----
  - model_name: gemini-2.5-pro
    litellm_params:
      # The "gemini/" prefix routes to AI Studio with GEMINI_API_KEY.
      # A bare "gemini-2.5-pro" would be auto-detected as Vertex AI
      # and the proxy would expect GCP application-default credentials.
      model: gemini/gemini-2.5-pro
      api_key: os.environ/GEMINI_API_KEY

general_settings:
  # The proxy also reads LITELLM_MASTER_KEY and DATABASE_URL straight from
  # the environment, so we don't repeat them here. Setting them in BOTH
  # config.yaml and .env risks divergence if one drifts.
  store_model_in_db: true

router_settings:
  routing_strategy: simple-shuffle  # the default; explicit for clarity
  allowed_fails: 3                  # cooldown threshold per 1-min window
  cooldown_time: 60                 # seconds a failed deployment is parked
  # On the FIRST failure of gpt-5.4, the router walks this list and tries
  # claude-sonnet-4-6, then gemini-2.5-pro. allowed_fails above controls
  # how soon gpt-5.4 gets parked, NOT when fallbacks fire.
  fallbacks:
    - gpt-5.4: ["claude-sonnet-4-6", "gemini-2.5-pro"]
  # If a request blows the gpt-5.4-mini window, escalate to full gpt-5.4.
  context_window_fallbacks:
    - gpt-5.4-mini: ["gpt-5.4"]
  # If Claude refuses on policy, route to gpt-5.4 (different policy stack).
  content_policy_fallbacks:
    - claude-sonnet-4-6: ["gpt-5.4"]

تفصيلان غير بديهيين يستحقان المعرفة قبل النشر:

1. anthropic/claude-sonnet-4-6 لا يحتوي على لاحقة تاريخ. بدءاً من جيل Claude 4.6، انتقلت Anthropic بعيداً عن معرفات model-name-YYYYMMDD؛ السلسلة الخالية من التاريخ هي بحد ذاتها لقطة مثبتة وليست اسماً مستعاراً دائماً.⁶ إذا كنت تقوم بترحيل تكوين من Claude 3.5 Sonnet، فإن هذا التغيير سيفاجئك.
2. البادئة gemini/ إلزامية لمسار AI Studio. بدونها، يقوم LiteLLM بتوجيه الطلب إلى Vertex AI وسيطالب الوكيل ببيانات اعتماد حساب خدمة GCP التي لا يملكها.⁷ هذا هو خطأ 401 الأكثر شيوعاً في تكوينات Gemini لأول مرة.

الخطوة 3 — كتابة ملف Compose مع صورة مثبتة وموقعة

أوسمة Docker للإنتاج ليست مكاناً للتساهل. نحن نثبت على ghcr.io/berriai/litellm-database:v1.85.0 — بدءاً من v1.84.0، تخلى LiteLLM عن لاحقة -stable القديمة وتستخدم الإصدارات المستقرة الآن أوسمة SemVer 2.0 عادية مثل v1.85.0 وهي غير قابلة للتغيير وموقعة.⁸⁹ تجنب :latest و :main-latest و :main-stable في الإنتاج: تلك الأوسمة المتغيرة يمكن أن تتغير بين عمليات النشر، وفي مارس 2026 قام المشروع نفسه بشحن إصدارين مخترقين من PyPI عبر تبعية Trivy ملوثة في CI.²

أنشئ Docker-compose.yml:

# Docker-compose.yml — Compose v2 (no `version:` key at top)
services:
  db:
    image: postgres:18-alpine
    restart: always
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: changeme_in_prod
      POSTGRES_DB: litellm
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"]
      interval: 5s
      retries: 10

  litellm:
    # The "litellm-database" variant ships pre-generated Prisma binaries
    # cached in /root/.cache, so the schema migration runs on first boot
    # even when /app/.cache is volume-mounted. The bare "litellm" image
    # works for in-memory deployments; for any DB-backed setup use this one.
    image: ghcr.io/berriai/litellm-database:v1.85.0
    restart: always
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    command: ["--config", "/app/config.yaml", "--port", "4000", "--num_workers", "4"]
    environment:
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY}
      LITELLM_SALT_KEY: ${LITELLM_SALT_KEY}
      DATABASE_URL: "postgresql://litellm:changeme_in_prod@db:5432/litellm"
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
      GEMINI_API_KEY: ${GEMINI_API_KEY:-}

volumes:
  pgdata:

بعض تعديلات الإنتاج التي يتغاضى عنها البدء السريع الرسمي:

• فحص صحة Postgres + condition: service_healthy يمنع الوكيل من مسابقة قاعدة البيانات عند البدء الأول — بدون ذلك، تفشل هجرات Prisma أحياناً مع رفض الاتصال عند البدء البارد.
• --num_workers 4 يشغل أربعة عمال Uvicorn خلف تطبيق FastAPI؛ قم بزيادة هذا العدد على المضيفات متعددة الأنوية.
• ${VAR:-} (الاحتياطي :-) يسمح للملف بالبدء حتى لو كان مفتاح المزود مفقوداً في .env، بدلاً من التوقف مع خطأ variable not set.

اختياري ولكن يُنصح به: تحقق من توقيع الصورة قبل البدء. يقوم LiteLLM بتوقيع كل صورة يتم نشرها على GHCR باستخدام cosign، بدءًا من الإصدار v1.83.0 — وهو نفس الإصدار الذي أغلق حادثة سلسلة التوريد في مارس. يتم إدراج المفتاح العام في المستودع عند cosign.pub ويتم الرجوع إليه من هاش التزام (commit hash) مثبت بحيث لا يمكن استبدال مفتاح التحقق نفسه من خلال اختراق مستقبلي للمستودع:⁸

# تثبيت cosign لمرة واحدة
brew install cosign     # macOS
# أو (Go 1.20+): go install GitHub.com/sigstore/cosign/v3/cmd/cosign@latest

# التحقق مقابل المفتاح العام للالتزام المثبت (النموذج الموصى به وفقًا لوثائق LiteLLM).
# نفس المفتاح يوقع جميع متغيرات الصور الأربعة (litellm، litellm-database،
# litellm-non_root، litellm-spend_logs).
cosign verify \
  --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \
  ghcr.io/berriai/litellm-database:v1.85.0

التشغيل السليم يطبع:

The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key

إذا فشلت خطوة التحقق، لا تقم بتشغيل الحاوية — اسحب تاغ (tag) مختلفًا وأعد التحقق قبل المتابعة. لقد اجتاز ملف wheel الخبيث في حادثة سلسلة التوريد الفحص البصري العابر؛ لكن cosign كان سيكتشفه.

الخطوة 4 — ابدأ الحزمة وتحقق من الإقلاع

Docker compose up -d
Docker compose logs -f litellm

انتظر ظهور السطر Application startup complete. (عادةً ما يستغرق حوالي 5 ثوانٍ بعد جاهزية Postgres). البروكسي يستمع الآن على http://localhost:4000.

فحص صحة سريع:

curl -s http://localhost:4000/health/liveliness
# "I'm alive!"

لاحظ هجاء نقطة النهاية: يستخدم LiteLLM /health/liveliness (بحرف "l" مزدوج)، وليس معيار Kubernetes المعتاد /health/liveness. شقيقه هو /health/readiness، والذي يضيف رحلة ذهاب وإياب لقاعدة البيانات ويبلغ عن db: "connected" عندما يكون الوصول إلى Postgres متاحًا.¹⁰

افحص Postgres للتأكد من أن البروكسي أنشأ المخطط (schema) الخاص به — ستكون Prisma قد قامت بتشغيل عمليات الهجرة (migrations) عند الإقلاع الأول:

Docker compose exec db psql -U litellm -d litellm -c "\dt" | head -20

يجب أن ترى بضع عشرات من الجداول مسبوقة بـ LiteLLM_ — مثل LiteLLM_VerificationToken (تخزين المفاتيح الافتراضية)، و LiteLLM_SpendLogs (دفتر أستاذ الإنفاق لكل مكالمة)، و LiteLLM_TeamTable، و LiteLLM_UserTable، و LiteLLM_BudgetTable، بالإضافة إلى جداول سجل التدقيق والتكوين. المخطط محدد في litellm/proxy/schema.prisma.

الخطوة 5 — قم بإجراء مكالمتك الأولى باستخدام المفتاح الرئيسي

يقوم المفتاح الرئيسي بالمصادقة ضد أي نقطة نهاية — مسارات الإدارة مثل /key/generate ومسارات الدردشة مثل /chat/completions — ولكن يجب ألا ترسله أبدًا إلى التطبيقات. نحن فقط نختبر طبقة التوجيه هنا.

source .env
curl -s http://localhost:4000/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Say hi in 5 words."}]
  }' | jq '.choices[0].message.content, .usage'

المخرجات المتوقعة (صياغة النموذج ستختلف):

"Hi there, friend, today!"
{
  "prompt_tokens": 14,
  "completion_tokens": 9,
  "total_tokens": 23
}

جرب نفس المكالمة ضد gpt-5.4 و gemini-2.5-pro — شكل الاستجابة متطابق لأن البروكسي يقوم بتوحيد كل شيء إلى تنسيق OpenAI Chat Completions. هذا التوحيد هو السبب الكامل لوجود البوابة.

الخطوة 6 — إنشاء مفتاح افتراضي بميزانية وحد لمعدل الاستخدام

المفاتيح الافتراضية هي المفاتيح التي تستخدمها تطبيقاتك وزملاؤك في الفريق فعليًا. كل مفتاح قابل للإلغاء بشكل مستقل، وله ميزانيته الخاصة التي يتم إعادة تعيينها وفقًا لجدول زمني، وله حدود RPM/TPM الخاصة به، ويمكنه تقييد النماذج التي يُسمح للمتصل بالوصول إليها.¹¹ يتم تخزينها في Postgres مشفرة باستخدام LITELLM_SALT_KEY.

قم بإنشاء مفتاح لـ "فريق النمو" (growth-team) الافتراضي بميزانية 50 دولارًا شهريًا، وحد أقصى 60 طلبًا في الدقيقة، ووصول إلى النموذجين الأرخص فقط:

curl -s http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["gpt-5.4-mini", "gemini-2.5-pro"],
    "max_budget": 50,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 200000,
    "metadata": {"team": "growth", "owner": "alice@example.com"}
  }' | jq

الاستجابة المتوقعة (وفقًا لمواصفات /key/generate الرسمية):¹¹

{
  "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxx"
}

تحتوي الاستجابة دائمًا على حقل key الجديد. يتم حفظ الميزانية، وقائمة النماذج المسموح بها، وحدود معدل الاستخدام التي أرسلتها في الطلب من جانب الخادم؛ قم بالاستعلام عنها مرة أخرى باستخدام GET /key/info?key=<key> متى احتجت لفحص ما هو مخزن. قد تعرض الإصدارات الحديثة بعض الحقول الإضافية مباشرة في /key/generate للتسهيل، لكن المواصفات الرسمية تضمن فقط key.

الآن اتصل بالبروكسي باستخدام المفتاح الجديد — وحاول الوصول إلى نموذج غير مسموح للمفتاح باستخدامه:

GROWTH_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxx   # الصق من الاستجابة السابقة

# مسموح — يستخدم gpt-5.4-mini
curl -s http://localhost:4000/chat/completions \
  -H "Authorization: Bearer $GROWTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }' | jq '.choices[0].message.content'

# ممنوع — gpt-5.4 ليس في قائمة نماذج المفتاح
curl -s http://localhost:4000/chat/completions \
  -H "Authorization: Bearer $GROWTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "ping"}]
  }' | jq '.error.message'
# "key not allowed to access model. This key can only access models=['gpt-5.4-mini', 'gemini-2.5-pro']..."

ملاحظتان للإنتاج:

• ميزانيات الفريق توضع بجانب ميزانيات المفاتيح، وتحل محل ميزانيات المستخدمين. عندما يتم تعيين team_id لمفتاح افتراضي، يظل الـ max_budget الخاص بالمفتاح ساريًا، ويتم فرض ميزانية الفريق المشتركة فوقه. يتم تجاوز ميزانية مستوى المستخدم لـ user_id الخاص بالمفتاح في هذا التكوين — هذا هو السلوك الموثق والطريقة السهلة لمنح فريق كامل محفظة واحدة مشتركة دون تعارض ميزانيات المهندسين الفردية.¹²
• تتم إعادة تعيين الميزانيات بناءً على budget_duration. تشمل الوحدات المقبولة الثواني ("30s")، والدقائق ("30m")، والساعات ("30h")، والأيام ("30d"). إذا حذفت budget_duration، تكون الميزانية لمرة واحدة ولا يتم إعادة تعيينها أبدًا.¹²

الخطوة 7 — شاهد عمل البدائل (fallbacks)

يتم تفعيل البدائل عند أول فشل لنشر مجموعة النماذج — allowed_fails: 3 لا تحكم البديل؛ بل تحكم فترة التهدئة (cooldown) (عدد الإخفاقات التي يمكن أن يراكمها النشر في نافذة مدتها دقيقة واحدة قبل أن يقوم الموجه بإزالته مؤقتًا من التدوير للطلبات المستقبلية).¹³ لإثبات البديل من البداية للنهاية دون انقطاع حقيقي للمزود، وجه نموذجًا واحدًا إلى مصدر معطل عمدًا (مفتاح API وهمي) وشاهد البديل وهو يتولى الأمر من المكالمة الأولى.

قم بتحرير config.yaml مؤقتًا — قم بتغيير كتلة gpt-5.4 لاستخدام مفتاح سيئ بالتأكيد:

  - model_name: gpt-5.4
    litellm_params:
      model: openai/gpt-5.4
      api_key: "sk-proj-INVALID-this-will-401"

أعد التشغيل واستدعِ gpt-5.4:

Docker compose restart litellm
sleep 3

curl -s http://localhost:4000/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "Reply with the literal word: ok"}]
  }' | jq '.choices[0].message.content, .model'

المخرجات المتوقعة: استجابة ناجحة، مع تعيين .model إلى claude-sonnet-4-6 بدلاً من gpt-5.4. رأى الموجه أن نشر OpenAI السيئ أعاد خطأ 401، فقام فورًا بالانتقال عبر مصفوفة fallbacks، وأجاب من Claude.¹³ أعد مفتاح OpenAI كما كان عند الانتهاء:

# استعادة مرجع متغير البيئة
sed -i.bak 's|"sk-proj-INVALID-this-will-401"|os.environ/OPENAI_API_KEY|' config.yaml
Docker compose restart litellm

تعمل قاعدة context_window_fallbacks بنفس الطريقة: عندما يتجاوز الطلب نافذة سياق النموذج النشط، ينتقل البروكسي إلى النموذج التالي في القائمة بدلاً من إعادة خطأ 400 للمتصل. سطر التكوين الواحد هذا هو الفرق بين "تعطل وكيلنا عند التعامل مع ملفات PDF طويلة" و "تبديل وكيلنا بشفافية إلى نموذج أكبر ونحن نتحمل التكلفة".

الخطوة 8 — قراءة تقرير الإنفاق

تكتب كل عملية إكمال ناجحة صفًا في LiteLLM_SpendLogs مع عدد التوكنات، والنموذج، ومعرف المفتاح، والتكلفة بالدولار المحسوبة مقابل جدول تسعير البروكسي.¹⁴ يغطي تتبع التكلفة أكثر من 100 مزود تلقائيًا — يشحن البروكسي مع ملف JSON لتسعير النماذج ويقوم بتحديثه في كل إصدار.

اسحب تقرير إنفاق لآخر 30 يومًا. تأخذ نقطة النهاية start_date و end_date بتنسيق YYYY-MM-DD البسيط — بدون مكون الوقت — وتعيد مصفوفة مجمعة حسب اليوم، مع مصفوفة teams متداخلة لكل يوم:¹⁴

# GNU date (Linux) أو BSD date (macOS) — كلاهما مدعوم عبر بديل ||
START=$(date -u -d '30 days ago' +%Y-%m-%d 2>/dev/null || date -u -v-30d +%Y-%m-%d)
END=$(date -u +%Y-%m-%d)

curl -s "http://localhost:4000/global/spend/report?start_date=$START&end_date=$END" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  | jq '.[] | {day: .group_by_day, teams: (.teams | map({team_name, total_spend}))}'

بالنسبة للإنفاق لكل مفتاح، يمكنك أيضًا استدعاء /key/info مباشرة:

curl -s "http://localhost:4000/key/info?key=$GROWTH_KEY" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" | jq '.info.spend, .info.models'

إذا كنت تفضل النقر بدلاً من استخدام curl، فافتح http://localhost:4000/ui في المتصفح وقم بتسجيل الدخول باستخدام المفتاح الرئيسي (أو متغيرات البيئة UI_USERNAME / UI_PASSWORD إذا قمت بضبطها). لوحة التحكم عبارة عن تطبيق ويب أحادي الصفحة (SPA) يتم تقديمه بواسطة البروكسي نفسه — يمكنك إضافة النماذج، وإنشاء المفاتيح، وفحص استهلاك التوكنات بالكامل من واجهة المستخدم.¹⁵

الخطوة 9 — الأسعار المرجعية التي تستخدمها البوابة

هذه هي أسعار "لكل مليون توكن" التي يطبقها LiteLLM عندما يضع علامة cost على كل صف في سجل الإنفاق، وتم التحقق منها مقابل صفحات أسعار المزودين الرسمية في 19-05-2026. هذه الأسعار ستتغير؛ تعامل معها كلقطة زمنية فقط.

النموذج	المدخلات ($/مليون)	المخرجات ($/مليون)	ملاحظات
Claude Sonnet 4.6	$3.00	$15.00	نافذة سياق 1 مليون توكن، لا توجد رسوم إضافية للسياق الطويل16
GPT-5.4 (≤272K مدخلات)	$2.50	$15.00	الفئة القياسية للمدخلات حتى 272 ألف توكن17
GPT-5.4 (>272K مدخلات)	$5.00	$22.50	رسوم إضافية 2× للمدخلات / 1.5× للمخرجات فوق 272 ألف، حتى ~1 مليون17
GPT-5.4 mini	$0.75	$4.50	النسخة الأرخص للأعمال ذات الحجم الكبير17
Gemini 2.5 Pro (≤200K مدخلات)	$1.25	$10.00	تسعير الفئة الأولى18
Gemini 2.5 Pro (>200K مدخلات)	$2.50	$15.00	رسوم إضافية للسياق الطويل18

لحساب تقديري سريع: مكالمة واحدة بـ 4 آلاف توكن مدخلات / ألف توكن مخرجات لنموذج GPT-5.4 تكلف حوالي $0.025 (4k × $2.50/M + 1k × $15.00/M). تكرار ذلك 100 مرة يومياً لمدة 30 يوماً يكلف حوالي 75 دولاراً شهرياً لكل بيئة عمل — وهو بالضبط سقف الميزانية الذي يفرضه max_budget: 50 على المفتاح الافتراضي.

التحقق

قم بتشغيل الاختبارات الأربعة أدناه؛ يجب أن تنجح جميعها قبل اعتبار البروكسي جاهزاً للعمل.

# 1. اختبار الحياة (Liveness) — نقطة النهاية هي /health/liveliness (بحرف "l" مزدوج)، ترجع
#    النص الصريح "I'm alive!"
test "$(-s http://localhost:4000/health/liveliness)" = '"I'\''m alive!"'

# 2. اختبار الجاهزية (Readiness) — يضيف رحلة ذهاب وعودة لقاعدة البيانات؛ يصبح حقل db هو "connected" عندما يكون جاهزاً
curl -s http://localhost:4000/health/readiness | jq '.db, .status'
# المتوقع: "connected" "connected"

# 3. التأكد من وجود مخطط (schema) Postgres
Docker compose exec -T db psql -U litellm -d litellm -tAc \
  "SELECT count(*) FROM information_schema.tables WHERE table_name LIKE 'LiteLLM_%';"
# المتوقع: >= 10

# 4. اختبار رحلة كاملة لإكمال الدردشة (chat completion)
curl -s http://localhost:4000/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"reply with: ok"}]}' \
  | jq -r '.choices[0].message.content'
# المتوقع: رد غير فارغ

الأخطاء الشائعة

خطأ Error decrypting value عند بدء التشغيل، مباشرة بعد تغيير الإعدادات. لقد قمت بتغيير LITELLM_SALT_KEY بعد أن تم تشفير الصفوف بالفعل بالمفتاح السابق. لا يوجد حل سوى حذف الصفوف المشفرة وإعادة إضافة النماذج. استعد مفتاح salt السابق من مدير كلمات المرور الخاص بك، أو استخدم Docker compose down -v لمسح وحدة التخزين والبدء من جديد إذا كان هذا جهاز تطوير.⁵

خطأ api_key client option must be set لـ Anthropic، على الرغم من أن ملف .env يحتوي على المفتاح. يقرأ البروكسي مفاتيح المزودين عبر توجيه os.environ/<NAME> في ملف config.yaml؛ إذا كتبت المفتاح الصريح في ملف YAML، فقد تجاوزت تشفير مفتاح salt وأي إعادة تشغيل لاحقة ستقرأ من البيئة ولن تجد شيئاً. انقل المفتاح إلى .env، وغير api_key: sk-ant-... إلى api_key: os.environ/ANTHROPIC_API_KEY، ثم قم بعمل Docker compose restart litellm.

مكالمات Gemini تعطي 401 مع "Could not find application default credentials." لقد أغفلت بادئة gemini/ في حقل model داخل litellm_params. بدونها، يكتشف LiteLLM تلقائياً المعرف المجرد gemini-2.5-pro كـ Vertex AI ويبحث عن بيانات اعتماد حساب خدمة GCP التي لا يملكها.⁷ أضف البادئة وأعد التشغيل.

البدائل (Fallbacks) لا تعمل؛ المكالمة تعيد الخطأ الأصلي. تعمل البدائل عند الفشل الأول للنشر المستهدف — يتحكم allowed_fails فقط في فترة التهدئة (cooldown) للطلبات المستقبلية، وليس بديل المكالمة الأولى. إذا كان الخطأ الأصلي يمر، فإن الأسباب الأكثر شيوعاً هي: (أ) الفشل يحدث في طبقة المصادقة/حد المعدل الخاصة بـ LiteLLM (المفتاح تجاوز الميزانية، تجاوز عدد الطلبات في الدقيقة) وليس لدى المزود الأساسي — هذه الأخطاء لا تخضع لبدائل النماذج؛ (ب) نموذج البديل المستهدف يفشل أيضاً؛ أو (ج) fallbacks لا يطابق اسم النموذج في الطلب (تحقق باستخدام Docker compose logs litellm وابحث عن سطر قرار التوجيه).

Docker compose up يشتكي من عدم العثور على وسم :v1.85.0. تحقق من شيئين: (1) مسار السجل هو ghcr.io/berriai/litellm-database، وليس Docker.io/berriai/litellm-database؛ (2) لم تضف لاحقة -stable القديمة — بدءاً من الإصدار v1.84.0، الصور المستقرة هي ببساطة :v1.85.0، والوسم :v1.85.0-stable غير موجود.⁸⁹

البروكسي يبدأ ولكن واجهة مسؤول النظام تعيد صفحة فارغة عند /ui. إما أنك قمت بضبط DISABLE_ADMIN_UI=True في مكان ما، أو أن البروكسي العكسي (reverse proxy) الخاص بك يقوم بإزالة ملف تعريف الارتباط JWT الذي تستخدمه /ui للمصادقة.¹⁵ حاول الوصول إلى /ui مباشرة بدون البروكسي العكسي أولاً؛ إذا عملت، فالمشكلة في الإعدادات العلوية.

الخطوات التالية

• استرجاع المتجهات بجانب بوابتك. ادمج LiteLLM مع فهرس متجهات للمطالبات المعززة بالاسترجاع (RAG) — راجع دليل ضبط pgvector HNSW للإنتاج للتعرف على مفاتيح التحكم في دقة الاسترجاع وزمن الاستجابة.
• عملاء يستخدمون الأدوات عبر البروكسي. بمجرد توجيه إكمالات الدردشة، الطبقة التالية هي استدعاءات الأدوات المهيكلة؛ يوضح دليلنا حول خادم TypeScript MCP مع OAuth و HTTP القابل للبث توصيلات جانب العميل التي تتناسب تماماً مع هذه البوابة.
• توسيع قاعدة بيانات Postgres. عندما يتجاوز جدول سجل الإنفاق مليون صف أو عندما يضغط عدد اتصالات البروكسي على قاعدة البيانات، انتقل إلى مجمع اتصالات (pooler) — يغطي دليل تجميع اتصالات Supabase Supavisor / PgBouncer أحجام تجميع المعاملات.
• تتبع البروكسي من مجمع سجلات. تعتبر الـ Workers وبيئات التشغيل الشبيهة بـ Lambda هي المداخل الأكثر شيوعاً لبوابة مثل هذه — يمنحك دليل مراقبة Cloudflare Workers مع Sentry شكل التتبع والسجلات للربط مع الأنظمة اللاحقة.

مراجع خارجية لمشغلي الأنظمة الإنتاجية:

• أفضل ممارسات LiteLLM للإنتاج — حالة التزامن عبر النسخ (Redis)، ضبط num_workers، ملاحظات حول تجميد قاعدة البيانات (deadlock).
• دليل أمان صور Docker لـ LiteLLM — التحقق من التوقيع (cosign)، واختيار الوسوم.
• تحديث أمني: حادثة سلسلة توريد مشتبه بها — الجدول الزمني لمارس 2026 وتقوية النظام بعد الحادثة.

Footnotes

1. إصدارات BerriAI/litellm. تم نشر v1.85.0 بتاريخ 17-05-2026. https://GitHub.com/BerriAI/litellm/releases ↩

2. "تحديث أمني: حادثة سلسلة توريد مشتبه بها،" مدونة LiteLLM، مارس 2026 — تصف اختراق v1.82.7 و v1.82.8 على PyPI لمدة 40 دقيقة تقريبًا في 24-03-2026، وناقل تسريب Trivy-CI-token، وخط الأنابيب المحصن v1.83.0. https://docs.litellm.ai/blog/security-update-march-2026 ↩ ↩²

3. ملف README الخاص بـ BerriAI/litellm: "حزمة تطوير برمجيات Python، خادم وكيل (بوابة ذكاء اصطناعي) لاستدعاء أكثر من 100 واجهة برمجة تطبيقات لنماذج اللغة الكبيرة بتنسيق OpenAI (أو التنسيق الأصلي)، مع تتبع التكلفة، والحواجز الوقائية، وموازنة التحميل، وتسجيل البيانات." https://GitHub.com/BerriAI/litellm ↩

4. الأسئلة الشائعة حول أمان وتشفير LiteLLM المستضاف ذاتيًا — تشرح كيف يقوم LITELLM_SALT_KEY بتشفير بيانات الاعتماد في قاعدة البيانات وعدم قابلية التراجع عن تغييره. https://docs.litellm.ai/docs/proxy/security_encryption_faq ↩

5. نفس المصدر أعلاه. تنص الأسئلة الشائعة صراحةً على أنه لا يمكن تغيير مفتاح salt بعد إضافة النماذج لأنه يُستخدم لتشفير/فك تشفير بيانات اعتماد مفتاح API المخزنة. ↩ ↩²

6. Anthropic، "نظرة عامة على النماذج" — تؤكد أن claude-sonnet-4-6 هو معرف ثابت بدون تاريخ لجيل Sonnet 4.6. https://platform.claude.com/docs/en/about-claude/models/overview ↩

7. LiteLLM، "Gemini - Google AI Studio" — وثائق المزود التي توضح أنه يجب بادئة معرفات النماذج بـ gemini/ للتوجيه إلى AI Studio API بدلاً من Vertex AI. https://docs.litellm.ai/docs/providers/gemini ↩ ↩²

8. دليل أمان صور LiteLLM Docker — يغطي التحقق من cosign، والتوصية بالتثبيت على علامات إصدار غير قابلة للتغيير مثل v1.85.0 (أو التثبيت عبر الخلاصة باستخدام @sha256:…)، والتحذير من العلامات المتغيرة مثل latest / main-stable في بيئة الإنتاج. لا تزال الإصدارات الأقدم تحمل اللاحقة القديمة -stable (مثل v1.83.0-stable)؛ وبدءًا من v1.84.0 فصاعدًا، تم إسقاط اللاحقة. https://docs.litellm.ai/docs/proxy/docker_image_security ↩ ↩² ↩³

9. مدونة LiteLLM، "تغيير نظام إصدارات LiteLLM: أسماء قياسية، إصدار MINOR أسبوعي، وإصدار PATCH للإصلاحات العاجلة" — توضح أنه بدءًا من v1.84.0 تم إسقاط لاحقة -stable وتستخدم الإصدارات المستقرة علامات SemVer 2.0 عادية (v1.84.0، v1.85.0، ...). يرتفع إصدار MINOR أسبوعيًا؛ بينما يُخصص PATCH للإصلاحات العاجلة. https://docs.litellm.ai/blog/cleaner-release-versions ↩ ↩²

10. LiteLLM، "فحوصات الحالة" — أسماء نقاط النهاية /health، /health/readiness، /health/liveliness (بـ "l" مزدوجة)، /health/services. استجابة liveliness هي النص الحرفي "I'm alive!"؛ بينما تعيد readiness ملف JSON يحتوي على حقول db و status. https://docs.litellm.ai/docs/proxy/health ↩

11. LiteLLM، "المفاتيح الافتراضية" — مخطط حمولة /key/generate بما في ذلك models، max_budget، budget_duration، rpm_limit، tpm_limit، و metadata. https://docs.litellm.ai/docs/proxy/virtual_keys ↩ ↩²

12. LiteLLM، "الميزانيات، حدود المعدل" — يصف حلول ميزانية الفريق ووحدات budget_duration. https://docs.litellm.ai/docs/proxy/users ↩ ↩²

13. LiteLLM، "البدائل" — افتراضيًا، يتنقل الموجه عبر قائمة البدائل عند أول فشل لنشر مجموعة النماذج. allowed_fails هي آلية منفصلة وموازية: فهي تتحكم في عدد حالات الفشل التي يمكن أن يراكمها النشر في نافذة زمنية مدتها دقيقة واحدة قبل إيقاف هذا النشر مؤقتًا (تبريده) وتخطيه في الطلبات اللاحقة. الآليتان تتعايشان؛ ولا تنتظر البدائل allowed_fails. https://docs.litellm.ai/docs/proxy/reliability ↩ ↩²

14. LiteLLM، "تتبع الإنفاق" — /global/spend/report يقبل start_date / end_date (بصيغة YYYY-MM-DD العادية) ويرجع مصفوفة من الكائنات مع group_by_day بالإضافة إلى مصفوفة teams متداخلة (team_name، total_spend، metadata). https://docs.litellm.ai/docs/proxy/cost_tracking ↩ ↩²

15. LiteLLM، "البداية السريعة (واجهة المستخدم)" — لوحة تحكم المسؤول في /ui، مصادقة ملفات تعريف الارتباط JWT، يتم تعطيلها باستخدام DISABLE_ADMIN_UI=True. https://docs.litellm.ai/docs/proxy/ui ↩ ↩²

16. صفحة تسعير Anthropic API، Claude Sonnet 4.6 مدرج بسعر 3.00 دولار / 15.00 دولار لكل مليون توكن. https://platform.claude.com/docs/en/about-claude/pricing ↩

17. تسعير OpenAI API، أسعار عائلة GPT-5.4. https://developers.openai.com/API/docs/pricing ↩ ↩² ↩³

18. تسعير Google Gemini Developer API — 2.5 Pro مقسم إلى 1.25 دولار / 10.00 دولار لسياق ≤200 ألف و 2.50 دولار / 15.00 دولار لما فوق ذلك. https://ai.google.dev/gemini-API/docs/pricing ↩ ↩²