Docker الخاص بـ vLLM: تشغيل خادم استنتاج مدعوم ببطاقة رسوميات في دقائق معدودة

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

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

• محرّك Docker الإصدار 20.10 أو أحدث — يعمل Docker Desktop على أنظمة Windows وmacOS عبر واجهة WSL2 الخلفية.
• وحدة معالجة رسوميات NVIDIA مع برنامج تشغيل يدعم CUDA 12.x. نفّذ الأمر التالي للتحقق: nvidia-smi لعرض الإصدار الأقصى من CUDA الذي يدعمه برنامج التشغيل لديك، كما هو مذكور في حقل «إصدار CUDA».
• أداة حاويات NVIDIA — الجسر الذي يسمح لـ Docker برؤية وحدة معالجة الرسومات (GPU). راجع القسم التالي لمزيد من التفاصيل.
• ما يكفي من ذاكرة VRAM لتشغيل النموذج المستهدف. استخدم حاسبة الذاكرة VRAM الأداة المُخصصة لذلك للتحقق قبل تنزيل النموذج.

تثبيت أداة حاويات NVIDIA

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

لينكس (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.

ويندوز (WSL2): ثبّت برنامج تشغيل NVIDIA الخاص بنظام Windows على الجهاز المضيف — ولا حاجة لتثبيت أداة أدوات الحاويات (Container Toolkit) بشكل منفصل داخل بيئة WSL2. ويقوم Docker Desktop تلقائيًا بإدارة عملية تمرير وحدة معالجة الرسومات (GPU passthrough).

نظام التشغيل macOS: لا تدعم وحدات معالجة الرسومات من شركة NVIDIA نظام macOS. ولا يمكن تشغيل vLLM على معالجات Apple Silicon عبر Docker باستخدام تسريع وحدة معالجة الرسومات (GPU acceleration). وللاستنتاج المحلي على أجهزة Apple، يمكنك النظر في إنشاء نسخة تعمل على وحدة المعالجة المركزية فقط (CPU-only build)، أو استخدام بيئة تشغيل مختلفة.

أدنى أمر تشغيل مطلوب

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

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

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

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

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

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

أبرز إعدادات خادم vLLM

تُمرَّر هذه العلمات بعد اسم الصورة — فهي وسائط تُرسل إلى عملية خادم vLLM، وليست إلى Docker.

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

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

وبمجرد أن تطبع الحاوية الرسالة INFO: Application startup completeيصبح واجهة برمجة التطبيقات (API) جاهزة للعمل.

# سرد النماذج المحملة
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_key.

مثال على ملف Docker Compose

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

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 تعادل ما تحققه المعلمة --gpus all.

الأخطاء الشائعة والحلول المُقترحة لها

الأسئلة الشائعة

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

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

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

الصورة القياسية تتطلب وحدة معالجة رسوميات من شركة NVIDIA. أما الاستنتاج على وحدة المعالجة المركزية فقط (CPU-only inference) فهو ممكن عبر بناء vLLM من الكود المصدري باستخدام المتغير VLLM_TARGET_DEVICE=cpuولكن الأداء سيكون أبطأ بمقدار رتبة كبيرة، ولا يُوصى به عمليًا لخدمة الاستعلامات. أما بالنسبة للاستنتاج المحلي على وحدة المعالجة المركزية فقط، فتُعد أدوات مثل `llama.cpp` أو `Ollama` بدائل أكثر ملاءمة — راجع دليل Ollama المقارنة المقدمة في الوثائق

كيف أُشغّل نموذجًا مقيدًا (gated model) يتطلب رمزًا من Hugging Face؟

مرر الرمز كمتغير بيئة: -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. واحفظه في ملف .env وأشر إليه باستخدام --env-file .env لتفادي تسريبه في سجل الأوامر (shell history). ويستخدم الخادم هذا الرمز أثناء التنزيل الأولي للنموذج، ولا يلزم وجوده بعد تخزين أوزان النموذج محليًا.

ما وظيفة الخيار `--tensor-parallel-size` ولماذا قد أحتاجه؟

يُقسِّم التوازي التنسوري (Tensor parallelism) مصفوفات أوزان النموذج عبر عدة وحدات معالجة رسوميات، مما يسمح بتشغيل نماذج أكبر من سعة وحدة معالجة رسوميات واحدة. عيّنه على عدد وحدات معالجة الرسوميات التي ترغب في استخدامها (غالبًا ٢ أو ٤). ويجب أن يتطابق هذا العدد مع عدد وحدات معالجة الرسوميات المُمرَّر إلى الخيار --gpusكما يجب أن يكون عدد رؤوس الانتباه (attention heads) في النموذج قابلاً للقسمة على هذا العدد.

هل يُعد تشغيل vLLM داخل حاوية Docker فعّالًا من حيث التكلفة مقارنةً بواجهة برمجة التطبيقات المُدارة (managed API)؟

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

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

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