Web Analytics

Mapperatorinator

⭐ 398 stars Persian by OliBomby

🌐 زبان

Mapperatorinator

مدل مولد را اینجا امتحان کنید، یا MaiMod را اینجا بررسی کنید. نمایش ویدیویی را اینجا ببینید.

Mapperatorinator یک چارچوب چندمدلی است که از ورودی‌های طیف‌نگار برای تولید نقشه‌های کامل osu! برای همه حالت‌های بازی و کمک به مدسازی نقشه‌ها استفاده می‌کند. هدف این پروژه تولید خودکار نقشه‌های osu! با کیفیت قابل رتبه‌بندی از هر آهنگی با درجه بالایی از سفارشی‌سازی است.

این پروژه بر پایه osuT5 و osu-diffusion ساخته شده است. در توسعه این پروژه حدود ۲۵۰۰ ساعت محاسبات GPU در ۱۴۲ اجرا روی ۴۰۶۰ Ti خودم و نمونه‌های اجاره‌ای ۴۰۹۰ در vast.ai صرف کردم.

#### از این ابزار به صورت مسئولانه استفاده کنید. همیشه استفاده از هوش مصنوعی در بیت‌مپ‌های خود را افشا کنید.

نصب

دستورالعمل زیر به شما اجازه می‌دهد تا بیت‌مپ‌ها را بر روی دستگاه محلی خود تولید کنید، همچنین می‌توانید آن را در فضای ابری با دفترچه colab اجرا کنید.

۱. مخزن را کلون کنید

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

۳. نصب وابستگی‌ها

pip install -r requirements.txt

رابط کاربری وب (توصیه‌شده)

برای تجربه‌ای کاربرپسندتر، استفاده از رابط کاربری وب را مدنظر قرار دهید. این رابط، یک واسط گرافیکی برای تنظیم پارامترهای تولید، شروع فرایند و نظارت بر خروجی فراهم می‌کند.

راه‌اندازی رابط کاربری گرافیکی

در ترمینال خود به پوشه‌ی کلون‌شده‌ی Mapperatorinator بروید و اجرا کنید:

python web-ui.py
این کار یک وب سرور محلی را راه‌اندازی کرده و رابط کاربری را به طور خودکار در یک پنجره جدید باز می‌کند.

استفاده از رابط گرافیکی (GUI)

رابط کاربری وب به عنوان یک پوشش راحت بر روی اسکریپت inference.py عمل می‌کند. برای گزینه‌های پیشرفته یا رفع اشکال، به دستورالعمل‌های خط فرمان مراجعه کنید.

python_u3zyW0S3Vs

استنتاج از طریق خط فرمان

برای کاربرانی که خط فرمان را ترجیح می‌دهند یا به تنظیمات پیشرفته نیاز دارند، مراحل زیر را دنبال کنید. توجه: برای رابط کاربری ساده‌تر، لطفاً به بخش رابط کاربری وب (توصیه‌شده) در بالا مراجعه کنید.

اسکریپت 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)

این اسکریپت شما را مرحله به مرحله از طریق مجموعه‌ای از پرسش‌ها برای پیکربندی تمام پارامترهای تولید راهنمایی می‌کند، درست مانند رابط کاربری وب.

از یک رابط رنگی برای وضوح بیشتر استفاده می‌کند. یک منوی پیشرفته چندانتخابی برای انتخاب توصیف‌کننده‌های سبک با استفاده از کلیدهای جهت و کلید فاصله ارائه می‌دهد. پس از پاسخ به تمام سوالات، فرمان نهایی را برای بررسی شما نمایش می‌دهد. سپس می‌توانید تأیید کنید تا آن را مستقیم اجرا کنید یا لغو کرده و فرمان را برای استفاده دستی کپی کنید.

نکات تولید

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، باید Mapperatorinator را نصب کنید. سپس اسکریپت mai_mod_ui.py را اجرا کنید. این کار یک وب سرور محلی راه‌اندازی کرده و رابط کاربری را به طور خودکار در یک پنجره جدید باز می‌کند:

python mai_mod_ui.py
afbeelding

نمای کلی

توکنیزاسیون

Mapperatorinator نقشه‌های osu! را به یک نمایش رویدادی واسط تبدیل می‌کند که می‌تواند مستقیماً به توکن‌ها تبدیل شود و بالعکس. این شامل آبجکت‌های ضربه، صدای ضربه‌ها، سرعت اسلایدرها، کمبوهای جدید، نقاط زمانی، زمان‌های kiai و سرعت اسکرول taiko/mania است.

در اینجا یک مثال کوچک از فرآیند توکنیزاسیون آمده است:

mapperatorinator_parser

برای صرفه‌جویی در اندازه واژگان، رویدادهای زمانی به بازه‌های ۱۰ میلی‌ثانیه‌ای و مختصات موقعیت به نقاط شبکه‌ای ۳۲ پیکسلی کوانتیزه می‌شوند.

معماری مدل

مدل اساساً یک لایه روی مدل HF Transformers Whisper است، با جاسازی‌های ورودی و تابع زیان سفارشی. اندازه مدل برابر با ۲۱۹ میلیون پارامتر است. این مدل نسبت به T5 برای این وظیفه سریع‌تر و دقیق‌تر ارزیابی شد.

نمای کلی سطح بالا از ورودی-خروجی مدل به شرح زیر است:

Picture2

مدل از فریم‌های اسپکتروگرام مل به عنوان ورودی رمزگذار استفاده می‌کند، با یک فریم برای هر موقعیت ورودی. خروجی رمزگشای مدل در هر گام یک توزیع softmax روی یک واژگان گسسته و از پیش تعریف شده از رویدادها است. خروجی‌ها پراکنده هستند، رویدادها فقط زمانی نیاز هستند که یک آبجکت ضربه رخ دهد، به جای نشانه‌گذاری هر فریم صوتی.

قالب آموزش چندوظیفه‌ای

Multitask training format

قبل از توکن SOS، توکن‌های اضافی وجود دارند که تولید شرطی را تسهیل می‌کنند. این توکن‌ها شامل حالت بازی، سختی، شناسه سازنده، سال و سایر اطلاعات متا هستند. در طول آموزش، این توکن‌ها برچسب همراه ندارند، بنابراین هیچ‌گاه توسط مدل تولید نمی‌شوند. همچنین در طول آموزش، احتمال تصادفی وجود دارد که یک توکن متادیتا با یک توکن «ناشناخته» جایگزین شود، تا هنگام استنتاج بتوانیم از این توکن‌های «ناشناخته» برای کاهش اطلاعات مورد نیاز مدل استفاده کنیم.

تولید بی‌وقفه طولانی

طول زمینه مدل برابر با ۸.۱۹۲ ثانیه است. این واضحاً برای تولید کامل یک beatmap کافی نیست، بنابراین باید آهنگ را به چندین پنجره تقسیم کنیم و beatmap را در بخش‌های کوچک تولید کنیم. برای اطمینان از اینکه beatmap تولید شده در بین پنجره‌ها درز قابل‌توجهی ندارد، از همپوشانی ۹۰٪ استفاده می‌کنیم و پنجره‌ها را به صورت متوالی تولید می‌کنیم. هر پنجره تولید به جز اولی با رمزگشا که تا ۵۰٪ پنجره تولید با توکن‌های پنجره قبلی پر شده شروع می‌شود.

ما از یک پردازشگر لاجیت برای اطمینان از اینکه مدل نتواند توکن‌های زمانی را که در ۵۰٪ اول پنجره تولید قرار دارند، تولید کند استفاده می‌کنیم. علاوه بر این، ۴۰٪ انتهایی پنجره تولید برای پنجره بعدی رزرو شده است. هر توکن زمانی تولید شده در این بازه به عنوان توکن EOS در نظر گرفته می‌شود. این کار تضمین می‌کند که هر توکن تولید شده حداقل بر اساس ۴ ثانیه توکن قبلی و ۳.۳ ثانیه صدای آینده شرطی شده است تا پیش‌بینی انجام دهد.

برای جلوگیری از رانش آفست در طول تولیدات طولانی، آفست‌های تصادفی به رویدادهای زمانی در دیکودر در طول آموزش اضافه شده‌اند. این باعث می‌شود مدل به جای تکیه بر زمان‌بندی دقیق، با گوش دادن به آغازها در صوت، خطاهای زمانی را اصلاح کند و نتیجه آن آفست دقیق و پایدار است.

مختصات پالایش‌شده با دیفیوژن

مختصات مکانی تولید شده توسط دیکودر به شبکه‌ای با گام ۳۲ پیکسل کوانتیده می‌شوند، بنابراین بعد از آن از دیفیوژن برای رفع نویز مختصات تا موقعیت نهایی استفاده می‌کنیم. برای این منظور نسخه‌ای اصلاح‌شده از osu-diffusion را آموزش داده‌ایم که به طور ویژه برای ۱۰٪ انتهایی برنامه نویز تخصصی شده و توکن‌های متادیتای پیشرفته‌تر Mapperatorinator را برای تولید شرطی می‌پذیرد.

از آنجا که مدل Mapperatorinator مقدار SV اسلایدرها را خروجی می‌دهد، طول مورد نیاز اسلایدر صرف‌نظر از شکل مسیر نقطه کنترلی ثابت است. بنابراین تلاش می‌کنیم فرآیند دیفیوژن را برای تولید مختصاتی که با طول اسلایدر مورد نیاز مطابقت دارند هدایت کنیم. این کار را با محاسبه مجدد موقعیت انتهایی اسلایدر پس از هر گام فرآیند دیفیوژن بر اساس طول مورد نیاز و مسیر فعلی نقاط کنترلی انجام می‌دهیم. این به این معناست که فرآیند دیفیوژن کنترل مستقیم بر موقعیت انتهایی اسلایدر ندارد، اما هنوز می‌تواند با تغییر مسیر نقاط کنترلی بر آن تأثیر بگذارد.

پس‌پردازش

Mapperatorinator برخی پس‌پردازش‌های اضافی برای بهبود کیفیت بیت‌مپ تولید شده انجام می‌دهد:

تولیدکننده سوپرتایمینگ

تولیدکننده سوپرتایمینگ الگوریتمی است که دقت و صحت زمان‌بندی تولید شده را با استنتاج زمان‌بندی کل آهنگ به مدت ۲۰ بار و میانگین‌گیری نتایج افزایش می‌دهد. این برای آهنگ‌هایی با 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: 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

۶. ریزتنظیم با 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 که باید مد نظر قرار دهید:

در هنگام استنتاج، می‌توانید وزن‌های LoRA مورد نظر را با آرگومان lora_path تعیین کنید. این مسیر می‌تواند محلی یا یک مخزن Hugging Face باشد.

همچنین ببینید

اعتبارات

تشکر ویژه از:

آثار مرتبط

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