Cheza Michezo ya NES Ndani ya Muundo wa Qwen3.5 Uliokusanywa kwa nesformer

nesformer ni nini?

nesformer ni runtime ya majaribio ya NES ambapo CPU ya console ya 6502, RAM ya kazi ya KB 2, na ROM ya programu ya katriji hufanya kazi ndani ya uzito na hali ya checkpoint ya kawaida ya Qwen3_5ForCausalLM. Uzito haukufunzwa. Badala yake, compiler iliuhesabu ili utekeleze mzunguko wa CPU.

Wakati wa mchezo, modeli hutabiri kumbukumbu ya utekelezaji wa CPU tokeni moja kwa wakati. Programu ya mwenyeji ya Python hutoa vipengele vilivyosalia vya console: huchora michoro, husoma ingizo la kidhibiti, hushughulikia muda, hujibu usomaji wa I/O, na huingiza usumbufu wa NMI wa vertical blanking.

Mradi huu umejengwa juu ya Qwenputer na hutumia tena compiler yake pamoja na mbinu yake kuu ya kumbukumbu. Kila kichwa cha Gated DeltaNet hudumisha matriki ya hali. Vifunguo na hoja za one-hot huruhusu safu katika matriki hiyo kufanya kazi kama seli za kumbukumbu, zikihifadhi rejesta, RAM, na data ya katriji.

Vipengele muhimu

• Imekompailiwa badala ya kufunzwa: kila uzito usio sifuri hutengenezwa kutokana na maelezo ya mzunguko.
• Muundo wa kawaida wa checkpoint: checkpoint ni folda ya kawaida ya Hugging Face na inaweza kupakiwa kwa Qwen3_5ForCausalLM.from_pretrained bila msimbo maalum wa modeli.
• Seti kamili rasmi ya maagizo ya 6502: mzunguko hutekeleza opcodes zote 151 rasmi, miundo ya anwani, bendera, shughuli za stack, BRK, na ingizo la NMI.
• Msaada unaoweza kutumika tena wa NROM: uzito uleule unaweza kuendesha ROM tofauti za iNES mapper 0 kwa sababu katriji iliyochaguliwa huandikwa katika hali ya modeli wakati wa kuanza.
• Vidhibiti vilivyoandikwa kwa hati: mibofyo ya vitufe inaweza kuratibiwa kwa fremu kupitia mstari wa amri.
• Uhamishaji wa picha: utekelezaji unaweza kuonyeshwa katika terminal inayooana na kuhifadhiwa kama fremu za GIF au PNG.
• Uthibitishaji wa utekelezaji: amri ya check hulinganisha matokeo ya modeli na CPU ya marejeleo iliyojumuishwa na husimama kwenye tofauti ya kwanza.
• Injini nyingi za utekelezaji: nesformer hutoa injini ya haraka ya numba, injini ya kawaida ya NumPy, na injini ya kawaida ya Transformers.

Elewa kinachoendesha ndani ya modeli

Checkpoint ina msingi wa 6502, rejesta na bendera za CPU, RAM ya kazi ya KB 2, na jedwali lisilobadilika la ROM ya programu la KB 32. Pia hushughulikia uchukuaji wa programu, usomaji wa data, shughuli za stack, na usomaji wa OAM DMA.

Mwenyeji bado anawajibika kwa kichoraji cha PPU, palette, vidhibiti, muda wa NMI ya vblank, kuhesabu mizunguko, na ushughulikiaji wa rejesta za APU. Sauti haijatekelezwa. Mwenyeji huingiza thamani za usomaji wa I/O na matukio ya NMI katika mtiririko wa tokeni, lakini haukagui moja kwa moja rejesta au RAM ya modeli nje ya ufuatiliaji unaotolewa.

nesformer huiga CPU kupitia uelekezaji wa modeli, lakini si NES kamili iliyotekelezwa yote ndani ya uzito.

Mahitaji na mpangilio wa folda

Unahitaji Python 3.11 au mpya zaidi, hifadhi ya chanzo ya nesformer, na hifadhi tofauti ya uzito. Toa hifadhi zote mbili katika folda moja ya kiwango cha juu. Saraka ya weights lazima iwe kando ya kifurushi cha Python badala ya kuwa ndani yake.

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

Endesha amri zote kutoka saraka ya kiwango cha juu iliyoonyeshwa hapo juu. Kwa chaguo-msingi, CLI hutafuta weights/ kando ya kifurushi cha nesformer/.

Thibitisha uzito uliopakuliwa

Tumia faili ya checksum iliyojumuishwa kuthibitisha kuwa uzito umetolewa kwa usahihi:

shasum -a 256 -c weights/SHA256SUMS

Ukiweka checkpoint mahali pengine, pitisha eneo lake kwa --weights /path/to/weights unapotumia run, check, au trace. Amri ya info hukubali moja kwa moja njia ya checkpoint.

Sakinisha nesformer

Unda na uwashe mazingira pepe, kisha sakinisha vifurushi vinavyohitajika vya nambari na uchakataji wa picha:

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

Kwenye Windows, washa mazingira kwa:

.venv\Scripts\activate

Injini ya fast ya chaguo-msingi hutumia numba. Uendeshaji wake wa kwanza hutumia takriban sekunde 20 kukompaili injini. Uendeshaji unaofuata hutumia tena kazi hiyo ya ukompaili.

Endesha mchezo wako wa kwanza

Hifadhi ya mradi inajumuisha ROM za majaribio zenye leseni huru. Amri ifuatayo huendesha Thwaite kwa fremu 600, huonyesha fremu kwenye terminal, na hutoa mfuatano ulioandikwa wa mibofyo ya vitufe vya Start na A:

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"

Chaguo la --show huchora kila fremu inayozalishwa kwenye terminal yenye msaada wa rangi za biti 24, kama iTerm2 au Windows Terminal. Utekelezaji unapokamilika, CLI huhifadhi GIF iliyohuishwa yenye jina la ROM, kama thwaite.gif.

Utendaji ni wa polepole zaidi kuliko NES halisi. Baada ya ukompaili wa awali, fremu kwa kawaida huchukua takriban sekunde moja hadi sita. Uendeshaji wa fremu 600 unawakilisha sekunde 10 za muda wa NES na unaweza kuchukua karibu dakika 25.

Endesha ROM yako inayooana

Weka ROM uliyoipata kihalali katika saraka ya roms/ au toa njia nyingine. ROM lazima itumie ubao wa NROM, unaotambuliwa kama iNES mapper 0. Mifano inayooana ni pamoja na Super Mario Bros., Donkey Kong, na Excitebike, ingawa ROM hizi za kibiashara hazijajumuishwa.

Katika mfano huu Super Mario Bros. inaanzishwa, kitufe cha Right kinashikiliwa, na miruko kadhaa inapangwa:

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 hupakiwa katika hali ya DeltaNet ya modeli wakati wa kuanzisha. Huhitaji kujenga upya checkpoint kwa kila mchezo unaooana.

Kuingiza vidhibiti kwa hati

Chaguo la --buttons hukubali maingizo yaliyotenganishwa kwa koma. Kila ingizo lina jina moja au zaidi la vitufe, alama ya @, na safu moja au zaidi za fremu.

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

• start@60-65 hubonyeza Start kuanzia fremu ya 60 hadi fremu ya 65.
• right@200-600 hushikilia Right kwa muda uliobainishwa.
• a@250-265+300-315 hupanga mibofyo miwili ya kitufe A.
• right+b@200-600 hushikilia Right na B kwa wakati mmoja.

Majina yanayopatikana ni a, b, select, start, up, down, left, na right. Fremu huanza wakati wa kuwasha na huendelea kwa fremu 60 kwa sekunde. Kwa hiyo, fremu ya 600 inalingana na sekunde 10 za muda wa NES.

Kwa kawaida ni salama kuanza kubonyeza mapema kidogo kwa sababu michezo hupuuza vidhibiti kwenye skrini ambazo harakati hazipatikani. Muda wa kubonyeza unaweza kuwa muhimu; kwa mfano, kubonyeza A kwa muda mrefu zaidi husababisha mruko wa juu zaidi katika Super Mario Bros.

Kudhibiti matokeo ya fremu

Kwa chaguo-msingi, run hutekeleza fremu 120 na kuandika GIF yenye jina la ROM. Tumia chaguo za matokeo kubinafsisha matokeo:

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

• --frames N husitisha baada ya fremu N.
• --gif PATH huchagua mahali pa GIF yenye uhuishaji.
• --png DIR huhifadhi fremu zilizochaguliwa kama faili mahususi za PNG.
• --every N huhifadhi kila fremu ya N.
• --scale N hukuza fremu zilizohifadhiwa kwa kizidishi kamili.
• --show huonyesha fremu zilizozalishwa kwenye terminali.

Kutumia --png pekee huzima matokeo ya GIF. Ongeza chaguo la wazi la --gif unapotaka fremu za PNG na uhuishaji kwa pamoja.

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

Kukagua na kuthibitisha utekelezaji

Kulinganisha na CPU ya rejeleo

Amri ya check huendesha checkpoint na 6502 ya kawaida ya rejeleo ya mradi kwa wakati mmoja. Husitisha inapopata tofauti ya kwanza ya tokeni:

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

Urefu wa chaguo-msingi wa ulinganisho ni tokeni 50,000. Unaweza kupitisha chaguo zilezile za --buttons, --weights, --engine, na --no-skip zinazokubaliwa na amri nyingine za utekelezaji.

Kuchapisha mtiririko wa tokeni wa modeli

Tumia trace kukagua rekodi za CPU zinazotolewa na modeli:

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

Urefu wa chaguo-msingi wa ufuatiliaji ni tokeni 40. Maagizo mengi ya CPU huhitaji tokeni moja, huku maagizo yanayohusisha I/O, usomaji wa vielekezi, utendakazi wa stack, au DMA yakizalisha rekodi za tokeni nyingi.

Kuhifadhi vitambulisho vya tokeni wakati wa uendeshaji

Amri ya run inaweza kuandika vitambulisho vya tokeni vilivyozalishwa kwenye faili kwa uchanganuzi wa baadaye:

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

Unaweza pia kutumia --max-tokens N kusitisha utekelezaji baada ya idadi maalum ya tokeni zilizozalishwa badala ya kutegemea kikomo cha fremu pekee.

Kuchagua injini ya utekelezaji

nesformer hutoa injini tatu zenye viwango tofauti vya utendaji na utegemezi:

• fast: utekelezaji chaguo-msingi wa numba. README inaripoti takribani tokeni 1,650 kwa sekunde kwenye kiini kimoja cha CPU cha mashine ya uundaji.
• numpy: utekelezaji rahisi wa NumPy unaoripotiwa kuwa na takribani tokeni 210 kwa sekunde.
• hf: Transformers za kawaida za Hugging Face, zikiripotiwa kuwa na takribani tokeni 10 kwa sekunde.

Chagua injini kwa kutumia --engine:

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

Kutumia Transformers za kawaida

Sakinisha vitegemezi vya ziada kabla ya kuchagua injini ya Hugging Face:

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

Checkpoint haihitaji utekelezaji maalum wa modeli. Ndani ya mfumo, nesformer huipakia, hufasiri tokeni moja ya padding, huandika hali ya awali ya mashine katika hali za DeltaNet za akiba, kisha hurudisha tokeni zilizozalishwa moja baada ya nyingine.

Vidokezo vya kina

Kuweka uzani nje ya hazina

Tumia --weights wakati checkpoint imehifadhiwa mahali pengine:

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

Kukagua metadata ya checkpoint

Tumia amri ya taarifa kueleza checkpoint:

python -m nesformer info

Ikiwa uzani hauko katika saraka chaguo-msingi, toa njia yake kwa info.

Kuunda upya checkpoint

Hazina inajumuisha compiler inayohitajika kuzalisha upya checkpoint ya mzunguko. Ujenzi wa kawaida huandika kwenye weights/ na huchukua takribani sekunde 10 kulingana na README:

python -m nesformer build

Chagua saraka nyingine ya matokeo kwa kutumia:

python -m nesformer build --out compiled-weights

Kuelewa kuruka mizunguko isiyotumika

Michezo ya NES mara nyingi husubiri vblank katika mizunguko mifupi. Mfumo mwenyeji anapotambua mzunguko unaojirudia kikamilifu bila maandishi kwenye RAM au I/O, husogeza saa karibu na tukio linalofuata la PPU kisha kutekeleza marudio yaliyosalia. Uboreshaji huu hupunguza kwa kiasi kikubwa uundaji wa tokeni huku ukihifadhi fremu zinazoonekana na muda wa I/O.

Pitisha --no-skip ili kutekeleza kila marudio ya mzunguko tulivu. Hii ni polepole zaidi, lakini inaweza kuwa muhimu unapochunguza mfuatano kamili wa tokeni:

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

Endesha seti ya majaribio

Sakinisha vitegemezi vya majaribio na uendeshe pytest:

pip install pytest py65
python -m pytest -q tests

Majaribio huchukua dakika chache. Hulinganisha CPU ya marejeo na kumbukumbu ya nestest, hukagua saketi iliyokusanywa dhidi ya marejeo, huthibitisha uzani unaoendesha bila kikomo, na hujaribu uboreshaji wa mzunguko tulivu.

Vikomo muhimu

• NROM pekee: michezo lazima itumie iNES mapper 0. Mapper zinazobadilisha benki kama MMC1 na MMC3 hazitumiki.
• Opkodi rasmi pekee: opkodi isiyo rasmi ya 6502 inapokumbana nayo, hutolewa HALT.
• Utekelezaji kutoka ROM: msimbo lazima utekelezwe kutoka ROM ya katriji; kurukia RAM hutoa HALT.
• Hakuna usaidizi wa IRQ: BRK na NMI hufanya kazi, lakini IRQ za fremu za APU na DMC hazifanyi kazi.
• Tabia ndogo ya I/O: maagizo ya kusoma-kubadilisha-kuandika kwenye rejista za I/O hayatoi uandishi wa I/O, na anwani kutoka $4020 hadi $7FFF husomeka kama sifuri.
• Maelezo ya michoro ya kukadiria: uchoraji hutokea mstari mmoja wa skani kwa wakati mmoja, athari za katikati ya mstari wa skani hazizalishwi upya, na hit ya sprite-0 pamoja na kufurika kwa sprite hukadiriwa.
• Hakuna sauti: uandishi kwenye rejista za APU hukubaliwa lakini sauti haitengenezwi.
• Utekelezaji wa polepole: hata kwa kuruka mizunguko tulivu, mradi huendesha takriban mara 150 hadi 290 polepole kuliko koni halisi.

Hitimisho

nesformer inaonyesha kwamba checkpoint ya transformer inaweza kutumika kama kompyuta iliyokusanywa kwa usahihi, badala ya kuwa tu modeli ya lugha iliyofunzwa. Baada ya chanzo na uzani kupangwa kwa usahihi, unaweza kuendesha michezo ya NROM inayooana, kuweka kiotomatiki ingizo la kidhibiti, kuhamisha fremu, kukagua tokeni za CPU, na kulinganisha utekelezaji dhidi ya 6502 ya marejeo. Vikomo vyake vya mapper, michoro, sauti na kasi vinaifanya kuwa mfumo wa majaribio, lakini checkpoint yake ya kawaida ya Qwen3.5 na zana za uthibitishaji vinatoa njia ya vitendo ya kuchunguza ukokotoaji uliowekwa moja kwa moja kwenye uzani wa modeli na hali ya DeltaNet.