استيراد نموذج 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 مباشرة، ولذلك توجد خطوة التحويل لسبب محدد.

يفترض كل ما يلي أن 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 فقط دون أي شيء آخر، فلن يجد Ollama ما يسحبه، وستحتاج إلى خطوة التحويل الموضحة أدناه.

ما تكميم الذي يختاره Ollama؟

توضح وثائق Ollama على Hugging Face، التي قُرئت في 25 August 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." لذلك، إذا كان المستودع ينشر عشرة إصدارات مكمّمة، فسيحصل Ollama على Q4_K_M. وإذا لم يتضمن المستودع Q4_K_M، فسيختار Ollama إصداراً نيابةً عنك. أعد قراءة تلك الصفحة قبل الاعتماد على هذا السلوك، لأن الإعدادات الافتراضية تتغير.

اطلب إصدار تكميم محدداً بإضافته باعتباره وسمًا:

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

اسم التكميم غير حساس لحالة الأحرف، لذلك يعني :iq3_m و:IQ3_M الشيء نفسه. يمكنك أيضاً تمرير اسم الملف الكامل باعتباره الوسم. وهذا هو الشكل الآمن عندما تكون الأسماء المختصرة في المستودع ملتبسة. يجب أن يطابق الوسم اسم ملف موجود في ذلك المستودع، لذلك افتح تبويب Files and versions واقرأ أسماء الملفات الفعلية قبل كتابة أحدها. يعتمد اختيار التكميم على الذاكرة والجودة، وتشرح الفروق بين 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 البنية، وعدد المعاملات، وطول السياق، ونوع quantization الذي قرأه Ollama من البيانات الوصفية الخاصة بالملف. اقرأ هذه القيم بدلاً من الوثوق باسم الملف، لأن اسم الملف مجرد نص أدخله شخص يدوياً. إذا أجاب النموذج عن مطالبة الاختبار باللغة المعتادة ثم توقف، فقد نجح الاستيراد. وإذا لم يفعل، فانتقل إلى قسم القالب أدناه، لأن القالب هو السبب في معظم الحالات.

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

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

يحتوي ollama create على خيار --quantize، وهو مخصص لحالة واحدة: نموذج مصدر بتنسيق FP16 أو FP32، أي أوزان بدقة كاملة. تذكر وثائق استيراد Ollama أن q8_0، بالإضافة إلى متغيري k-means q4_K_S وq4_K_M، هي الأهداف المتاحة.

ollama create --quantize q4_K_M my-model

لا تمرر هذا الخيار إلى ملف تمت quantization له مسبقاً. إن ملف .gguf الذي يتضمن اسمه Q4_K_M أو Q5_K_S خضع لهذه الخطوة بالفعل، ولا يوجد ما ينفذه الخيار. إن quantization عملية تحويل باتجاه واحد من دقة أعلى إلى دقة أقل، لذلك لا يوجد مسار من Q4 للعودة إلى Q8. إذا كان مصدرك مستودع Hugging Face يحتوي على ملفات .safetensors، فحوّله أولاً باستخدام convert_hf_to_gguf.py من مستودع llama.cpp، وهي الأداة التي تشير إليها وثائق Ollama، ثم استورد ملف 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، وفقاً لقراءتها في 25 August 2026، أن Q4_K_M يُستخدم عندما يكون هذا quant موجوداً في المستودع، وأن Ollama يختار عند عدم وجوده نوع quant مناسباً موجوداً في المستودع. أضف tag مثل :Q8_0 للتحكم في ذلك. تحقّق مما حصلت عليه فعلياً باستخدام ollama show <model>، الذي يطبع quantization من metadata الملف، وليس من اسمه.

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

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

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

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

كيف أسحب مستودع 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} مع مستودعاتك الخاصة ومع المستودعات الموجودة في مؤسسة تنتمي إليها.