ما هو vLLM؟ تسريع استدلال LLM لواجهات برمجية سريعة وقابلة للتوسع

هل تبني تطبيقات نماذج اللغة الكبيرة (LLM) وتواجه بطءًا في الاستدلال أو ضغطًا على ذاكرة الـ GPU؟ يقدّم vLLM طريقة عملية لخدمة النماذج بإنتاجية أعلى، وتجميع طلبات ديناميكي، واستهلاك ذاكرة أفضل. في هذا الدليل ستتعرف على vLLM، آلية عمله، طريقة تثبيته، وتشغيله للاستدلال الدفعي أو كخادم API متوافق مع OpenAI.

جرّب Apidog اليوم

ما هو vLLM؟ ولماذا يهم مطوري واجهات LLM API؟

vLLM هو محرك استدلال مفتوح المصدر عالي الإنتاجية وفعّال في استخدام الذاكرة، مصمم لخدمة نماذج اللغة الكبيرة في بيئات التطوير والإنتاج.

يعالج vLLM مشكلتين شائعتين في نشر نماذج LLM:

• بطء الاستدلال عند وجود عدد كبير من المستخدمين المتزامنين.
• استهلاك ذاكرة GPU بشكل غير فعّال بسبب طريقة إدارة KV cache في آليات الانتباه التقليدية.

يعتمد vLLM على ميزتين أساسيتين:

• PagedAttention: يقلل هدر ذاكرة KV cache عبر تقسيمها إلى صفحات مرنة.
• Continuous batching: يدمج الطلبات الواردة ديناميكيًا بدل انتظار دفعات ثابتة.

النتيجة: خادم LLM أكثر ملاءمة لواجهات API عالية التزامن، خصوصًا عندما تريد تشغيل نموذجك محليًا أو داخل بنيتك التحتية بدل الاعتماد الكامل على مزود خارجي.

لماذا يستخدم مطورو الـ Backend وواجهات API vLLM؟

يفيد vLLM الفرق التي تريد تشغيل LLM API قابلة للتوسع مع تحكم أكبر في النموذج والبنية التحتية.

أهم ما يقدمه:

• إنتاجية أعلى: خدمة طلبات أكثر في الثانية.
• استخدام أفضل للـ GPU: تقليل الهدر في الذاكرة وزيادة الاستفادة من العتاد.
• تجميع ديناميكي للطلبات: مناسب لحركة مرور API غير المنتظمة.
• واجهة API متوافقة مع OpenAI: يمكنك استخدام عملاء OpenAI SDK مع خادم vLLM.
• دعم نماذج واسع: مثل Llama، Mistral، Qwen، OPT، Falcon وغيرها.
• دعم للاستدلال الدفعي والخدمة المباشرة: مناسب للتقييم، المعالجة بالجملة، أو واجهات الإنتاج.

راجع القائمة الرسمية هنا: النماذج المدعومة في vLLM.

نصيحة عملية: إذا كنت تبني API فوق vLLM، استخدم أداة مثل Apidog لتوثيق نقاط النهاية، اختبار الطلبات، وإعداد سيناريوهات تحقق لفريق الـ Backend وQA.

النماذج المدعومة في vLLM

يدعم vLLM مجموعة كبيرة من نماذج Transformer، ومنها:

• Llama / Llama 2 / Llama 3
• Mistral و Mixtral
• Qwen و Qwen2
• GPT-2 و GPT-J و GPT-NeoX
• OPT
• Bloom
• Falcon
• MPT
• نماذج أخرى، بما في ذلك بعض النماذج متعددة الوسائط

للتأكد من توافق النموذج قبل النشر، راجع دائمًا قائمة النماذج المدعومة الرسمية.

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

كيف يعمل vLLM؟ المفاهيم المهمة

1. PagedAttention

في الاستدلال التقليدي، تُخزن KV cache في ذاكرة متجاورة، ما قد يؤدي إلى تجزئة وهدر في VRAM.

يقسم vLLM هذه الذاكرة إلى صفحات، بطريقة مشابهة لإدارة الذاكرة الافتراضية في أنظمة التشغيل. هذا يساعد على:

• تقليل هدر الذاكرة.
• تمكين خدمة تسلسلات أطول.
• تحسين التعامل مع الطلبات المتزامنة.
• مشاركة الذاكرة في بعض الحالات للبادئات المشتركة.

2. Continuous batching

في التجميع الثابت، ينتظر النظام اكتمال دفعة كاملة قبل بدء المعالجة، ما يؤدي إلى وقت خمول للـ GPU.

أما في vLLM، فتُضاف الطلبات الجديدة إلى المعالجة فور توفر الموارد. هذا مفيد جدًا في واجهات API لأن الطلبات تصل غالبًا بشكل غير منتظم.

المتطلبات قبل تثبيت vLLM

قبل البدء، تأكد من توفر التالي:

• نظام تشغيل Linux: هو الأكثر دعمًا. يمكن استخدام WSL2 أو macOS في بعض الحالات، لكن Linux هو الخيار الأفضل.
• Python: الإصدارات 3.9 أو 3.10 أو 3.11 أو 3.12.
• GPU من NVIDIA مع CUDA: للحصول على أفضل أداء.
• بيئة افتراضية: لتجنب تضارب الحزم.
• مساحة كافية على القرص: لأن النماذج قد تكون كبيرة.

تحقق من الـ GPU:

nvidia-smi

وتحقق من إصدار Python:

python --version

تثبيت vLLM خطوة بخطوة

الطريقة 1: التثبيت باستخدام pip

python -m venv vllm-env
source vllm-env/bin/activate

pip install vllm

على Windows:

vllm-env\Scripts\activate

تحقق من التثبيت:

python -c "import vllm; print(vllm.__version__)"
vllm --help

الطريقة 2: التثبيت باستخدام Conda

conda create -n vllm-env python=3.11 -y
conda activate vllm-env

pip install vllm

إذا كنت تحتاج إصدار CUDA مخصصًا، ثبّت PyTorch المناسب أولًا، ثم ثبّت vLLM.

الطريقة 3: التثبيت باستخدام uv

uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate

uv pip install vllm

تشغيل استدلال دفعي باستخدام vLLM

استخدم الاستدلال الدفعي عندما تريد تمرير قائمة prompts ومعالجتها دفعة واحدة، مثل:

• تقييم نموذج.
• توليد بيانات.
• معالجة ملفات كثيرة.
• اختبار إعدادات sampling مختلفة.

مثال عملي:

from vllm import LLM, SamplingParams

prompts = [
    "The capital of France is",
    "Explain the theory of relativity in simple terms:",
    "Write a short poem about a rainy day:",
    "Translate 'Hello, world!' to German:",
]

sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.95,
    max_tokens=150,
    stop=["\n", " Human:", " Assistant:"]
)

llm = LLM(model="mistralai/Mistral-7B-Instruct-v0.1")

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    print("-" * 20)
    print(f"Prompt: {output.prompt!r}")
    print(f"Generated Text: {output.outputs[0].text!r}")

ملاحظات مهمة

• يستخدم vLLM عادة نماذج Hugging Face Hub.
• لاستخدام ModelScope:

export VLLM_USE_MODELSCOPE=1

• إذا أردت استخدام إعدادات vLLM الافتراضية بدل إعدادات النموذج:

llm = LLM(
    model="mistralai/Mistral-7B-Instruct-v0.1",
    generation_config="vllm"
)

• عند استخدام نماذج Quantized مثل AWQ أو GPTQ، راجع بطاقة النموذج ووثائق vLLM قبل التشغيل.

تشغيل vLLM كخادم API متوافق مع OpenAI

إذا كنت تريد تقديم النموذج عبر HTTP API، يمكن تشغيل vLLM كخادم متوافق مع واجهات OpenAI.

ابدأ الخادم:

source vllm-env/bin/activate

vllm serve mistralai/Mistral-7B-Instruct-v0.1

أو استخدم نموذجًا أصغر للتجربة:

vllm serve Qwen/Qwen2-1.5B-Instruct

يعمل الخادم افتراضيًا على:

http://localhost:8000

خيارات مفيدة عند التشغيل

vllm serve mistralai/Mistral-7B-Instruct-v0.1 \
  --host 0.0.0.0 \
  --port 8000 \
  --api-key your-api-key

خيارات شائعة:

• --host 0.0.0.0: السماح بالوصول من خارج الجهاز المحلي.
• --port 8000: تحديد المنفذ.
• --tensor-parallel-size N: توزيع النموذج على N من وحدات GPU.
• --api-key: فرض مفتاح API على الطلبات.
• --generation-config vllm: استخدام إعدادات توليد vLLM.
• --chat-template: تمرير قالب دردشة مخصص عند الحاجة.

اختبار endpoint التكملة Completions

باستخدام cURL

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.1",
    "prompt": "San Francisco is a city in",
    "max_tokens": 50,
    "temperature": 0.7
  }'

إذا فعّلت --api-key:

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.1",
    "prompt": "Explain the benefits of using vLLM:",
    "max_tokens": 100
  }'

باستخدام OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1"
)

completion = client.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.1",
    prompt="Explain the benefits of using vLLM:",
    max_tokens=150,
    temperature=0.5
)

print(completion.choices[0].text)

اختبار endpoint الدردشة Chat Completions

باستخدام cURL

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.1",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is the main advantage of PagedAttention in vLLM?"
      }
    ],
    "max_tokens": 100,
    "temperature": 0.7
  }'

باستخدام Python

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1"
)

chat_response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.1",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful programming assistant."
        },
        {
            "role": "user",
            "content": "Write a simple Python function to calculate factorial."
        }
    ],
    max_tokens=200,
    temperature=0.5
)

print(chat_response.choices[0].message.content)

توثيق واختبار API باستخدام Apidog

بعد تشغيل vLLM كخادم API، يمكنك إنشاء مجموعة endpoints في Apidog لاختبارها وتوثيقها.

مثال endpoints:

POST /v1/completions
POST /v1/chat/completions

مثال body لـ /v1/chat/completions:

{
  "model": "mistralai/Mistral-7B-Instruct-v0.1",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Explain vLLM in one paragraph."
    }
  ],
  "max_tokens": 120,
  "temperature": 0.7
}

هذا يساعد الفريق على:

• توحيد طريقة اختبار endpoints.
• مشاركة أمثلة الطلبات والاستجابات.
• توثيق API داخليًا أو خارجيًا.
• اختبار مفاتيح API والـ headers.
• محاكاة سيناريوهات فشل أو نجاح قبل ربط الواجهة بالتطبيق.

واجهات الانتباه الخلفية في vLLM

يدعم vLLM عدة backends لحساب الانتباه:

• FlashAttention 1 و 2: غالبًا الخيار الأسرع على GPUs حديثة من NVIDIA.
• xFormers: خيار واسع التوافق، وقد يكون مفيدًا مع بعض البيئات.
• FlashInfer: خيار متقدم وقد يتطلب إعدادًا يدويًا.

افتراضيًا، يختار vLLM backend المناسب حسب البيئة والنموذج.

إذا أردت فرض backend محدد:

export VLLM_ATTENTION_BACKEND=FLASH_ATTN

أو:

export VLLM_ATTENTION_BACKEND=XFORMERS

أو:

export VLLM_ATTENTION_BACKEND=FLASHINFER

ثم شغّل الخادم:

vllm serve mistralai/Mistral-7B-Instruct-v0.1

استكشاف الأخطاء الشائعة

1. خطأ CUDA out of memory

إذا ظهرت أخطاء نفاد ذاكرة GPU:

• استخدم نموذجًا أصغر.
• قلل max_tokens.
• قلل عدد الطلبات المتزامنة.
• استخدم نموذجًا quantized مثل AWQ أو GPTQ إن كان مدعومًا.
• استخدم أكثر من GPU مع:

vllm serve mistralai/Mistral-7B-Instruct-v0.1 \
  --tensor-parallel-size 2

• تحقق من العمليات التي تستهلك الذاكرة:

nvidia-smi

2. مشاكل التثبيت أو التوافق

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

• إصدار CUDA.
• تعريف NVIDIA.
• إصدار PyTorch.
• إصدار Python.

راجع مصفوفة توافق PyTorch.

إذا أردت إعدادًا أسهل، استخدم صور Docker الرسمية لـ vLLM.

3. فشل تحميل النموذج

جرّب التالي:

• تأكد من اسم النموذج:

mistralai/Mistral-7B-Instruct-v0.1

• تحقق من اتصال الإنترنت ومساحة القرص.
• إذا كان النموذج يتطلب كودًا مخصصًا، قد تحتاج إلى تفعيل trust_remote_code=True في حالات معينة.
• استخدم مسارًا محليًا إذا كان النموذج محملًا مسبقًا.

4. الاستدلال بطيء

لتحسين الأداء:

• راقب استخدام GPU:

nvidia-smi

• حدّث vLLM والتبعيات.
• جرّب backend مختلف للانتباه.
• قلل max_tokens إذا كان مرتفعًا.
• راجع طول الـ prompt؛ كلما زاد السياق زاد زمن المعالجة.

5. الناتج غير منطقي أو غير متوقع

تحقق من:

• تنسيق prompt المناسب للنموذج.
• استخدام قالب chat template الصحيح.
• إعدادات temperature و top_p.
• تجربة نموذج آخر لعزل المشكلة.
• قراءة بطاقة النموذج على Hugging Face لمعرفة طريقة الاستخدام الصحيحة.

مثال سريع لهيكلة خدمة Backend فوق vLLM

يمكنك وضع API وسيطة بين تطبيقك وخادم vLLM لإضافة المصادقة، القيود، التسجيل، أو تنسيق الاستجابة.

مثال بسيط باستخدام FastAPI:

from fastapi import FastAPI
from pydantic import BaseModel
from openai import OpenAI

app = FastAPI()

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1"
)

class ChatRequest(BaseModel):
    message: str

@app.post("/ask")
def ask_model(payload: ChatRequest):
    response = client.chat.completions.create(
        model="mistralai/Mistral-7B-Instruct-v0.1",
        messages=[
            {"role": "system", "content": "You are a concise technical assistant."},
            {"role": "user", "content": payload.message}
        ],
        max_tokens=200,
        temperature=0.5
    )

    return {
        "answer": response.choices[0].message.content
    }

شغّل التطبيق:

uvicorn app:app --reload --port 3000

ثم اختبره:

curl http://localhost:3000/ask \
  -H "Content-Type: application/json" \
  -d '{"message": "اشرح PagedAttention باختصار"}'

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

باستخدام vLLM يمكنك تشغيل واجهات API لنماذج LLM بكفاءة أعلى، سواء للاستدلال الدفعي أو الخدمة المباشرة المتوافقة مع OpenAI.

للبدء عمليًا:

1. اختر نموذجًا مناسبًا لذاكرة GPU لديك.
2. ثبّت vLLM داخل بيئة افتراضية.
3. اختبر الاستدلال الدفعي أولًا.
4. شغّل vllm serve كخادم API.
5. اختبر /v1/completions و /v1/chat/completions.
6. وثّق الطلبات والاستجابات في أداة API مثل Apidog.
7. راقب الأداء والذاكرة قبل الانتقال للإنتاج.

للميزات المتقدمة مثل quantization، و multi-LoRA، والخدمة الموزعة، وفك التشفير التخميني، راجع وثائق vLLM الرسمية.