vLLM Docker: قم بتشغيل خادم استدلال مدعوم بـ GPU في دقائق

تنشر vLLM صورة Docker رسمية، vllm/vllm-openai، وتحتوي على خادم استدلال متوافق مع OpenAI جاهز للتشغيل. أسرع طريقة: قم بتثبيت NVIDIA Container Toolkit على المضيف، ثم قم بتشغيل الصورة باستخدام --gpus all ومعرّف نموذج من Hugging Face. بعد تحميل النموذج، يكون الخادم مباشراً على المنفذ 8000 ويقبل نفس الطلبات التي تقبلها واجهة برمجية OpenAI.

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

• Docker Engine 20.10+ — Docker Desktop على Windows و macOS يعمل عبر خلفية WSL2.
• وحدة معالجة رسوميات NVIDIA مع برنامج تشغيل يدعم CUDA 12.x. قم بتشغيل nvidia-smi للتأكد؛ إصدار "CUDA Version" المعروض هو الحد الأقصى الذي يدعمه برنامج التشغيل الخاص بك.
• أداة حاويات NVIDIA — الجسر الذي يسمح لـ Docker برؤية GPU. انظر القسم التالي.
• VRAM كافٍ لنموذجك المستهدف. استخدم حاسبة VRAM للتحقق قبل الالتزام بتحميل النموذج.

تثبيت NVIDIA Container Toolkit

تخط هذا القسم إذا docker run --gpus all nvidia/cuda:12.0-base nvidia-smi يعمل بالفعل على جهازك.

Linux (Ubuntu/Debian):

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | 
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | 
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | 
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

RHEL/CentOS: استبدل deb بعنوان URL المستودع rpm المقابل من توثيق NVIDIA واستخدم dnf بدلاً من apt-get.

Windows (WSL2): قم بتثبيت برنامج تشغيل NVIDIA للويندوز على المضيف — لا يلزم تثبيت مجموعة أدوات منفصلة داخل WSL2. يتعامل Docker Desktop مع المرور تلقائياً.

macOS: بطاقات NVIDIA GPU غير مدعومة على macOS. لا يعمل vLLM على Apple Silicon عبر Docker مع تسريع GPU. للاستدلال المحلي على أجهزة Apple، فكر في بنية CPU فقط أو وقت تشغيل مختلف.

أمر التشغيل الأساسي

docker run --runtime nvidia --gpus all 
  --ipc=host 
  -v ~/.cache/huggingface:/root/.cache/huggingface 
  -p 8000:8000 
  vllm/vllm-openai:latest 
  --model meta-llama/Meta-Llama-3-8B-Instruct

الخيار	لماذا يهم هذا
--runtime nvidia	توجيه استدعاءات GPU عبر وقت تشغيل حاوية NVIDIA.
--gpus all	يكشف عن جميع وحدات معالجة الرسومات على المضيف. استخدم "device=0,1" لاستهداف بطاقات GPU محددة.
--ipc=host	مشاركة مساحة الاسم IPC للمضيف. مطلوب لذاكرة PyTorch المشتركة؛ عدم تضمينها يسبب Bus error أو انهيار الذاكرة المشتركة.
-v ~/.cache/huggingface:…	ربط ذاكرة تخزين HF على المضيف حتى تبقى الأوزان محفوظة بعد إعادة تشغيل الحاوية.
-p 8000:8000	عرض خادم متوافق مع OpenAI على المضيف.
--model	أي معرّف نموذج من Hugging Face أو مسار محلي مرتبط في الحاوية.

لسحب نموذج مقيد (Llama 3، Mistral، إلخ)، مرّر أيضاً -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. قم بتخزين الرمز في .env ملف وقم بتمريره باستخدام --env-file .env بدلاً من إدراجه مباشرة في سجل shell الخاص بك.

ربط ذاكرة تخزين Hugging Face المؤقتة

vLLM يقوم بتنزيل أوزان النموذج إلى /root/.cache/huggingface داخل الحاوية. بدون تثبيت volume، كل docker run يعيد تنزيل النموذج بالكامل — غالباً من 5 إلى 80 GB. سطر التثبيت هو:

-v ~/.cache/huggingface:/root/.cache/huggingface

إذا كانت نماذجك موجودة في موقع غير افتراضي، قم بتعيين -e HF_HOME=/your/path وقم بتثبيت هذا المسار بدلاً منه. بالنسبة للبيئات المعزولة عن الشبكة، قم بتنزيل النموذج باستخدام huggingface-cli download أولاً، ثم قم بتمرير --model /path/in/container جنباً إلى جنب مع تثبيت volume لمجلد الأوزان.

أعلام خادم vLLM الرئيسية

يتم تمرير هذه العلامات بعد اسم الصورة — وهي وسيطات لعملية خادم vLLM، وليس لـ Docker.

الخيار	الافتراضي	متى يتم تغييره
--tensor-parallel-size N	1	قم بتعيينه لعدد وحدات معالجة الرسومات (GPUs) للخدمة متعددة وحدات معالجة الرسومات. يجب أن تكون رؤوس الانتباه في النموذج قابلة للقسمة على N. اجمع مع --gpus "device=0,1,..." مع إدراج عدد الأجهزة بالضبط N.
--gpu-memory-utilization 0.X	0.90	قلّل إلى 0.75–0.80 إذا رأيت أخطاء OOM أو تشارك وحدة معالجة الرسومات مع عمليات أخرى.
--max-model-len N	إعدادات النموذج	يحد من حجم ذاكرة التخزين المؤقت KV. مفيد عندما يكون السياق الافتراضي للنموذج (مثلاً 128 k) قد يستنزف VRAM. جرّب --max-model-len 8192 كأول تقليل.
--dtype auto	auto	استبدل بـ bfloat16 أو أو float16 إذا اختارت الكشف التلقائي دقة غير متوقعة.
--quantization awq / أو gptq	أو none	فعّل هذا للحصول على متغيرات نموذج مكمّاة مسبقاً. يقلل VRAM تقريباً بمقدار النصف مع بعض فقدان الجودة.
--port	8000	غيّره إذا كان الرقم 8000 مشغولاً بالفعل على المضيف.

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

عرض واختبار نقطة النهاية المتوافقة مع OpenAI

بمجرد طباعة الحاوية INFO: Application startup complete، تصبح واجهة برمجة التطبيقات نشطة.

# قائمة بالنماذج المحملة
curl http://localhost:8000/v1/models

# إكمال النص
curl http://localhost:8000/v1/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "عاصمة فرنسا هي", "max_tokens": 20}'

# إكمال الدردشة
curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "messages": [{"role": "user", "content": "مرحباً"}]}'

أي عميل متوافق مع OpenAI — Python openai SDK أو LangChain أو LlamaIndex — يعمل بتعيين base_url="http://localhost:8000/v1" وتوفير أي سلسلة غير فارغة كـ مفتاح API.

مثال Docker Compose

للنشرات الدائمة، ملف Compose أسهل في الإدارة من docker run أمر طويل:

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8000:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model meta-llama/Meta-Llama-3-8B-Instruct
      --gpu-memory-utilization 0.90
      --max-model-len 8192

ابدأ بـ docker compose up -d. كتلة deploy.resources هي المعادل من Compose v3 لـ --gpus all.

الأخطاء الشائعة والإصلاحات

خطأ	السبب	الحل
Bus error أو /dev/shm صغير جداً	الافتراضي في Docker /dev/shm هو 64 MB — صغير جداً بالنسبة لـ PyTorch.	أضف --ipc=host إلى أمر run. أو يمكنك استخدام --shm-size=8g إذا كنت لا تستطيع مشاركة مساحة الاسم IPC للمضيف.
CUDA error: no kernel image is available	إصدار CUDA المترجم في صورة vLLM يتجاوز ما يدعمه برنامجك.	تشغيل nvidia-smi للعثور على أقصى إصدار CUDA مدعوم، ثم قيّد نسخة صورة محددة (مثل vllm/vllm-openai:v0.5.5).
torch.cuda.OutOfMemoryError	أوزان النموذج بالإضافة إلى ذاكرة التخزين المؤقت KV تتجاوز VRAM المتاح.	جرّب --max-model-len 4096 أولاً. ثم اخفض --gpu-memory-utilization إلى 0.80. إذا استمرت مشكلة OOM، استخدم متغيراً محدياً أو معالج رسومات أكبر.
إذن مرفوض في دليل التخزين المؤقت	يعمل الحاوية كمسؤول؛ الدليل على المضيف مملوك لمستخدم آخر.	تشغيل chmod -R a+rw ~/.cache/huggingface على المضيف، أو استخدم وحدة تخزين Docker مسماة بدلاً من ربط الربط.
تبدأ الحاوية ولكن curl يرجع رفض الاتصال	النموذج قيد التحميل، أو -p 8000:8000 مفقود.	انتظر سطر السجل Application startup complete . تحقق من وجود تعيين المنفذ في أمر التشغيل.

الأسئلة المتكررة

أي علامة صورة vLLM Docker يجب أن أستخدم؟

vllm/vllm-openai:latest تتابع أحدث إصدار وهي جيدة للتجريب. للإنتاج، قيّد نسخة علامة محددة (مثل v0.6.0) بحيث تكون البنايات قابلة للتكرار. تشير كل علامة إصدار على Docker Hub إلى إصدار CUDA الذي تم ترجمته، والذي يجب أن يكون أقل من أو مساوياً للإصدار الذي يدعمه برنامجك.

هل يمكنني تشغيل vLLM في Docker بدون وحدة معالجة رسومات؟

تتطلب الصورة القياسية وحدة معالجة رسومات NVIDIA. الاستدلال عام CPU فقط ممكن ببناء vLLM من المصدر باستخدام VLLM_TARGET_DEVICE=cpu, but throughput is orders of magnitude slower and not practical for serving. For CPU-only local inference, llama.cpp or Ollama are more suitable alternatives — see the دليل Ollama للمقارنة.

كيف أقوم بتشغيل نموذج مقيد يتطلب رمز Hugging Face؟

مرر الرمز كمتغير بيئة: -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. خزنه في .env ملف وأرجع إليه باستخدام --env-file .env لتجنب تسريبه في سجل shell. يستخدمه الخادم أثناء تنزيل النموذج الأولي؛ لا يكون مطلوباً بعد تخزين الأوزان محلياً في التخزين المؤقت.

ماذا يفعل --tensor-parallel-size ومتى أحتاجه؟

يقسّم Tensor parallelism مصفوفات أوزان النموذج عبر عدة معالجات GPU، مما يتيح استخدام نماذج كبيرة جداً بحيث لا تتسع في بطاقة واحدة. عيّن القيمة على عدد معالجات GPU التي تريد استخدامها (2 أو 4 خيارات شائعة). يجب أن تطابق هذه القيمة عدد معالجات GPU المُمررة إلى --gpus، وجماعات الاهتمام في النموذج يجب أن تكون قابلة للقسمة على هذا الرقم.

هل تشغيل vLLM في Docker فعال من حيث التكلفة مقارنة بـ API مدار؟

يعتمد ذلك تمامًا على حجم طلباتك. فالاستضافة الذاتية تتضمّن تكاليف ثابتة مرتفعة (مثل تأجير جهاز يحتوي على وحدة معالجة رسوميات أو شراء الأجهزة)، لكن التكلفة الهامشية لكل طلب تكون قريبة من الصفر. أما واجهات برمجة التطبيقات المُدارة فلا تتضمّن تكاليف ثابتة، لكنها تفرض رسومًا عن كل رمز (token). واستخدم حاسبة المقارنة بين الاستضافة الذاتية وواجهة برمجة التطبيقات (API) حاسبة نقطة التعادل (break-even calculator)

كيف أقدّم خدمة نماذج متعددة في وقت واحد؟

شغّل حاوية واحدة لكل نموذج، مع تعيين كل منها إلى منفذ مختلف على الجهاز المضيف (مثل 8000 و8001). ولا يدعم vLLM حاليًا خدمة نماذج متعددة من عملية واحدة. ولتوجيه الطلبات حسب اسم النموذج إلى المنفذ الصحيح، ضع وكيل عكسـي (reverse proxy) مثل `nginx` أو `Caddy` أمام الحاويات.