mflux-model-porting

Skill do Cursora, który prowadzi Cię przez powtarzalny proces przenoszenia modeli uczenia maszynowego do frameworka mflux/MLX. Zamiast od razu optymalizować wydajność, skupiasz się najpierw na zgodności z implementacją referencyjną — porównujesz wyjścia, blokujesz poprawność testami deterministycznymi, a dopiero potem refaktoryzujesz kod do stylu mflux. Zawiera checklist workflow'u: definiowanie parity, szybkie przenoszenie do referencji, mapowanie wag, testowanie i ostateczną optymalizację.

1. Zainstaluj skill w Cursorze, wskazując repozytorium filipstrand/mflux. Skill będzie dostępny jako narzędzie do planowania i wsparcia przy portowaniu modeli.

2. Zdefiniuj zakres pracy: określ, jakie metryki parity chcesz osiągnąć (zgodność wyjść, prędkość, zużycie pamięci), jakie tolerancje są akceptowalne, i zidentyfikuj pliki referencyjne oraz checkpointy do skopiowania. Skill pomoże Ci przygotować plan Cursora przed rozpoczęciem implementacji.

3. Stwórz szkielet pakietu modelu z klasą wariantu i inicjalizatorem, podążając za strukturą niedawnych portów (np. z_image_turbo, flux2_klein). Wdróż mapowania wag wcześnie, aby ładowanie było testowane — możesz pominąć kwantyzację w pierwszych przebiegach.

4. Porównaj wyjścia modelu PyTorch z wyjściami MLX, używając tych samych danych wejściowych. Jeśli chcesz ścisłą parity dla szumów losowych, wyeksportuj dokładne początkowe tensory z referencji i załaduj je w MLX zamiast polegać na dopasowaniu seed'ów.

5. Zablokuj poprawność testami deterministycznymi, zanim zaczniesz refaktoryzować kod. Unikaj prematurowej optymalizacji (mx.compile, kernel fusion) — dodaj ją dopiero po tym, jak testy będą zielone.

6. Refaktoryzuj kod w kierunku wspólnych komponentów i czystych API'ów, korzystając ze wskazówek skilla dotyczących stylu mflux i najlepszych praktyk.