Mapperatorinator
مدل مولد را اینجا امتحان کنید، یا MaiMod را اینجا بررسی کنید. نمایش ویدیویی را اینجا ببینید.
Mapperatorinator یک چارچوب چندمدلی است که از ورودیهای طیفنگار برای تولید نقشههای کامل osu! برای همه حالتهای بازی و کمک به مدسازی نقشهها استفاده میکند. هدف این پروژه تولید خودکار نقشههای osu! با کیفیت قابل رتبهبندی از هر آهنگی با درجه بالایی از سفارشیسازی است.
این پروژه بر پایه osuT5 و osu-diffusion ساخته شده است. در توسعه این پروژه حدود ۲۵۰۰ ساعت محاسبات GPU در ۱۴۲ اجرا روی ۴۰۶۰ Ti خودم و نمونههای اجارهای ۴۰۹۰ در vast.ai صرف کردم.
#### از این ابزار به صورت مسئولانه استفاده کنید. همیشه استفاده از هوش مصنوعی در بیتمپهای خود را افشا کنید.
نصب
دستورالعمل زیر به شما اجازه میدهد تا بیتمپها را بر روی دستگاه محلی خود تولید کنید، همچنین میتوانید آن را در فضای ابری با دفترچه colab اجرا کنید.
۱. مخزن را کلون کنید
git clone https://github.com/OliBomby/Mapperatorinator.git
cd Mapperatorinator2. (اختیاری) ایجاد محیط مجازی
از Python 3.10 استفاده کنید، نسخههای بعدی ممکن است با وابستگیها ناسازگار باشند.
python -m venv .venvIn cmd.exe
.venv\Scripts\activate.bat
In PowerShell
.venv\Scripts\Activate.ps1
In Linux or MacOS
source .venv/bin/activate۳. نصب وابستگیها
- پایتون ۳.۱۰
- گیت
- افافامپگ
- CUDA (برای کارتهای گرافیک NVIDIA) یا ROCm (برای کارتهای گرافیک AMD روی لینوکس)
- پایتورچ: مطمئن شوید راهنمای شروع را دنبال میکنید تا
torchوtorchaudioرا با پشتیبانی از GPU نصب کنید. نسخه صحیح Compute Platform که در مرحله قبل نصب کردهاید را انتخاب کنید. - و سایر وابستگیهای پایتون:
pip install -r requirements.txtرابط کاربری وب (توصیهشده)
برای تجربهای کاربرپسندتر، استفاده از رابط کاربری وب را مدنظر قرار دهید. این رابط، یک واسط گرافیکی برای تنظیم پارامترهای تولید، شروع فرایند و نظارت بر خروجی فراهم میکند.
راهاندازی رابط کاربری گرافیکی
در ترمینال خود به پوشهی کلونشدهی Mapperatorinator بروید و اجرا کنید:
python web-ui.py
این کار یک وب سرور محلی را راهاندازی کرده و رابط کاربری را به طور خودکار در یک پنجره جدید باز میکند.استفاده از رابط گرافیکی (GUI)
- پیکربندی: مسیرهای ورودی/خروجی را با استفاده از فیلدهای فرم و دکمههای "مرور" تنظیم کنید. پارامترهای تولید مانند حالت بازی، درجه سختی، سبک (سال، شناسه نگارنده، توصیفگرها)، زمانبندی، ویژگیهای خاص (صداهای ضربه، زمانبندی ویژه) و غیره را تنظیم کنید که مشابه گزینههای خط فرمان هستند. (توجه: اگر یک
beatmap_pathوارد کنید، رابط کاربری به طور خودکارaudio_pathوoutput_pathرا از آن تعیین میکند، بنابراین میتوانید این فیلدها را خالی بگذارید) - شروع: برای آغاز ساخت بیتمپ، دکمه "شروع استنتاج" را کلیک کنید.
- لغو: میتوانید فرآیند جاری را با دکمه "لغو استنتاج" متوقف کنید.
- باز کردن خروجی: پس از اتمام، از دکمه "باز کردن پوشه خروجی" برای دسترسی سریع به فایلهای تولید شده استفاده کنید.
inference.py عمل میکند. برای گزینههای پیشرفته یا رفع اشکال، به دستورالعملهای خط فرمان مراجعه کنید.استنتاج از طریق خط فرمان
برای کاربرانی که خط فرمان را ترجیح میدهند یا به تنظیمات پیشرفته نیاز دارند، مراحل زیر را دنبال کنید. توجه: برای رابط کاربری سادهتر، لطفاً به بخش رابط کاربری وب (توصیهشده) در بالا مراجعه کنید.
اسکریپت inference.py را اجرا کنید و برخی آرگومانها را برای تولید بیتمپها وارد کنید. برای این منظور از سینتکس override های 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را ویرایش کرده و آرگومانهای خود را به جای وارد کردن هر بار در ترمینال، آنجا اضافه کنید. - تمام توصیفکنندههای موجود را میتوانید اینجا پیدا کنید.
- همیشه یک آرگومان سال بین ۲۰۰۷ تا ۲۰۲۳ ارائه دهید. اگر نامشخص بگذارید، مدل ممکن است تولیدی با سبک ناسازگار ایجاد کند.
- همیشه یک آرگومان سختی ارائه دهید. اگر نامشخص بگذارید، مدل ممکن است تولیدی با سختی ناسازگار ایجاد کند.
- پارامتر
cfg_scaleرا افزایش دهید تا اثربخشی آرگومانهایmapper_idوdescriptorsبیشتر شود. - میتوانید از آرگومان
negative_descriptorsبرای هدایت مدل دور از سبکهای خاص استفاده کنید. این فقط زمانی کار میکند کهcfg_scale > 1باشد. مطمئن شوید تعداد توصیفکنندههای منفی با تعداد توصیفکنندهها برابر باشد. - اگر سبک آهنگ شما با سبک نقشه ضرب مورد نظر مطابقت خوبی نداشته باشد، مدل ممکن است از دستورالعملهای شما پیروی نکند. به عنوان مثال، تولید نقشه ضرب با SR بالا و SV بالا برای یک آهنگ آرام دشوار است.
- اگر زمانبندی و زمانهای Kiai آهنگ را قبلاً انجام دادهاید، میتوانید این اطلاعات را به مدل بدهید تا سرعت و دقت استنتاج به طور قابل توجهی افزایش یابد: از آرگومانهای
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 نمیتوانند آنها را تشخیص دهند. میتواند مشکلاتی مانند:
- ضرب یا الگوهای ریتمیک نادرست
- نقاط زمانبندی غیر دقیق
- موقعیتهای ناسازگار اشیاء ضرب یا قرارگیری نامناسب کامبوهای جدید
- اشکال عجیب اسلایدرها
- هیتساند یا حجمهای ناسازگار
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، باید Mapperatorinator را نصب کنید. سپس اسکریپتmai_mod_ui.py را اجرا کنید. این کار یک وب سرور محلی راهاندازی کرده و رابط کاربری را به طور خودکار در یک پنجره جدید باز میکند:python mai_mod_ui.py
نمای کلی
توکنیزاسیون
Mapperatorinator نقشههای osu! را به یک نمایش رویدادی واسط تبدیل میکند که میتواند مستقیماً به توکنها تبدیل شود و بالعکس. این شامل آبجکتهای ضربه، صدای ضربهها، سرعت اسلایدرها، کمبوهای جدید، نقاط زمانی، زمانهای kiai و سرعت اسکرول taiko/mania است.
در اینجا یک مثال کوچک از فرآیند توکنیزاسیون آمده است:
برای صرفهجویی در اندازه واژگان، رویدادهای زمانی به بازههای ۱۰ میلیثانیهای و مختصات موقعیت به نقاط شبکهای ۳۲ پیکسلی کوانتیزه میشوند.
معماری مدل
مدل اساساً یک لایه روی مدل HF Transformers Whisper است، با جاسازیهای ورودی و تابع زیان سفارشی. اندازه مدل برابر با ۲۱۹ میلیون پارامتر است. این مدل نسبت به T5 برای این وظیفه سریعتر و دقیقتر ارزیابی شد.نمای کلی سطح بالا از ورودی-خروجی مدل به شرح زیر است:
مدل از فریمهای اسپکتروگرام مل به عنوان ورودی رمزگذار استفاده میکند، با یک فریم برای هر موقعیت ورودی. خروجی رمزگشای مدل در هر گام یک توزیع softmax روی یک واژگان گسسته و از پیش تعریف شده از رویدادها است. خروجیها پراکنده هستند، رویدادها فقط زمانی نیاز هستند که یک آبجکت ضربه رخ دهد، به جای نشانهگذاری هر فریم صوتی.
قالب آموزش چندوظیفهای
قبل از توکن SOS، توکنهای اضافی وجود دارند که تولید شرطی را تسهیل میکنند. این توکنها شامل حالت بازی، سختی، شناسه سازنده، سال و سایر اطلاعات متا هستند. در طول آموزش، این توکنها برچسب همراه ندارند، بنابراین هیچگاه توسط مدل تولید نمیشوند. همچنین در طول آموزش، احتمال تصادفی وجود دارد که یک توکن متادیتا با یک توکن «ناشناخته» جایگزین شود، تا هنگام استنتاج بتوانیم از این توکنهای «ناشناخته» برای کاهش اطلاعات مورد نیاز مدل استفاده کنیم.
تولید بیوقفه طولانی
طول زمینه مدل برابر با ۸.۱۹۲ ثانیه است. این واضحاً برای تولید کامل یک beatmap کافی نیست، بنابراین باید آهنگ را به چندین پنجره تقسیم کنیم و beatmap را در بخشهای کوچک تولید کنیم. برای اطمینان از اینکه beatmap تولید شده در بین پنجرهها درز قابلتوجهی ندارد، از همپوشانی ۹۰٪ استفاده میکنیم و پنجرهها را به صورت متوالی تولید میکنیم. هر پنجره تولید به جز اولی با رمزگشا که تا ۵۰٪ پنجره تولید با توکنهای پنجره قبلی پر شده شروع میشود.
ما از یک پردازشگر لاجیت برای اطمینان از اینکه مدل نتواند توکنهای زمانی را که در ۵۰٪ اول پنجره تولید قرار دارند، تولید کند استفاده میکنیم. علاوه بر این، ۴۰٪ انتهایی پنجره تولید برای پنجره بعدی رزرو شده است. هر توکن زمانی تولید شده در این بازه به عنوان توکن EOS در نظر گرفته میشود. این کار تضمین میکند که هر توکن تولید شده حداقل بر اساس ۴ ثانیه توکن قبلی و ۳.۳ ثانیه صدای آینده شرطی شده است تا پیشبینی انجام دهد.
برای جلوگیری از رانش آفست در طول تولیدات طولانی، آفستهای تصادفی به رویدادهای زمانی در دیکودر در طول آموزش اضافه شدهاند. این باعث میشود مدل به جای تکیه بر زمانبندی دقیق، با گوش دادن به آغازها در صوت، خطاهای زمانی را اصلاح کند و نتیجه آن آفست دقیق و پایدار است.
مختصات پالایششده با دیفیوژن
مختصات مکانی تولید شده توسط دیکودر به شبکهای با گام ۳۲ پیکسل کوانتیده میشوند، بنابراین بعد از آن از دیفیوژن برای رفع نویز مختصات تا موقعیت نهایی استفاده میکنیم. برای این منظور نسخهای اصلاحشده از osu-diffusion را آموزش دادهایم که به طور ویژه برای ۱۰٪ انتهایی برنامه نویز تخصصی شده و توکنهای متادیتای پیشرفتهتر Mapperatorinator را برای تولید شرطی میپذیرد.
از آنجا که مدل Mapperatorinator مقدار SV اسلایدرها را خروجی میدهد، طول مورد نیاز اسلایدر صرفنظر از شکل مسیر نقطه کنترلی ثابت است. بنابراین تلاش میکنیم فرآیند دیفیوژن را برای تولید مختصاتی که با طول اسلایدر مورد نیاز مطابقت دارند هدایت کنیم. این کار را با محاسبه مجدد موقعیت انتهایی اسلایدر پس از هر گام فرآیند دیفیوژن بر اساس طول مورد نیاز و مسیر فعلی نقاط کنترلی انجام میدهیم. این به این معناست که فرآیند دیفیوژن کنترل مستقیم بر موقعیت انتهایی اسلایدر ندارد، اما هنوز میتواند با تغییر مسیر نقاط کنترلی بر آن تأثیر بگذارد.
پسپردازش
Mapperatorinator برخی پسپردازشهای اضافی برای بهبود کیفیت بیتمپ تولید شده انجام میدهد:
- پالایش مختصات مکانی با دیفیوژن.
- اسنپ کردن رویدادهای زمانی به نزدیکترین تیک با استفاده از تقسیمکنندههای اسنپ تولید شده توسط مدل.
- اسنپ کردن همپوشانیهای مکانی تقریبا کامل.
- تبدیل رویدادهای ستون مانیا به مختصات X.
- تولید مسیر اسلایدر برای طبلنوازیهای تایکو.
- رفع اختلافات بزرگ بین طول مورد نیاز اسلایدر و طول مسیر نقطه کنترلی.
تولیدکننده سوپرتایمینگ
تولیدکننده سوپرتایمینگ الگوریتمی است که دقت و صحت زمانبندی تولید شده را با استنتاج زمانبندی کل آهنگ به مدت ۲۰ بار و میانگینگیری نتایج افزایش میدهد. این برای آهنگهایی با BPM متغیر یا آهنگهایی با تغییر BPM مفید است. نتیجه تقریباً بینقص است و فقط گاهی بخشی نیاز به اصلاح دستی دارد.
آموزش
دستورالعمل زیر یک محیط آموزشی روی سیستم محلی شما ایجاد میکند.
۱. کلون کردن مخزن
git clone https://github.com/OliBomby/Mapperatorinator.git
cd Mapperatorinator۲. ایجاد دیتاست
دیتاست خود را با استفاده از برنامه کنسولی 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. ساخت کانتینر داکر
آموزش در محیط venv شما نیز ممکن است، اما ما استفاده از Docker بر روی WSL را برای عملکرد بهتر توصیه میکنیم.docker compose up -d --force-recreate
docker attach mapperatorinator_space
cd Mapperatorinator
۵. پیکربندی پارامترها و شروع آموزش
تمام تنظیمات در فایل ./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: 100Begin 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۶. ریزتنظیم با 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_path تعیین کنید.
این مسیر میتواند محلی یا یک مخزن Hugging Face باشد.همچنین ببینید
اعتبارات
تشکر ویژه از:
- نویسندگان osuT5 برای کد آموزش آنها.
- تیم Hugging Face برای ابزارهای آنها.
- Jason Won و Richard Nagyfi برای تبادل ایدهها.
- Marvin برای اهدا اعتبار آموزش.
- جامعه osu! برای beatmapها.
آثار مرتبط
- تولیدکننده Beatmap برای 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)