شغّل موديلات ذكاء اصطناعي محلية بسرعة على Apple Silicon باستعمال Splash

شنو هو Splash؟

‏Splash هو محرّك للاستدلال المحلي مصمّم خصيصاً لمعالجات Apple silicon. كيخدم نماذج لغوية محسّنة مع وكلاء البرمجة والتطبيقات اللي كيدعمو واجهات OpenAI أو Anthropic. السيرفر كيخدم محلياً فوق Mac واحد وكيعرّض الواجهة ديالو فـ 127.0.0.1:8000.

بخلاف محرّك استدلال عام، Splash كيخصّص النوى، ونموذج المسودة ديال فكّ الترميز التخميني، وتخطيط الأوزان، وخطة الذاكرة لكل نموذج مدعوم. حزم النماذج كتوصّل واجدة للتشغيل، يعني ما محتاجش Xcode ولا سلسلة أدوات ديال المترجم ولا ضبط خاص بالنموذج.

الخصائص الرئيسية

• استدلال محلي فوق Apple silicon: ‏Splash كيشغّل النماذج مباشرة فوق Mac مدعوم.
• التوافق مع OpenAI: كيوفّر Chat Completions فـ /v1/chat/completions وResponses فـ /v1/responses.
• التوافق مع Anthropic: طلبات Anthropic Messages متاحة فـ /v1/messages.
• دعم متقدّم للطلبات: الواجهات كتدعم البث، واستدعاءات الأدوات، ومخرجات JSON Schema، والصور، وملفات PDF المضمّنة.
• الاندماج مع وكلاء البرمجة: ‏Splash فيه أوامر لـ OpenCode وClaude وCodex وHermes.
• تسريع خاص بكل نموذج: كل حزمة نموذج فيها مسودة DFlash 2 لفكّ الترميز التخميني ونوى Metal مبرمجة مسبقاً ومضبوطة على الأبعاد الدقيقة ديال النموذج.
• تخطيط تلقائي للذاكرة: ‏Splash كيحسب السعة ديال السياق، وKV-cache، وحدود الدفعات عند بدء التشغيل، حسب الذاكرة المتاحة لـ Metal.
• فحص التعليمات: نقطتا النهاية /tokenize و/apply-template كيرجّعو معرّفات الرموز أو التعليمات المهيّأة بلا ما يشغّلو الاستدلال.

متطلبات النظام

قبل ما تثبّت Splash، تأكّد بلي النظام ديالك كيستوفي هاد المتطلبات كاملين:

• معالج Apple M3 أو أحدث
• macOS 26.4 أو أحدث
• Homebrew
• على الأقل 36 GB ديال الذاكرة الموحّدة
• من المستحسن 48 GB أو أكثر من الذاكرة الموحّدة

السعة القابلة للاستعمال ديال السياق كتتعلّق بالذاكرة المتاحة. ورغم أن النماذج المدعومة عندها نافذة سياق أصلية حتى لـ 256K، فالنافذة كاملة ما يمكنش تناسب كل Mac.

تثبيت Splash

ثبّت الإصدار المعبّأ عبر مستودع Inco ديال Homebrew:

brew install incoai/tap/splash

ما كايناش شي حاجة لخلق ملف إعدادات. Splash كيستعمل خيارات سطر الأوامر ومتغيّرات البيئة للإعدادات الاختيارية.

بدء تشغيل سيرفر نموذج

خدم حزمة Qwen3.8-27B المحسّنة بهاد الأمر:

splash serve --model incoai/Qwen3.8-27B-Splash

فأول تشغيل، Splash كيحمّل حزمة النموذج وكيحقّق منها، وكيشيّك على الذاكرة المتاحة، وكيصاوب خطة للذاكرة، وكيبدأ السيرفر فـ 127.0.0.1:8000. حزمة Qwen3.8-27B حجم التحميل ديالها 17.4 GB وكتضم النموذج المستهدف بـ 4-bit ومسودة DFlash 2 ديالو.

تسنى حتى يطبع التيرمينال Ready. خلّي داك التيرمينال محلول ما دام كتستعمل النموذج. من بعد تقدر تحل http://127.0.0.1:8000 فالمتصفح باش تدخل لصفحة الدردشة.

ضغط على Ctrl+C فالتيرمينال ديال السيرفر ملي تبغي توقف Splash.

استعمال النموذج البديل

‏Splash كينشر حتى حزمة بحجم 20.9 GB فيها نموذج Qwen3.6-35B-A3B بـ 4-bit ومسودة DFlash 2 ديالو:

splash serve --model incoai/Qwen3.6-35B-A3B-Splash

الخيار --model يقدر يشير لمستودع آخر بصيغة owner/repo فيه حزمة Splash صالحة. نقاط تفتيش MLX وTransformers العادية ما متوافقةش. بالنسبة لمستودع خاص فـ Hugging Face، وفّر HF_TOKEN مناسب.

ربط وكيل برمجة

من بعد ما يعلن السيرفر بلي واجد، حل تيرمينال آخر وشغّل واحد من وكلاء البرمجة المثبّتين والمدعومين:

splash opencode
splash claude
splash codex
splash hermes

شغّل غير الأمر ديال الوكيل اللي بغيتي تستعمل. خاص عملية السيرفر الأصلية تبقى خدامة طول الوقت اللي الوكيل كيبعث فيه الطلبات.

استدعاء OpenAI Chat Completions API

التطبيقات تقدر تستعمل Splash كسيرفر محلي متوافق مع OpenAI. الطلب التالي كيطلب من النموذج الخدّام شرحاً فجملة وحدة:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "incoai/Qwen3.8-27B-Splash",
    "messages": [
      {
        "role": "user",
        "content": "Explain speculative decoding in one sentence."
      }
    ]
  }'

الخاصية model اختيارية. إلا ضمّنتيها، خاص القيمة ديالها تطابق الحزمة اللي خدامة دابا.

اختيار نقطة النهاية المناسبة للواجهة

• استعمل /v1/chat/completions مع عملاء OpenAI Chat Completions.
• استعمل /v1/responses مع عملاء OpenAI Responses.
• استعمل /v1/messages مع عملاء Anthropic Messages.
• استعمل /tokenize باش تحصل على معرّفات الرموز بلا ما تشغّل النموذج.
• استعمل /apply-template باش تفحص التعليمات المهيّأة بلا ما تشغّل الاستدلال.

التحكّم فالتفكير

التفكير مفعّل بشكل افتراضي. باش تعطّلو، زِد "reasoning_effort": "none" لجسم الطلب. Qwen3.8-27B كيدعم حتى low وmedium وxhigh.

{
  "model": "incoai/Qwen3.8-27B-Splash",
  "reasoning_effort": "none",
  "messages": [
    {
      "role": "user",
      "content": "Summarize speculative decoding."
    }
  ]
}

تعطيل التفكير يقدر يكون مفيد إلا كانت المهمة ما كتحتاجش لعملية تفكير مطوّلة. بالنسبة لمهام Qwen3.8-27B اللي كتستافد فعلاً من التفكير، اختار مستوى مدعوم ديال الجهد على حساب طبيعة الخدمة.

ضبط حدود الذاكرة والسياق

Splash كايحدّد الإعدادات الافتراضية المناسبة أوتوماتيكياً، ولكن splash serve كيوفّر خيارات اختيارية باش تتحكّم بشكل أدق:

• --max-memory 28G كايحدّد السقف ديال تخصيصات Metal.
• --max-context 100K كايحدّد نافذة السياق، حتى للحد الأصلي ديال الموديل وهو 256K.
• --max-image-pixels كايتحكّم فالعدد الأقصى ديال البيكسلات من بعد تغيير الحجم لكل صورة. القيمة الافتراضية هي 4,194,304.
• --allowed-host كايسمح باسم إضافي ديال HTTP Host، بحال اسم كيستعملو بروكسي. هاد الخيار يمكن تعاودو أكثر من مرة.
• --no-webui كاايعطّل صفحة الدردشة فالمتصفح.

مثلاً، الأمر التالي كاايحدّد تخصيصات Metal فـ 28 GB وكاايحدّد السياق فـ 100K:

splash serve \
  --model incoai/Qwen3.8-27B-Splash \
  --max-memory 28G \
  --max-context 100K

إلا ما قدرش موديل يدخل فالذاكرة المتاحة، Splash كاايطبع تفصيل ميزانية الذاكرة وكاايوقف بلا ما يشغّل سيرفر ما غاديش يخدم مزيان. تنقيص متطلبات السياق ولا الذاكرة يقدر يعاون، ولكن أوزان الموديل وحالة التشغيل الضرورية خاصها حتى هي تدخل فالذاكرة.

حماية الواجهة البرمجية المحلية

المصادقة معطّلة افتراضياً. تقدر تفرض استعمال مفتاح بتعيين SPLASH_API_KEY فالـ shell اللي كاايشغّل السيرفر:

export SPLASH_API_KEY='replace-with-your-key'
splash serve --model incoai/Qwen3.8-27B-Splash

عيّن نفس متغيّر البيئة فالـ shell المستعمل لتشغيل coding agent اللي كاايديرو Splash:

export SPLASH_API_KEY='replace-with-your-key'
splash opencode

عملاء API يقدرو يرسلو المفتاح على شكل bearer token ولا عبر ترويسة x-api-key. وتقدر حتى تعطي المفتاح مباشرة باستعمال خيار السيرفر --api-key. اختبارات الصحة والاستعداد كاتبقى متاحة للعموم.

نصائح متقدمة

خطّط لاستعمال كاش الموديلات

الحزم اللي كتتهبط كتتخزّن فكاش Hugging Face. تشغيل brew upgrade splash كاايحافظ على هاد الحزم، وروابط الموديلات، وجلسات الوكلاء، وبهذا ترقية المحرّك ما كتحتاجش تمسحهم.

استعمل السماح بالمضيفين مع بروكسي

السيرفر كاايربط محلياً فـ 127.0.0.1:8000. إلا كان بروكسي محلي كاايرسل قيمة مختلفة ديال HTTP Host، زِد داك الاسم باستعمال --allowed-host. عاود الخيار إلا كان خاص قبول أسماء مضيفين متعددة.

عطّل الواجهة الويب للاستعمال عبر API فقط

إلا كان Splash غادي يقدّم الخدمة غير للتطبيقات ولا للوكلاء، شغّلو مع --no-webui. هاد الشي كاايطفّي صفحة الدردشة وكيخلّي نقاط النهاية المدعومة ديال API متاحة.

عاين المطالبات قبل الاستدلال

استعمل /tokenize ملي كتحتاج معرّفات التوكنات، ولا /apply-template ملي كتحتاج تعاين المطالبة النهائية المعرّضة. حيث هاد النهايات ما كااتشغّلش الموديل، فهي مفيدة لتصحيح حجم السياق وتنسيق المطالبة.

جرّب تفريغ الكاش على SSD

كااين تنفيذ تجريبي فـ طلب السحب 3 يقدر يفرّغ KV-cache وحالات GDN على SSD. بنِ داك الفرع وشغّل السيرفر مع --max-cache-disk 8G باش تفعّلو. هاد الشي يقدر يحافظ على البوادئ القابلة لإعادة الاستعمال ملي كتكون RAM محدودة، وينقص من الخدمة المكررة ديال prefill.

ميزة التفريغ على SSD تجريبية وماشي جزء من سير العمل القياسي للحزم المشروح فالبداية السريعة.

فهم أداء Splash

Splash كاايزيد فالسرعة حيث كاايتخصّص معظم مكوّنات مكدّس الاستدلال لكل موديل. فك الترميز التخميني هو مسار فك الترميز القياسي، وماشي وضع اختياري. مسودة DFlash 2 مخصّصة للموديل كااتقترح مجموعات ديال التوكنات، ومن بعد الموديل المستهدف كااايتحقق منها بالتوازي.

نوى Metal المدموجة ديالو كااايتترجم للمقاسات الدقيقة ديال الموديل، وكااايتقراو الأوزان المعبّأة بطريقة خاصة من القرص بلا نسخة إضافية. وعند الانطلاق، Splash كاايحسب حتى هو حدود السياق والكاش والدفعات حسب الجهاز الحالي.

حسب قياسات المشروع على M5 Pro بمعالج رسومي من 16 نواة وذاكرة بحجم 48 GB، وصل Qwen3.8-27B لـ 74 توكن فالثانية ففك ترميز المطالبات القصيرة، ورجّع أول توكن فـ 282 ms ملي عاود تشغيل سياق مخزّن بحجم 32K. النتائج كتتبدّل على حساب الموديل، والمطالبة، والتزامن، والعتاد، وظروف الذاكرة. مقالة إطلاق Splash كاتوثّق طريقة القياس والمقارنات.

الخلاصة

Splash كاايقدّم طريقة مبسّطة لتشغيل موديلات مختارة ومحسّنة بزاف على أجهزة Apple silicon الحديثة. ثبّتو باستعمال Homebrew، وشغّل حزمة موديل متوافقة مع Splash، ومن بعد ربط بها عبر المتصفح، ولا coding agent مدعوم، ولا API متوافقة مع OpenAI أو Anthropic. الإعدادات الافتراضية الأوتوماتيكية كااتسهّل البداية، بينما خيارات الذاكرة والسياق والأمان والمضيف والواجهة كااتسمح بنشرات أكثر تحكّماً.