nesformer yordamida kompilyatsiya qilingan Qwen3.5 modeli ichida NES o‘yinlarini ishga tushiring

nesformer nima?

nesformer — konsolning 6502 protsessori, 2 KB ishchi RAM’i va kartrij dastur ROM’i standart Qwen3_5ForCausalLM checkpointining og‘irliklari va holati ichida ishlaydigan eksperimental NES runtime’idir. Og‘irliklar o‘qitilmagan. Buning o‘rniga kompilyator ularni protsessor sxemasini amalga oshirish uchun hisoblab chiqadi.

O‘yin davomida model protsessor bajarilish jurnalini bir vaqtning o‘zida bitta token orqali bashorat qiladi. Python host dasturi konsolning qolgan qismlarini ta’minlaydi: grafikani chizadi, kontroller kiritmalarini o‘qiydi, vaqtni boshqaradi, kiritish-chiqarish o‘qishlariga javob beradi va vertikal bo‘shliqdagi NMI uzilishini kiritadi.

Loyiha Qwenputer asosida qurilgan va uning kompilyatori hamda markaziy xotira texnikasidan qayta foydalanadi. Har bir Gated DeltaNet boshi holat matritsasini saqlaydi. One-hot kalitlar va so‘rovlar ushbu matritsadagi qatorlarga xotira kataklari kabi ishlash, registrlar, RAM va kartrij ma’lumotlarini saqlash imkonini beradi.

Asosiy imkoniyatlar

• O‘qitilmaydi, kompilyatsiya qilinadi: nolga teng bo‘lmagan har bir og‘irlik sxema spetsifikatsiyasidan hosil qilinadi.
• Standart checkpoint formati: checkpoint oddiy Hugging Face papkasi bo‘lib, uni maxsus model kodisiz Qwen3_5ForCausalLM.from_pretrained yordamida yuklash mumkin.
• 6502’ning to‘liq rasmiy ko‘rsatmalar to‘plami: sxema barcha 151 ta rasmiy opcode, adreslash rejimlari, flaglar, stek operatsiyalari, BRK va NMI’ga kirishni amalga oshiradi.
• Qayta foydalaniladigan NROM qo‘llovi: ishga tushirishda tanlangan kartrij model holatiga yozilgani sababli bir xil og‘irliklar turli iNES mapper 0 ROM’larini ishga tushira oladi.
• Skript orqali boshqarish: tugma bosishlarini buyruq satridan kadrlar bo‘yicha rejalashtirish mumkin.
• Vizual eksport: ishga tushirishlarni mos terminalda ko‘rsatish va GIF yoki PNG kadrlar sifatida saqlash mumkin.
• Bajarilishni tekshirish: check buyrug‘i model chiqishini birga keltirilgan referens protsessor bilan taqqoslaydi va birinchi farqda to‘xtaydi.
• Bir nechta bajarish mexanizmi: nesformer tezkor numba mexanizmi, oddiy NumPy mexanizmi va standart Transformers mexanizmini taqdim etadi.

Model ichida nimalar ishlashini tushunish

Checkpoint 6502 yadrosini, protsessor registrlari va flaglarini, 2 KB ishchi RAM’ni hamda belgilangan 32 KB dastur-ROM jadvalini o‘z ichiga oladi. Shuningdek, u dastur olish, ma’lumot o‘qish, stek operatsiyalari va OAM DMA o‘qishlarini ham boshqaradi.

Host PPU rendereri, palitra, kontrollerlar, vblank NMI vaqti, sikllarni sanash va APU registrlarini boshqarish uchun javobgar bo‘lib qoladi. Ovoz amalga oshirilmagan. Host kiritish-chiqarish o‘qishlari va NMI hodisalari uchun qiymatlarni tokenlar oqimiga kiritadi, biroq chiqarilgan izdan tashqarida model registrlari yoki RAM’ni bevosita tekshirmaydi.

nesformer model inferensiyasi orqali protsessorni emulyatsiya qiladi, ammo u to‘liq NES’ni butunlay og‘irliklar ichida amalga oshirmaydi.

Talablar va papkalarni sozlash

Sizga Python 3.11 yoki undan yangiroq versiyasi, nesformer manba arxivi va alohida og‘irliklar arxivi kerak bo‘ladi. Ikkala arxivni bir xil yuqori darajadagi papkaga chiqaring. weights papkasi Python paketi ichida emas, uning yonida joylashishi kerak.

nesformer/
├── nesformer/
├── chipformer/
├── roms/
├── examples/
├── tests/
├── pyproject.toml
└── weights/
    ├── config.json
    ├── generation_config.json
    ├── model.safetensors
    ├── nesformer.json
    └── SHA256SUMS

Barcha buyruqlarni yuqorida ko‘rsatilgan yuqori darajadagi papkadan ishga tushiring. Sukut bo‘yicha CLI weights/ papkasini nesformer/ paketi yonidan izlaydi.

Yuklab olingan og‘irliklarni tekshirish

Og‘irliklar to‘g‘ri chiqarilganini tasdiqlash uchun birga keltirilgan checksum faylidan foydalaning:

shasum -a 256 -c weights/SHA256SUMS

Checkpoint’ni boshqa joyda saqlasangiz, run, check yoki trace buyruqlaridan foydalanganda uning joylashuvini --weights /path/to/weights orqali ko‘rsating. info buyrug‘i checkpoint yo‘lini bevosita qabul qiladi.

nesformer’ni o‘rnatish

Virtual muhit yarating va uni faollashtiring, so‘ngra kerakli sonli hisoblash va tasvirni qayta ishlash paketlarini o‘rnating:

python3 -m venv .venv
source .venv/bin/activate
pip install numpy scipy numba pillow

Windows’da muhitni quyidagi buyruq bilan faollashtiring:

.venv\Scripts\activate

Sukut bo‘yicha fast mexanizmi numba’dan foydalanadi. Uning birinchi ishga tushirilishida mexanizmni kompilyatsiya qilish uchun taxminan 20 soniya ketadi. Keyingi ishga tushirishlarda ushbu kompilyatsiya natijasi qayta ishlatiladi.

Birinchi o‘yiningizni ishga tushiring

Repository’da erkin litsenziyalangan test ROM’lari mavjud. Quyidagi buyruq Thwaite’ni 600 kadr davomida ishga tushiradi, kadrlarni terminalda ko‘rsatadi va Start hamda A tugmalarining skript orqali berilgan ketma-ket bosilishlarini yuboradi:

python -m nesformer run roms/thwaite.nes --frames 600 --show \
  --buttons "start@90-95+200-205,a@230-233+250-253+270-273+290-293+310-313+330-333+350-353+370-373+390-393+410-413+430-433+450-453+470-473+490-493+510-513+530-533+550-553+570-573+590-593"

--show opsiyasi har bir hosil qilingan kadrni 24-bit rangni qo‘llab-quvvatlaydigan terminalda, masalan iTerm2 yoki Windows Terminal’da chizadi. Bajarilish tugagach, CLI ROM nomi asosida animatsiyalangan GIF’ni, masalan thwaite.gif faylini saqlaydi.

Ishlash tezligi haqiqiy NES’nikidan ancha past. Dastlabki kompilyatsiyadan so‘ng bitta kadr odatda bir-olti soniya vaqt oladi. 600 kadrli ishga tushirish NES vaqtining 10 soniyasini ifodalaydi va taxminan 25 daqiqa davom etishi mumkin.

Mos ROM’ingizni ishga tushiring

Qonuniy ravishda olingan ROM’ingizni roms/ papkasiga joylashtiring yoki boshqa yo‘lni ko‘rsating. ROM NROM platasidan foydalanishi va iNES mapper 0 sifatida aniqlanishi kerak. Mos misollar qatoriga Super Mario Bros., Donkey Kong va Excitebike kiradi, biroq ushbu tijoriy ROM’lar birga keltirilmagan.

Bu misol Super Mario Bros. o‘yinini ishga tushiradi, Right tugmasini bosib turadi va bir nechta sakrashni rejalashtiradi:

python -m nesformer run roms/smb.nes --frames 600 --show \
  --buttons "start@60-65,right@200-600,a@250-265+300-315+360-375+420-435+480-495+540-555"

ROM ishga tushirilganda modelning DeltaNet holatiga yuklanadi. Har bir mos o‘yin uchun checkpointni qayta yaratish shart emas.

Kontrollerni skript orqali boshqarish

--buttons parametri vergul bilan ajratilgan yozuvlarni qabul qiladi. Har bir yozuvda bir yoki bir nechta tugma nomi, @ belgisi va bir yoki bir nechta kadr oralig‘i bo‘ladi.

start@60-65
right@200-600
a@250-265+300-315
right+b@200-600

• start@60-65 60-kadrdan 65-kadrgacha Start tugmasini bosadi.
• right@200-600 belgilangan oraliqda Right tugmasini bosib turadi.
• a@250-265+300-315 A tugmasini ikki marta bosishni rejalashtiradi.
• right+b@200-600 Right va B tugmalarini bir vaqtda bosib turadi.

Mavjud nomlar: a, b, select, start, up, down, left va right. Kadrlar qurilma yoqilgan paytdan boshlab hisoblanadi va soniyasiga 60 kadr tezlikda ilgarilaydi. Shuning uchun 600-kadr NES vaqtining 10 soniyasiga to‘g‘ri keladi.

Odatda tugmani biroz oldinroq bosish xavfsiz, chunki o‘yinlar harakat mavjud bo‘lmagan ekranlarda boshqaruvlarni e’tiborsiz qoldiradi. Tugmani bosib turish davomiyligi muhim bo‘lishi mumkin; masalan, Super Mario Bros. o‘yinida A tugmasini uzoqroq bosish balandroq sakrashga olib keladi.

Kadr chiqishini boshqarish

Odatiy holatda run 120 kadrni bajaradi va ROM nomi asosida GIF fayl yozadi. Natijani moslashtirish uchun chiqish parametrlaridan foydalaning:

python -m nesformer run roms/thwaite.nes \
  --frames 300 \
  --every 2 \
  --scale 3 \
  --gif output/thwaite.gif

• --frames N N ta kadrdan keyin to‘xtaydi.
• --gif PATH animatsiyali GIF manzilini belgilaydi.
• --png DIR saqlangan kadrlarni alohida PNG fayllari sifatida yozadi.
• --every N har N-kadrda bittasini saqlaydi.
• --scale N saqlangan kadrlarni butun sonli koeffitsiyent bilan kattalashtiradi.
• --show yaratilgan kadrlarni terminalda ko‘rsatadi.

--png parametrining o‘zi GIF chiqishini o‘chiradi. PNG kadrlar va animatsiya ikkalasi ham kerak bo‘lsa, aniq --gif parametrini qo‘shing.

python -m nesformer run roms/thwaite.nes \
  --frames 120 \
  --png frames \
  --gif thwaite.gif

Bajarilishni tekshirish va tasdiqlash

Ma’lumotnoma CPU bilan solishtirish

check buyrug‘i checkpoint va loyihaning odatiy 6502 ma’lumotnoma dasturini yonma-yon ishga tushiradi. U birinchi token farqida to‘xtaydi:

python -m nesformer check roms/thwaite.nes --tokens 50000

Odatiy solishtirish uzunligi 50 000 tokenni tashkil etadi. Boshqa bajarish buyruqlari qabul qiladigan --buttons, --weights, --engine va --no-skip parametrlarini ham berishingiz mumkin.

Model tokenlar oqimini chiqarish

Model chiqargan CPU yozuvlarini tekshirish uchun trace buyrug‘idan foydalaning:

python -m nesformer trace roms/thwaite.nes --tokens 100

Odatiy trace uzunligi 40 tokenni tashkil etadi. Aksariyat CPU ko‘rsatmalari bitta tokenni talab qiladi, I/O, ko‘rsatkichlarni o‘qish, stek operatsiyalari yoki DMA bilan bog‘liq ko‘rsatmalar esa bir nechta tokenli yozuvlarni hosil qilishi mumkin.

Ishlash vaqtida token IDlarini saqlash

run buyrug‘i keyingi tahlil uchun yaratilgan token IDlarini faylga yozishi mumkin:

python -m nesformer run roms/thwaite.nes \
  --frames 60 \
  --trace trace.txt

Faqat kadr chegarasiga tayanish o‘rniga, bajarilishni belgilangan miqdordagi yaratilgan tokenlardan keyin to‘xtatish uchun --max-tokens N parametridan ham foydalanishingiz mumkin.

Bajarish mexanizmini tanlash

nesformer unumdorlik va bog‘liqlik talablari turlicha bo‘lgan uchta mexanizmni taqdim etadi:

• fast: odatiy numba implementatsiyasi. README ma’lumotiga ko‘ra, ishlab chiqish mashinasining bitta CPU yadrosida soniyasiga taxminan 1 650 token.
• numpy: soddaroq NumPy implementatsiyasi, uning tezligi taxminan soniyasiga 210 token deb ko‘rsatilgan.
• hf: standart Hugging Face Transformers, tezligi taxminan soniyasiga 10 token deb ko‘rsatilgan.

Mexanizmni --engine parametri orqali tanlang:

python -m nesformer run roms/thwaite.nes --frames 3 --engine numpy

Standart Transformers’dan foydalanish

Hugging Face mexanizmini tanlashdan oldin qo‘shimcha bog‘liqliklarni o‘rnating:

pip install "torch>=2.6" "transformers>=5.22"
python -m nesformer run roms/thwaite.nes --frames 3 --engine hf

Checkpoint uchun maxsus model implementatsiyasi kerak emas. Ichkarida nesformer uni yuklaydi, bitta to‘ldiruvchi tokenni dekodlaydi, boshlang‘ich mashina holatini keshning DeltaNet holatlariga yozadi va keyin yaratilgan tokenlarni birma-bir qayta uzatadi.

Qo‘shimcha maslahatlar

Og‘irliklarni repozitoriydan tashqarida saqlash

Checkpoint boshqa joyda saqlangan bo‘lsa, --weights parametridan foydalaning:

python -m nesformer run roms/thwaite.nes \
  --weights /path/to/weights \
  --frames 120

Checkpoint metama’lumotlarini tekshirish

Checkpointni tavsiflash uchun ma’lumot buyrug‘idan foydalaning:

python -m nesformer info

Og‘irliklar odatiy katalogda bo‘lmasa, ularning manzilini info buyrug‘iga bering.

Checkpointni qayta yaratish

Repozitoriyda circuit checkpointni qayta yaratish uchun zarur kompilyator mavjud. Oddiy build weights/ katalogiga yozadi va README ma’lumotiga ko‘ra, taxminan 10 soniya davom etadi:

python -m nesformer build

Boshqa chiqish katalogini quyidagicha tanlang:

python -m nesformer build --out compiled-weights

Bo‘sh sikllarni o‘tkazib yuborishni tushunish

NES o‘yinlari ko‘pincha zich sikllarda vblank’ni kutadi. Xost RAM yoki kiritish-chiqarishga hech qanday yozish amalini bajarmaydigan, aynan takrorlanuvchi siklni aniqlasa, soatni keyingi PPU hodisasiga yaqin vaqtgacha oldinga suradi va qolgan iteratsiyalarni ishga tushiradi. Bu optimallashtirish ko‘rinadigan kadrlar va kiritish-chiqarish vaqtini saqlagan holda tokenlar generatsiyasini sezilarli darajada kamaytiradi.

Har bir bo‘sh sikl iteratsiyasini bajarish uchun --no-skip parametrini uzating. Bu sekinroq, ammo to‘liq tokenlar ketma-ketligini o‘rganishda foydali bo‘lishi mumkin:

python -m nesformer trace roms/thwaite.nes --tokens 100 --no-skip

Testlar to‘plamini ishga tushirish

Testlash bog‘liqliklarini o‘rnating va pytest’ni ishga tushiring:

pip install pytest py65
python -m pytest -q tests

Testlar bir necha daqiqa davom etadi. Ular ma’lumotnoma protsessorini nestest jurnali bilan taqqoslaydi, kompilyatsiya qilingan sxemani ma’lumotnoma bilan tekshiradi, erkin ishlaydigan og‘irliklarni tasdiqlaydi va bo‘sh sikl optimallashtirishini sinaydi.

Muhim cheklovlar

• Faqat NROM: o‘yinlar iNES mapper 0’dan foydalanishi kerak. MMC1 va MMC3 kabi bank almashtiruvchi mapperlar qo‘llab-quvvatlanmaydi.
• Faqat rasmiy opkodlar: norasmiy 6502 opkodi uchrasa, HALT chiqariladi.
• ROM’dan bajarish: kod kartrij ROM’idan bajarilishi kerak; RAM’ga sakrash HALT chiqaradi.
• IRQ qo‘llab-quvvatlanmaydi: BRK va NMI ishlaydi, ammo APU frame va DMC IRQ’lari ishlamaydi.
• Cheklangan kiritish-chiqarish xatti-harakati: kiritish-chiqarish registrlaridagi o‘qish-o‘zgartirish-yozish ko‘rsatmalari kiritish-chiqarish yozuvini hosil qilmaydi, $4020 dan $7FFF gacha bo‘lgan manzillar esa nol sifatida o‘qiladi.
• Grafika tafsilotlari taxminiy: renderlash bir vaqtning o‘zida bitta skan-qator bo‘yicha amalga oshiriladi, skan-qator o‘rtasidagi effektlar takrorlanmaydi, sprite-0 urilishi va sprite toshib ketishi taxminiy hisoblanadi.
• Audio yo‘q: APU registrlariga yozishlar qabul qilinadi, ammo tovush hosil qilinmaydi.
• Sekin ishlash: bo‘sh sikllarni o‘tkazib yuborish yoqilganida ham loyiha haqiqiy konsoldan taxminan 150–290 marta sekinroq ishlaydi.

Xulosa

nesformer transformer chekpointi o‘qitilgan til modeli emas, balki aniq kompilyatsiya qilingan kompyuter sifatida xizmat qilishi mumkinligini namoyish etadi. Manba va og‘irliklar to‘g‘ri joylashtirilgach, mos NROM o‘yinlarini ishga tushirish, boshqaruv kiritishlarini avtomatlashtirish, kadrlarni eksport qilish, protsessor tokenlarini tekshirish va bajarilishni ma’lumotnoma 6502 bilan taqqoslash mumkin. Uning mapper, grafika, audio va tezlik bo‘yicha cheklovlari uni eksperimental tizimga aylantiradi, ammo standart Qwen3.5 chekpointi va tekshirish vositalari model og‘irliklari hamda DeltaNet holatiga bevosita kodlangan hisoblashni o‘rganishning amaliy usulini taqdim etadi.