مُنفِّذ نموذج Docker: دليل إعداد حجم السياق

กำหนด حجم السياق في Docker Model Runner باستخدام حلول بديلة

Page content

تهيئة أحجام السياق في Docker Model Runner أكثر تعقيدًا مما ينبغي أن يكون.

بينما يتوفر معلمة context_size في تكوين docker-compose، غالبًا ما تتجاهلها صورة docker/model-runner:latest-cuda، والتي تحدد بشكل مسبق حجم سياق 4096 مقطعًا. هذا الدليل يستكشف الحدود ويقدم حلولًا عملية.

تهيئة سيارة تم إنشاء هذه الصورة بواسطة Flux 1 dev.

فهم المشكلة

عند استخدام Docker Model Runner مع docker-compose، قد تهيئة حجم السياق على النحو التالي:

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

ومع ذلك، عند فحص السجلات، ستظهر الحجم الفعلي المستخدم:

docker compose logs 2>&1 | grep -i "n_ctx"

سترى خرجًا مثل:

llamaCppArgs: [... --ctx-size 4096 ...]
llama_context: n_ctx = 4096

صورة docker/model-runner:latest-cuda تحدد بشكل مسبق --ctx-size 4096 عند استدعاء llama.cpp، وتتجاهل تمامًا إعدادك context_size: 10240.

سبب حدوث ذلك

يتم تحديد حجم السياق (n_ctx) في وقت تهيئة النموذج في llama.cpp، وهو المحرك الأساسي للتنبؤ الذي يستخدمه Docker Model Runner. يحدث هذا أثناء مرحلة بناء سياق النموذج، قبل معالجة أي طلبات API. يبدو أن دمج Docker Model Runner مع docker-compose يحتوي على عيب حيث لا يتم نقل معلمة context_size بشكل صحيح من قسم النماذج إلى عملية llama.cpp الأساسية. بدلًا من ذلك، يتم الافتراض إلى 4096 مقطعًا بغض النظر عن إعدادك.

هذا القيود يعني أن حتى لو اعترفت Docker Compose بمعلمة context_size في ملف YAML الخاص بك، فإن صورة docker/model-runner:latest-cuda لا تأخذها في الاعتبار عند إنشاء معلمات سطر الأوامر لـ llama.cpp. يأخذ العلم المحدد --ctx-size 4096 الأولوية على أي إعداد تحدده.

الحلول والبدائل

ماذا يجب أن تفعل؟ الطرق 1-2-3 ستكون فعالة، لكنها تحتوي على قيود.

طريقة 1. مؤقتة، ستكون فعالة. طريقة 2. محددة مسبقًا في النموذج. طريقة 3. تتطلب تعبئة حاوياتك الخاصة ووضع تطبيقك الخاص في التكوين. هذا أقرب إلى الإنتاج.

الطريقة 1: استخدام docker model configure (محدودة)

يمكنك تهيئة حجم السياق باستخدام واجهة سطر الأوامر لـ Docker Model، والتي تخزن الإعداد في بيانات النموذج الخاصة بـ Docker:

docker model configure --context-size=10000 ai/gemma3-qat:4B

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

القيود:

  • لا تعمل هذه الطريقة عند استخدام docker model run مباشرة، فقط عبر curl إلى نقطة النهاية الخاصة بالواجهة
  • لا يمكنك استخدام docker model run بعد التكوين - ستتجاهل الإعداد
  • يتم تجاهل الإعداد عند استخدام docker-compose مع صورة docker/model-runner:latest-cuda
  • قد تفقد الإعداد عند تحديث النموذج أو سحبه مرة أخرى

تعمل هذه الطريقة بشكل أفضل للاختبار مع مكالمات API مباشرة، لكنها ليست مناسبة للنشر باستخدام docker-compose.

الطريقة 2: تعبئة نموذجك الخاص

الطريقة الأكثر موثوقية لتعيين حجم سياق مخصص هي تعبئة نموذجك الخاص بحجم السياق المطلوب باستخدام docker model package. هذا يضمن حجم السياق في بيانات النموذج أثناء عملية التعبئة:

docker model package \
  --gguf /path/to/model.gguf \
  --context-size 10240 \
  --name my-model:custom-context

هذا ينشئ عنصرًا جديدًا من OCI (متشابهًا مع صورة Docker) مع حجم السياق مُحدد بشكل دائم. يمكن بعد ذلك دفع النموذج المعبأ إلى Docker Hub أو أي سجل متوافق مع OCI وسحبه مثل أي نموذج آخر لـ Docker Model Runner.

ومع ذلك، تتطلب هذه الطريقة:

  • الوصول إلى ملف النموذج الأصلي (التنسيق المُكمّس المستخدم من قبل llama.cpp)
  • إعادة التعبئة كلما أردت تغيير حجم السياق، وهو ما قد يكون مرهقًا في الوقت
  • إدارة سجل نماذجك الخاصة أو حساب Docker Hub
  • فهم عملية تعبئة Docker Model Runner

هذه الطريقة مناسبة بشكل أفضل للبيئات الإنتاجية حيث تحتاج إلى حجم سياق متسق ومُعاد تكوينه عبر النشرات.

الطريقة 3: Docker Compose

هذا مكسور حاليًا لـ docker/model-runner:latest-cuda

لكن لتطبيقك الخاص في الصورة قد تعمل :)

بينما توجد التركيبة في docker-compose.yml:

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

هذا لا يعمل - تُعترف معلمة context_size من قبل docker-compose ولكن لا تُطبَّق. لا يزال النموذج يستخدم 4096 مقطعًا.

الطريقة 4: المتغيرات البيئية (مكسورة أيضًا)

محاولة استخدام متغير البيئة MODEL_CONTEXT:

services:
  llm:
    image: docker/model-runner:latest-cuda
    environment:
      - MODEL_CONTEXT=10240

هذا أيضًا لا يعمل - لا يتم احترام متغير البيئة عند استخدام docker-compose.

التحقق من حجم السياق

للحصول على حجم السياق الفعلي المستخدم، تحقق من السجلات:

# تحقق من معلمات llama.cpp
docker compose logs 2>&1 | grep "llamaCppArgs"

# تحقق من حجم السياق الفعلي
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

سترى خرجًا مثل:

llamaCppArgs: [-ngl 999 --metrics --model /models/... --ctx-size 4096 ...]
llama_context: n_ctx = 4096
llama_context: n_ctx_per_seq = 4096

إذا رأيت n_ctx = 4096 رغم إعداد قيمة مختلفة، فإن إعدادك يتم تجاهله.

اختبار حجم السياق

لتأكيد ما إذا كان إعداد حجم السياق الخاص بك يتم تطبيقه فعليًا، تحتاج إلى اختبار مع طلبات تتجاوز الحد الافتراضي لـ 4096 مقطع. إليك نموذجًا عمليًا لاختبار ما إذا كان إعداد حجم السياق الخاص بك يعمل باستخدام Python:

#!/bin/bash
MODEL="ai/gemma3-qat:4B"
PORT=8085

# اختبار مع طلب كبير
python3 -c "print('test ' * 5000)" > large_prompt.txt

python3 << 'PYTHON' > request.json
import json
import os

with open('large_prompt.txt', 'r') as f:
    large_prompt = f.read().strip()

request = {
    "model": os.environ.get("MODEL", "ai/gemma3-qat:4B"),
    "messages": [{
        "role": "user",
        "content": large_prompt
    }]
}
print(json.dumps(request))
PYTHON

curl -s http://localhost:${PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @request.json > response.json

# تحقق من استخدام الرموز
python3 << 'PYTHON'
import json
with open('response.json') as f:
    r = json.load(f)
    if 'usage' in r:
        print(f"Prompt tokens: {r['usage']['prompt_tokens']}")
        if r['usage']['prompt_tokens'] > 4096:
            print("✅ يتجاوز حجم النافذة 4096!")
        else:
            print("⚠️ يبدو أن حجم النافذة محدود إلى 4096")
PYTHON

حلول بديلة

إذا كنت بحاجة إلى تكوين أكثر مرونة لحجم السياق، ففكر في هذه الحلول البديلة:

  • Ollama - حل بديل لاستضافة نماذج LLM يوفر سيطرة أفضل على أحجام السياق وتكوين أبسط. يسمح Ollama لك بتخصيص حجم السياق لكل نموذج ولا يحتوي على نفس قيود docker-compose.

  • مقارنة Docker Model Runner مع Ollama - مقارنة تفصيلية بين الحلولتين، بما في ذلك قدرات تكوين حجم السياق، الأداء، ومتى تختار كل منصة.

الموارد المرتبطة

Docker Model Runner

Docker والبنية التحتية

حلول بديلة لـ LLM

الوثائق الرسمية

الخاتمة

تهيئة أحجام السياق في Docker Model Runner تظل مشكلة عند استخدام docker-compose. بينما توجد معلمة التكوين في مواصفات docker-compose، إلا أنها لا تُطبَّق بشكل صحيح في صورة docker/model-runner:latest-cuda، والتي تحدد بشكل مسبق حجم سياق 4096 مقطعًا بغض النظر عن إعدادك.

الحل الأكثر موثوقية هو تعبئة نماذجك الخاصة بحجم السياق المطلوب باستخدام docker model package، على الرغم من أن هذا يضيف تعقيدًا لعملية تكوينك ويحتاج إلى الوصول إلى ملفات النماذج الأصلية GGUF. أو يمكنك استخدام docker model configure للوصول المباشر إلى الواجهة، لكن هذا لا يعمل مع النشرات docker-compose.

لأغراض الاستخدام العادية، يكون حجم السياق الافتراضي 4096 مقطعًا كافيًا لتطبيقات الذكاء الاصطناعي التحويلية. إذا كنت بحاجة إلى نافذة سياق أكبر أو تكوين أكثر مرونة، ففكر في استخدام Ollama كخيار بديل، والذي يوفر سيطرة أفضل على أحجام السياق دون قيود docker-compose.

يمكنك لا تزال تحسين استخدام VRAM من خلال وسائل أخرى مثل كمّية النموذج (Q4، Q6، Q8) وتكوين طبقات وحدات معالجة الرسومات (MODEL_GPU_LAYERS)، وهي أكثر فعالية في تقليل استهلاك الذاكرة من تعديلات حجم السياق بأي حال.

للمزيد من التفاصيل حول تحسين وحدات معالجة الرسومات وإدارة VRAM، راجع دليلنا حول تهيئة دعم وحدات معالجة الرسومات NVIDIA.