شغّل Qwen3.8-Flash-Next على Colab A100 بواجهة API متوافقة مع OpenAI

شنو كيدير collabosm

collabosm كيشغّل Qwen3.8-Flash-Next فوق instance وحدة ديال Colab A100 80 GB High-RAM. الموديل هو mixture-of-experts بقدرة 125B-A6B، بهندسة هجينة كتجمع بين Gated-DeltaNet وfull-attention، وبطول سياق أصلي كيوصل لـ 262,144 token.

المشروع كيوفّر ولا كيرجّع Colab VM، كينصّب runtime مثبت ديال ExLlamaV3، كيحمّل أوزان الموديل المثبتة، كيشغّل HTTP server متوافق مع OpenAI، وكيكشفو عبر Cloudflare tunnel. الكليان كيتاصلو بعنوان tunnel تحت /v1 باستعمال bearer key مولّد.

ExLlamaV3 هو محرك الاستدلال الوحيد اللي كيستعملو المستودع. أما API server براسو فمطبق من طرف collabosm حيت ExLlamaV3 ما فيهش HTTP server.

الميزات الرئيسية

• تشغيل فوق GPU وحدة: كيشغّل الأوزان اللي كتاخذ تقريباً 63.6 GiB من VRAM فوق runtime وحدة A100 80 GB High-RAM.
• واجهات متوافقة مع OpenAI: كيدعم بجوج /v1/chat/completions و/v1/responses، بما فيها streaming تدريجي.
• استرجاع آمن لـ Colab: كيربط من جديد التخصيصات اليتيمة عوض ما يثق فالسجلات المحلية المؤقتة ديال جلسات CLI ولا ينشئ VMs مكررة كتتحسب عليها الفلوس.
• التحقق من العتاد: كيرفض وكيوقف A100 غير متوافق بقدرة 40 GB قبل ما يحمّل الموديل.
• تخزين مؤقت دائم للـ prompt: كيخلي ExLlamaV3 Generator واحد خدام لمدة طويلة باش يبقاو page table وcache ديال pinned-RAM محافظين على الحالة بين الطلبات.
• تصميم cache بجوج مستويات: كيجمع بين سعة GPU KV وcache اختياري فـ pinned host-RAM باش يرجّع بسرعة المحادثات اللي ما خداماش.
• اختبار البروتوكول محلياً: كيوفّر fake engine كيجرّب HTTP handler الحقيقي بلا GPU ولا أوزان الموديل.
• الرؤية اختيارية: يقدر يحمّل مكوّن الرؤية ديال الموديل ويقبل مدخلات الصور المحمية بضوابط.
• كليان وواجهة محلية: فيه محادثة من terminal، وواجهة فالمتصفح، وصفحات الحالة، ومقاييس الأداء المستخرجة من stream، وproxy كيخلي المفتاح upstream مخبي على المتصفح.

القياسات اللي بلغ عليها المشروع كتشمل حتى لـ 3,882 token فالثانية فـ prefill بالنسبة لـ prompt ديال 30K مع GCS=8192، و97.4 token فالثانية فـ decode مع MTP depth 4 وسياق 30K، و90.1 token فالثانية مع سياق 114K. راجع docs/MEASURED.md باش تعرف المصدر والتحفظات، وما تعتبرش هاد الأرقام ضمانات.

المتطلبات وتخطيط السعة

قبل ما تبدا، تأكد باللي البيئة ديالك كتستوفي جميع المتطلبات التالية:

• خطة Colab قادرة تخصص A100.
• شكل الآلة HIGH_RAM. A100 عادية بقدرة 40 GB ما تقدرش تحمّل هاد الموديل.
• حوالي 110 GiB من مساحة القرص فـ Colab للأوزان.
• أداة سطر الأوامر ديال Google Colab، منصّبة باستعمال uv tool install google-colab-cli.
• اختيارياً، GitHub CLI إلا كنت ناوي تدير fork ولا push للمستودع.

uv tool install google-colab-cli

متطلب High-RAM إجباري. ما تحددش البطاقة المناسبة بالبحث فمخرجات العتاد على “80”، حيت A100 تقدر تبيّن compute capability ديال sm_80 حتى إلا كانت فيها غير 40 GB من VRAM. collabosm كيقارن قيمة vram_GiB المبلّغ عليها.

المشروع تطوّر فوق فئة Colab Pro فيها تقريباً 200 وحدة حساب فالشهر. التكلفة المقاسة ديال A100 High-RAM كانت 7.52 CU فالساعة، أي تقريباً 0.75 دولار فالساعة فـ البيئة الموثقة. الأثمنة وتوفر التخصيصات يقدرو يتبدلو بشكل مستقل على المستودع.

بدا السيرفر

1. حلّ مجلد المستودع

نزّل ولا دير clone لمستودع collabosm، ومن بعد شغّل الأوامر التالية من المجلد الجذر ديالو. السكريبتات كتتوقع مسارات نسبية للمستودع بحال scripts/up.sh وscripts/bootstrap.sh وscripts/serve.sh.

2. وفّر البيئة، دير bootstrap وشغّل الخدمة

bash scripts/up.sh

هاد الأمر الواحد كيرجّع تخصيص موجود إلا كان ممكن ولا كينشئ تخصيص جديد High-RAM، كيرفع المشروع، كينصّب runtime المثبت، كيحمّل الأوزان المثبتة، كيشغّل API، كيطلق Cloudflare tunnel، وكيستنى حتى ينجح health check.

الاستدعاء الناجح كيخرج بالحالة 0 غير من بعد ما يكونو API وعنوان tunnel العمومي واجدين بجوج. الأمر كيطبع عنوان tunnel ومفتاح API. المفتاح كيتخزن حتى هو فـ VM فالمسار /content/api-key.txt.

الـ runtime كيتختار من wheel مسبق البناء ومثبت ديال ExLlamaV3، متوافق مع بيئة Colab ديال Python وPyTorch وCUDA. الأوزان كيتجابو من Hugging Face من revision مثبت. إلا تعطل مسار تنزيل Xet، فالـ README كيشير لـ HF_HUB_DISABLE_XET=1 كحل بديل.

3. سجّل إعدادات الاتصال

base_url = https://<host>.trycloudflare.com/v1
api_key  = <printed API key>
model    = qwen3.8-flash-next-exl3

اسم المضيف ديال quick tunnel يقدر يتبدل بين عمليات التشغيل. باش تستعمل اسم مضيف مستقر، كوّن Cloudflare tunnel مسمّى باستعمال TUNNEL_TOKEN وربطو مع PUBLIC_URL ديال العنوان اللي كيبان فمخرجات الحالة.

4. عاين الإعدادات اللي خدامة

طلب GET /v1/status كيبين المعاملات اللي توصلات بها العملية الخدامة فعلياً، بما فيها إعدادات cache، ومعاملات التشغيل، ومدة الخدمة، وتوفر الرؤية، وسياسة إدخال الصور.

المستودع كينبّه باللي الإعدادات الافتراضية الحالية ما تحققوش كاملين مجموعين. راجع endpoint ديال الحالة المباشرة وdocs/MEASURED.md قبل ما تفترض أن تركيبة معينة متحقق منها.

كوّن caches والتوليد

كاع كونطرولات ديال الإقلاع الرئيسية هما متغيّرات ديال البيئة كيدوزو لـ scripts/up.sh. مثال:

SESSION=mybox CACHE_SIZE=524288 CPU_CACHE_GB=8 bash scripts/up.sh

• SESSION: سميّة السيشن المحلية؛ الافتراضي هو collabosm.
• CACHE_SIZE: مجموع ديال توكنات KV بين جميع الجوبات؛ الافتراضي 500224 وخصّو يكون من مضاعفات 256.
• CACHE_QUANT: عرض البِتّات ديال كاش KV؛ الافتراضي 4، والقيم من 2 حتى لـ 8 مسموحة.
• CPU_CACHE_GB: كاش من المستوى الثاني لصفحات KV فـ RAM محجوزة؛ الافتراضي 32 GiB، و0 كيعطّلو.
• RECURRENT_CACHE_GB: تخزين فـ RAM ديال الجهاز لـ checkpoints ديال Gated-DeltaNet؛ الافتراضي 24 GiB.
• GCS: حجم chunk ديال المولّد وكونترول مهم لأداء prefill؛ الافتراضي 8192.
• NDT: العمق ديال draft فالتنبؤ متعدد التوكنات؛ الافتراضي 4.
• RUNTIME: wheel للـ runtime الجاهز مسبقاً، أو source لإعداد مبني من السورس.
• TUNNEL_TOKEN: توكن اختياري ديال tunnel مسمّى.

الكاشات ديال RAM ديال الجهاز ماشي سعة مجانية. الكاش الافتراضي ديال CPU كيتخصّص كامل كذاكرة محجوزة، والكاش recurrent حتى هو كيستهلك كمية مهمة من RAM. وكيخدمو بجوج مع جدول n-gram الموثّق فالمستودع، اللي الحجم ديالو 36.4 GiB.

المستوى ديال RAM المحجوزة كيسرّع الرجوع للمحادثات الخاملة اللي تحيدات صفحاتها اللي ما بقاتش مستعملة. ما كيزيدش عدد السياقات اللي كتخدم فـ نفس الوقت، حيت الصفحات الحيّة ما يمكنش تتحيد بحال إلا RAM ديال الجهاز swap عادي.

عيّط لـ API المتوافق مع OpenAI

عرض الموديل

curl https://<host>.trycloudflare.com/v1/models \
  -H "Authorization: Bearer <api-key>"

الـ endpoint كيرجّع معرّف موديل واحد: qwen3.8-flash-next-exl3. المصادقة ضرورية لهاد المسار ديال API، بينما /health ما كيتطلبش المصادقة وكيرجّع ok عادي.

إنشاء إكمال ديال محادثة

curl https://<host>.trycloudflare.com/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-flash-next-exl3",
    "messages": [
      {"role": "user", "content": "Reply with exactly: pong"}
    ],
    "max_tokens": 16
  }'

واجهة المحادثة كترجّع المحتوى تحت choices[].message.content، وسبب نهاية stop ولا length، ومعلومات الاستعمال اللي تقدر تشمل توكنات الـ prompt المخزّنة فالكاش.

بثّ الإكمال

عيّن stream لـ true باش توصلك Server-Sent Events بينما الموديل كيديكود. فإكمالات المحادثة، البث كيسالي بـ [DONE]. تعيين stream_options.include_usage كيطلب بيانات الاستعمال فالرد المبثوث.

{
  "model": "qwen3.8-flash-next-exl3",
  "messages": [{"role": "user", "content": "Explain prompt caching briefly."}],
  "stream": true,
  "stream_options": {"include_usage": true},
  "max_completion_tokens": 200
}

الـ endpoint /v1/responses حتى هو كيدعم البث. تسلسل الأحداث ديالو كيشمل أحداث الإنشاء، والتقدّم، وعنصر الإخراج، وجزء المحتوى، وفرق النص، والإكمال، والرد النهائي. كل حدث مبثوث فيه sequence_number تصاعدي، بينما الـ deltas فيها فهارس العنصر والمحتوى اللي كيحتاجها العميل باش يربطهم بالطريقة الصحيحة.

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

التفكير معطّل افتراضياً باش يبقى متوافق مع عملاء المحادثة العاديين. فعّلو بـ enable_thinking: true ولا بقيمة مدعومة ديال reasoning_effort: xhigh أو medium أو low. فواجهة المحادثة، أثر التفكير كيرجع بوحدو فـ message.reasoning_content وما كيدخلش للحقل العادي ديال المحتوى.

temperature وtop_p مقبولين ولكن دابا ما كيتستعملوش، حيت السيرفر كينشئ الجوبات بـ sampler=None. كونطرولات التفكير، وmax_tokens، وتسلسلات التوقيف خدامين.

استعمال العميل المرفق

العميل المحلي collabosm.py كيستعمل غير المكتبة القياسية ديال Python وما كيحتاج حتى تثبيت بوحدو. هيّأ الإعدادات ديالو بالـ tunnel endpoint والمفتاح المولّد:

python collabosm.py config --init \
  --endpoint https://<host>.trycloudflare.com/v1 \
  --api-key <key>

من بعد تقدر تدير chat من التيرمينال ولا تطلق واجهة المتصفح المحلية:

python collabosm.py chat "hello"
python collabosm.py ui
python collabosm.py start

ui كيسير الصفحة والـ proxy فـ http://127.0.0.1:8790. start كيفتح نوافذ المحادثة والحالة. العميل ما كيبداش وما كيوقفش Colab VM عمداً، يعني فتحو بوحدو ما كيستهلكش وحدات الحوسبة.

عطي للعميل الموجود والمتوافق مع OpenAI الـ proxy المحلي بلاصة endpoint ديال VM إلا بغيتي الـ proxy يضيف bearer key الحقيقي:

base URL : http://127.0.0.1:8790/v1
API key  : anything
model    : qwen3.8-flash-next-exl3

هاد التصميم كيخلي المفتاح الحقيقي داخل عملية الـ proxy المحلية، وكيجنّب سياسة CORS واسعة، وكيخلّي واجهة المتصفح تتحدّث باستقلالية على VM.

اختبار البروتوكول بلا GPU

استعمل development stub باش تتحقّق من سلوك الطلبات والبث بلا ما تخلّص على A100 ولا تهبط الأوزان:

python scripts/dev_stub.py --port 8099 --chunk 24 --delay 0.01
python scripts/check_surface.py --base http://127.0.0.1:8099/v1

الـstub كيدخل معالج الشحن الحقيقي وكيبدّل غير دالة ديال جزء المحرّك. الفاحص ديال السطح كيدير 13 اختبار، منهم الفروقات المبكّرة، والأحداث النهائية، والتطابق بين مخرجات Chat وResponses، وفهارس العناصر المطلوبة، وأرقام التسلسل اللي كتزاد بشكل متتابع. كيخرج بالحالة 1 إلا فشل شي اختبار.

زيد --think لأمر الـstub باش تجرّب دورة حياة عنصر التفكير. هاد الشي مفيد خصوصاً قبل ما تبدّل أشكال أحداث البث أو تربط عملاء صارمين بحال Codex CLI.

فعّل واختبر الرؤية بحذر

حزمة النموذج متعددة الوسائط، ولكن الرؤية معطّلة افتراضياً حيث ما تقاساش بعد تكلفة VRAM الإضافية ديال برج الرؤية على البطاقة اللي عامرة بزاف من قبل. فعّل مكوّن الرؤية بشكل صريح:

VISION=1 bash scripts/up.sh

من إعدادات الصور الاختيارية كاينين:

IMAGE_URLS=1
MAX_IMAGE_BYTES=12582912
MAX_IMAGES=8

الجوج ديال لهجات API المدعومين كيقبلو أجزاء الصور القياسية ديال OpenAI. روابط Data URL مقبولة ملي كتكون الرؤية مفعّلة. روابط الصور البعيدة عبر HTTP أو HTTPS كتبقى معطّلة إلا كان IMAGE_URLS=1.

{
  "role": "user",
  "content": [
    {"type": "text", "text": "What colour is this image?"},
    {
      "type": "image_url",
      "image_url": {"url": "data:image/png;base64,..."}
    }
  ]
}

ملي كتكون الروابط البعيدة مفعّلة، السيرفر كيتحقق من اسم المضيف وكيشترط أن كل عنوان يكون قابل للتوجيه عالمياً. كيرفض عناوين loopback والخاصة وlink-local والـmetadata، وما كيتبعش التحويلات. مسارات نظام الملفات ما كتقبلش نهائياً. إلا تعذّر تضمين صورة، السيرفر كيرجع خطأ JSON بحالة 400 من النوع vision_unavailable عوض ما يتجاهل الصورة بصمت.

استعمل GET /v1/status باش تعرف واش الرؤية خدامة، ومن بعد تحقق من السلوك المفعّل أو المرفوض عمداً باستعمال:

python scripts/check_vision.py \
  --base https://<host>.trycloudflare.com/v1 \
  --key <key>

نصائح للتزامن والأداء

الـAPI كتستعمل مولّداً واحداً طويل الأمد محميّاً بقفل. لذلك الطلبات متسلسلة: التدفقات المتعددة كتتصفّف عوض ما يتم فك ترميزها بالتوازي. حجم دفعة أكبر من واحد ما تجرّبش، والقياسات المنشورة تستعمل خانة وحدة.

السعة المقاسة للجلسات الحية كتتعلق بزاف بطول السياق:

• 500K توكن لكل تدفق: جلسة حية وحدة.
• 262K توكن لكل تدفق: جوج جلسات حية.
• 131K توكن لكل تدفق: 5 جلسات حية.
• 32K توكن لكل تدفق: 11 جلسة حية.
• 16K توكن لكل تدفق: 14 جلسة حية.

كل خانة حية كتستهلك تقريباً 546 MiB من حالة Gated-DeltaNet قبل تخزين KV. فالسياقات القصيرة، الحالة التكرارية كتولي هي العامل المحدِّد؛ والنطاق العملي الموثّق هو تقريباً من 8 حتى 14 خانة حية، مع أن الطلبات كتبقى متسلسلة بالقفل الحالي ديال الـAPI.

بالنسبة لأداء الملء المسبق، كان GCS أكبر عامل مؤثر لقا المشروع. ولكن إعدادات الكاش الأكبر أو المعدّلة خاصها تتراجع مقابل استعمال VRAM وذاكرة RAM ديال المضيف، وما خاصهاش تنسخ بشكل أعمى.

تجنّب إنشاء Generator جديد لكل طلب. جدول الصفحات وكاش الصفحات ديال المعالج كيتنشؤو داخل Generator.__init__؛ وإعادة بنائه غادي تضيع بصمت إعادة استعمال كاش البرومبت وتفرض عمليات ملء مسبق متكررة. السيرفر المرفق كيبقى محافظ على النسخة طويلة الأمد الصحيحة.

استكشاف الأخطاء

الـCLI كايقول ما كايناش جلسات نشطة

سجل جلسة محلي يقدر يختفي ملي كتنتهي صلاحية رمز وكيل التشغيل، حتى إلا بقات الآلة الافتراضية نشطة وكتتحسب عليها التكلفة. استعمل سير العمل ديال الاسترجاع الموجود فالمستودع عوض ما تنشئ آلة افتراضية أخرى يدوياً. scripts/restore.py كيسول على التعيينات من جهة السيرفر وكيعاود يربط النسخة اليتيمة.

النموذج ما كيدخلش

تأكد أن بيئة التشغيل فيها تقريباً 80 GB ديال VRAM وأنها من نوع High-RAM. سكريبت الاسترجاع مصمّم باش يرفض ويوقف تعيين 40 GB قبل تحميل النموذج.

الـAPI سليمة ولكن ما كيبان حتى URL عام

up.sh كيميز بين آلة افتراضية سليمة بلا URL منشور للنفق وبين الجاهزية الكاملة. الحالة 9 كتعني هاد الحالة. فحص سجلات الخدمة والنفق عوض ما تفترض أن نقطة النهاية متاحة للعموم.

الطلبات باينة كتتجاهل إعدادات أخذ العينات

هاد الشي متوقّع بالنسبة لـtemperature وtop_p فالسيرفر الحالي. كيتحللو ولكن ما كيتبعثوش لأخذ العينات.

التوافق مع البث كيتعطّل

عاود إنتاج المشكل باستعمال scripts/dev_stub.py، ومن بعد شغّل scripts/check_surface.py. المعالج الحقيقي داخل الاختبار، وبهذا كيتلقطو تراجعات البروتوكول بلا ما تجهّز النموذج.

وقف الآلة الافتراضية وتحكّم فالتكاليف

ملي تسالي، وقف بيئة التشغيل اللي كتتحسب بالدقيقة فوراً:

bash scripts/down.sh

هاد هو أهم أمر فالمشروع للتحكم فالتكاليف. تسدّ المتصفح، أو يضيع سجل الـCLI المحلي، أو تنقطع من Colab ما كيثبتش أن الفوترة وقفات.

طبقة التحكم الأمامية الاختيارية كتزيد التأكيد قبل التجهيز، ودفتر محلي لوحدات CU، والإيقاف التلقائي عند الخمول، ومدة قصوى للجلسة، والإلغاء، والتنظيف ملي كيفشل التجهيز من بعد التعيين. تقدر تدرّب على هاد السير العمل بلا بطاقة ولا وحدات حوسبة:

python frontend/server.py --fake-provision
python frontend/server.py --mock
python scripts/dev_stub.py --port 8099 &
python frontend/server.py --mock --backend http://127.0.0.1:8099

الخلاصة

collabosm كيجمع الأجزاء الصعيبة ديال تشغيل Qwen3.8-Flash-Next فوق Colab: طلب الشكل الصحيح ديال A100، استرجاع التخصيصات اللي بقات بلا مالك، تثبيت runtime متوافق مع ExLlamaV3، تحميل الأوزان المثبّتة، الحفاظ على الكاشات، إتاحة نفق مؤمَّن، وتقديم جوج ديال لهجات API متوافقة مع OpenAI.

بدا بـ bash scripts/up.sh، وتحقق من الإعدادات النشيطة عبر /v1/status، وربط الاتصال من خلال endpoint /v1 اللي كيبان، ودائماً سالِي بـ bash scripts/down.sh. فالتجارب القريبة من الإنتاج، ردّ بالك مزيان للطلبات المتسلسلة، وضوابط أخذ العينات اللي مازال ما تطبقاتش، وتكاليف ذاكرة الكاش، والاستهلاك الاختياري ديال VRAM فالرؤية، والفرق بين استئناف الكاش الخامل والقدرة الحقيقية ديال الجلسات النشيطة.