Dlala Imidlalo ye-NES Ngaphakathi Kwemodeli Ye-Qwen3.5 Ehlanganisiwe nge-nesformer

Yini i-nesformer?

i-nesformer iyindawo yokusebenza yokuhlola ye-NES lapho i-CPU engu-6502 yekhonsoli, i-RAM esebenzayo engu-2 KB, kanye ne-cartridge program ROM kusebenza ngaphakathi kwezisindo nesimo se-checkpoint evamile ye-Qwen3_5ForCausalLM. Lezi zisindo azizange ziqeqeshwe. Kunalokho, umhlanganisi wazibala ukuze zisebenzise isekethe ye-CPU.

Ngesikhathi somdlalo, imodeli ibikezela ilogi yokusebenza kwe-CPU ithokheni eyodwa ngesikhathi. Uhlelo lwe-Python olusingatha umsebenzi lunikeza ezinye izingxenye zekhonsoli: ludweba izithombe, lufunde okokufaka kwesilawuli, luphatha isikhathi, luphendule ukufundwa kwe-I/O, futhi lufake ukuphazamiseka kwe-NMI kwe-vertical blanking.

Le phrojekthi yakhela ku-Qwenputer futhi iphinde isebenzise umhlanganisi wayo kanye nendlela yayo yememori emaphakathi. Ikhanda ngalinye le-Gated DeltaNet ligcina i-matrix yesimo. Okhiye nemibuzo be-one-hot benza imigqa kuleyo matrix iziphathe njengamaseli ememori, igcine amarejista, i-RAM, kanye nedatha ye-cartridge.

Izici ezibalulekile

• Kuhlanganiswa esikhundleni sokuqeqeshwa: zonke izisindo ezingezona uziro zikhiqizwa kusukela ekucacisweni kwesekethe.
• Ifomethi evamile ye-checkpoint: i-checkpoint iyifolda evamile ye-Hugging Face futhi ingalayishwa nge-Qwen3_5ForCausalLM.from_pretrained ngaphandle kwekhodi yemodeli yangokwezifiso.
• Iqoqo eliphelele lemiyalelo esemthethweni ye-6502: isekethe isebenzisa wonke ama-opcode asemthethweni angu-151, izindlela zokukhomba, amafulegi, imisebenzi yesitaki, i-BRK, kanye nokungena kwe-NMI.
• Ukusekelwa kwe-NROM okuphinde kusetshenziswe: izisindo ezifanayo zingasebenzisa ama-ROM ahlukene e-iNES mapper 0 ngoba i-cartridge ekhethiwe ibhalwa esimweni semodeli ekuqaleni.
• Izilawuli ezibhalwe kusengaphambili: ukucindezelwa kwezinkinobho kungahlelwa ngohlaka kusuka kulayini womyalo.
• Ukuthunyelwa kwezithombe: ukusebenza kungaboniswa ku-terminal ehambisanayo futhi kugcinwe njengama-frame e-GIF noma e-PNG.
• Ukuqinisekiswa kokusebenza: umyalo we-check uqhathanisa okukhipha imodeli ne-CPU eyireferensi efakiwe futhi ume ekuhlukeni kokuqala.
• Izinjini eziningi zokusebenza: i-nesformer inenjini esheshayo ye-numba, injini evamile ye-NumPy, kanye nenjini ye-Transformers ejwayelekile.

Qonda okusebenza ngaphakathi kwemodeli

I-checkpoint iqukethe ingqikithi ye-6502, amarejista namafulegi e-CPU, i-RAM esebenzayo engu-2 KB, kanye nethebula elingaguquki le-program-ROM elingu-32 KB. Iphinde iphathe ukulandwa kwezinhlelo, ukufundwa kwedatha, imisebenzi yesitaki, kanye nokufundwa kwe-OAM DMA.

I-host isalokhu iphethe umdwebi we-PPU, iphalethi, izilawuli, isikhathi se-vblank NMI, ukubalwa kwemijikelezo, kanye nokuphathwa kwamarejista e-APU. Umsindo awusetshenziswa. I-host ifaka amanani okufundwa kwe-I/O nemicimbi ye-NMI emgqeni wamathokheni, kodwa ayihloli ngokuqondile amarejista noma i-RAM yemodeli ngaphandle komkhondo okhishiwe.

i-nesformer ilingisa i-CPU ngokusebenzisa inference yemodeli, kodwa ayiyona i-NES ephelele eyakhiwe ngaphakathi kwezisindo kuphela.

Izidingo nokuhlelwa kwamafolda

Udinga i-Python 3.11 noma entsha, ingobo yomlando yomthombo we-nesformer, kanye nengobo yomlando ehlukile yezisindo. Khipha womabili ama-archive kufolda efanayo esezingeni eliphezulu. Ifolda ye-weights kufanele ibe seceleni kwephakheji ye-Python, hhayi ngaphakathi kuyo.

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

Qalisa yonke imiyalo usuka kufolda esezingeni eliphezulu eboniswe ngenhla. Ngokuzenzakalela, i-CLI ibheka i-weights/ eseceleni kwephakheji ye-nesformer/.

Qinisekisa izisindo ezilandiwe

Sebenzisa ifayela le-checksum elifakiwe ukuqinisekisa ukuthi izisindo zikhishwe kahle:

shasum -a 256 -c weights/SHA256SUMS

Uma ugcina i-checkpoint kwenye indawo, nikeza indawo yayo nge---weights /path/to/weights lapho usebenzisa i-run, i-check, noma i-trace. Umyalo we-info wamukela indlela ye-checkpoint ngokuqondile.

Faka i-nesformer

Dala futhi uvule i-virtual environment, bese ufaka amaphakheji adingekayo ezibalo nasekucubunguleni izithombe:

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

Ku-Windows, vula indawo usebenzisa:

.venv\Scripts\activate

Injini ezenzakalelayo ye-fast isebenzisa i-numba. Ekusebenzeni kwayo kokuqala ichitha cishe imizuzwana engu-20 ihlanganisa injini. Ukusebenza okulandelayo kuphinde kusetshenziswe lowo msebenzi wokuhlanganisa.

Qalisa umdlalo wakho wokuqala

Indawo yokugcina ihlanganisa ama-ROM okuhlola anamalayisense akhululekile. Umyalo olandelayo usebenzisa i-Thwaite ama-frame angu-600, ubonise ama-frame ku-terminal, futhi unikeze ukulandelana okubhalwe kusengaphambili kokucindezelwa kwezinkinobho ze-Start ne-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"

Inketho ye---show idweba ifreyimu ngayinye ekhiqiziwe ku-terminal enokusekelwa kombala we-24-bit, njenge-iTerm2 noma i-Windows Terminal. Lapho ukusebenza sekuphelile, i-CLI igcina i-GIF enyakazayo eqanjwe nge-ROM, njenge-thwaite.gif.

Ukusebenza kuhamba kancane kakhulu kune-NES yangempela. Ngemva kokuhlanganiswa kokuqala, ifreyimu ngokuvamile ithatha cishe umzuzwana owodwa kuya kweyisithupha. Ukusebenza kwama-frame angu-600 kumelela imizuzwana engu-10 yesikhathi se-NES futhi kungathatha cishe imizuzu engu-25.

Qalisa i-ROM yakho ehambisanayo

Beka i-ROM oyithole ngokusemthethweni kufolda ye-roms/ noma unikeze enye indlela. I-ROM kufanele isebenzise ibhodi le-NROM, elikhonjwa njenge-iNES mapper 0. Izibonelo ezihambisanayo zifaka i-Super Mario Bros., i-Donkey Kong, ne-Excitebike, nakuba lawa ma-ROM ezentengiso engafakiwe.

Lesi sibonelo siqala i-Super Mario Bros., sibambe u-Right, bese sihlela ukweqa okuningana:

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"

IRO M ilayishwa esimweni se-DeltaNet semodeli ekuqaleni. Awudingi ukwakha kabusha i-checkpoint kumdlalo ngamunye ohambisanayo.

Lawula okokufaka kwesilawuli ngeskripthi

Inketho ethi --buttons yamukela okufakiwe okuhlukaniswe ngamakhoma. Okufakwayo ngakunye kuqukethe igama lenkinobho elilodwa noma amaningi, uphawu lwe-@, kanye nobubanzi befreyimu obubodwa noma ngaphezulu.

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

• start@60-65 icindezela u-Start kusukela kufreyimu 60 kuya kufreyimu 65.
• right@200-600 ibamba u-Right phakathi nesikhathi esishiwo.
• a@250-265+300-315 ihlela ukucindezelwa kwenkinobho A kabili.
• right+b@200-600 ibamba u-Right no-B ngesikhathi esisodwa.

Amagama atholakalayo athi a, b, select, start, up, down, left, kanye no-right. Amafreyimu aqala ngesikhathi sokuvulwa kwamandla futhi aqhubeke ngamafreyimu angu-60 ngomzuzwana. Ngakho ifreyimu 600 ihambisana nemizuzwana engu-10 yesikhathi se-NES.

Ngokuvamile kuphephile ukuqala ukucindezela ngaphambi kancane, ngoba imidlalo iyayiziba imiyalo ezikrinini lapho ukunyakaza kungatholakali khona. Ubude besikhathi inkinobho icindezelwe ngaso bungabaluleka; isibonelo, ukucindezela u-A isikhathi eside kwenza ukweqa kube phezulu ku-Super Mario Bros.

Lawula okukhiphayo kwamafreyimu

Ngokuzenzakalela, i-run isebenzisa amafreyimu angu-120 bese ibhala i-GIF eqanjwe ngegama le-ROM. Sebenzisa izinketho zokukhipha ukuze wenze umphumela ngendlela oyifunayo:

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

• --frames N ima ngemva kwamafreyimu angu-N.
• --gif PATH ikhetha indawo okuyiwa kuyo i-GIF egqwayizayo.
• --png DIR igcina amafreyimu agciniwe njengamafayela e-PNG ngamanye.
• --every N igcina wonke amafreyimu angu-N.
• --scale N ikhulisa amafreyimu agciniwe ngesici esiyinombolo ephelele.
• --show ibonisa amafreyimu akhiqiziwe kutheminali.

Ukusebenzisa --png kukodwa kukhubaza okukhiphayo kwe-GIF. Faka inketho ecacile ethi --gif uma ufuna kokubili amafreyimu e-PNG nokugqwayiza.

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

Hlola futhi uqinisekise ukusebenza

Qhathanisa ne-CPU eyireferensi

Umyalo othi check usebenzisa i-checkpoint kanye ne-6502 eyireferensi evamile yephrojekthi eceleni. Ima ekuhlukeni kokuqala kwethokheni:

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

Ubude bokuqhathanisa obuzenzakalelayo bungamathokheni angu-50,000. Ungadlulisa izinketho ezifanayo ezithi --buttons, --weights, --engine, kanye ne---no-skip ezamukelwa eminye imiyalo yokusebenza.

Phrinta uchungechunge lwamathokheni emodeli

Sebenzisa i-trace ukuze uhlole amarekhodi e-CPU akhishwa imodeli:

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

Ubude be-trace obuzenzakalelayo bungamathokheni angu-40. Imiyalo eminingi ye-CPU idinga ithokheni eyodwa, kanti imiyalo ehilela i-I/O, ukufundwa kwezikhombisi, imisebenzi yesitaki, noma i-DMA ingakhiqiza amarekhodi anamathokheni amaningi.

Gcina ama-ID amathokheni ngesikhathi sokusebenza

Umyalo othi run ungabhala ama-ID amathokheni akhiqiziwe efayeleni ukuze ahlaziywe kamuva:

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

Ungasebenzisa futhi --max-tokens N ukuze umise ukusebenza ngemva kwenani elinqunyiwe lamathokheni akhiqiziwe, esikhundleni sokuthembela kuphela emkhawulweni wamafreyimu.

Khetha injini yokusebenza

i-nesformer inikeza izinjini ezintathu ezinamazinga ahlukene okusebenza kanye nezidingo zokuncika:

• fast: ukuqaliswa okuzenzakalelayo kwe-numba. I-README ibika cishe amathokheni angu-1,650 ngomzuzwana ku-CPU core eyodwa yomshini wokuthuthukisa.
• numpy: ukuqaliswa okulula kwe-NumPy okubikwa cishe ngamathokheni angu-210 ngomzuzwana.
• hf: i-Hugging Face Transformers ejwayelekile, ebikwa cishe ngamathokheni angu-10 ngomzuzwana.

Khetha injini nge---engine:

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

Sebenzisa i-Transformers ejwayelekile

Faka okunye ukuncika ngaphambi kokukhetha injini ye-Hugging Face:

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

I-checkpoint ayidingi ukuqaliswa kwemodeli ngokwezifiso. Ngaphakathi, i-nesformer iyayilayisha, ihlukanise ithokheni yokugcwalisa eyodwa, ibhale isimo sokuqala somshini ezimweni ze-DeltaNet ze-cache, bese ibuyisela amathokheni akhiqiziwe ngamunye ngamunye.

Izeluleko ezithuthukile

Gcina izisindo ngaphandle kwe-repository

Sebenzisa --weights lapho i-checkpoint igcinwe kwenye indawo:

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

Hlola imethadatha ye-checkpoint

Sebenzisa umyalo wolwazi ukuchaza i-checkpoint:

python -m nesformer info

Uma izisindo zingekho kufolda ezenzakalelayo, nikeza i-info indlela yazo.

Yakha kabusha i-checkpoint

I-repository ihlanganisa i-compiler edingekayo ukuze ikhiqize kabusha i-checkpoint yesekhethi. Ukwakha okuvamile kubhalela ku-weights/ futhi kuthatha cishe imizuzwana engu-10 ngokwe-README:

python -m nesformer build

Khetha enye ifolda yokukhipha nge:

python -m nesformer build --out compiled-weights

Qonda ukweqa amaluphu angasebenzi

Imidlalo ye-NES ivamise ukulinda i-vblank kumaluphu aqinile. Lapho umsingathi ethola iluphu ephindaphindeka ngokunembile engenakho ukubhala ku-RAM noma ku-I/O, iqhubekisela iwashi eduze komcimbi olandelayo we-PPU bese iqhuba izimpinda ezisele. Lokhu kulungiselelwa kunciphisa kakhulu ukwenziwa kwamathokheni ngenkathi kugcinwa amafreyimu abonakalayo nesikhathi se-I/O.

Dlulisa i---no-skip ukuze kuqhutshwe zonke izimpinda zeluphu engasebenzi. Lokhu kuhamba kancane, kodwa kungasiza lapho ufunda ukulandelana kwamathokheni okuphelele:

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

Qalisa iqoqo lokuhlola

Faka okuncikile kokuhlola bese uqalisa i-pytest:

pip install pytest py65
python -m pytest -q tests

Ukuhlola kuthatha imizuzu embalwa. Kuqhathanisa i-CPU yereferensi nelogi ye-nestest, kuhlola isekhethi ehlanganisiwe iqhathaniswa nereferensi, kuqinisekisa izisindo ezisebenza ngokuqhubekayo, futhi kuhlola ukulungiselelwa kokweqa iluphu engasebenzi.

Imikhawulo ebalulekile

• I-NROM kuphela: imidlalo kufanele isebenzise i-iNES mapper 0. Ama-mapper ashintsha amabhange afana ne-MMC1 ne-MMC3 awasekelwa.
• Ama-opcode asemthethweni kuphela: ukuhlangana ne-opcode ye-6502 engekho emthethweni kukhipha i-HALT.
• Ukusebenzisa kusuka ku-ROM: ikhodi kufanele isebenze isuka ku-cartridge ROM; ukugxumela ku-RAM kukhipha i-HALT.
• Akukho kusekelwa kwe-IRQ: i-BRK ne-NMI kuyasebenza, kodwa ama-IRQ e-APU frame ne-DMC awasebenzi.
• Ukuziphatha kwe-I/O okulinganiselwe: imiyalelo ye-read-modify-write kumarejista e-I/O ayikhiqizi ukubhala kwe-I/O, futhi amakheli asuka ku-$4020 kuya ku-$7FFF afundeka njengoziro.
• Imininingwane yezithombe elinganiselwe: ukunikezwa kwenzeka nge-scanline eyodwa ngesikhathi, imiphumela yaphakathi kwe-scanline ayiphindaphindwa, futhi i-sprite-0 hit nokuchichima kwama-sprite kuyalinganiselwa.
• Awukho umsindo: ukubhalwa kwamarejista e-APU kuyamukelwa kodwa umsindo awukhiqizwa.
• Ukusebenza kuhamba kancane: ngisho noma kweqiwa amaluphu angasebenzi, iphrojekthi ihamba cishe kancane izikhathi ezingu-150 kuya kwezingu-290 kunekhonsoli yangempela.

Isiphetho

i-nesformer ikhombisa ukuthi i-transformer checkpoint ingasebenza njengekhompyutha ehlanganiswe ngokunembile, kunokuba ibe imodeli yolimi eqeqeshiwe kuphela. Uma umthombo nezisindo sekuhlelwe kahle, ungasebenzisa imidlalo ye-NROM ehambisanayo, wenze ngokuzenzakalelayo okokufaka kwesilawuli, ukhiphe amafreyimu, uhlole amathokheni e-CPU, futhi uqhathanise ukusebenza ne-6502 yereferensi. Imikhawulo yayo ku-mapper, ezithombeni, emsindweni, nasejubaneni iyenza ibe isistimu yokuhlola, kodwa i-Qwen3.5 checkpoint yayo ejwayelekile namathuluzi okuqinisekisa kunikeza indlela esebenzayo yokufunda ukubalwa okubhalwe ngokuqondile ezisindweni zemodeli nasesimweni se-DeltaNet.