MLX 모델 포팅 및 최적화은(는) 무엇을 하나요?

임무

정확하고 재현 가능하며 아키텍처 인식적인 MLX 구현을 만듭니다. 정확성이 속도보다 우선합니다. 모든 속도 또는 메모리 주장은 하드웨어, 소프트웨어 버전, 워크로드, 기준선 및 품질 관문을 명시해야 합니다.

변경 불가능한 규칙

수용 중에 신뢰할 수 없는 모델 코드를 실행하지 마십시오. JSON, safetensors 헤더, 소스 파일 및 라이선스를 정적으로 검사합니다. auto_map, 커스텀 모듈, 설치 훅 및 trust_remote_code를 검토 관문으로 취급합니다.
소스를 고정합니다. 저장소, 리비전, 모델 파일, 토크나이저/프로세서 리비전, 라이선스 및 체크섬 또는 아티팩트 매니페스트를 기록합니다.
포팅 전에 소스 오라클을 구축합니다. 결정론적 픽스처를 고정하고 의미 있는 경계에서 중간 텐서를 캡처합니다.
먼저 가장 작은 eager 경로를 포팅합니다. 기본 패리티가 통과할 때까지 양자화, 컴파일, 커스텀 커널, 배칭 또는 추측 디코딩을 수행하지 마십시오.
한 번에 하나의 최적화 차원을 변경합니다. 측정 및 롤백 기록을 유지합니다.
기본 MLX 연산을 선호합니다. 커스텀 Metal 커널 전에 기본 제공 융합 연산, 레이아웃 변경, 캐시 설계 및 mx.compile을 시도합니다.
CUDA 지식을 기계적으로 번역하지 마십시오. CUDA 기법은 Metal/MLX 병목 지점과 구현이 입증될 때까지 연구 후보일 뿐입니다.
처리량 뒤에 품질 저하를 숨기지 마십시오. 오디오, 언어, 비전 및 생성 모델의 경우 텐서 허용 오차 외에도 작업별 품질 검사를 사용합니다.
라이선스 및 출처 확인 없이 변환된 가중치를 게시하지 마십시오. 원본 모델 카드, 귀속 정보, 생성 구성, 토크나이저/프로세서 파일 및 변환 레시피를 보존합니다.
일일 연구 자동화는 검토 전용입니다. 후보를 수집하고 순위를 매길 수 있지만, 런북을 자동으로 덮어쓰거나 권장 사항을 병합해서는 안 됩니다.

워크플로

1. 검사 및 분류

실행:

python3 scripts/inspect_model.py MODEL_OR_DIRECTORY --output inspection.json
python3 scripts/make_port_plan.py inspection.json --output PORT_PLAN.md
python3 scripts/recommend_optimizations.py inspection.json --markdown OPTIMIZATIONS.md

수용 및 라우팅을 읽습니다. 다음을 확인합니다:

작업 및 모델 도메인;
아키텍처 패밀리 및 순환/캐시 상태;
소스 프레임워크 및 커스텀 연산;
파라미터 수, dtypes, 결합/공유 가중치, 샤드 및 어댑터;
전처리, 토큰화, 샘플링 및 후처리;
라이선스 및 원격 코드 위험;
대상 Mac, 메모리 예산, 지연 시간/처리량 목표 및 품질 목표.

아키텍처, 소스 리비전 또는 평가 대상이 모호하면 구현을 시작하지 마십시오. 추측하지 말고 PORT_PLAN.md에 불확실성을 기록합니다.

2. 가장 가까운 입증된 MLX 참조 선택

모델 지원 맵 및 assets/architectures.yaml을 참조합니다.

다음 순서를 사용합니다:

공식 MLX / MLX-LM 구현;
테스트가 있는 활성 MLX-VLM 또는 MLX-Audio 구현;
활성 타사 MLX 구현;
업스트림 소스 구현 및 아키텍처 논문;
새로운 MLX 구현이 필요한 연구 프로토타입.

복사된 가정이 아닌 아키텍처 패턴을 재사용합니다. 고정된 소스에 대해 구성 의미론과 텐서 레이아웃을 검증합니다.

3. 소스 오라클 설정

패리티 및 테스트를 따릅니다:

결정론적 시드 및 추론 모드 설정;
전처리 후 정확한 입력 저장;
임베딩/프론트엔드 이후, 모든 블록 그룹, 병목 지점, 캐시 업데이트, 로짓/잠재 및 디코더/보코더 출력의 모양/dtype/통계 및 선택된 텐서 캡처;
이식 가능한 .npz, .json 또는 .wav 픽스처에 소스 출력 저장;
dtype 및 연산별 허용 오차 기록;
최소 하나의 최소, 하나의 일반 및 하나의 경계 케이스를 포함합니다.

4. 최소 eager MLX 그래프 구현

핵심 포팅 방법 및 해당 아키텍처 런북을 읽습니다:

초기 구현 제약 조건:

부동 소수점 가중치만;
배칭이 본질적이지 않은 한 배치 크기 1;
컴파일 데코레이터 없음;
커스텀 커널 없음;
명시적 상태 및 캐시 객체;
모든 중요한 변환 주변의 모양 어설션;
되돌릴 수 있는 가중치 맵 매니페스트.

5. 가중치 결정론적으로 변환

소스 키, 대상 키, 소스 모양, 대상 모양, 변환, dtype 및 결합/공유 규칙이 포함된 가중치 맵을 만듭니다. 검증합니다:

python3 scripts/validate_weight_map.py   --source source-manifest.json   --target target-manifest.json   --mapping WEIGHT_MAP.json

누락되거나 추가된 가중치를 숨기기 위해 로드 시간 strict=False에 절대 의존하지 마십시오. 모든 예외를 의도적으로 무시됨, 생성됨, 공유됨 또는 지원되지 않음으로 분류합니다.

6. 패리티 사다리 통과

scripts/compare_tensors.py를 사용하고 순서대로 통과합니다:

구성 및 전처리 패리티;
가중치 범위 및 변환된 모양 패리티;
단일 기본 요소/블록 패리티;
단계별 중간 패리티;
종단간 결정론적 패리티;
작업 품질 패리티;
캐시/상태 및 증분 생성 패리티;
경계, 긴 입력, 스트리밍 및 배치 패리티.

패리티가 실패하면 실패 아틀라스를 사용하십시오. 실패하는 그래프를 최적화하지 마십시오.

7. 최적화를 선택하기 전에 프로파일링

벤치마킹을 읽습니다. 다음을 분리합니다:

프리필/인코더/프론트엔드 시간;
토큰당 또는 프레임당 디코드 시간;
코덱/보코더/후처리 시간;
컴파일 및 첫 실행 비용;
최대 및 정상 상태 메모리;
데이터 이동, 동기화 및 Python 오버헤드.

사용:

python3 scripts/benchmark_command.py --warmup 2 --runs 8 --output benchmark.json -- COMMAND ...

8. 최적화 사다리 적용

assets/optimization_guidance.yaml, assets/recommendation-taxonomy.yaml, assets/techniques.yaml을 참조하고 관련 가이드만 로드합니다:

기본 순서:

의도하지 않은 평가 및 호스트 전송 제거;
올바른 dtype 및 텐서 레이아웃;
기본 융합 연산 및 고속 SDPA 사용;
할당 감소 및 상태/캐시 업데이트 명시화;
안정적인 영역 컴파일 및 재컴파일 제어;
아키텍처가 허용하는 경우 프리필/프론트엔드 청크 또는 스트리밍;
KV/캐시 정책 및 배칭 최적화;
가중치 양자화, 그런 다음 정당화되는 경우 KV/상태;
호환되는 자기회귀 경로에 대해서만 추측 또는 다중 토큰 디코딩 추가;
프로파일링이 남아 있는 커널 병목 지점을 입증한 후에만 커스텀 Metal 커널 작성.

모든 변경에 대해 가설, diff, 정확성 결과, 벤치마크 결과, 메모리 결과, 품질 결과 및 유지/되돌리기 결정을 기록합니다.

9. 패키징 및 게시

패키징 및 게시를 따릅니다. 포함:

고정된 소스 및 변환 명령;
호환 가능한 MLX 및 라이브러리 버전;
모델/구성/토크나이저/프로세서 파일;
정확한 양자화 레시피 및 제외 사항;
결정론적 스모크 테스트;
벤치마크 프로토콜 및 원시 결과;
알려진 제한 사항;
원본 라이선스 및 귀속 정보;
지원되지 않는 "더 빠름" 또는 "무손실" 표현 금지.

10. 엔지니어링 보고서 반환

최종 응답은 다음을 요약해야 합니다:

아키텍처 및 선택된 런북;
소스 리비전 및 증거 참조;
구현 및 가중치 맵 상태;
패리티 매트릭스;
기준 및 최적화된 메트릭;
수용 및 거부된 최적화;
남은 위험 및 지원되지 않는 경로;
재현 가능한 명령 및 아티팩트 위치.

assets/의 템플릿을 사용합니다.

중단 시점

다음과 같은 경우 즉흥적으로 진행하지 말고 중단하고 보고합니다:

소스 라이선스가 요청된 배포를 금지하는 경우;
필요한 소스 동작이 검토되지 않은 원격 코드에만 존재하는 경우;
단계별 검사 후에도 패리티를 국소화할 수 없는 경우;
최적화가 마이크로벤치마크를 개선하지만 종단간 지연 시간, 메모리 또는 품질을 악화시키는 경우;
커스텀 커널에 이식 가능한 폴백 또는 적절한 테스트가 없는 경우;
성능 주장에서 하드웨어, MLX 버전, 워크로드 또는 품질 대상이 누락된 경우.

유지 관리

소스 검토, 보안 및 일일 후보 파이프라인에 대해서는 유지 관리 및 출처를 읽습니다. 이 스킬을 배포하기 전에 scripts/audit_skill.py 및 scripts/validate_sources.py를 실행합니다.

MLX 모델 포팅 및 최적화