استيراد نموذج GGUF إلى Ollama وتشغيله

طريقتان لاستيراد نموذج GGUF إلى Ollama

هناك طريقتان لاستيراد نموذج GGUF إلى Ollama، وتعتمد الطريقة المناسبة على مكان وجود الملف حالياً. إذا كان النموذج موجوداً في مستودع على Hugging Face، فإن أمر ollama run واحداً يجلبه ويشغّله من دون استخدام Modelfile. وإذا كان ملف .gguf موجوداً مسبقاً على قرص الخادم، فاكتب Modelfile من سطرين وشغّل ollama create.

تنتهي الطريقتان بالنتيجة نفسها: نموذج مُسمّى في مكتبة Ollama المحلية يمكن لـollama run وواجهة Ollama API تقديمه. استخدم الطريقة الأولى عندما يكون شخص آخر قد نشر الملف. واستخدم الثانية عندما تكون قد أجريت quantization للنموذج بنفسك، أو عندما وصل الملف عبر scp أو rsync، أو عندما لا يستطيع الجهاز الوصول إلى Hugging Face.

ملف GGUF عبارة عن ملف ثنائي واحد يحتوي على الأوزان وtokenizer والبيانات الوصفية للنموذج معاً. هذا هو التنسيق الذي يقرأه llama.cpp، وتُبنى Ollama على llama.cpp، ولذلك تتوفر تقريباً لكل نموذج مفتوح المصدر نسخة GGUF حوّلها المجتمع. يمكن لـOllama أيضاً استيراد مجلد يحتوي على أوزان .safetensors، لكن ذلك مسار منفصل، ويوضح القسم الخاص بـ--quantize أدناه موضع استخدامه.

يفترض كل ما يلي أن Ollama مثبتة مسبقاً وأن خدمتها قيد التشغيل. إذا لم تكن كذلك، فابدأ بـتثبيت Ollama على VPS ثم عد إلى هنا. شغّل ollama list أولاً. إذا أعاد الأمر جدولاً، حتى لو كان فارغاً، بدلاً من خطأ في الاتصال، فهذا يعني أن الخادم يعمل، وسيعمل باقي هذا الدليل.

المسار الأول: تشغيل ملف GGUF من Hugging Face دون Modelfile

يمكن لـOllama سحب ملف GGUF مباشرةً من مستودع على Hugging Face. يتكوّن الأمر من مسار المستودع مع بادئة hf.co/:

ollama run hf.co/{username}/{repository}

يعمل كل من hf.co وhuggingface.co بوصفهما اسم النطاق. إليك مثالاً فعلياً من وثائق Hugging Face:

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

ينزّل التشغيل الأول الملف، لذلك لا يظهر موجّه الدردشة حتى يكتمل التنزيل. بعد ذلك يصبح النموذج في مكتبتك المحلية ويبدأ بسرعة. افتح shell ثانية ونفّذ ollama list لمعرفة الاسم الذي حُفظ به. هذا الاسم هو سلسلة hf.co/... كاملةً مع الوسم، ولذلك يصعب كتابته في كل مرة. امنحه اسماً مستعاراً قصيراً:

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

يعمل هذا المسار فقط مع المستودعات التي تحتوي فعلياً على ملفات GGUF. إذا كان المستودع ينشر أوزان .safetensors ولا ينشر غيرها، فلن يجد هذا المسار ملفاً لتنزيله، وستحتاج إلى أحد أساليب الاستيراد المحلية الموضحة لاحقاً.

أي quantization يختار Ollama؟

توضح وثائق Ollama على Hugging Face، كما قُرئت في 10 October 2026، الإعداد الافتراضي صراحةً: "By default, the Q4_K_M quantization scheme is used, when it's present inside the model repo. If not, we default to picking one reasonable quant type present inside the repo." لذلك يمنحك المستودع الذي ينشر عشرة أنواع quant النوع Q4_K_M، بينما يمنحك المستودع الذي لا يحتوي على Q4_K_M خياراً اختاره Ollama نيابةً عنك. أعد قراءة تلك الصفحة قبل الاعتماد على هذا السلوك، لأن الإعدادات الافتراضية تتغير.

اطلب نوع quant محدداً بإضافته بوصفه وسمًا:

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

اسم quantization غير حساس لحالة الأحرف، لذلك يعني :iq3_m و:IQ3_M الشيء نفسه. يمكنك أيضاً تمرير اسم الملف الكامل بوصفه الوسم. وهذا هو الخيار الآمن عندما تكون الأسماء المختصرة في المستودع غامضة. يجب أن يشير الوسم إلى ملف موجود في ذلك المستودع، لذلك افتح علامة التبويب Files and versions واقرأ أسماء الملفات الفعلية قبل كتابة أحدها. يعتمد اختيار quant الذي تريده على الذاكرة والجودة، وتشرح الفروق بين Q4 وQ8 وFP16 هذه المفاضلة بصورة صحيحة.

المسار الثاني: استيراد ملف .gguf من قرصك الخاص

عندما يكون الملف موجوداً على الخادم، تحتاج إلى Modelfile. يمكن أن يتكوّن من سطر واحد. أنشئ دليلاً، وضع Modelfile فيه، ثم وجّه FROM إلى الملف:

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

احفظ ذلك باسم Modelfile، ثم أنشئ النموذج:

ollama create my-model

يقرأ ollama create افتراضياً ملفاً باسم Modelfile في الدليل الحالي. استخدم -f عندما يكون لملفك اسم آخر أو يوجد في مكان مختلف، كما في ollama create my-model -f /home/you/models/my-model/Modelfile. شغّل ollama create --help لعرض الخيار وقيمته الافتراضية في إصدارك. يمكن أن يكون المسار في FROM مطلقاً أو نسبياً إلى Modelfile، لذلك يعمل FROM ./my-model-Q4_K_M.gguf عندما يكون الملفان في الدليل نفسه. يزيل المسار المطلق هذا الالتباس تماماً.

تحقق من النتيجة قبل الوثوق بها:

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ينبغي أن يتضمن ollama list الآن my-model. يطبع ollama show my-model البنية وعدد المعلمات وطول السياق ومستوى التكميم الذي قرأه Ollama من البيانات الوصفية الخاصة بالملف. اقرأ هذه القيم بدلاً من الوثوق باسم الملف، لأن اسم الملف مجرد نص أدخله شخص يدوياً. إذا أجاب النموذج عن مطالبة الاختبار بلغة طبيعية ثم توقف، فقد نجح الاستيراد. وإذا لم يفعل، فانتقل إلى قسم القالب أدناه، لأن القالب هو السبب في معظم الحالات.

هناك أمر مهم يتعلق بمساحة القرص: ينسخ ollama create ملف GGUF إلى مخزن النماذج الخاص بـOllama بدلاً من الإشارة إلى مكان وجود الملف. تبقى الأوزان على القرص مرتين إلى أن تحذف النسخة الأصلية. احذف الملف المصدر بعد نجاح ollama run my-model، أو احتفظ به في مكان لا تدفع تكلفة تخزينه مرتين فيه. يشرح مكان تخزين Ollama لنماذجه على القرص البنية وكيفية نقلها.

متى ينطبق --quantize ومتى لا ينطبق

يتضمن ollama create خيار --quantize، وهو ينطبق حالياً على حالة واحدة فقط: نموذج مستورد من دليل يحتوي على أوزان .safetensors. يذكر نص المساعدة في مصدر Ollama الحالي، الذي جرى التحقق منه في 10 October 2026، ما يلي: "Quantize safetensors model to this level (e.g. nvfp4)"، والقيم التي يقبلها هي int4 وint8 وnvfp4 وmxfp4 وmxfp8. تُرفض أسماء تكميم GGUF مثل q8_0 أو q4_K_M باعتبارها أنواعاً غير مدعومة. توضح وثائق استيراد Ollama ذلك صراحةً فيما يخص GGUF: "Ollama does not quantize GGUF models during import."

ollama create --quantize int8 my-model

يفترض هذا الأمر وجود Modelfile يشير سطر FROM فيه إلى الدليل الذي يحتوي على ملفات .safetensors.

لا تمرر هذا الخيار عندما يحدد FROM ملف .gguf، مهما كانت دقته. يُرفض ملف GGUF بدقة FP16 أو FP32 بالطريقة نفسها التي يُرفض بها ملف Q4_K_M، مع ظهور خطأ يبدأ بالعبارة "create-time quantization is only supported for safetensors imports". يكون ملف .gguf الذي يحمل اسمه Q4_K_M أو Q5_K_S مكمماً مسبقاً، ولا يمكن استعادة الدقة التي فُقدت أثناء التكميم. يستطيع llama-quantize في llama.cpp إعادة ترميز هذا الملف كنوع آخر، بما في ذلك Q8_0، عند تمرير --allow-requantize، لكن دليله يحذّر من أن ذلك "can severely reduce quality compared to quantizing from 16bit or 32bit"، كما أن إعادة كتابة ملف Q4 بصيغة Q8 تجعله أكبر من دون تحسين جودته. لتقليص حجم ملف GGUF كامل الدقة، شغّل llama-quantize عليه أولاً، فهذه هي الأداة التي تشير إليها وثائق Ollama، ثم استورد الملف الذي تنشئه. إذا كان مصدرك مستودعاً على Hugging Face يحتوي على ملفات .safetensors، فيمكنك توجيه FROM إلى ذلك الدليل وترك ollama create يستورده، مع استخدام --quantize إذا أردت حجماً أصغر، أو تحويله باستخدام convert_hf_to_gguf.py من مستودع llama.cpp ثم استيراد ملف GGUF الذي ينشئه ذلك البرنامج النصي. يشرح العلاقة بين Ollama وllama.cpp سبب ارتباط هذه الأدوات بالمشروع الآخر.

لماذا يجيب GGUF المستورَد بنص غير مفهوم أو لا يتوقف أبداً؟

هذا هو العطل الذي تتجاهله معظم أدلة الاستيراد، وستواجهه غالباً. تبدو الأعراض كأن النموذج تالف. تظهر رموز التحكم كنص ظاهر في الإجابة، مثل السلاسل <|im_start|>assistant أو <|end|>. يجيب النموذج، ثم يكتب سؤال مستخدم جديداً ويجيب عنه أيضاً. يستمر التوليد حتى تضغط Ctrl+C.

النموذج سليم. قالب المحادثة غير صحيح. قالب المحادثة هو الغلاف الذي يحوّل رسالتك إلى تسلسل الرموز الدقيق الذي دُرِّب النموذج عليه، مع علامات خاصة تحدد نهاية مطالبة النظام وبداية دور المستخدم. يختار Ollama قالباً لك؛ إذ تذكر الوثائق أن قالباً «سيُختار تلقائياً من قائمة بالقوالب الشائعة الاستخدام»، استناداً إلى البيانات الوصفية المضمّنة tokenizer.chat_template المخزّنة داخل ملف GGUF. عندما تكون هذه البيانات الوصفية مفقودة، أو لا تطابق أي قالب في القائمة، تحصل على غلاف عام. عندها يرى النموذج مطالبة بتنسيق يختلف عن كل ما واجهه أثناء التدريب، لذلك لا يصل أبداً إلى علامة نهاية الدور التي تعلّم التوقف عندها.

اطبع القالب الذي اختاره Ollama فعلياً:

ollama show --template my-model
ollama show --modelfile my-model

يؤكد القالب الفارغ أو العام بوضوح وجود المشكلة. اكتب القالب بنفسك في Modelfile:

FROM /home/you/models/my-model-Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|system|>
{{ .System }}<|end|>
{{ end }}{{ if .Prompt }}<|user|>
{{ .Prompt }}<|end|>
{{ end }}<|assistant|>
{{ .Response }}<|end|>"""

PARAMETER stop "<|end|>"

أعد البناء باستخدام ollama create my-model، ثم أرسل مطالبة الاختبار نفسها مرة أخرى. المعلَمة stop هي آلية الأمان لديك؛ فهي تخبر Ollama بإيقاف التوليد عند ظهور تلك السلسلة، وبذلك تنهي مشكلة عدم التوقف حتى أثناء ضبط الغلاف نفسه. إذا استمرت الإجابة لأن أياً من العلامات التي حددتها لا يظهر، فإن سقف num_predict يوقفها عند عدد ثابت من الرموز، بصرف النظر عما يصدره القالب.

يجب أن يكون القالب قالب Go، وليس قالب Jinja. تذكر وثائق Hugging Face ذلك صراحة، وهذا مهم لأن الحقل tokenizer.chat_template في مستودع النموذج الأصلي يحتوي على Jinja. لا يعمل لصق هذا الحقل كما هو. تستخدم صياغة Ollama ثلاثة متغيرات: {{ .System }} لمطالبة النظام، و{{ .Prompt }} لرسالة المستخدم، و{{ .Response }} لإجابة النموذج. ابحث عن علامات الأدوار الفعلية للنموذج في بطاقة النموذج أو في tokenizer_config.json، ثم أعد كتابتها يدوياً باستخدام صياغة Go.

هناك اختصار يوفّر معظم هذا العمل. تشترك نماذج كثيرة في تنسيق مطالبة واحد. إذا كان نموذج آخر في مكتبتك يستخدم التنسيق نفسه، فشغّل ollama show --template عليه وانسخ الناتج.

ملفات template وsystem وparams في مستودع Hugging Face

يوفّر مسار Hugging Face عناصر التحكم نفسها من خلال ملفات في المستودع، بدلاً من تعليمات داخل Modelfile. إذا كنت تملك المستودع أو تنشر quant خاصاً بك، فأضف هذه الملفات إليه، وستستخدمها كل ollama run hf.co/....

• يحتوي ملف باسم template على قالب Go. القاعدة نفسها: استخدم Go، وليس Jinja.
• يحتوي ملف باسم system على system prompt.
• يحتوي ملف باسم params على sampling parameters، ويجب أن يكون بتنسيق JSON.

ملف params بسيط:

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

إذا لم تكن تملك المستودع، فلا يمكنك إضافة هذه الملفات. اسحب النموذج مرة واحدة، وشغّل ollama show --modelfile hf.co/... لتفريغ ما حصلت عليه، ثم احفظ الناتج كملف Modelfile. يشير سطر FROM فيه إلى blob الذي نزّله Ollama مسبقاً، لذلك عدّل السطرين TEMPLATE وPARAMETER، ثم شغّل ollama create لإنشاء نسخة محلية ثابتة دون تنزيل أي شيء مرة أخرى. هذه هي الطريقة القياسية لإصلاح quant معطوب يخص شخصاً آخر.

كيفية استيراد مستودع GGUF خاص

يحتاج المستودع الخاص إلى المفتاح SSH الخاص بـOllama في حسابك على Hugging Face. تستخدم الطريقة الموثّقة لهذا المسار مفتاح SSH بدلاً من رمز API، لذلك لن يفتح المستودعَ رمزٌ تملكه مسبقاً.

اطبع المفتاح العام. على خادم Linux ثُبّت عليه Ollama باستخدام البرنامج النصي الرسمي، تعمل الخدمة بالمستخدم ollama، لذلك يوجد المفتاح في الدليل الرئيسي لهذا المستخدم:

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

إذا شغّلت ollama serve بنفسك كمستخدمك، فسيكون المسار هو ~/.ollama/id_ed25519.pub بدلاً من ذلك. انسخ السطر بالكامل، وافتح إعدادات حسابك على Hugging Face من https://huggingface.co/settings/keys، وأضِفه كمفتاح SSH جديد. يعمل الأمر المعتاد عندئذٍ مع مستودعاتك الخاصة:

ollama run hf.co/{username}/{repository}

إذا استمر السحب في الفشل بعد إضافة المفتاح، فمن المحتمل أنك طبعت الملف الخطأ. ينفّذ الخادم عملية التنزيل ويقدّم مفتاحه الخاص، كما أن الخادم الذي بدأه systemd لا يقرأ ~/.ollama الخاص بمستخدمك، لذلك لا يكون المفتاح الموجود ضمن دليلك الرئيسي هو المفتاح الذي يراه Hugging Face.

هل سيلائم النموذج خادم VPS لديك؟

العامل الحاسم هو حجم الملف على القرص، مضافاً إليه الذاكرة التي تحتاج إليها نافذة السياق. تُحمَّل الأوزان في الذاكرة بحجم يقارب المساحة التي تشغلها في الملف، وتُضاف إليها مساحة السياق التي تزداد مع عدد الرموز المسموح بها. شغّل ollama list لقراءة الحجم الذي سجّله Ollama للنموذج، وقارنه بنتيجة free -h على الخادم، واترك هامشاً لنظام التشغيل ولأي خدمات أخرى يشغّلها الخادم. إذا أردت قراءة هذا الحساب مطبقاً على نموذج حقيقي، يوضح تشغيل Nemotron 3.5 Lightning على خادم VPS الوسم الدقيق المطلوب سحبه، وحجم RAM الذي يحتاج إليه، وما إذا كان خادم CPU-only يواكب الأداء.

السياق هو الجزء الذي ينساه كثيرون. قد يفشل نموذج يُحمَّل ضمن نافذة السياق الافتراضية بعد رفع قيمة num_ctx، لأن مساحة الذاكرة المخصصة له تتناسب مع حجم النافذة التي طلبتها. يوضح ضبط num_ctx وتكلفته من الذاكرة كيفية تقدير الحجم. عندما يتجاوز الإجمالي الذاكرة المتاحة، يكون الحل المعتاد استخدام quant أصغر للنموذج نفسه. وتتناول مقارنة Q4 مع Q8 هذه المفاضلة.

الفشل واضح. على خادم VPS يعمل بـCPU-only، يوقف قاتل نفاد الذاكرة في kernel العملية، ويعرض journalctl -u ollama -n 50 مع dmesg عملية الإيقاف. على خادم مزود بـGPU، يطبع ollama ps عمود PROCESSOR الذي يوضح ما إذا كان النموذج المحمّل قد وُضع في ذاكرة GPU، أو في ذاكرة النظام، أو قُسّم بينهما. يظل النموذج الذي انتقل جزء منه إلى ذاكرة النظام قادراً على الإجابة، لكن ببطء. يحوّل قياس عدد الرموز في الثانية عبارة «ببطء» إلى رقم يمكنك مقارنته بين إصدارات quant المختلفة.

تحقّق مما استوردته

شغّل هذه الأوامر الأربعة بعد أي عملية استيراد، بهذا الترتيب:

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

يثبت ollama list وجود النموذج ويعرض الحجم الذي سجّله Ollama. يثبت ollama show أن Ollama قرأ البيانات الوصفية التي يحتاج إليها من ملف GGUF. يثبت ollama show --modelfile القالب والمعلمات اللذين سيستخدمهما فعلياً. هذا هو الفحص الذي يكشف مشكلة المخرجات غير الصالحة قبل أن يكتشفها المستخدمون. يختبر موجّه الاختبار السلسلة كاملة، لأن النموذج الذي يحتوي على قالب معطوب يفشل حتى مع أقصر طلب. بعد عودة هذا الموجّه بنتيجة سليمة، يصبح الاسم الذي منحته للنموذج هو الاسم نفسه الذي تمرّره إلى أي مكوّن آخر يتصل بواجهة Ollama API، بما في ذلك وكيل برمجي موجّه إلى خادمك الخاص. أزل عملية استيراد معطوبة باستخدام ollama rm my-model ثم أعد إنشاء النموذج. يحذف هذا الأمر نسخة Ollama ويترك المصدر .gguf دون تغيير.

FAQ

هل يمكنني استيراد ملف GGUF إلى Ollama من دون كتابة Modelfile؟

نعم، عندما يكون الملف موجوداً في مستودع على Hugging Face. يسحب ollama run hf.co/{username}/{repository} الملف ويشغّله مباشرة، ويحدد ollama run hf.co/{username}/{repository}:{quantization} quant محدداً. لا تحتاج إلى Modelfile إلا عند استخدام .gguf موجوداً على القرص المحلي، وعندها يمكن أن يتكوّن الملف من السطر الوحيد FROM /path/to/file.gguf، يليه ollama create my-model.

ما نوع quantization الذي ينزّله Ollama عندما لا أحدد نوعاً؟

تذكر وثائق Hugging Face، وفقاً لما كان منشوراً في 10 October 2026، أن Q4_K_M يُستخدم عندما يكون هذا الـquant موجوداً في المستودع، وأن Ollama يختار بخلاف ذلك نوع quant مناسباً موجوداً في المستودع. أضف وسمًا مثل :Q8_0 للتحكم في ذلك. تحقّق مما استلمته فعلياً باستخدام ollama show <model>، الذي يطبع quantization من metadata الملف، وليس من اسمه.

لماذا يكرر النموذج الذي استوردته إجاباته أو لا يتوقف عن التوليد؟

قالب المحادثة لا يطابق النموذج. يختار Ollama القالب تلقائياً من metadata tokenizer.chat_template داخل GGUF. عندما تكون هذه metadata مفقودة أو غير معروفة، يستخدم Ollama غلافاً عاماً، لذلك لا يرى النموذج marker نهاية الدور الذي تدرب عليه. اطبع القالب الحالي باستخدام ollama show --template <model>، ثم أضف كتلة TEMPLATE وسطر PARAMETER stop إلى Modelfile، وشغّل ollama create مرة أخرى. اكتب القالب بصيغة Go template. لن يعمل قالب Jinja من المستودع الأصلي.

هل ينبغي أن أستخدم --quantize مع ملف GGUF نزّلته؟

لا. يعمل --quantize فقط مع عمليات استيراد safetensors أثناء ollama create، ويرفض أي مصدر GGUF، بما في ذلك مصدر FP16 أو FP32، مع ظهور خطأ يطلب منك إجراء quantization لنماذج GGUF قبل استيرادها. إذا كان اسم الملف يتضمن quant مثل Q4_K_M، فهذا يعني أنه حُوِّل مسبقاً. ولا يمكن لإجراء quantization مرة أخرى استعادة الدقة التي فُقدت. يمكن لـ llama-quantize --allow-requantize إعادة كتابته بصيغة Q8_0، لكن النتيجة ستكون أكبر من دون أي تحسن. للحصول على ملف أصغر من GGUF كامل الدقة، شغّل llama-quantize الخاص بـ llama.cpp عليه، ثم استورد الناتج.

كيف أسحب مستودع GGUF خاصاً؟

أضف مفتاح Ollama العام عبر SSH إلى حسابك على Hugging Face. اطبعه باستخدام sudo cat /usr/share/ollama/.ollama/id_ed25519.pub في تثبيت Linux قياسي، أو باستخدام ~/.ollama/id_ed25519.pub عند تشغيل الخادم بصفتك المستخدم الخاص بك. ثم أضفه في صفحة إعدادات مفاتيح SSH لحسابك. بعد ذلك، يعمل ollama run hf.co/{username}/{repository} مع مستودعاتك الخاصة ومع المستودعات الموجودة في مؤسسة تنتمي إليها.