이 레포가 무엇을 하는 물건인가.
큰 AI 모델은 보통 남의 서버(클라우드 GPU)에서 돈다. coreai-models는 그 모델을 내 기기 칩에 맞게 짐을 다시 싸서(export·compress) 옮기고, 도착한 곳에서 풀어 작동시키는(Swift runtime) 도구·레시피·설명서를 전부 제공한다. 인터넷도, 서버 비용도, 데이터 유출 걱정도 없이 기기 안에서 끝난다.
Apple은 칩(Apple Silicon) 안에 AI 전용 연산기인 뉴럴 엔진(Neural Engine)과 GPU를 넣어 왔다. 문제는, Hugging Face에 올라온 보통의 PyTorch 모델은 그 칩에서 곧바로 돌지 않는다는 점이다. 모델을 Apple이 이해하는 포맷(.aimodel)으로 변환하고, 칩에 맞게 구조를 다듬고, 압축해야 한다. coreai-models는 이 과정을 모델 종류별 레시피로 정리해 둔 공식 저장소다.
구성은 네 덩어리다. ① 모델 내보내기(models/) — Qwen3·Gemma3·Stable Diffusion 같은 인기 모델을 변환하는 레시피. ② 파이썬 기본 부품(python/) — 직접 모델을 만들 때 쓰는 빌딩 블록. ③ Swift 런타임(swift/) — 변환된 모델을 앱에서 실제로 실행하는 패키지. ④ Agent Skills(skills/) — 코딩 AI가 이 모든 작업을 알아서 하게 가르치는 플러그인.
.aimodel이다. 계보로 보면 오랫동안 쓰여 온 Core ML 툴체인(coremltools·.mlmodel)의 생성형 AI 세대 후신 격으로, LLM·확산 모델 같은 큰 모델을 칩 위에서 돌리는 데 초점이 맞춰져 있다.트렌딩 이유 · 경쟁 대비 장점.
이 저장소는 커밋 1개짜리 갓 공개된 레포인데도 단숨에 트렌딩에 올랐다. 이유는 세 가지다. 첫째, Apple이 직접 내놓은 공식 레시피라는 무게감. 그동안 "맥/아이폰에서 LLM 돌리기"는 커뮤니티 프로젝트(llama.cpp·MLX 등)에 의존했는데, 이제 제조사 1차 자료가 생겼다. 둘째, 단순 모델 저장소가 아니라 전체 파이프라인(변환→압축→컴파일→실행)을 코드와 함께 준다. 셋째, Agent Skills를 끼워 코딩 AI가 이 작업을 대신하게 만든 점 — 최신 "스킬·플러그인" 흐름과 정확히 맞물린다.
| 비교 항목 | 기존 방식 | apple/coreai-models |
|---|---|---|
| 출처 | 커뮤니티 포팅(llama.cpp·Ollama·MLX) | Apple 1차 공식 레시피·런타임 |
| 가속기 활용 | 주로 GPU/Metal 중심 | 뉴럴 엔진까지 정조준(에너지 효율) |
| 범위 | 대개 LLM 위주 | LLM·확산·비전·오디오·텍스트 전부 |
| 앱 통합 | 직접 브리징 작업 필요 | Swift 패키지 + FoundationModels 연동 |
| 자동화 | 수작업 변환 | Agent Skills로 코딩 AI가 대행 |
PyTorch 모델을 Apple 칩에 올리려면 어떤 연산이 뉴럴 엔진에서 지원되는지, 어떻게 압축해야 정확도가 안 깨지는지, 메모리에 들어가는지를 일일이 시행착오로 알아내야 했다. 흩어진 블로그·깃헙 이슈를 뒤지는 게 일이었다.
모델 가족마다 "이 명령 한 줄이면 변환된다"는 레시피가 있고, skills/ 폴더에는 뉴럴 엔진/GPU에서 뭐가 되고 안 되는지(랭크 제한·정밀도·정적 shape 등)를 정리한 경험칙 문서가 들어 있다. 도박이 절차로 바뀌었다.
"파이썬으로 내보내고, Swift로 실행"하는 두 세계.
이 레포는 거의 정확히 반반이다 — 파이썬(변환·압축 쪽)과 Swift(기기 실행 쪽). 두 세계를 .aimodel 파일이 다리처럼 잇는다.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 패키지 관리 | uv (Astral) | 의존성·실행. uv run coreai.llm.export … |
| 파이썬 | 3.11 (.python-version) | 변환 스크립트 런타임 |
| 모델 정의 | PyTorch + transformers | 원본 모델 로드·재작성(authoring) |
| 변환 | coreai-torch (TorchConverter) | PyTorch → AIProgram(.aimodel) |
| 압축 | coreai-opt | 양자화·팔레타이즈(하드웨어 인지) |
| 컴파일 | coreai-build (xcrun) | 기기별 사전(AOT) 컴파일 |
| 단독 레시피 | PEP 723 인라인 의존성 | models/<name>/export.py를 그대로 실행 |
| 품질 도구 | ruff·mypy·pytest | 린트·타입체크·테스트 |
| 레이어 | 기술 | 역할 |
|---|---|---|
| 패키지 | Swift 6.0 Package(SwiftPM) | macOS/iOS 27.0+ 타깃 |
| 런타임 코어 | CoreAI 프레임워크 | AIModel 로드·추론 실행 |
| 토크나이저 | swift-transformers (HF) | LLM·확산 토크나이즈 |
| 제약 디코딩 | CXGrammar(xgrammar, C++ 바인딩) | JSON 등 문법 강제 생성 |
| CLI | swift-argument-parser | llm-runner 등 명령행 도구 |
| 라이브러리 4종 | CoreAILM · CoreAIDiffusion · CoreAISegmentation · CoreAIObjectDetection | 도메인별 실행 유틸 |
pip+venv+pyenv를 한 방에 대체한다. uv run X는 "필요한 환경을 알아서 갖춘 뒤 X를 실행"한다는 뜻이라 설치 단계가 거의 사라진다.coreai-build(xcrun coreai-build compile)가 담당하며, 첫 실행 지연을 줄여 준다.PyTorch 모델 하나가 아이폰 화면까지 가는 5단계.
핵심 파이프라인은 ① 저작(Author) → ② 압축(Compress) → ③ 내보내기(Export) → ④ 컴파일(Compile) → ⑤ 실행(Run)이다. ①②는 선택이고(많은 모델은 곧장 ③), ③~⑤가 필수 줄기다.
가장 중요한 설계 결정은 "어느 연산기에서 돌릴 것인가"다. Apple 칩에는 셋이 있고, 각각 규칙이 다르다. 이 선택이 ① 저작 단계의 모든 제약을 결정한다.
| 연산기 | 강점 | 핵심 저작 제약 |
|---|---|---|
| 뉴럴 엔진 | 에너지 효율 최고, 배터리 친화, 상시 구동 | BC1S 레이아웃 · fp16 전용 · 정적 shape · 제한된 연산 집합 |
| GPU | 높은 처리량, 큰 모델, 유연한 연산 | 표준 레이아웃 · fp32 지원 · 동적 shape OK |
| CPU | 작은 모델, 낮은 지연, 정확도 검증·폴백 | 모든 연산 실행 가능(느림) |
뉴럴 엔진은 데이터를 (Batch, Channels, 1, Sequence) 모양, 줄여서 BC1S 형태로 다룬다. 행렬 곱을 1×1 Conv2d로 구현하는 하드웨어라서 그렇다. 게다가 마지막 축은 64바이트(fp16 32개)로 정렬돼야 하고, 안 맞으면 패딩 낭비가 최대 32배까지 난다. 그래서 "잘 도는 모델"을 만들려면 텐서 모양을 칩에 맞춰 재설계해야 한다.
skills/model-authoring/references/neural_engine_rules.md가 이 경험칙을 집대성해 놨다. 같은 모델도 이 규칙을 따르면 에너지·속도가 크게 좋아진다.Swift 런타임의 영리한 부분은 EngineFactory다. 변환된 모델 묶음을 보고 알맞은 실행 엔진을 알아서 고른다. 개발자는 모델 URL만 넘기면 된다.
// 모델 구조를 들여다보고 엔진 변형을 자동 선택
let engine = try await EngineFactory.createEngine(
config: configData,
modelURL: modelURL,
options: EngineOptions() // variant=nil → 자동 감지
)엔진 변형은 모델·플랫폼 특성에 따라 셋으로 나뉜다. 이 분리가 macOS(동적)와 iOS(정적)의 차이를 흡수한다.
| 엔진 변형 | 언제 쓰나 |
|---|---|
| SequentialEngine | 레이어를 순차 실행하는 기본형 |
| PipelinedEngine | 단계를 겹쳐 처리량을 높이는 파이프라인형 |
| StaticShapeEngine | iOS처럼 고정 shape가 필요한 경우(정적 KV 캐시) |
macOS는 "조절 가능한 책상", iOS는 "맞춤 제작 책상"이다. macOS 모델은 동적 KV 캐시로 문맥 길이를 늘였다 줄였다 한다(조절 책상). iOS 모델은 내보낼 때 문맥 길이를 못박아야 한다(맞춤 책상) — 대신 메모리가 예측 가능하고 뉴럴 엔진에 잘 맞는다. 그래서 같은 Qwen3라도 --platform iOS면 --max-context-length가 필수가 된다.
어떤 폴더가 무슨 일을 하나.
| 위치 | 역할 |
|---|---|
python/.../model_registry.py | 단일 진실원. 단축명(qwen3-0.6b)을 HF ID·압축·정밀도·문맥길이 기본값에 연결. 새 모델은 여기 ModelPreset(...) 한 줄 추가. |
python/.../primitives/ | RMSNorm·SDPA·RoPE·MLP·KV캐시 등을 macos/·ios/로 나눠 둔 부품함. 새 모델 저작 시 바닥부터 짜지 말고 여기서 가져다 쓴다. |
models/<name>/export.py | 표준 파이프라인에 안 맞는 모델용 단독 스크립트. PEP 723 인라인 의존성이라 uv run으로 바로 실행. |
swift/.../InferenceEngines/ | 엔진 3종 + EngineFactory + KV캐시. LLM 디코드 루프의 심장. |
swift/.../Tools/llm-runner | 맥에서 변환 모델을 바로 돌려보는 명령행 도구. |
skills/skills/ | SKILL.md + references/ 문서 + 검증된 scripts/. 코딩 AI가 읽고 작업을 대행하는 지식 베이스. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
가장 큰 배움은 사고의 전환이다. GPU 서버에서 잘 돌던 모델이 칩에서는 안 돈다 — 텐서 랭크, 정밀도(fp16), shape의 정적/동적, 메모리 정렬이 전부 제약이 된다. skills/model-authoring/references/neural_engine_rules.md와 gpu_rules.md는 이 경험칙의 보물창고다. ML 엔지니어라면 한 번은 정독할 가치가 있다.
압축은 한 번에 정답이 없다. coreai-models는 이를 실험 스윕으로 푼다 — 여러 압축 설정을 돌려 보고 PSNR(출력 품질)과 용량을 표로 비교한다. model-compression-exploration 스킬의 compression_metrics.py·quality_metrics.py는 이론적 압축 크기·평균 비트폭·품질 지표 공식이 검증된 채 들어 있어 그대로 재사용 가능.
# macOS 기본 4비트로 내보내기
uv run coreai.llm.export Qwen/Qwen3-0.6B
# iOS는 팔레타이즈 + 임베딩 8비트
uv run coreai.llm.export Qwen/Qwen3-0.6B --platform iOS토큰을 하나씩 뽑는 자기회귀 생성이 실제로 어떻게 구현되는지 볼 수 있다 — KV 캐시 관리, 샘플러(Samplers/), 디코딩 전략(DecodingStrategies/), 그리고 xgrammar 기반 제약 디코딩(JSON 강제 출력)까지. swift/Sources/CoreAILanguageModels/가 교과서다.
이 레포의 skills/는 잘 만든 Agent Skill의 표본이다. SKILL.md는 짧고, 상세 내용은 references/로 미루는 점진적 공개(progressive disclosure), 검증된 scripts/ 분리, "먼저 다 읽지 말고 필요할 때 참조하라"는 지침까지. Claude Code·Codex·Gemini CLI에 플러그인으로 설치된다.
xgrammar(C++)를 Swift에 바인딩한 CXGrammar로 구현한다.변환하려면 / 기기에서 돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 변환·압축(파이썬) | uv(brew install uv) + 파이썬 3.11. uv run coreai.llm.export … |
| 실행 OS | macOS · iOS 27.0+ (Apple Silicon) |
| 빌드 도구 | Xcode 27.0+ (Swift 6.0, xcrun coreai-build 포함) |
| 맥에서 CLI 실행 | swift run -c release llm-runner --model … --prompt "Hello" |
| 메모리 고려 | 모델이 기기 메모리를 넘으면 OS가 앱을 종료. 런타임에 os_proc_available_memory()로 가용 메모리 확인 권장 |
| 모델 묶음 | .aimodel + 필요 시 토크나이저·리소스 폴더(LLM·확산은 다중 자산) |
이 레포는 가장 최신 macOS/iOS(연도 기반 버전 명명으로 27 세대)와 Xcode 27을 전제로 한다. 구형 기기·이전 OS에서는 동작이 보장되지 않는다. 또한 현재 코드 PR은 받지 않고(출시 초기 정책) 이슈·피드백만 받는다는 점도 기여 전에 알아 둘 것.
난이도별로 손에 익히는 단계.
맥이라면 클론 후 레지스트리를 조회해 어떤 모델이 어떤 플랫폼을 지원하는지 본다. 변환 없이도 카탈로그 구조를 파악할 수 있다.
git clone https://github.com/apple/coreai-models.git
cd coreai-models
uv run coreai.model.registry --list-models --type llm가장 작은 Qwen3 0.6B를 macOS용으로 변환한다. --dry-run으로 해석된 설정만 먼저 확인하고, 실제 변환 후 llm-runner로 한 문장 생성까지 돌려 본다.
uv run coreai.llm.export Qwen/Qwen3-0.6B --dry-run # 설정 미리보기
uv run coreai.llm.export Qwen/Qwen3-0.6B # 변환
swift run -c release llm-runner \
--model ./Qwen3-0.6B --prompt "양자컴퓨터란?"같은 모델을 --compression none(무압축)과 기본 4비트로 각각 내보내, 용량과 출력 품질이 어떻게 달라지는지 비교한다. iOS 팔레타이즈 프리셋(group32 vs group8)도 바꿔 본다.
Claude Code에 이 레포의 스킬 플러그인을 등록하면, "이 PyTorch 모델 아이폰용으로 내보내 줘" 같은 자연어 요청을 AI가 working-with-coreai 스킬을 따라 수행한다.
# Claude Code 안에서
/plugin marketplace add git@github.com:apple/coreai-models.git
/plugin install coreai-skills@coreai-models표준 파이프라인에 맞는 모델이라면 model_registry.py에 ModelPreset(...) 한 줄을 더해 단축명으로 변환 가능하게 만든다. 특이한 모델이면 models/<name>/export.py 단독 레시피를 PEP 723 패턴으로 작성한다. (PR은 막혀 있으니 포크에서 학습용으로.)
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 온디바이스 AI 큰 그림 + uv 환경 | README · guidance.md · working-with-coreai 스킬 |
| 2주차 | 모델 내보내기 실습(LLM·확산) | models/README.md · coreai.llm.export 돌려보기 |
| 3주차 | 뉴럴엔진/GPU 저작 규칙 | neural_engine_rules.md · gpu_rules.md · primitives/ |
| 4주차 | 모델 압축(양자화·팔레타이즈) | model-compression-exploration 스킬 · coreai-opt 문서 |
| 5주차 | Swift 추론 런타임·KV캐시·샘플러 | swift/Sources/CoreAILanguageModels/ 정독 |
| 6주차 | 앱 통합 + 제약 디코딩 | FoundationModels 연동 · GuidedGeneration/ · xgrammar |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| 온디바이스 AI | 모델을 서버가 아닌 사용자 기기에서 실행. 프라이버시·오프라인·무비용. |
| Core AI | Apple의 온디바이스 AI 프레임워크. Core ML 툴체인의 생성형 AI 세대 후신 격. |
| .aimodel | Core AI가 쓰는 변환된 모델 파일 포맷. 파이썬 변환의 결과물. |
| 뉴럴 엔진 | Apple 칩의 AI 전용 연산기. 에너지 효율 최고, 대신 제약 많음. |
| BC1S | 뉴럴 엔진의 텐서 레이아웃 (Batch, Channels, 1, Sequence). 행렬곱을 1×1 Conv2d로. |
| coreai-torch | PyTorch→.aimodel 변환기(TorchConverter). 파이프라인의 EXPORT 단계. |
| coreai-opt | 하드웨어 인지 압축(양자화·팔레타이즈) 패키지. COMPRESS 단계. |
| coreai-build | 기기별 사전(AOT) 컴파일러(xcrun). COMPILE 단계. |
| 양자화/팔레타이즈 | 가중치 비트 수를 줄이는 압축. 용량↓ 메모리↓ 대신 정확도 주의. |
| PSNR | 압축 전후 출력 유사도 지표. 높을수록 품질 보존. 실제 입력으로 측정. |
| KV 캐시 | LLM이 이전 토큰 계산을 재활용하려 저장하는 캐시. 동적(macOS)/정적(iOS). |
| 제약 디코딩 | 출력이 정해진 문법(JSON 등)만 되게 강제. xgrammar/CXGrammar로 구현. |
| uv | Rust로 만든 초고속 파이썬 패키지·실행 관리자. |
| PEP 723 | 스크립트 한 파일 안에 의존성을 적어 두는 표준. export.py를 바로 실행. |
| Agent Skill | 코딩 AI에게 절차·지식을 가르치는 플러그인. SKILL.md + 참조 문서. |