شغّل GLM-5.3-Flash على جوج DGX Sparks باستعمال TensorFold

شنو كيدير هاد المشروع

هاد المشروع كيشغّل GLM-5.3-Flash على جوج ديال أنظمة NVIDIA DGX Spark باستعمال TensorFold v0.5.0. كل Spark كيشغّل رتبة موزعة وحدة، بينما الـSpark اللول كيوفّر حتى API ديال HTTP متوافق مع OpenAI.

الإعداد الافتراضي كيدعم أربعة ديال الطلبات فآن واحد، ونافذة سياق قصوى فيها 1,048,576 توكن لكل طلب، وإدخال الصور والفيديو، واستدعاء الأدوات، والإخراج المنظّم، ونقاط نهاية للتجزئة، ومقاييس Prometheus. التواصل بين النظامين كيدوز عبر وصلة RoCE مباشرة ديال ConnectX-7.

النشر كيستعمل نقطة التحقق Mia-AiLab GLM-5.3-Flash EXL3. الخبراء الموجّهين مخزنين تقريباً بأربعة بيتات لكل وزن، بينما أوزان نقطة التحقق الأخرى بصيغة BF16. نقطة التحقق كاملة الحجم ديالها تقريباً 176 GB.

أهم الميزات

• API متوافق مع OpenAI: استعمل نقاط نهاية إكمال المحادثات، والإكمالات، والاستجابات، ولائحة النماذج.
• سياق طويل: حتى لـ1,048,576 توكن ديال الطلب والجواب لطلب فردي مع إعداد FP8 KV الافتراضي.
• استدلال متزامن: فكّ ترميز حتى لأربعة طلبات مع بعضياتها باستعمال DFlash2 drafter الافتراضي.
• مجمع كاش مشترك: المحادثات المتزامنة كتستعمل مجمع FP8 KV واحد فيه تقريباً بين 2.1 و2.7 مليون توكن، على حساب الذاكرة المتاحة.
• طلبات متعددة الوسائط: صيفط مدخلات JPEG وPNG وWebP وMP4 وWebM وMOV وMKV وفيديوهات أخرى قابلة للفك باستعمال FFmpeg.
• التحكم فالتفكير: اختار مجهود تفكير منخفض أو عالٍ أو أقصى، ولا عطّل التفكير فطلب معيّن.
• ميزات الوكلاء: استعمل استدعاء الأدوات والإخراجات المنظّمة المقيّدة بالمخطط عبر xgrammar.
• نقاط نهاية تشغيلية: راقب الحالة، وحوّل المدخلات إلى توكنات أو رجّعها من التوكنات، وجمّع مقاييس Prometheus.
• نشر أوتوماتيكي: أمر واحد كيحضّر الجهازين، وكيشغّل الرتبتين، وكيجري اختباراً سريعاً، وكيعطي عنوان الـAPI.

متطلبات العتاد والبرمجيات

خاصك جوج DGX Sparks، أو جوج أنظمة GB10، كل واحد فيهم فيه 128 GB ديال الذاكرة الموحّدة. خاص تقريباً 110 GiB تكون خالية فكل GPU ملي كيبدا السيرفر، لذلك حبّس أولاً أي أحمال كبيرة أخرى على GPU.

متطلبات الشبكة

ربط منافذ ConnectX-7 بكابل QSFP، وعطي لكل طرف عنوان IPv4 فـنفس الشبكة الفرعية الخاصة. مثلاً، يقدر الـhead يستعمل 192.0.2.1/24 والـworker يستعمل 192.0.2.2/24. خاص العناوين تكون قابلة للوصول باستعمال ping، وخاص يكون GID ديال RoCE v2 متوفر.

إلى كانو جوج منافذ CX7 مربوطين ومعطّيين العناوين، يقدر المشروع يستعمل الجوج ديال المسارات. حسب القياسات اللي فـREADME، all-gather ديال جزء من الطلب كيكون تقريباً أسرع بـ1.8 مرة باستعمال جوج المسارات.

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

• ولوج SSH باستعمال المفاتيح من Spark ديال الـhead للـworker.
• Docker مع وقت تشغيل حاويات NVIDIA فالجوج ديال الأنظمة.
• الحساب ديالك يكون فمجموعة docker فالجوج ديال الأنظمة.
• يكون rsync منصّب فالجوج ديال الأنظمة.
• تقريباً 205 GB ديال المساحة فالقرص فكل Spark.
• اختيارياً، CLI ديال Hugging Face hf وتوكن ديال Hugging Face فالـhead.

صايب مفتاح SSH إلا كان ضروري، ونسخو للـworker، وتأكد من الولوج بلا تفاعل:

ssh-keygen -t ed25519
ssh-copy-id user@192.0.2.2
ssh -o BatchMode=yes user@192.0.2.2 true

الـDFlash2 drafter مرخّص برخصة CC BY-NC-ND 4.0 ومخصّص للاستعمال غير التجاري. اختار MTP drafter ديال نقطة التحقق قبل أول إعداد إلا بغيتي تتفادى تحميل أو استعمال DFlash2.

تنصيب المشروع وإعداده

1. كلون المستودع فالـhead

git clone https://github.com/MiaAI-Lab/GLM-5.3-Flash-EXL3-2x-DGX-Sparks-TensorFold.git
cd GLM-5.3-Flash-EXL3-2x-DGX-Sparks-TensorFold
cp scripts/local.sh.example scripts/local.sh

الـworker ما محتاجش checkout ديالو. سكريبتات الإعداد كتنقل صورة الحاوية والملفات الضرورية ديال النموذج من الـhead.

2. حدّد عنوان الـworker

عدّل scripts/local.sh وخلي WORKER كيشير لهدف SSH ديال الـworker:

WORKER=user@192.0.2.2

الرتب الموزعة كتتواصل عبر المسار المستعمل للوصول للـworker. إلا كان WORKER كيشير لعنوان فشبكة أخرى، عيّن FABRIC_PEER لعنوان CX7 الخاص بالـworker:

WORKER=user@worker-hostname
FABRIC_PEER=192.0.2.2

3. اختار drafter إلا كان ضروري

الافتراضي هو DRAFTER=dflash2، وكيتيح حتى لأربعة طلبات متزامنة وكيعطي تحسناً مقاساً ففك الترميز تقريباً بين 5 و10 فالمئة. باش تستعمل MTP head ديال نقطة التحقق بلاصتو، عيّنو قبل أول تشغيل:

DRAFTER=mtp

MTP كيتفادى رخصة وتحميل DFlash2، ولكن افتراضياً كيخدم طلب واحد فكل مرة.

4. شغّل الرتبتين بجوج

./start.sh

فأول تشغيل، السكريبت كيتحقق من النظامين بجوج، وكيجيب أو كيبني صورة الحاوية اللي الحجم ديالها تقريباً 25 GB، وكيحمّل نقطة التحقق والـdrafter فالـhead، وكيصيفطهم للـworker، وكيكمبايل نوى CUDA داخل ~/.cache/tensorfold-glm53.

التشغيلات اللاحقة كتحتاج غالباً بين جوج وستة دقايق لتحميل تقريباً 80 GiB من الأوزان على كل Spark. المشغّل كيتبع سجل الرتبة 0، وكيعرض تقدم التحميل، وكيجري اختباراً سريعاً موزعاً، وكيطبع نقطة نهاية مباشرة على المنفذ 8888.

باش تجهّز النظامين بجوج بلا ما تشغّل الـAPI، نفّذ:

scripts/prepare.sh

باش تفرض إعادة بناء نظيفة لصورة الحاوية، استعمل:

scripts/prepare.sh --rebuild

دير أول طلب ديالك للـ API

المعرّف الافتراضي ديال الموديل هو GLM-5.3-Flash-EXL3، والـ URL الأساسي هو http://<head-address>:8888/v1.

عرض الموديلات المتاحة

curl -s http://<head-address>:8888/v1/models

صيفط طلب إكمال محادثة

curl -s http://<head-address>:8888/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "GLM-5.3-Flash-EXL3",
    "messages": [
      {"role": "user", "content": "Write a Python fibonacci function."}
    ],
    "max_tokens": 2000
  }'

الموديل كيفكّر قبل ما يجاوب بشكل افتراضي. الاستدلال كيرجع فـ reasoning_content، والجواب النهائي كيبان فـ content. خصّص عدد كافي ديال توكنات الخرج للجوج المراحل. إلا كان content خاوي، فالغالب الموديل صرف الحصة ديال الخرج فالتفكير.

التحكم فالتفكير وأخذ العينات

عيّن reasoning_effort على low أو high أو max. استعمل none باش تطلب جواب مباشر بلا تفكير:

curl -s http://<head-address>:8888/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "GLM-5.3-Flash-EXL3",
    "messages": [{"role": "user", "content": "Summarize TCP in two sentences."}],
    "reasoning_effort": "low",
    "temperature": 0,
    "max_tokens": 1000
  }'

الـ API كيدعم حتى temperature وtop_p وtop_k وmin_p وseed. إلا ما عيّنتيش seed صراحة، الـ sampler كيستخرج المفتاح ديالو من الـ prompt، وبهذا الطلبات المتطابقة كتعطي نفس الجواب.

صيفط الصور والفيديوهات

برج الرؤية ديال GLM ككيخدم فالرتبة 0 بشكل افتراضي. الصور والفيديوهات كيتقدمو كأجزاء ديال المحتوى على طريقة OpenAI داخل رسالة ديال المستخدم.

حلّل صورة محلية

IMG=$(base64 -w0 photo.jpg)
curl -s http://<head-address>:8888/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "GLM-5.3-Flash-EXL3",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,'"$IMG"'"}},
        {"type": "text", "text": "What is in this picture?"}
      ]
    }],
    "max_tokens": 2000
  }'

بشكل افتراضي، السيرفر كيقبل الوسائط عبر data URLs. عيّن VISION_URLS=1 إلا بغيتي السيرفر حتى هو يجيب URLs عمومية ديال HTTPS.

حدود الوسائط المدعومة

• حتى لـ 50 صورة فالطلب الواحد، بحد أقصى 10 MB لكل صورة و64 MB لمجموع بيانات الصور.
• حتى لـ 4 فيديوهات فالطلب الواحد، بحد أقصى 64 MB لكل فيديو و96 MB لمجموع بيانات الفيديو.
• كل فيديو يقدر يوصل حتى لساعة وحدة ديال التسجيل.
• جسم الطلب يقدر يوصل حتى لـ 96 MiB، وكيخلي تقريباً 70 MB للوسائط المشفّرة بـ base64.
• الصورة الواحدة كتاخذ على الأكثر 2,048 توكن، وجميع الصور فطلب واحد كيتقاسمو حصة افتراضية قدرها 16,384 توكن.
• أخذ عينات الفيديو مضبوط افتراضياً على جوج إطارات فالثانية وبحد أقصى 128 إطار فالمقطع.

بالنسبة للفيديو، بدّل جزء محتوى الصورة بجزء video_url فيه data URL بحال data:video/mp4;base64,....

إلا كنت محتاج غير للنص، عيّن VISION=0. هاد الشي كيتفادى تحميل برج الرؤية وكيخلّي تقريباً 1.8 GiB إضافية فالذاكرة ديال الرتبة 0 لاستعمال الكاش.

شغّل السيرفر وراقبو

عاود التشغيل ووقف الخدمة

./start.sh restart
./stop.sh

خاص تعاود التشغيل من بعد ما تبدّل الإعدادات الدائمة. إيقاف الخدمة كيحرّر ذاكرة الـ GPU فالجوج ديال الماكينات.

فحص السجلات

docker logs -f glm53-flash-tf
ssh <worker> docker logs -f glm53-flash-tf

الأمر الأول كيتبع الرتبة 0 فـ head. والثاني كيتبع الرتبة 1، وكيكون مفيد بزاف ملي كيخرج الـ worker بشكل مفاجئ.

فحص الصحة والمقاييس

curl -s http://<head-address>:8888/health
curl -s http://<head-address>:8888/metrics

استجابة الصحة كتعطي الحالة واش مشغول، والـ streams النشيطة، وسعة الـ pool المشترك، بما فيها pool_tokens وpool_free_tokens. نقطة النهاية ديال المقاييس كتكشف مقاييس Prometheus ديال الطلبات، والكمون، والوقت حتى لأول توكن، والصحة.

فهم السياق والذاكرة المشتركة KV

الإعداد الافتراضي كيستعمل كاش KV بصيغة FP8 وكيعطي لكل طلب نافذة قصوى قدرها 1,048,576 توكن. أربعة طلبات كيتقاسمو pool مقاس بـ 2,684,928 توكن فواحد التشغيل الموثّق، ولكن السعة الدقيقة كتعتمد على الذاكرة الحرة.

طلب واحد يقدر يستعمل النافذة كاملة، ولكن جميع المحادثات النشيطة والمحتافظ بها خاصها تدخل فـ pool المشترك. مثلاً، جوج محادثات يقدرو يقربو كل وحدة لمليون توكن، بينما المحادثات الأقصر والمتزامنة تقدر تتقاسم السعة الباقية. الطلب اللي ما يقدرش يتحط دابا كيتسنى حتى تسالي طلبات أخرى.

استعمل CONTEXT=0 باش تحسب أكبر نافذة كتدخل، ولكن رد بالك: بهاد الطريقة ما كاتبقاش ذاكرة للاحتفاظ بحالات الـ prompt ديال المحادثات الأخرى. التحويل لتخزين KV دقيق بصيغة BF16 كينقص النافذة المتاحة بشكل كبير.

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

إعدادات متقدمة

تقدر تعطي الإعدادات عبر البيئة، أو scripts/local.sh، أو ملف .env حدّ start.sh. ترتيب الأولوية هو البيئة، من بعدها scripts/local.sh، من بعدها .env، وفالأخير الإعدادات الافتراضية ديال المستودع.

بدّل التوازي فتشغيل واحد

PARALLEL=2 ./start.sh restart

يمكن تعيين PARALLEL من واحد حتى لأربعة ملي كيكون DFlash2 مفعّل. MTP كيبدا افتراضياً بطلب واحد فكل مرة.

بدّل نافذة السياق

CONTEXT=524288 ./start.sh restart

السياق الأصغر يقدر ينقص الضغط على الكاش ملي ما كتكونش نافذة المليون توكن كاملة ضرورية.

كبّر الحدّ الافتراضي للإخراج

./start.sh restart --max-tokens 16384

المعاملات الإضافية ديال سطر الأوامر كتمشي لـ tensorfold serve من بعد الإعدادات الافتراضية المكوّنة، وبالتالي كتكون هي الغالبة. شغّل ./start.sh --help باش تشوف المعاملات المدعومة.

فرض التحضير أو تخطّاه

PREPARE=1 ./start.sh restart
PREPARE=0 ./start.sh restart

الأمر اللول كيفرض فحص الإعدادات وعملية التحضير. الثاني كيتخطّاها.

استعمل إعادة استعمال البرومبت بفعالية

إعادة استعمال البادئة المشتركة مفعّلة افتراضياً بـ SHARED_PREFIX=1. البرومبتات المتكررة ديال النظام والبرومبتات المتطابقة اللي باقية يقدرو يكملو من الحالة المخزّنة فالكاش بلا ما يتعاودو يتجلبو مسبقاً. فالقِياسات الموثّقة، برومبت متكرر فيه 64K توكن هبط من 34 ثانية لأقل من 0.07 ثانية، بينما إعادة استعمال برومبت نظام فيه 7.9K توكن نقصات وقت البدء من 4.24 ثانية لـ 0.13 ثانية.

اختار دقة الكاش والأوزان

• KV=fp8 هي الافتراضية وكتفعّل أكبر نافذة سياق.
• KV=bf16 كتستعمل تخزين دقيق للكاش، ولكن كتقصّر بزاف النافذة المتاحة.
• DENSE=q4 هي الافتراضية لمكوّنات نقاط التحقق الكثيفة.
• DENSE=fp8 وDENSE=bf16 بدائل متاحة، وكل وحدة عندها تأثير مختلف على الذاكرة.

قدرات إضافية ديال API

بالإضافة لإكمالات الدردشة، السيرفر كيوفّر /v1/completions و/v1/responses و/v1/models و/tokenize و/detokenize و/health و/metrics. مسارات تقسيم التوكنات متاحة حتى هي تحت /v1/. السيرفر ما كيوفّرش endpoint متوافق مع Anthropic من نوع /v1/messages.

استدعاء الأدوات كيدعم tools وtool_calls فالبث، والمعاملات كتكون مكتوبة حسب الـ schema المعطى. التوليد المهيكل كيدعم json_object وjson_schema وJSON الموجّه والتعابير النمطية والاختيارات والقواعد النحوية وحقول أخرى ديال الإخراج المهيكل، وكيتم فرضها عبر xgrammar من بعد ما كيسالي الاستدلال.

إلا تجاوز مجموع البرومبت وmax_tokens نافذة السياق المكوّنة، API كيرجع HTTP 400 مع رمز الخطأ على طريقة OpenAI: context_length_exceeded.

حلّ مشاكل البدء الشائعة

• الذاكرة ما كافياش: إلا بان فالبداية بلي غير عدد محدود من GiB متاح، شوف docker ps ووقّف خدامات GPU الأخرى فالجوج ديال Sparks.
• ما كاينش جهاز ولا مسار RoCE: تأكد بلي واجهات CX7 عندها عناوين IPv4 باستعمال ip -4 addr. إلا كان SSH كيستعمل شبكة أخرى، عيّن FABRIC_PEER بعنوان CX7 ديال العامل.
• كاش العامل ما قابلش للكتابة: صحّح المالك ديال كاش Hugging Face عند العامل إلا خلّاه container سابق مملوك لـ root.
• رتبة وحدة خرجات: راجع السجلات فالجهازين بجوج. المشغّل كيوقف عادةً الرتبة الباقية إلا فشل شي طرف.
• الإعدادات تبدلات: من بعد ما تبدّل patches أو TensorFold أو الصورة الأساسية أو شي مدخلات مرتبطة بالبناء، شغّل scripts/prepare.sh --rebuild.

توقعات الأداء

فالقِياسات الافتراضية ديال README بجوج ديال Sparks، فكّ النصوص تراوح من 60.4 توكن فالثانية لطلب واحد حتى لـ 108.8 توكن فالثانية كمجموع لأربعة طلبات متزامنة. التوليد المهيكل تراوح من 114.7 حتى 227.9 توكن فالثانية كمجموع. الـ Prefill كان تقريباً 1,952 توكن فالثانية لبرومبت فيه 8,219 توكن، و1,015 توكن فالثانية لبرومبت needle-in-a-haystack فيه 981,841 توكن، فين تلقات الإبرة.

تقاسات هاد الأرقام باستعمال أربعة streams، وكاش KV بـ FP8، وأوزان كثيفة بأربع بتات، وDFlash2 وcopy drafts، والرؤية مفعّلة، وسرعة GPU محدودة فـ 2,200 MHz. اعتابرها نتائج مرجعية لهاد الإعداد، وماشي ضمانات لكل بيئة.

الخلاصة

هاد النشر كيجمع إعداد معقّد ديال TensorFold بجوج العقد وكيحطّو ورا سير عمل عملي للبدء وAPI متوافق مع OpenAI. منين كيكون رابط CX7 وولوج SSH ووقت تشغيل Docker والتخزين وعنوان العامل واجدين، ./start.sh كيتكلف بالتحضير والإطلاق الموزّع والتحقق والتشغيل. من تما، تقدر تستعمل عملاء API عاديين وتضبط التزامن والسياق والاستدلال والحدود متعددة الوسائط وسلوك الذاكرة حسب الخدمة ديالك.