مابراتوريناتور

جرّب النموذج التوليدي هنا، أو MaiMod هنا. شاهد فيديو توضيحي هنا.

مابراتوريناتور هو إطار عمل متعدد النماذج يستخدم مدخلات الطيف الترددي لإنشاء خرائط إيقاع osu! كاملة الميزات لجميع أوضاع اللعب ومساعدة تعديل الخرائط. هدف هذا المشروع هو توليد خرائط osu! قابلة للترتيب تلقائيًا من أي أغنية مع درجة عالية من التخصيص.

هذا المشروع مبني على osuT5 و osu-diffusion. أثناء تطويره، قضيت حوالي 2500 ساعة من حسابات GPU عبر 142 تجربة على بطاقة 4060 Ti وأجهزة 4090 مستأجرة من vast.ai.

#### استخدم هذه الأداة بمسؤولية. احرص دائمًا على الإفصاح عن استخدام الذكاء الاصطناعي في خرائط الإيقاع الخاصة بك.

التثبيت

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

١. استنساخ المستودع

git clone https://github.com/OliBomby/Mapperatorinator.git
cd Mapperatorinator

2. (اختياري) إنشاء بيئة افتراضية

استخدم Python 3.10، قد لا تكون الإصدارات الأحدث متوافقة مع الاعتمادات.

python -m venv .venv
In cmd.exe
.venv\Scripts\activate.bat
In PowerShell
.venv\Scripts\Activate.ps1
In Linux or MacOS
source .venv/bin/activate

3. تثبيت المتطلبات

• بايثون 3.10
• جيت
• ffmpeg
• CUDA (لبطاقات NVIDIA) أو ROCm (لبطاقات AMD على لينكس)
• PyTorch: تأكد من اتباع دليل البدء حتى تقوم بتثبيت torch وtorchaudio مع دعم وحدة معالجة الرسومات. اختر إصدار منصة الحوسبة الصحيح الذي قمت بتثبيته في الخطوة السابقة.
• والمتطلبات المتبقية للبايثون:

pip install -r requirements.txt

واجهة المستخدم الرسومية على الويب (موصى بها)

للحصول على تجربة أكثر سهولة للمستخدم، يُنصح باستخدام واجهة الويب. فهي توفر واجهة رسومية لتكوين معلمات التوليد، بدء العملية، ومراقبة المخرجات.

تشغيل الواجهة الرسومية

انتقل إلى دليل Mapperatorinator المستنسخ في الطرفية الخاصة بك وقم بتشغيل:

python web-ui.py

سيقوم هذا بتشغيل خادم ويب محلي وفتح واجهة المستخدم تلقائيًا في نافذة جديدة.

استخدام الواجهة الرسومية

• الإعداد: قم بتحديد مسارات الإدخال/الإخراج باستخدام حقول النموذج وأزرار "تصفح". اضبط معلمات التوليد مثل وضع اللعبة، الصعوبة، النمط (السنة، معرف الصانع، الأوصاف)، التوقيت، الميزات المحددة (مؤثرات الضربات، التوقيت الفائق)، وغير ذلك، لتعكس خيارات سطر الأوامر. (ملاحظة: إذا قمت بتحديد beatmap_path، ستحدد الواجهة تلقائيًا audio_path و output_path منه، لذا يمكنك ترك هذه الحقول فارغة)
• البدء: اضغط على زر "بدء الاستدلال" لبدء توليد خريطة الإيقاع.
• إلغاء: يمكنك إيقاف العملية الجارية باستخدام زر "إلغاء الاستدلال".
• فتح الإخراج: بعد الانتهاء، استخدم زر "فتح مجلد الإخراج" للوصول السريع إلى الملفات المولدة.

تعمل واجهة الويب كغلاف مريح حول البرنامج النصي inference.py. للمزيد من الخيارات المتقدمة أو استكشاف الأخطاء، راجع تعليمات سطر الأوامر.

الاستدلال عبر سطر الأوامر

للمستخدمين الذين يفضلون سطر الأوامر أو يحتاجون للوصول إلى إعدادات متقدمة، اتبع الخطوات التالية. ملاحظة: للحصول على واجهة رسومية أبسط، يرجى مراجعة قسم واجهة الويب (موصى بها) أعلاه.

قم بتشغيل inference.py ومرر بعض الوسيطات لتوليد خرائط الإيقاع. لهذا استخدم بنية تجاوز Hydra. راجع configs/inference_v29.yaml لجميع المعلمات المتاحة.

python inference.py \
  audio_path           [Path to input audio] \
  output_path          [Path to output directory] \
  beatmap_path         [Path to .osu file to autofill metadata, and output_path, or use as reference] \
  
  gamemode             [Game mode to generate 0=std, 1=taiko, 2=ctb, 3=mania] \
  difficulty           [Difficulty star rating to generate] \
  mapper_id            [Mapper user ID for style] \
  year                 [Upload year to simulate] \
  hitsounded           [Whether to add hitsounds] \
  slider_multiplier    [Slider velocity multiplier] \
  circle_size          [Circle size] \
  keycount             [Key count for mania] \
  hold_note_ratio      [Hold note ratio for mania 0-1] \
  scroll_speed_ratio   [Scroll speed ratio for mania and ctb 0-1] \
  descriptors          [List of beatmap user tags for style] \
  negative_descriptors [List of beatmap user tags for classifier-free guidance] \
  
  add_to_beatmap       [Whether to add generated content to the reference beatmap instead of making a new beatmap] \
  start_time           [Generation start time in milliseconds] \
  end_time             [Generation end time in milliseconds] \
  in_context           [List of additional context to provide to the model [NONE,TIMING,KIAI,MAP,GD,NO_HS]] \
  output_type          [List of content types to generate] \
  cfg_scale            [Scale of the classifier-free guidance] \
  super_timing         [Whether to use slow accurate variable BPM timing generator] \
  seed                 [Random seed for generation] \

مثال:

python inference.py beatmap_path="'C:\Users\USER\AppData\Local\osu!\Songs\1 Kenji Ninuma - DISCO PRINCE\Kenji Ninuma - DISCOPRINCE (peppy) [Normal].osu'" gamemode=0 difficulty=5.5 year=2023 descriptors="['jump aim','clean']" in_context=[TIMING,KIAI]

واجهة سطر الأوامر التفاعلية

بالنسبة لأولئك الذين يفضلون العمل عبر الطرفية ولكن يرغبون في إعداد موجه، فإن برنامج سطر الأوامر التفاعلي يعد بديلاً ممتازاً عن واجهة المستخدم عبر الويب.

تشغيل واجهة الأوامر

انتقل إلى الدليل الذي تم نسخه. قد تحتاج أولاً إلى جعل البرنامج النصي قابلاً للتنفيذ.

# Make the script executable (only needs to be done once)
chmod +x cli_inference.sh

# Run the script
./cli_inference.sh

استخدام واجهة الأوامر (CLI)

سيرشدك البرنامج النصي عبر سلسلة من التعليمات التوضيحية لتكوين جميع معلمات التوليد، تمامًا مثل واجهة الويب.

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

نصائح التوليد

• يمكنك تعديل الملف configs/inference_v29.yaml وإضافة الوسائط الخاصة بك هناك بدلاً من كتابتها في الطرفية في كل مرة.
• جميع الأوصاف المتاحة يمكن العثور عليها هنا.
• يجب دائمًا تقديم وسيط السنة بين 2007 و2023. إذا تركته غير معروف، قد يولد النموذج بأسلوب غير متناسق.
• يجب دائمًا تقديم وسيط الصعوبة. إذا تركته غير معروف، قد يولد النموذج بصعوبة غير متناسقة.
• قم بزيادة معامل cfg_scale لزيادة فعالية وسائط mapper_id وdescriptors.
• يمكنك استخدام وسيط negative_descriptors لتوجيه النموذج بعيدًا عن أنماط معينة. هذا يعمل فقط عندما يكون cfg_scale > 1. تأكد من أن عدد الأوصاف السلبية يساوي عدد الأوصاف.
• إذا كان أسلوب أغنيتك وأسلوب خريطة الضربات المطلوب غير متطابقين جيدًا، قد لا يتبع النموذج تعليماتك. على سبيل المثال، من الصعب توليد خريطة ضربات بقيمة SR وSV عالية لأغنية هادئة.
• إذا كان لديك بالفعل توقيت وأوقات كياي لأغنية، يمكنك إعطاؤها للنموذج لزيادة سرعة ودقة الاستدلال بشكل كبير: استخدم وسائط beatmap_path وin_context=[TIMING,KIAI].
• لإعادة تعيين جزء فقط من خريطة الضربات، استخدم وسائط beatmap_path وstart_time وend_time وadd_to_beatmap=true.
• لتوليد صعوبة ضيف لخريطة ضربات، استخدم وسائط beatmap_path وin_context=[GD,TIMING,KIAI].
• لتوليد أصوات ضربات لخريطة ضربات، استخدم وسائط beatmap_path وin_context=[NO_HS,TIMING,KIAI].
• لتوليد التوقيت فقط لأغنية، استخدم وسائط super_timing=true وoutput_type=[TIMING].

MaiMod: أداة التعديل المدفوعة بالذكاء الاصطناعي

MaiMod هي أداة لتعديل خرائط osu! تستخدم تنبؤات Mapperatorinator للعثور على الأخطاء والتناقضات المحتملة التي لا يمكن اكتشافها بواسطة أدوات التعديل التلقائي الأخرى مثل Mapset Verifier. يمكنها اكتشاف مشكلات مثل:

• التقاط أو أنماط إيقاعية غير صحيحة
• نقاط توقيت غير دقيقة
• مواضع أشياء الضربات أو تعيين مجموعات جديدة غير متناسقة
• أشكال سلايدرات غريبة
• أصوات ضربات أو مستويات صوت غير متناسقة

يمكنك تجربة MaiMod من هنا، أو تشغيلها محليًا: لتشغيل MaiMod محليًا، ستحتاج إلى تثبيت Mapperatorinator. ثم قم بتشغيل البرنامج النصي mai_mod.py مع تحديد مسار خريطة ضرباتك باستخدام وسيط beatmap_path.

python mai_mod.py beatmap_path="'C:\Users\USER\AppData\Local\osu!\Songs\1 Kenji Ninuma - DISCO PRINCE\Kenji Ninuma - DISCOPRINCE (peppy) [Normal].osu'"

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

قد يرتكب النموذج أخطاء، خاصة في المشكلات ذات المفاجأة المنخفضة، لذا تحقق دائمًا من الاقتراحات قبل تطبيقها على خريطة الإيقاع الخاصة بك. الهدف الرئيسي هو مساعدتك في تضييق نطاق البحث عن المشكلات المحتملة، حتى لا تضطر إلى فحص كل عنصر ضرب في خريطة الإيقاع يدويًا.

واجهة MaiMod الرسومية

لتشغيل واجهة MaiMod Web UI، ستحتاج إلى تثبيت Mapperatorinator. ثم، قم بتشغيل برنامج mai_mod_ui.py. سيؤدي ذلك إلى بدء خادم ويب محلي وفتح الواجهة تلقائيًا في نافذة جديدة:

python mai_mod_ui.py

نظرة عامة

الترميز إلى رموز

يقوم Mapperatorinator بتحويل خرائط osu! إلى تمثيل وسيط للأحداث يمكن تحويله مباشرة إلى رموز والعكس صحيح. يتضمن ذلك الكائنات التي يتم ضربها، أصوات الضربات، سرعات المنزلق، المجموعات الجديدة، نقاط التوقيت، أوقات الكيائي، وسرعات التمرير في تايكو/مانيا.

إليك مثال صغير على عملية الترميز إلى رموز:

لتوفير حجم المفردات، يتم تقطيع الأحداث الزمنية إلى فترات 10 مللي ثانية، ويتم تقطيع إحداثيات المواقع إلى نقاط شبكة بمقدار 32 بكسل.

بنية النموذج

النموذج هو في الأساس غلاف حول نموذج HF Transformers Whisper، مع تضمينات إدخال مخصصة ودالة خسارة مخصصة. حجم النموذج يبلغ 219 مليون معامل. وقد تبين أن هذا النموذج أسرع وأكثر دقة من T5 لهذه المهمة.

النظرة العامة عالية المستوى للمدخلات والمخرجات في النموذج كما يلي:

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

تنسيق التدريب متعدد المهام

قبل رمز SOS هناك رموز إضافية تسهل التوليد الشرطي. تشمل هذه الرموز نمط اللعبة، الصعوبة، معرف المصمم، السنة، وبيانات وصفية أخرى. خلال التدريب، هذه الرموز ليس لها تسميات مرافقة، لذلك لا يتم إنتاجها أبدًا من قبل النموذج. أيضًا خلال التدريب هناك احتمال عشوائي أن يتم استبدال رمز من البيانات الوصفية برمز "غير معروف"، لذلك أثناء الاستدلال يمكننا استخدام هذه الرموز "غير المعروفة" لتقليل كمية البيانات الوصفية التي يجب إعطاؤها للنموذج.

توليد متواصل بلا فواصل

طول سياق النموذج هو 8.192 ثانية. من الواضح أن هذا غير كافٍ لتوليد خريطة كاملة، لذلك يجب تقسيم الأغنية إلى نوافذ متعددة وتوليد الخريطة في أجزاء صغيرة. لضمان عدم وجود فواصل ملحوظة في الخريطة الناتجة بين النوافذ، نستخدم تداخل بنسبة 90% ونولد النوافذ بالتسلسل. كل نافذة توليد باستثناء الأولى تبدأ بمفكك النموذج المعبأ مسبقًا حتى 50% من نافذة التوليد باستخدام الرموز من النوافذ السابقة. نستخدم معالج لوغيت للتأكد من أن النموذج لا يمكنه توليد رموز الوقت التي تقع في أول 50% من نافذة التوليد. بالإضافة إلى ذلك، يتم حجز آخر 40% من نافذة التوليد للنافذة التالية. أي رموز وقت يتم توليدها في هذا النطاق تُعامل كرُموز نهاية تسلسل (EOS). يضمن ذلك أن كل رمز يتم توليده يعتمد على 4 ثوانٍ على الأقل من الرموز السابقة و3.3 ثوانٍ من الصوت المستقبلي للتوقع.

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

إحداثيات محسّنة بالانتشار

الإحداثيات المكانية التي يولدها وحدة فك الترميز يتم تقريبها إلى شبكة من 32 بكسل، لذا نستخدم بعد ذلك الانتشار لإزالة الضوضاء من الإحداثيات إلى المواقع النهائية. لهذا قمنا بتدريب نسخة معدلة من osu-diffusion متخصصة فقط في آخر 10% من جدول الضوضاء، وتقبل رموز بيانات وصفية أكثر تقدماً يستخدمها Mapperatorinator للتوليد الشرطي.

نظرًا لأن نموذج Mapperatorinator يخرج SV للمنزلقات، فإن الطول المطلوب للمنزلق ثابت بغض النظر عن شكل مسار نقطة التحكم. لذلك، نحاول توجيه عملية الانتشار لإنشاء إحداثيات تتناسب مع أطوال المنزلق المطلوبة. نفعل ذلك من خلال إعادة حساب مواقع نهاية المنزلق بعد كل خطوة من عملية الانتشار بناءً على الطول المطلوب ومسار نقطة التحكم الحالي. هذا يعني أن عملية الانتشار ليس لديها سيطرة مباشرة على مواقع نهاية المنزلق، لكنها لا تزال تستطيع التأثير عليها من خلال تغيير مسار نقطة التحكم.

المعالجة اللاحقة

يقوم Mapperatorinator ببعض المعالجة الإضافية لتحسين جودة خريطة الإيقاع المولدة:

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

مولد التوقيت الفائق

مولد التوقيت الفائق هو خوارزمية تحسن دقة وضبط التوقيت المولد من خلال استنتاج التوقيت للأغنية بالكامل 20 مرة وأخذ متوسط النتائج. هذا مفيد للأغاني ذات معدل نبض متغير، أو الأغاني التي بها تغييرات في معدل النبض. النتيجة تقريباً مثالية مع فقط في بعض الأحيان جزء يحتاج لتعديل يدوي.

التدريب

التعليمات أدناه تنشئ بيئة تدريب على جهازك المحلي.

1. استنساخ المستودع

git clone https://github.com/OliBomby/Mapperatorinator.git
cd Mapperatorinator

2. إنشاء مجموعة البيانات

أنشئ مجموعة البيانات الخاصة بك باستخدام تطبيق وحدة تحكم Mapperator. يتطلب ذلك رمز عميل OAuth لـ osu! للتحقق من خرائط الإيقاع والحصول على بيانات وصفية إضافية. ضع مجموعة البيانات في مجلد datasets بجوار مجلد Mapperatorinator.

Mapperator.ConsoleApp.exe dataset2 -t "/Mapperatorinator/datasets/beatmap_descriptors.csv" -i "path/to/osz/files" -o "/datasets/cool_dataset"

3. (اختياري) إعداد Weight & Biases للتسجيل

أنشئ حسابًا على Weight & Biases واحصل على مفتاح API الخاص بك من إعدادات حسابك. ثم قم بتعيين متغير البيئة WANDB_API_KEY، حتى يعرف سير عملية التدريب التسجيل باستخدام هذا المفتاح.

export WANDB_API_KEY=

4. إنشاء حاوية دوكر

يمكنك التدريب في البيئة الافتراضية الخاصة بك أيضًا، لكننا نوصي باستخدام دوكر على WSL للحصول على أداء أفضل.

docker compose up -d --force-recreate
docker attach mapperatorinator_space
cd Mapperatorinator

5. ضبط المعلمات وبدء التدريب

جميع الإعدادات موجودة في ./configs/train/default.yaml. تأكد من تعيين train_dataset_path و test_dataset_path بشكل صحيح لمسار مجموعة بياناتك، بالإضافة إلى مؤشر بداية ونهاية مجموعة الخرائط لتقسيم التدريب/الاختبار. المسار محلي داخل حاوية الدوكر، لذلك إذا وضعت مجموعة بياناتك المسماة cool_dataset داخل دليل datasets، فيجب أن يكون /workspace/datasets/cool_dataset.

أوصي بإنشاء ملف إعدادات مخصص يتجاوز الإعداد الافتراضي، حتى يكون لديك سجل لإعدادات تدريبك لضمان إمكانية إعادة التجربة.

data:
  train_dataset_path: "/workspace/datasets/cool_dataset"
  test_dataset_path: "/workspace/datasets/cool_dataset"
  train_dataset_start: 0
  train_dataset_end: 90
  test_dataset_start: 90
  test_dataset_end: 100

Begin training by calling python osuT5/train.py or torchrun --nproc_per_node=NUM_GPUS osuT5/train.py for multi-GPU training.

python osuT5/train.py -cn train_v29 train_dataset_path="/workspace/datasets/cool_dataset" test_dataset_path="/workspace/datasets/cool_dataset" train_dataset_end=90 test_dataset_start=90 test_dataset_end=100

6. ضبط LoRA بدقة

يمكنك أيضًا ضبط نموذج مدرّب مسبقًا باستخدام LoRA لتكييفه مع نمط أو وضع لعبة معين. للقيام بذلك، قم بتعديل configs/train/lora.yaml حسب احتياجاتك وشغّل إعداد التدريب lora:

python osuT5/train.py -cn lora train_dataset_path="/workspace/datasets/cool_dataset" test_dataset_path="/workspace/datasets/cool_dataset" train_dataset_end=90 test_dataset_start=90 test_dataset_end=100

معلمات LoRA المهمة التي يجب أخذها في الاعتبار:

• pretrained_path: مسار أو مستودع HF لنموذج الأساس المراد تحسينه.
• r: رتبة مصفوفات LoRA. القيم الأعلى تزيد من قدرة النموذج ولكنها تزيد أيضًا من استهلاك الذاكرة.
• lora_alpha: عامل موازنة لتحديثات LoRA.
• total_steps: إجمالي عدد خطوات التدريب. قم بموازنة هذا حسب حجم مجموعة بياناتك.
• enable_lora: ما إذا كنت ستستخدم LoRA أو تحسين النموذج الكامل.

أثناء الاستدلال، يمكنك تحديد أوزان LoRA المراد استخدامها مع وسيطة lora_path. يمكن أن يكون هذا مسارًا محليًا أو مستودعًا على Hugging Face.

أنظر أيضًا

• مصنف Mapper
• RComplexion

الشكر والتقدير

شكر خاص لـ:

• مؤلفي osuT5 على كود التدريب الخاص بهم.
• فريق Hugging Face على الأدوات.
• Jason Won و Richard Nagyfi على تبادل الأفكار.
• Marvin على التبرع بأرصدة التدريب.
• مجتمع osu! على الخرائط الإيقاعية (beatmaps).

الأعمال ذات الصلة

• مولد خرائط osu! بواسطة Syps (Nick Sypteras)
• osumapper بواسطة kotritrona، jyvden، Yoyolick (Ryan Zmuda)
• osu-diffusion بواسطة OliBomby (Olivier Schipper)، NiceAesth (Andrei Baciu)
• osuT5 بواسطة gyataro (Xiwen Teoh)
• Beat Learning بواسطة sedthh (Richard Nagyfi)
• osu!dreamer بواسطة jaswon (Jason Won)

--- Tranlated By Open Ai Tx | Last indexed: 2026-01-24 ---