GGUF
GGUF تنسيق أحادي الملف يستخدمه llama.cpp لتخزين أوزان نموذج LLM ومقسّم الرموز والبيانات الوصفية، وغالبًا ما تُكمّم مكوناته إلى 4-8 بتات لتناسب الأجهزة المحلية.
GGUF تنسيق ملفات ثنائي لتخزين النماذج التي تعمل على GGML، وهي مكتبة C للمصفوفات التي تقف وراء llama.cpp والأدوات المبنية عليها. ويضم ملف GGUF واحد كل ما يلزم لتشغيل نموذج لغوي كبير (LLM): البنية والمعلمات الفائقة، ومفردات المُرمّز، وقالب المحادثة، وأوزان النموذج، التي تُضغط عادةً باستخدام تكميم النماذج إلى ما بين 2 و8 بتات لكل وزن. وقدّم مشروع llama.cpp تنسيق GGUF في أغسطس 2023 ليحل محل تنسيقات GGML وGGMF وGGJT الأقدم، وأصبح الطريقة القياسية لمشاركة النماذج ذات الأوزان المفتوحة من أجل الاستدلال محلياً على وحدة CPU في حاسوب محمول، أو جهاز Mac بمعالج Apple Silicon، أو GPU استهلاكي، مع وجود آلاف مستودعات GGUF على Hugging Face.
محتويات ملف GGUF#
يحدّد مواصفات GGUF أربعة أجزاء بالترتيب. يحتوي الرأس على بايتات التعرّف GGUF، وإصدار التنسيق (3 حالياً)، وعدد المصفوفات ومدخلات البيانات الوصفية. تليه بيانات وصفية مكتوبة الأنواع بصيغة مفتاح وقيمة، مثل general.architecture وllama.context_length وtokenizer.ggml.tokens وtokenizer.chat_template، التي تضمّن تجزئة الرموز وتنسيق الموجّه في الملف نفسه. ثم يسرد جدول اسم كل مصفوفة وشكلها ونوع بياناتها وإزاحتها، وتأتي بيانات المصفوفات أخيراً، مع حشو افتراضي لمحاذاتها إلى 32 بايت كي يتمكن وقت التشغيل من ربط الملف بالذاكرة وتحميله على الفور تقريباً. وتبحث أدوات القراءة عن البيانات الوصفية باستخدام المفاتيح، لذا يمكن إضافة بنيات وحقول جديدة من دون الإخلال بتوافق الملفات الأقدم.
لكل مصفوفة نوعها الخاص، لذا يمكن للملف الواحد أن يمزج بين درجات الدقة. وتكتب حزمة Python المسماة gguf، التي تُصان في مستودع llama.cpp، التنسيق وتقرأه وتنفّذ عدة أنواع من التكميم:
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")تسرد الحزمة مفتاحي البيانات الوصفية general.architecture وllama.context_length، ثم تعرض 16.0 بتاً لكل وزن مع متوسط خطأ 0.0001 لـF16، و8.5 بتات و0.0045 لـQ8_0، و4.5 بتات و0.0719 لـQ4_0. يخزّن Q8_0 وQ4_0 كتل أوزان من 32 وزناً، مع مقياس FP16 واحد لكل كتلة، وهو مصدر نصف البت الإضافي.
أنواع التكميم#
تنقسم أنواع التكميم في GGUF إلى ثلاثة أجيال. تستخدم تنسيقات الكتل الأصلية، مثل Q4_0 وQ8_0، مقياساً واحداً لكل 32 وزناً. أما تكميم K، مثل Q4_K وQ6_K، فيجمع الكتل ضمن كتل فائقة من 256 وزناً ذات مقاييس مكمّمة، وتشير أسماء الملفات مثل Q4_K_M إلى مزيج يحافظ على أعلى دقة للموترات الأكثر حساسية. وتصل أنواع تكميم I، مثل IQ2_XXS وIQ4_XS، إلى نحو 2–4 بتات لكل وزن، وغالباً ما تستعين بمصفوفة أهمية يحسبها llama-imatrix من نصوص نموذجية كي تحتفظ الأوزان الأكثر تأثيراً بأعلى دقة. وتشمل الإضافات الأحدث MXFP4، وهو تنسيق الفاصلة العائمة ذي 4 بتات الذي استخدمته OpenAI لإصدار gpt-oss. وتُنتج معظم ملفات GGUF المنشورة باستخدام مسار التحويل نفسه:
GGUF مقارنةً بتنسيقات النماذج الأخرى#
- GGML وGGMF وGGJT: خزّنت تنسيقات llama.cpp الأقدم المعلمات الفائقة في قائمة غير محددة الأنواع، من دون حقل للبنية، لذا كان إدراج معلمة يكسر توافق الملفات الموجودة.
- Safetensors: تنسيق Hugging Face لتخزين المصفوفات الخام بأمان، عادةً بدقة كاملة أو نصفية، مع حفظ الإعدادات والمُرمّز في ملفات منفصلة.
- ONNX: يخزّن رسم الحوسبة الكامل مع الأوزان، بحيث تتمكن أي بيئة تشغيل متوافقة مع ONNX من تنفيذ النموذج من دون شيفرة خاصة ببنية معينة.
تشغيل نماذج GGUF#
يشغّل llama.cpp ملفات GGUF من سطر الأوامر أو بصفته llama-server، الذي يتيح API متوافقة مع OpenAI، ويمكنه إسناد أي عدد من الطبقات إلى GPU وتشغيل الباقي على CPU، ما يتيح تشغيل نموذج يتجاوز حجمه ذاكرة GPU. وتشغّل Ollama وLM Studio نماذج GGUF عبر مكتبة نماذج وواجهة دردشة، بينما يعرض Hugging Face Hub بيانات كل ملف GGUF الوصفية وأنواع مصفوفاته في المتصفح. ويحافظ الاستدلال المحلي على الموجّهات داخل الجهاز، وهو أمر مهم لـخصوصية البيانات واستخدامات الذكاء الاصطناعي الطرفي غير المتصلة بالإنترنت. ويمكن لواجهة Ultralytics للنماذج اللغوية الكبيرة استدعاء نموذج GGUF يقدّمه llama-server أو Ollama عبر نقاط نهاية إكمال المحادثة المتوافقة مع OpenAI، بحيث يستطيع مسار YOLO26 أن يطلب من نموذج محلي وصف اكتشافاته من دون إرسال البيانات إلى API سحابية. ويمتد التنسيق إلى ما يتجاوز النماذج اللغوية: إذ تحمّل العقد المخصصة ComfyUI-GGUF نماذج الانتشار المكمّمة، مثل FLUX.1، من ملفات GGUF لتناسب ذاكرة وحدات GPU الاستهلاكية.










