MLX LM على Apple Silicon

يتضمن Libre WebUI مكوّنًا إضافيًا باسم MLX LM (Apple Silicon) لتشغيل نماذج اللغة بتنسيق MLX مباشرةً على جهاز Mac من سلسلة M. يتصل المكوّن بواجهة HTTP API المتوافقة مع OpenAI والمضمّنة في MLX LM.

يفيد هذا المسار عندما تريد استدلال Metal أصليًا من دون تحويل نقطة تحقق MLX إلى نموذج Ollama أو GGUF.

البنية

Libre WebUI in native development mode
  frontend http://localhost:5173
  backend  http://localhost:3001
                  |
                  | OpenAI-compatible chat request
                  v
mlx_lm.server http://127.0.0.1:8081
                  |
                  v
MLX model on Apple Silicon unified memory

اختيار المنفذ 8081 مقصود. يستخدم MLX LM عادةً 8080 افتراضيًا، وهو ما يتعارض مع خادم npx libre-webui المضمّن.

المتطلبات

• جهاز Mac بمعالج Apple Silicon ‏(M1 أو أحدث).
• macOS مع توفر أدوات سطر أوامر Xcode.
• Python 3.10 أو أحدث.
• ذاكرة موحدة كافية للنموذج المختار وذاكرة KV المؤقتة وmacOS.
• تشغيل Libre WebUI أصليًا. مسار التطوير من المصدر هو أبسط إعداد لأن الخادمين يستطيعان استخدام واجهة loopback في Mac.

يشغل نموذج Ternary Bonsai الافتراضي نحو 8.5 GB على القرص ويحتاج إلى ذاكرة أكبر أثناء التشغيل. يستطيع Mac بذاكرة موحدة 16 GB التعامل مع سياقات أقصر، لكن 24 GB أو أكثر توفر هامشًا عمليًا أكبر. استخدم نقطة تحقق MLX أصغر وأضف معرّف مستودعها إلى تعريف منسوخ للمكوّن إذا كانت الذاكرة ضيقة.

تثبيت MLX LM

يحافظ uv على عزل الأمر عن حزم Python في Homebrew:

brew install uv
uv tool install --upgrade mlx-lm
rehash
mlx_lm.server --help

إذا كانت الأداة موجودة بالفعل:

uv tool upgrade mlx-lm
rehash

تتطلب نماذج Qwen 3.5 إصدار mlx-lm 0.30.7 أو أحدث. ويتطلب مثال المستودع الإصدار 0.31.3 أو أحدث.

تشغيل الخادم

لنموذج Ternary Bonsai:

mlx_lm.server \
  --model "prism-ml/Ternary-Bonsai-27B-mlx-2bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --max-tokens 262144 \
  --allowed-origins "http://localhost:5173,http://127.0.0.1:5173"

ينزّل التشغيل الأول النموذج من Hugging Face، وتستخدم العمليات اللاحقة الذاكرة المؤقتة المحلية. يعلن Ternary Bonsai عن 262144 موضعًا كحد أقصى. تتشارك المطالبة والمخرجات المولّدة نافذة السياق، لذلك تقلل المطالبة الطويلة عدد الرموز التي يمكن توليدها حتى مع ضبط سماح الخادم على الحد الأقصى للنموذج.

لنموذج بداية أصغر:

mlx_lm.server \
  --model "mlx-community/Llama-3.2-3B-Instruct-4bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --max-tokens 2048

يحتوي المستودع أيضًا مشغّلًا قابلًا لإعادة الاستخدام:

cd examples/mlx-lm-server
uv run server.py

افحص الأمر الناتج من دون تحميل نموذج:

uv run server.py --dry-run

التحقق من API المتوافق مع OpenAI

تحقق من الصحة واكتشاف النماذج:

curl http://127.0.0.1:8081/health
curl http://127.0.0.1:8081/v1/models

أرسل طلب محادثة بلا تدفق:

curl http://127.0.0.1:8081/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "prism-ml/Ternary-Bonsai-27B-mlx-2bit",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Reply with: MLX is ready."}
    ],
    "temperature": 0.7,
    "top_p": 0.95,
    "max_tokens": 64,
    "stream": false
  }'

يدعم الخادم أيضًا Server-Sent Events متدفقة عندما تكون "stream": true.

توصيل Libre WebUI

من جذر مستودع Libre WebUI:

npm install
npm run dev

افتح http://localhost:5173، ثم:

1. افتح الإعدادات > المكوّنات الإضافية.
2. ابحث عن MLX LM (Apple Silicon).
3. تأكد من أن نقطة النهاية هي http://127.0.0.1:8081/v1/chat/completions.
4. فعّل المكوّن. لا يحتاج MLX المحلي إلى مفتاح API.
5. عُد إلى المحادثة واختر نموذج MLX.

تتضمن قائمة النماذج المضمّنة:

• prism-ml/Ternary-Bonsai-27B-mlx-2bit

يجب أن يطابق النموذج المحدد في Libre WebUI نموذجًا متاحًا لخادم MLX. لاستخدام نقطة تحقق أخرى، صدّر أو انسخ plugins/mlx-lm.json، وأضف معرّف المستودع إلى model_map، واستورد التعريف المعدل من الإعدادات > المكوّنات الإضافية.

إعدادات التوليد

توصيات Ternary Bonsai المنشورة:

الإعداد	القيمة
درجة الحرارة	0.7
Top P	0.95
Top K	20

يرسل Libre WebUI درجة الحرارة وTop P عبر المكوّن. شغّل الخادم باستخدام --top-k 20 لتطبيق توصية Top K:

mlx_lm.server \
  --model "prism-ml/Ternary-Bonsai-27B-mlx-2bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --top-k 20 \
  --max-tokens 262144

Work واستدعاء الأدوات

قد يظهر مكوّن MLX في Work لأنه يستخدم تنسيق المحادثة المتوافق مع OpenAI. لا تختره لـ Work إلا عندما يدعم النموذج وقالب المحادثة الخاص به استدعاءات أدوات على نمط OpenAI بصورة موثوقة. لا يثبت نجاح توليد النص المعتاد في المحادثة أن نقطة التحقق تدعم الأدوات.

تتغير محللات الأدوات وقوالب النماذج بسرعة. إذا أعادت عملية Work استدعاءات أدوات مشوهة، فحدّث mlx-lm واختبر طلب الأداة نفسه مباشرةً مع الخادم، وجرّب نموذجًا توثق بطاقة MLX الخاصة به استخدام الأدوات صراحةً.

شبكة Docker

يوصى بتطوير Libre WebUI أصليًا، إذ لا تستطيع الحاوية الوصول إلى 127.0.0.1 في Mac.

إذا كان Libre WebUI يعمل في Docker:

1. شغّل MLX LM باستخدام --host 0.0.0.0.
2. استخدم عنوان شبكة محلية خاصًا لـ Mac، مثل http://192.168.1.20:8081/v1/chat/completions، نقطة نهاية للمكوّن.
3. اسمح بالمنفذ 8081 على الشبكات المحلية الموثوقة فقط.

لا تكشف mlx_lm.server مباشرةً للإنترنت العام. يصفه المشرفون عليه بأنه خادم محلي بفحوص أمان أساسية فقط. ضع reverse proxy موثّقًا عبر HTTPS أمامه لأي نشر غير محلي.

استكشاف الأخطاء وإصلاحها

Model type qwen3_5 not supported

لا يزال مشغّل قديم مستخدمًا:

rehash
which -a mlx_lm.server
uv tool upgrade mlx-lm

يعرض Libre WebUI النموذج لكن الطلبات تفشل

تحقق مباشرةً من عمل معرّف النموذج نفسه:

curl http://127.0.0.1:8081/v1/models

ثم تأكد من أن نقطة نهاية المكوّن تتضمن /v1/chat/completions.

العنوان مستخدم بالفعل

أبقِ Libre WebUI على منفذه المعتاد وانقل MLX:

mlx_lm.server --model "owner/model" --port 8082

حدّث نقطة نهاية المكوّن إلى http://127.0.0.1:8082/v1/chat/completions.

النموذج بطيء في طلبه الأول

التحميل الأولي وملء المطالبة أغلى من التوليد رمزًا بعد رمز. راقب ضغط الذاكرة في Activity Monitor واختر نموذجًا أصغر أو محادثة أقصر إذا بدأ macOS استخدام swap.

مستندات ذات صلة

• المكوّنات الإضافية
• العمل مع النماذج
• متطلبات الأجهزة
• Work: مساحات العمل المعزولة