역공학(Reverse-engineered)된 프라이빗 API를 통해 Apple의 Neural Engine (ANE)에서 직접 신경망을 학습시킵니다. CoreML 학습 API도, Metal도, GPU도 사용하지 않는 순수한 ANE 연산입니다.

이 프로젝트가 받은 모든 관심에 진심으로 감사드립니다. 주말 동안 진행한 연구용 해킹 프로젝트가 이렇게까지 화제가 될 줄은 전혀 예상하지 못했습니다. 스타(Star)를 눌러주시고, 포크(Fork)하고, 각자의 하드웨어에서 벤치마크를 실행하며, 이 작업을 공유해 주신 모든 분께 감사드립니다. 정말 큰 의미가 있습니다.

그럼에도 불구하고, 이 프로젝트가 무엇이고 무엇이 아닌지에 대해 명확한 기대치를 설정하고자 합니다.

이것은 프로덕션 프레임워크가 아닌 **연구 프로젝트 (Research project)**입니다.

목표는 Apple Neural Engine — 그리고 잠재적으로 다른 NPU(Neural Processing Unit) — 에서의 학습이 가능하다는 것, 그리고 그동안의 장벽은 하드웨어 성능이 아니라 소프트웨어 지원이었다는 것을 증명하는 것이었습니다. ANE는 매우 뛰어난 성능을 가진 실리콘이지만, Apple은 CoreML을 통해 추론(Inference) 전용으로만 사용하도록 제한하고 있습니다. 이 프로젝트는 역공학된 프라이빗 API를 사용하여 그 제한을 우회함으로써, 하드웨어에 기회를 주었을 때 무엇이 가능한지를 보여줍니다.

• _ANEClient 및 _ANECompiler 프라이빗 API를 통한 ANE 학습의 개념 증명 (Proof of concept)

• 실제 ANE 성능 특성(처리량(Throughput), 전력, SRAM 동작)을 기록한 벤치마크 세트

• CoreML 외부에서 ANE에 직접 접근하는 것을 탐구하는 모든 이들을 위한 참조 자료

• 흥미로운 점을 발견할 때마다 업데이트하는 연구용 코드

• 유지 관리되는 프레임워크나 라이브러리

• CoreML, MLX, llama.cpp 또는 기타 프로덕션 추론 스택의 대체제

• (아직은) 소비자용 하드웨어에서 대규모 모델을 학습하기 위한 경로

이 프로젝트에 대한 일부 보도들은 그 영향력을 과장했습니다. 명확히 말씀드리자면:

• 학습은 작동하지만, 활용률(Utilization)은 낮으며 (~피크 성능의 5-9%), 여전히 상당한 엔지니어링 과제가 남아 있습니다.
• 많은 요소별 연산(Element-wise operations)이 여전히 CPU로 폴백(Fallback)됩니다.
• 현재로서는 작은 연구용 모델 이외의 어떤 용도로도 GPU 학습을 대체할 수 없습니다.

모든 한계점을 포함한 솔직한 결과는 첨부된 문서들에 기록되어 있습니다:

저는 이것을 대규모 커뮤니티 프로젝트로 키울 의도는 없습니다. 저의 초점은 독창적인 연구(Edge AI 최적화를 위한 컴파일러 인프라)에 있으며, 오픈 소스 프레임워크를 유지 관리하는 것은 그 연구에 투입할 시간을 뺏기 때문입니다.

그럼에도 불구하고:

• 흥미로운 것을 발견할 때마다 업데이트를 계속 진행할 것입니다.
• 버그 수정 및 벤치마크 기여(특히 제가 소유하지 않은 하드웨어에서의 기여)는 언제든 환영합니다.
• 기능 요청(Feature requests)은 처리되지 않을 가능성이 높지만, 자유롭게 포크(fork)하십시오.
• PR(Pull Request)은 비교적 느린 속도로 병합될 것입니다. 그렇지 않으면 제가 이 기술을 둘러싼 커뮤니티 성장의 병목 현상(bottleneck)이 될 것이기 때문입니다.

이 프로젝트가 MIT 라이선스로 제공되는 데에는 이유가 있습니다. 이제 모든 사람은 몇 시간 만에 코드를 적응시키고 확장할 수 있는 AI 지원 개발 도구에 접근할 수 있습니다. 만약 이 프로젝트가 당신에게 유용하다면 — 가져가서, 수정하고, 더 나은 것을 만드십시오. 만약 이것으로 멋진 것을 만든다면, 꼭 소식을 듣고 싶습니다. 향후 커뮤니티가 하나의 단일 소스(single source of truth) 저장소를 유지하기로 결정한다면, 저는 전적으로 지지할 것입니다.

Apple Silicon의 ANE에서 실행되는 트랜스포머(transformer) 학습(순전파(forward) + 역전파(backward) 패스)의 바닥부터 시작하는(from-scratch) 구현체입니다. ANE는 Apple이 학습 용도로는 노출하지 않는 15.8 TFLOPS FP16 (M4) 추론 가속기입니다. 이 프로젝트는 _ANEClient / _ANECompiler 비공개 API와 MIL (Model Intermediate Language) 형식을 역공학(reverse-engineers)하여, 역전파(backpropagation)를 포함한 커스텀 연산 그래프(compute graphs)를 ANE 하드웨어에서 직접 실행합니다.

현재 결과:

• 모든 순전파(forward) 및 역전파(backward) dx 패스는 ANE에서 수행되며, dW 그래디언트(gradients)는 CPU (Accelerate cblas)에서 수행됩니다.
• Adam 옵티마이저(optimizer), 그래디언트 누적(gradient accumulation), exec() 재시작을 통한 체크포인트/재개(checkpoint/resume)를 지원합니다.
• 헤드별 타일링/리덕션(tiling/reduction)을 포함한 GQA (Grouped-Query Attention)를 지원합니다.
• 공유 IOSurface를 통한 GPU↔ANE 제로 카피(zero-copy) 파이프라인 (GPU prefill → ANE decode)을 지원합니다.

INT8 W8A8 양자화(quantization) — 1.88x 처리량(throughput) (M4, H16G):

INT8 활성화 함수 (activations)는 MIL quantize / dequantize 연산을 통해 타일(tile) 간의 L2 SRAM 대역폭(bandwidth)을 절반으로 줄입니다. 가중치(Weights)는 constexpr_affine_dequantize를 사용합니다 (int8로 저장되며, 컴파일 타임에 fp16으로 처리).

동적 파이프라인 (dynamic pipeline)은 가중치가 공간 차원(spatial dimensions)에 패킹된 공유 ANE 커널 (kernels)을 사용합니다 (가중치가 변경되어도 재컴파일이 필요 없음):

MHA 모델 (Stories110M) — 레이어당 6개 커널:

GQA 모델 (Qwen3-0.6B) — 레이어당 10개 커널:
그룹 쿼리 어텐션 (GQA, Q_DIM ≠ DIM)을 위해 별도의 woFwd, qBwd, kvBwd 커널을 추가합니다.

CPU 담당: RMSNorm 순전파/역전파 (forward/backward), 잔차 연결 (residual connections, DeepNet α scaling), 손실 계산 (loss computation), dW 그래디언트 누적 (gradient accumulation, cblas_sgemm), Adam 옵티마이저 (optimizer) 업데이트.

주요 최적화 사항:

Channel-first CPU 레이아웃 (layout) — ANE IOSurface [1,C,1,S] 형식과 일치하여 모든 전치 (transpose) 오버헤드를 제거함
vDSP 벡터화된 RMSNorm (vectorized RMSNorm) — 단순 구현(naive) 방식보다 10배 빠름 (6.7ms → 0.7ms)
GCD 비동기 cblas 중첩 (async cblas overlap) — dW 그래디언트 sgemm이 직렬 디스패치 큐 (serial dispatch queue)에서 ANE 평가 (evals)와 병렬로 실행됨
지연된 cblas 대기 (Deferred cblas wait) — 최대 중첩을 위해 대기 시점을 다음 단계의 순전파 (forward pass)로 미룸
ANE RMSNorm 융합 (fusion) — RMSNorm을 MIL 연산 (reduce_sum + pow + mul)으로서 순전파 커널에 통합
Wo^T 융합 (fusion) — 출력 투영 역전파 (output projection backward)를 SDPA 역전파 커널에 병합
순전파 탭 (Forward taps) — Q, K, V, 어텐션 스코어 (attention scores), 은닉 상태 (hidden states)를 결합된 출력 (concat outputs)을 통해 노출하여 CPU 재계산 방지
exec() 재시작 (restart) — 프로세스당 약 119회의 ANE 컴파일 제한을 우회

├── api_exploration.m # 초기 ANE API 탐색
├── inmem_basic.m # 인메모리 (In-memory) MIL 컴파일 개념 증명 (PoC)
├── inmem_bench.m # ANE 디스패치 (dispatch) 지연 시간 벤치마크
...

학습을 위해서는 사전 토큰화된 (pretokenized) TinyStories 데이터가 필요합니다. 다운로드 방법:

cd training && bash download_data.sh

자세한 학습 지침은 training/README.md를 참조하세요.

Apple Silicon (M4에서 테스트됨) 기반의 macOS 15 이상 버전이 필요합니다.

# 동적 파이프라인 (Dynamic pipeline) (권장) — 빌드 시점에 모델 선택
cd training/training_dynamic
make MODEL=stories110m # Stories110M (12L, MHA, 109M 파라미터)
...

외부 의존성이 없습니다. 시스템 프레임워크와 objc_msgSend를 통해 런타임에 해결되는 비공개 (private) ANE API만을 사용합니다.

MIL 생성 (MIL generation) — Objective-C 코드가 런타임에 MIL 프로그램 텍스트를 구축하며, 컨볼루션 (convolutions, 선형 레이어용), 행렬 곱 (matmul, 어텐션용), 소프트맥스 (softmax), 요소별 연산 (element-wise ops)을 지정합니다.

인메모리 컴파일 (In-memory compilation) — _ANEInMemoryModelDescriptor가 MIL 텍스트와 가중치 블롭 (weight blobs)을 ANE 프로그램으로 직접 컴파일하며, 디스크 상의 mlmodelc는 필요하지 않습니다.

IOSurface I/O — 입출력 텐서가 [1, channels, 1, spatial] 형식의 IOSurface 공유 메모리를 통해 전달됩니다 (fp16 또는 fp32; fp16 직접 I/O가 약 37% 더 빠름).

동적 가중치 (Dynamic weights) — 활성화 값 (activations)과 가중치가 단일 공간 입력 차원으로 패킹되어 MIL 커널 내부에서 분리됩니다. 재컴파일 없이 가중치를 변경할 수 있습니다.

그래디언트 흐름 (Gradient flow) — 순전파 (Forward) 탭이 역전파 (backward)에 필요한 중간값들을 노출합니다. 역전파 커널은 ANE에서 dx (입력 그래디언트)를 계산하며, dW (가중치 그래디언트)는 CPU에서 cblas를 통해 계산됩니다.

INT8 양자화 (INT8 quantization) — int8 가중치를 위한 constexpr_affine_dequantize, L2 SRAM 내 int8 활성화 캐싱을 위한 레이어 간 quantize/dequantize 사용 (처리량 1.88배 향상).

SDPA 인과적 마스킹 (SDPA causal masking) — ANE 하드웨어는 SDPA 연산 중 attn_mask를 무시합니다. 인과적 어텐션 (causal attention)은 Q@K^T (ANE) → mask+softmax (CPU) → scores@V (ANE)로 분해됩니다.

~119회 컴파일 제한 — ANE 컴파일러의 리소스 누수 문제; exec()를 통해 우회함

체크포인트로 재시작

FP16 gradient underflow (FP16 그래디언트 언더플로우) — fp16에서 역전파 행렬 곱셈 (backward matmuls) 시 언더플로우 발생; 전역 손실 스케일링 (global loss scaling, 256 * NLAYERS)으로 해결

Single-input constraint (단일 입력 제약) — 다중 입력 ANE 요청 시 0x1d 에러 발생; 대신 입력을 공간 차원 (spatial dimension)으로 패킹하여 해결

Training throughput (M4) (학습 처리량):

ANE peak throughput (M4, H16G) (ANE 최대 처리량):

GPU↔ANE inference pipeline (M4, seq=256) (GPU↔ANE 추론 파이프라인):

이 프로젝트는 Apple의 비공개 및 문서화되지 않은 API (_ANEClient, _ANECompiler, _ANEInMemoryModelDescriptor)를 사용합니다. 이러한 API는 어떠한 공개적인 안정성 보장도 받지 않으며, macOS 업데이트에 따라 변경되거나 작동이 중단될 수 있습니다. 본 프로젝트는 공정 이용 (fair use) 및 상호 운용성 규정 (see Sega v. Accolade, 1992; DMCA §1201(f))에 따라 연구 및 교육 목적으로 런타임 인트로스펙션 (runtime introspection)을 통해 발견된 API를 사용하는 Apple Neural Engine 아키텍처에 대한 독립적인 연구입니다. 이 저장소에는 Apple의 독점 코드나 바이너리가 포함되어 있지 않습니다. 본 프로젝트는 Apple Inc.와 제휴하거나 승인받지 않았습니다. 사용 시 발생하는 위험은 사용자 본인에게 있습니다.

MIT — LICENSE 참조

사람과 Claude가 주말마다 하나씩 만들어 나갑니다.