كيفية تثبيت vLLM على أنظمة Linux وWindows وmacOS

لتثبيت vLLM على نظام Linux مزوَّد ببطاقة رسومية من NVIDIA، أنشئ بيئة Python 3.12 نظيفة وشغِّل pip install vllm، ثم ابدأ تشغيل الخادم باستخدام vllm serve Qwen/Qwen3-8B. وهذه هي الطريقة الموصى بها للحصول على تجربة سلسة وخالية من المشاكل. أما على نظام Windows، فيتطلَّب الأمر استخدام WSL2 أو Docker لأن vLLM ينشر حزمًا تنفيذية مخصصة فقط لأنظمة Linux، بينما يتطلَّب نظام macOS بناءً من الكود المصدري يؤدي الاستنتاجات على وحدة المعالجة المركزية فقط.

قبل التثبيت: ما المتطلبات الفعلية التي يحتاجها vLLM

المتطلبات	ما الذي يعمل بالفعل
نظام التشغيل	Linux (ويُعتبر x86_64 الهدف الأساسي؛ وبعض الإصدارات تنشر أيضًا حزمًا تنفيذية لمنصة aarch64). ولا يدعم Windows إلا عبر WSL2 أو Docker. أما macOS فيتطلب بناءً من الكود المصدري.
بايثون	يدعم نطاق الإصدارات 3.9–3.12 الإصدارات حتى منتصف عام 2025 تقريبًا، مع إضافة دعم إصدار 3.13 في الإصدارات اللاحقة. ويختلف هذا النطاق الداعم بين الإصدارات المختلفة — لذا تحقَّق من ملاحظات الإصدار الخاصة بالإصدار الذي تخطط لتثبيته.
وحدة معالجة الرسومات (GPU)	بطاقات رسومية من NVIDIA ذات قدرة حسابية (compute capability) 7.0 أو أعلى (مثل V100 وT4 وسلسلة RTX 20 وما بعدها، بالإضافة إلى A10 وL4 وA100 وH100 وH200). أما بطاقات AMD فتتطلَّب بناءً منفصلًا باستخدام ROCm.
CUDA	برنامج تشغيل NVIDIA حديث. فحزمة PyPI الافتراضية تتضمَّن وقت تشغيل CUDA الذي تحتاجه نسخة PyTorch المدمجة معها، وبالتالي لا ليس تحتاج إلى تثبيت حزمة أدوات CUDA النظامية ما لم تقم بالبناء من الكود المصدري.
القرص الصلب	يبلغ حجم الحزمة نفسها بضعة جيجابايت. أما أوزان النماذج فهي العامل المهيمن — وتُخزن في ~/.cache/huggingface وتتراوح أحجامها بين بضعة جيجابايت وآلاف الجيجابايت.

توجد القائمة الرسمية والمُحدَّثة باستمرار في وثائق المشروع نفسها على docs.vllm.ai، كما تُسجَّل التغييرات الخاصة بكل إصدار على صفحة إصدارات vLLM. وتظهر الحزم التنفيذية المنشورة والنسخ المدعومة من Python على PyPI.

تثبيت vLLM على نظام Linux مزوَّد ببطاقة رسومية من NVIDIA

الخيار 1: uv (الأسرع، وهو ما توصي به وثائق vLLM حاليًا)

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate
uv pip install vllm --torch-backend=auto

الـ --torch-backend=auto يسمح هذا العلم لـ uv باكتشاف برنامج التشغيل لديك واختيار إصدار PyTorch/CUDA المتوافق. وإذا كان إصدار برنامج التشغيل لديك أقدم من المتوقع في الحزمة التنفيذية، فاستبدل تلقائي بعلم محدد لإصدار معين مثل cu126. وتتغير إصدارات CUDA المتوفرة مع كل إصدار جديد، لذا راجع صفحة التثبيت بدلًا من افتراض وجود علامة معيَّنة.

الخيار 2: pip القياسي وvenv

python3.12 -m venv ~/vllm-env
source ~/vllm-env/bin/activate
pip install --upgrade pip
pip install vllm

الخيار 3: conda

conda create -n vllm python=3.12 -y
conda activate vllm
pip install vllm

لاحظ أن vLLM يجب تثبيته باستخدام pip حتى داخل بيئة conda. ولا تثبِّت PyTorch بشكل منفصل مسبقًا — إذ سيقوم vLLM تلقائيًا بتثبيت الإصدار الدقيق من torch الذي تم تجميعه معه.

تحقق من صحة التثبيت

vllm --version
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
nvidia-smi

إذا torch.cuda.is_available() يُظهر خاطئ، توقف هنا — فالمسألة تكمن في برنامج التشغيل أو بيئة النظام لديك، وليست في vLLM، ولن تعمل أي أوامر تشغيل (serve) قبل أن تُرجع هذه القيمة صحيح.

التثبيت باستخدام Docker (وهو الخيار الأدق من حيث إعادة الإنتاج)

يُنشر المشروع صورة رسمية لخادم متوافقة مع واجهة OpenAI. وهذه الطريقة تتفادى مشاكل بيئة بايثون تمامًا، وهي الخيار الأنسب عند استخدام صندوق مشترك أو بيئة إنتاج:

docker run --runtime nvidia --gpus all 
  -v ~/.cache/huggingface:/root/.cache/huggingface 
  --env "HF_TOKEN=$HF_TOKEN" 
  -p 8000:8000 
  --ipc=host 
  vllm/vllm-openai:latest 
  --model Qwen/Qwen3-8B

الـ --ipc=host الوسم (flag) مهم جدًّا: إذ يستخدم vLLM الذاكرة المشتركة بين العمليات، بينما تكون القيمة الافتراضية الصغيرة لـ Docker /dev/shm تؤدي إلى تعطل عند استخدام التوازي على المصفوفات (tensor parallelism). وإذا لم تتمكن من استخدام الـ IPC الخاص بالمضيف (host IPC)، فاستخدم بدلًا منه --shm-size=8g إن تركيب ذاكرة التخزين المؤقت الخاصة بمنصة Hugging Face يعني أنك ستقوم بتنزيل كل نموذج مرة واحدة فقط، بدلًا من تنزيله في كل حاوية على حدة. وهذا يتطلب تثبيت أداة NVIDIA Container Toolkit على المضيف.

تثبيت vLLM على نظام Windows (عبر WSL2)

لا يحتوي vLLM على بناء أصلي لنظام Windows. أما WSL2 فهو الطريق المدعوم، وهو يعمل بكفاءة عالية:

1. قم بتثبيت برنامج تشغيل NVIDIA القياسي ويندوز . ولا تُثبِّت برنامج تشغيل عرض لينكس داخل WSL — إذ يقوم نظام CUDA الخاص بـ WSL بربط طبقة التشغيل عبر برنامج التشغيل الخاص بنظام Windows. وتوضّح شركة NVIDIA هذه النقطة في دليل المستخدم الخاص بـ CUDA على WSL.
2. في PowerShell: wsl --install -d Ubuntu-24.04، ثم أعد التشغيل إذا طُلب منك ذلك.
3. داخل نظام Ubuntu، نفّذ الأمر nvidia-smi. وإذا لم تظهر بطاقتك الرسومية في القائمة، فعليك إصلاح هذه المشكلة أولًا قبل المتابعة.
4. تثبيت python3.12-venv، وأنشئ بيئة افتراضية (venv)، واتبع التعليمات الخاصة بلينكس الواردة أعلاه.

تحذيران محدَّدان خاصان بـ WSL: فـ WSL يحدد سقفًا افتراضيًّا لحجم الذاكرة العشوائية (RAM)، لذا يجب إضافة قسم [wsl2] يحتوي على memory= في عميل OpenAI الخاص بك إلى C:\Users\\.wslconfig إذا تم إنهاء عملية تحميل النموذج بشكل قسري؛ كما أن أوزان النماذج المخزنة على نظام الملفات الخاص بنظام Windows (/mnt/c/...) تُحمَّل بسرعة أبطأ ملحوظة مقارنةً بأوزان النماذج المخزنة داخل نظام ملفات WSL.

تثبيت vLLM على نظام macOS

لا توجد حزمة تنفيذية (wheel) خاصة بنظام macOS على PyPI. أما دعم شرائح Apple silicon فهو متاح فقط عبر بناء من الكود المصدري للوحدة المركزية (CPU-only):

xcode-select --install
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -r requirements/cpu.txt
pip install -e .

لقد تغيَّر مسار ملف المتطلبات بين الإصدارات (كان اسمه requirements-cpu.txt في الإصدارات الأقدم)، لذا تحقَّق من هيكل المستودع للعلامة (tag) التي استخرجتها. وبشكل جوهري، لا يستخدم هذا البناء تقنية Metal أو وحدة معالجة الرسوميات الخاصة بشركة Apple — بل تتم الاستنتاجات (inference) على وحدة المعالجة المركزية فقط، وهي أبطأ بكثير من الجهاز الذي يستخدم CUDA. فهدف تصميم vLLM هو تقديم استنتاجات دفعية (batched) عالية الأداء على وحدات معالجة الرسوميات الخاصة بالخوادم، وليس هذا ما توفره أجهزة كمبيوتر Mac المحمولة. فإذا كان هدفك تشغيل نموذج محليًّا على نظام macOS، فاستخدم طريق Ollama أو LM Studio، وكلاهما يستخدم تقنية Metal بشكل صحيح.

أنظمة Linux المزودة ببطاقات رسومية من AMD أو Intel أو تلك التي تعتمد على وحدة المعالجة المركزية فقط

أما منصات ROCm (AMD)، ووحدات معالجة الرسوميات/المعالجات الخاصة بشركة Intel (GPU/XPU)، والوحدات المركزية فقط (x86) فهي تمتلك مسارات تثبيت خاصة بها، غالبًا ما تكون إما صورة جاهزة مبنية مسبقًا باستخدام Docker أو بناء من الكود المصدري مع متغير بيئة مخصَّص للجهاز المستهدف مثل VLLM_TARGET_DEVICE=cpu، وهذه المنصات تتطور أسرع من مسار CUDA، وتتغير الأوامر الدقيقة بين الإصدارات، لذا يُرجى اتباع الصفحة الخاصة بالعتاد في الوثائق الحالية بدلًا من نسخ أمر من أحد الدروس التعليمية.

ابدأ الخادم واختبره

vllm serve Qwen/Qwen3-8B 
  --max-model-len 8192 
  --gpu-memory-utilization 0.90 
  --port 8000

Qwen3-8B يُعد خيارًا جيدًا للتجربة الأولى لأنه غير مقيد (ungated)، ويتم تنزيله بسرعة، ويناسب بطاقات الرسوميات ذات سعة 24 غيغابايت الواحدة عند استخدام تنسيق bf16. وبعد ذلك اختبره عبر:

curl http://localhost:8000/v1/models

curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "Qwen/Qwen3-8B", "messages": [{"role": "user", "content": "Say hi"}]}'

ملاحظة أمنية: vllm serve يبدأ بدون مصادقة. لذا استخدم الوسم --مفتاح_الواجهة_البرمجة وأبقِ المنفذ 8000 خلف جدار ناري أو وكيل عكسي (reverse proxy) — إذ إن إتاحة نقطة نهاية vLLM للعامة تعني فتح قناة استنتاج غير مقيدة على أجهزتك الخاصة، ما قد يؤدي إلى فواتير ضخمة.

الوسوم المفيدة عند التشغيل الأول: --tensor-parallel-size N لتقسيم الحمل على N بطاقات رسوميات، --max-model-len لتحديد أقصى طول للسياق (وهو أكثر وسيلة فاعلية واحدة ضد حدوث خطأ نفاد الذاكرة أثناء بدء التشغيل OOM)، --التكمين للمراجعات المُكمَّنة مسبقًا (pre-quantized checkpoints)، --served-model-name لإعطاء اسم مختصر للنموذج يُستخدم من قِبل العملاء، و --enforce-eager لتخطي عملية التقاط الرسوم البيانية لـ CUDA عندما ترغب في بدء تشغيل أسرع أثناء التصحيح.

هل سيتناسب النموذج مع مواردي؟ قِسْ حجمه قبل التثبيت

يقوم vLLM بتحميل أوزان النموذج افتراضيًّا بصيغة bf16، لذا احسب ما يقارب 2 غيغابايت من الذاكرة الفيديوية (VRAM) لكل مليار معلَّمة، بالإضافة إلى ذاكرة التخزين المؤقت للمفاتيح والقيم (KV cache) — ويخصص vLLM هذه الذاكرة مسبقًا وبشكل حازم (90% من البطاقة عند القيمة الافتراضية --gpu-memory-utilization)، إذ يحتاج النموذج المكوَّن من 8 مليارات معلَّمة إلى نحو 16 غيغابايت من الذاكرة الفيديوية عند استخدام تنسيق bf16. أما عند تكمينه إلى 4 بت، فينخفض حجم نفس النموذج إلى نحو 5 غيغابايت، وفقًا لما ورد في تقرير Convly قاعدة بيانات النماذج:

النموذج	السياق	~VRAM عند 4-bit	إعداد عملي لعقدة واحدة
Qwen3 8B	128 ألف رمز	~5 غيغابايت	بطاقة استهلاكية واحدة سعة 12–24 غيغابايت
Llama 3.1 8B	128 ألف رمز	~5 غيغابايت	بطاقة استهلاكية واحدة سعة 12–24 غيغابايت
Gemma 3 27B	128 ألف رمز	حوالي ١٦ جيجابايت	بطاقة واحدة سعة 24 غيغابايت عند استخدام التكمين إلى 4 بت
Qwen3 32B	128 ألف رمز	~20 جيجابايت	بطاقة واحدة سعة 24 جيجابايت بتعميق 4 بت، مع ضيق في مساحة ذاكرة التخزين المؤقت KV
Llama 3.3 70B	128 ألف رمز	~40 جيجابايت	بطاقتان سعة 24 جيجابايت مع --tensor-parallel-size 2، أو بطاقة واحدة سعة 48 جيجابايت
DeepSeek R1	128 ألف رمز	نحو 400 جيجابايت	خادوم متعدد وحدات معالجة رسومية (Multi-GPU)، وليس محطة عمل (Workstation)

للحصول على قيمة رقمية مُحدَّدة تتوافق مع طول السياق (context length) وحجم الدفعة (batch size) المُستخدَمين في حالتك، استخدم حاسبة الذاكرة VRAM؛ أما التفصيل الكامل لنماذج كل نموذج على حدة فيوجد في دليل متطلبات الذاكرة VRAM. وإذا كنت لا تزال تختار الأجهزة، فاطّلع على أفضل وحدات معالجة الرسوميات لتشغيل نماذج اللغة الكبيرة محليًّا. وبما أن شراء أي معدات يتطلب تخطيطًا دقيقًا، فمن المفيد حساب التكاليف مسبقًا باستخدام حاسبة المقارنة بين الاستضافة الذاتية وواجهة برمجة التطبيقات (API) — Llama 3.3 70B تبلغ تكلفة الخدمة المقدمة من مزود استضافة (hosted provider) 0.10 دولار أمريكي للإدخال و0.32 دولار أمريكي للإخراج لكل مليون رمز (token)، وهي تكلفة يصعب تجاوزها باستخدام كهرباء منزلك ما لم تكن نسبة الاستخدام المستمر مرتفعة جدًّا.

الأخطاء الشائعة أثناء تثبيت vLLM وبدء تشغيله

العرض المرضي	السبب والحل
استثناء الاستيراد (ImportError) على vllm._C، أو خطأ في واجهة الربط الثنائية (ABI) أو في الرموز (symbol) من torch	تم تثبيت vLLM فوق إصدار غير متوافق من PyTorch. احذف البيئة الحالية وأعد إنشاءها من جديد نظيفة، ثم ثبِّت vLLM أولًا.
«أقصى طول تسلسلي (max seq len) للنموذج يتجاوز أقصى عدد من الرموز التي يمكن تخزينها في ذاكرة التخزين المؤقت KV»	لا توجد ذاكرة VRAM حرة كافية للسياق المطلوب. قلِّل --max-model-len، أو زِد --gpu-memory-utilization، أو استخدم نموذجًا مكمَّنًا (quantized checkpoint).
نفاد الذاكرة في CUDA (CUDA out of memory) أثناء تحميل الأوزان (weights)	الأوزان نفسها لا تتسع في الذاكرة. قسِّمها إلى أجزاء (shard) باستخدام --tensor-parallel-size أو اختر نموذجًا أصغر حجمًا.
لم يتم العثور على برنامج تشغيل NVIDIA	لا توجد وحدة معالجة رسومية (GPU) مرئية للعملية الجارية. وفي بيئة WSL، يجب أن يكون برنامج التشغيل مثبتًا على جانب نظام Windows؛ أما في بيئة Docker، فإنك تفتقر إلى --gpus all.
خطأ 401/403 أثناء تنزيل نموذج	مستودع مقيد (Gated repository). اقبل الترخيص على منصة Hugging Face، ثم قم بالمصادقة (authenticate) عبرhf auth login في الإصدارات الحالية من واجهة سطر أوامر Hugging Face (CLI)، huggingface-cli login في الإصدارات القديمة)، أو عيِّن متغير البيئة HF_TOKEN.
توقف طويل قبل أن يبدأ الخادوم في قبول الطلبات	أمر طبيعي: يتم التقاط الرسوم البيانية لـ CUDA وترجمتها. استخدم --enforce-eager لتجاوز هذه الخطوة أثناء التصحيح (debugging).

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

هل يمكنني تثبيت vLLM بشكل أصلي على نظام Windows؟

لا. تنشر vLLM حزم تثبيت (wheels) لأنظمة لينكس فقط، و pip install vllm في بيئة بايثون على نظام ويندوز لن يمنحك خادوم GPU عمليًّا. استخدم بيئة WSL2 مع توزيعة أوبونتو، أو شغِّل صورة Docker الرسمية. وكلا الخيارين مدعومان بالكامل ويحقِّقان أداءً يقارب الأداء الأصلي (near-native performance) على نفس الأجهزة.

هل يجب عليّ تثبيت حزمة أدوات CUDA أولًا؟

ليس مطلوبًا بالنسبة للحزمة الافتراضية (default wheel). فهي تتضمن وقت تشغيل CUDA (CUDA runtime) عبر إصدار PyTorch المُثبَّت مسبقًا، وبالتالي يكفي توفر برنامج تشغيل NVIDIA حديث نسبيًّا. أما إذا قمت بترجمة vLLM من الشيفرة المصدرية (source) أو ببناء نوى مخصصة (custom kernels)، فحينها ستحتاج فقط إلى مجموعة أدوات التطوير الكاملة (full toolkit) مع في متغير البيئة PATH. .

كيف أُثبِّت إصدارًا معيَّنًا من vLLM أو الإصدار التجريبي (nightly build)؟

ثبِّته مثل أي حزمة أخرى عبر: pip install vllm==، واختر الإصدار المناسب من القائمة المنشورة على PyPI. وتُنشر حزم الإصدارات التجريبية (nightly) والحزم الخاصة بكل عملية ترقيم (per-commit) بشكل منفصل من قِبل المشروع، وتُثبَّت باستخدام عنوان URL إضافي لفهرسة الحزم — والعنوان الحالي موثَّق في صفحة التثبيت، وقد تغيَّر سابقًا، لذا يُرجى الاطلاع عليه هناك بدلًا من نسخ أمر قديم.

لماذا يستهلك vLLM الذاكرة الكاملة لبطاقتي الرسومية (GPU)؟

وهذا مقصودٌ تصميميًّا. ففي وقت بدء التشغيل، يتم تخصيص مسبَّق لحوض كبير من كتل ذاكرة التخزين المؤقت KV — ويتم التحكم فيه عبر --gpu-memory-utilization، والتي تكون قيمتها الافتراضية 0.9 — وذلك لأن تقنية الانتباه المُقسَّم (paged attention) هي ما يمنح vLLM أداءً عاليًا في معدل الإرسال (throughput) تحت ظروف التزامن (concurrency). وقلِّل هذه القيمة إذا كنت بحاجة إلى مشاركة البطاقة مع عمليات أخرى، ونتيجة لذلك ستتوقَّع تقليل عدد الطلبات المتزامنة.

هل ينبغي أن أستخدم vLLM أم Ollama؟

Ollama هو مثبِّت واحد متعدد المنصات يستهدف مستخدمًا واحدًا على جهاز واحد؛ راجع دليل تثبيت Ollama إذا كان هذا ينطبق عليك. أما vLLM فهو محرك خدمة مصمَّم للتعامل مع العديد من الطلبات المتزامنة لكل وحدة معالجة رسومية، مع دعم التجميع المستمر (continuous batching) والتوازي الموحَّد (tensor parallelism) وواجهة برمجة تطبيقات (API) متوافقة مع OpenAI. ثبِّت vLLM عندما تكون تقوم بتشغيل تطبيق ما، وليس عند إجراء محادثة محلية.

أي نموذج يجب أن أبدأ بتشغيله أولًا؟

ابدأ بنموذج صغير وغير مقيد (ungated) حتى تركز على تصحيح مشاكل التثبيت بدلًا من مشاكل التنزيل — فنموذج من فئة 8B بحجم نحو 5 جيجابايت عند تكمينه بعمق 4 بت هو الخيار الأمثل. وبمجرد أن يستجيب الخادوم لطلب /v1/models، يمكنك الترقية تدريجيًّا. أما لوحة تصنيف النماذج اللغوية الكبيرة (LLM) فهو وسيلة معقولة لاختيار المرشحين المناسبين بناءً على قدراتهم وأسعارهم وطول السياق المدعوم قبل أن تخصص مساحة VRAM لنموذج معين.