شنو كيدير هاد المشروع
هاد المستودع كيجمع موديل الفيديو MiniMax H3 باش يخدم مع TensorFold فوق Apple Silicon. كيجمع عائلة H3 ديال TensorFold مع نوى MLX int8 ديال Metal ومحوّل LightX2V Turbo باش يولّد الفيديو بصوت ستيريو متزامن.
الحزمة كتدعم تحويل النص لفيديو، ومن الإصدار 1.1 حتى تحويل الصورة لفيديو باستعمال أول إطار كتزوّدو به. فوق Mac Studio M5 Ultra اللي تقاسات عليه النتائج وبذاكرة 256 GB، مقطع مدتو 5 ثواني وبقياس 864x480 كياخذ تقريباً 50 ثانية مع محوّل Turbo. ومقطع 768x448 كياخذ تقريباً 40 ثانية فظروف الاختبار الموثقة.
المستودع هو مسار للتصيير والتطوير، ماشي سيرفر ولا منتوج. ما كايناش تعليمة tensorfold generate؛ الموديل كيتحمّل مع كل عملية تصيير عبر السكريبتات المرفقة.
الميزات الرئيسية
- تحويل النص لفيديو: وصف المشهد وتوليد MP4 فيه فيديو وصوت ستيريو.
- تحويل الصورة لفيديو: عطِ أول إطار ووصف شنو غادي يوقع من بعد.
- التوليد بـ Turbo: محوّل LightX2V كينقص التصيير لثلاث عمليات forward فالمسار السريع الموثق.
- نوى MLX وint8: عمليات مختارة من المحوّل ومفكّك الترميز كتستعمل نوى Metal int8 فوق عتاد M5 المتوافق مع tensor.
- إعداد قابل لإعادة الإنتاج: برنامج التثبيت كيثبّت إصدارات TensorFold وMLX والمكتبات المساندة، ومراجعات الموديلات، وبصمات المحوّل.
- تصيير اختياري بالموديل الأساسي: عطّل المحوّل واستعمل تقريباً 20 خطوة ديال أخذ العينات إلا بغيتي تصييراً أقرب للموديل الأساسي.
متطلبات العتاد والبرمجيات
الأرقام المنشورة ديال الأداء تقاسات فوق Mac Studio M5 Ultra بذاكرة موحّدة 256 GB وخدام بـ macOS 27.0.1. المشروع كيوضح بلي خاص على الأقل 128 GB ديال الذاكرة، فحين دمج المحوّل يقدر يوصل لاستهلاك أقصى ديال الذاكرة بحوالي 103 GB. بلا محوّل، الاستهلاك الأقصى مذكور فحوالي 65 GB.
نوى int8 محتاجة لعمليات tensor ديال Metal 4، وهاد الشي علاش التسريع المذكور موجه لعتاد M5 المتوافق. فالأنظمة اللي ما فيهاش هاد العمليات، عائلة H3 كتخدم بـ bfloat16 وقد تكون أبطأ من البدائل المبنية بـ C اللي موصوفة فـ README.
حتى Homebrew وPython 3.11 وuv وFFmpeg خاصّك. تحميل موديل MiniMax H3 حجمو تقريباً 144 GB، ومحوّل Turbo حجمو تقريباً 1.96 GB.
ثبّت المشروع
كلونِي المستودع وثبّت أدوات النظام المطلوبة:
git clone https://github.com/drowzeys/keys-Mac-TensorFold-MiniMax-H3-MLX.git
cd keys-Mac-TensorFold-MiniMax-H3-MLX
brew install python@3.11 uv ffmpegشغّل سكريبت الإعداد الكامل:
bash oneshot-setup.shبرنامج التثبيت كينشئ بيئة معزولة فـ ~/.local/opt/tensorfold-h3 وكيثبّت TensorFold 0.6.5 مع عائلة H3 وقفل الاعتماديات المثبّت. إلا كان Docker متوفر، يقدر يجيب حمولة TensorFold متحقَّق من بصمتها من الحامل الجاهز مسبقاً ديال المشروع فـ GHCR؛ وإلا كيجيب المراجعة المطابقة للمصدر من Git.
الإعداد حتى هو كيدير clone للمراجعة المطلوبة ديال minimax-h3-mlx، وكيحمّل تقسيم MiniMax H3 FL2VA لـ ~/h3-models/MiniMax-H3، وكيحمّل محوّل Turbo، وكيصيّر مقطع تجريبي فـ outputs/test.mp4.
باش تفحص تثبيت موجود بلا ما تعاود تثبّتو، شغّل:
bash oneshot-setup.sh --verifyباش تفوّت التصيير التجريبي الأول، استعمل:
bash oneshot-setup.sh --no-render
تقدر تبدّل المسارات الافتراضية ديال التثبيت والموديل باستعمال متغيّرات البيئة PREFIX وH3_MODEL_DIR.
ولّد مقطع من النص للفيديو
استعمل scripts/generate.sh مع برومبت واسم ملف الإخراج:
bash scripts/generate.sh "A hummingbird hovering over red flowers, soft wing hum" out.mp4المسار الافتراضي كيستعمل محوّل Turbo المكوَّن وإعدادات التوليد الافتراضية ديال المستودع. البرومبت كيوصف المشهد البصري وحتى الصوت المقصود ملي كيكون مفيد.
باش تدير تنويعة قابلة لإعادة الإنتاج، عطِ seed واختار لوحة مدعومة:
WIDTH=768 HEIGHT=448 SEED=7 bash scripts/generate.sh "A quiet train crossing a snowy valley at dawn" out.mp4تقدر تخلي البرومبتات فملف نصي. فهاد الحالة، دوز برومبت خاوي وحدد PROMPT_FILE:
PROMPT_FILE=prompts/black-mirror-scene.txt SEED=2077 bash scripts/generate.sh "" out.mp4ولّد مقطع من الصورة للفيديو
حدّد FIRST_FRAME لملف صورة. الصورة كتولي أول إطار، والبرومبت كيفسّر الحركة ولا الحدث اللي غادي يجي من بعد:
FIRST_FRAME=photo.jpg WIDTH=1344 HEIGHT=768 bash scripts/generate.sh "She turns to the camera and smiles" out.mp4الصورة كتتمطّط حتى توصل للوحة المختارة، لذلك اختار أبعاد عندها نفس نسبة العرض للارتفاع ولا قصّ الصورة قبل التصيير. الـ README كيوصي بـ 1344x768 لـ 16:9، و768x1344 لـ 9:16، و768x768 للمحتوى المربّع.
برومبتات تحويل الصورة لفيديو على طريقة MiniMax تقدر تحدد أول إطار بشكل صريح، مثلاً:
For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced. The subject walks through the doorway and looks toward the window.توليد الفريم اللولاني متاح باستعمال أداپتور Turbo وبمسار الأساس ديال 20 خطوة. مودات الفريم الأخير وصورة المرجع ما مدموجينش فهاد الحزمة.
تحكّم فالفريمات، الدقة، وأخذ العينات
عدد الفريمات خاصّو يتبع الصيغة 17n + 5. الـREADME كيسرد أمثلة مدعومة، من بينها 56 و73 و90 و124 و192 و243 و362 فريم. العرض والعلو خاصّهم يكونو مضاعفات ديال 32، والحدّ ديال الموديل المنشور هو كانفاس مجموعو ما يفوتش 768x1344 بيكسل.
المسار السريع Turbo كيستعمل ثلاثة forwards. باش تعطّل الأداپتور وتستعمل رندير ديال 20 خطوة، عيّن ADAPTER=none وPOINTS=21:
ADAPTER=none POINTS=21 bash scripts/generate.sh "A lantern glowing beside a forest path" base-model.mp4الـREADME كيشرح بأن هاد الإعداد أقرب للموديل الأساسي، بينما Turbo يقدر يخرج فريمات حادّة بسرعة، ولكن مرات يقدر يكرّر الشخصيات. الجوج ديال المودات يقدرو يخرجو كومپوزيسيونات مختلفة حتى إلا كان نفس الـseed.
فهم المقايضات ديال السرعة
أكبر تحسّن فالسرعة جاي من ثلاثة forwards ديال أداپتور Turbo بلاصة 20. كيربحو حتى كيرنلات int8 SwiGLU MLP وعمليات int8 QKV، وattention output، وvideo decoder فالهاردوير المدعوم ديال M5 tensor.
فالبينشمارك الموثّق بدقة 864x480، المسار Turbo خدا تقريباً 27.6 ثانية فإزالة الضجيج وحوالي 50 ثانية فالمجموع، بما فيها ترميز النص، والتحميل والكمّية، وفكّ الترميز. رندير TensorFold int8 ديال 20 خطوة خدا تقريباً 210 ثواني فالمجموع فنفس المقارنة.
هاد الأرقام مرتبطة بالهاردوير وما خاصّهاش تتعتبر عامة. الريپوزيتوري كيشير حتى لأن attention بحدّ ذاتو باقي كيستعمل MLX scaled dot-product attention، حيث البديل int8 بنمط flash اللي تقاس ما عطاش زيادة مفيدة فالسرعة.
إعدادات متقدمة ونصائح لسير العمل
استعمل الـcarrier الموجد من قبل
الـinstaller يقدر يستعمل GHCR carrier، ولكن هاد الـcarrier ماشي runtime ديال Mac. Metal ما كيخدمش داخل الـcontainer؛ الـcarrier غير كيوفّر TensorFold wheel، وقفل الاعتماديات، وسكريپت التوليد، والـchecksums باش يتدار التثبيت native.
docker pull ghcr.io/drowzeys/keys-mac-tensorfold-minimax-h3-mlx:1.1
docker run --rm -v "$PWD":/out ghcr.io/drowzeys/keys-mac-tensorfold-minimax-h3-mlx:1.1 cp -a /payload/. /out/payload/باش تعاود تبني وتدفع الـcarrier، الريپوزيتوري كيوفّر:
PUSH=1 bash scripts/build-carrier.shردّ بالك لاستعمال الذاكرة
تحميل الموديل ودمج الأداپتور كيستهلكو بزاف ديال الذاكرة. سدّ التطبيقات اللي ما محتاجهاش قبل ما تبدا الرندير، خصوصاً ملي كتستعمل أداپتور Turbo. الريپوزيتوري كييقول بأن إسقاط جداول AdaLN مرة وحدة فكل تشغيل وتحرير الأوزان كيوفّر تقريباً 24 GiB فالمسار اللي تقاس.
اختار الكانفاس المناسب من صورة لفيديو
حيت الصورة اللولة كتتمطّط وما كتتقصّش أوتوماتيكياً باش تحافظ على الكومپوزيسيون ديالها، وجّه الصورة المصدر للنسبة المستهدفة. هاد الشي كيتفادى التشويه غير المرغوب فيه ملي كتولّد مقاطع عمودية أو أفقية أو مربعة.
استعمل الأداپترات البديلة بحذر
الـloader يقدر يقرا FastH3 باستعمال مسار أداپتور وPOINTS=5، مثلاً مع ADAPTER=.../adapter_model.safetensors. الـREADME كييقول بأن هاد المسار تجرّب بدقة 864x480، وخدا 76 ثانية فـprompt الاختبار، وبان عامر بالتفاصيل أكثر من Turbo. تنشر بدقة 1344x768، ولكن هاد الدقة ما تجرّباتش فالمشروع.
فسّر مقارنات الجودة بالشكل الصحيح
الـREADME كيشدّد على أن الجودة ما تقيّماش بشكل شامل. مسار int8 يقدر يحافظ على الكومپوزيسيون ديال bfloat16 مع تبديل التفاصيل، ورندير Turbo بثلاثة forwards يقدر يختلف على رندير Turbo بـbfloat16. لذلك جداول البينشمارك كتقارن السرعة المقاسة ولقطات مختارة، وما كتضمنش حركة أو جودة صوت متطابقة.
الترخيص وحالة المشروع
الحزمة ما فيهاش أوزان الموديل. قبل ما تحمّل MiniMax H3، قرا MiniMax H3 Community License، بما فيها الاستثناءات الترابية ديالها. وراجع حتى الاعتمادات ديال الريپوزيتوري، واذكر عند الاقتضاء المؤلفين الأصليين ديال MiniMax وTensorFold وMLX وH3 والأداپتور والمشاريع المرتبطة.
عائلة H3 المستعملة هنا موصوفة بأنها pull request مسودة مقترحة من upstream، وماشي جزء من نسخة TensorFold منشورة. لذلك تثبيت المراجعات الموثّقة مهم باش تعاود نفس الإعداد.
الخلاصة
هاد الريپوزيتوري كيوفّر طريقة مركّزة باش تشغّل توليد الفيديو بـMiniMax H3 بشكل native على أجهزة Mac المتوافقة مع Apple Silicon. من بعد ما تثبّت البيئة المقيّدة وتحمل الموديل، تقدر تولّد مقاطع من النص للفيديو، وتحرك فريم لولاني، وتبدّل بين أداپتور Turbo السريع ومسار الأساس ديال 20 خطوة، وتضبط الكانفاس وعدد الفريمات والـseed وإعدادات الـprompt. توقّع احتياجات كبيرة فالذاكرة والتخزين، واعتبر التوقيتات المنشورة قياسات ديال نظام M5 المحدد، ماشي ضمانات عامة.