coreai-model-zoo 发布 Apple Core AI 模型库与转换配方

Core AI is Apple's on-device ML runtime in iOS 27 / macOS 27 and the successor to Core ML: PyTorch models are exported with Apple's coreai-torch (LLMs: coreai.llm.export) into .aimodel bundles that run on the GPU or the Neural Engine, e.g. Qwen3-8B 4-bit decodes at 94 tok/s on an M4 Max GPU, MLX 90 under the same protocol (apple-silicon-llm-bench, macOS 27 beta 26A5353q, 2026-06-11).

Converted models + conversion recipes for Apple Core AI (.aimodel, iOS 27 / macOS 27): every model here is downloadable, gated against the original model before it ships, and carries the recipe that produced it in models/<model>/recipe.toml — rerun it (zoo_convert.py run <name>), check the published bundle against its source model (zoo_verify.py), or adapt it for your own port. Don't take the gates on faith — they are run here, and everything needed to re-run them is published. Each card states what was measured on which hardware (iPhone tier is device-measured; the large models are Mac-only and say so) and how strong that model's parity proof is, because it differs per model. Where the shipped configuration could not be recovered from the repository, the recipe says so rather than guessing. Model ports are open to everyone — the catalog serves community ports from the contributor's own Hugging Face namespace, credited by name (who). Successor to CoreML-Models.

Start here — put one model in your Swift app

CoreAIKit 0.4.1: requirements, install and first answer →

Start with qwen3-0.6b in the release's built-in catalog. CoreAIKit downloads the matching platform bundle once and caches it; your prompts and inference stay on the device. The first download is about 352 MB on Mac (the separate iPhone variant is about 456 MB). Follow the Kit README for the exact tested OS/SDK and current device verification. A Mac run is not evidence for the iPhone variant.

import CoreAIKit

guard let modelID = ModelCatalog.builtin.entry(id: "qwen3-0.6b")?.modelID else {
    throw CoreAIKitError.modelNotAvailableOnPlatform(id: "qwen3-0.6b")
}
let chat = try await ChatSession(model: modelID)
let reply = try await chat.respond(to: "What is the capital of Japan?")
print(reply)

The same published release includes the ChatDemo app and CLI:

git clone --branch 0.4.1 --depth 1 https://github.com/john-rocky/coreai-kit
cd coreai-kit/Examples/ChatDemo
export DEVELOPER_DIR=/Applications/Xcode-27.0.0-Beta.5.app/Contents/Developer
swift run -c release chat-cli --model qwen3-0.6b --prompt "What is the capital of Japan?"

Adjust DEVELOPER_DIR to your installed beta 5 app if its name differs. Expect a text answer mentioning Tokyo after the initial download and model load. For a conversation, keep one ChatSession and call respond(to:) again. The GUI is in ChatDemo.xcodeproj; use My Mac or a physical iPhone with the required OS and SDK.

After that first success, try text-to-speech with Speak and VoxCPM 0.5B from the same release (a separate download, about 1.37 GB on Mac). Each model card below links its own runner, minimal Swift function and integration requirements.

For FoundationModels apps, KitLanguageModel(model: modelID) supplies a chat model to LanguageModelSession. Tool calling depends on the model's dialect; guided generation also needs a compatible sequential engine. Check the capability matrix. The catalog includes non-chat tasks, which use their own Kit APIs.

If a run fails, start with the Kit README's troubleshooting links and the observed error index. For details about using Apple's adapter directly, see FoundationModels integration notes.

Rebuild a bundle — the conversion recipes

Every published bundle carries the configuration that produced it in models/<model>/recipe.toml, and one command runs it:

python3 conversion/zoo_convert.py list                    # what can be rebuilt
python3 conversion/zoo_convert.py show  qwen3.5-0.8b      # the command + everything it needs
python3 conversion/zoo_convert.py run   qwen3.5-0.8b --dry-run
python3 conversion/zoo_convert.py run   qwen3.5-0.8b      # do it

show prints four kinds of prerequisite, and the run-time ones matter as much as the rest — an export that skips them still succeeds, and the bundle then misbehaves inside the app:

Ports whose exporter is self-contained need no setup at all:

uv run conversion/export_da3.py --variant small --dtype float16 --res 504

Paths never assume a machine: python3 conversion/_paths.py prints where downloads, exports and the Hugging Face cache resolve, and ZOO_WORK_ROOT / ZOO_EXPORTS / ZOO_CODE_ROOT / HF_HUB_CACHE move them.

A recipe marked unverified refuses to run without --force. It means the repository does not record which configuration produced the published bundle, and it prints the exact question it cannot answer. Running it anyway yields a bundle, not the bundle.

Do not expect a checksum match. Conversion is not byte-deterministic here: the same recipe run twice on the same machine produces bundles that differ from each other (measured: main.mlirb by 7 bytes, main.hash entirely). A rebuild is judged by the gates the export runs — and by checking the published artifact itself:

python3 conversion/zoo_verify.py mlboydaisuke/Gemma-4-12B-CoreAI     # one repo
python3 conversion/zoo_verify.py --all --json models/_VERIFY.json    # the whole catalog, minutes

That compares a bundle's tokenizer, chat template, context length and declared precision against the source model it names in its own metadata.json — no oracle, no device, no weights.

The numerical check is a different command. zoo_verify.py checks that a bundle is described correctly; it does not check that the bundle still computes the right thing. That is conversion/coreai_gate.py, which rebuilds the reference model in fp32 and compares a greedy decode token for token:

python3 conversion/coreai_gate.py <bundle-dir> Qwen/Qwen3.5-2B --revision <sha> \
    --transcript models/qwen3.5-2b/gate.json

It runs outside this working tree — point --runner / ZOO_LLM_RUNNER at your llm-runner and --python / ZOO_CONVERT_PYTHON at an interpreter that has the export overlay, and it tells you which one is missing rather than failing obscurely. It currently covers the decode architectures in --arch (the oracle is a per-architecture transcription of that model's export, so it grows one port at a time, not all at once).

--transcript is the part worth publishing: the pinned revision, the exact input_ids, both sides' generated tokens, the tie margins, and the verdict. Rebuilding the oracle is expensive; re-running the engine side against a published transcript is not — it needs the bundle, llm-runner, and the recorded input_ids, and the output must match engine.gen_text.

New ports publish one. For models ported before the flag existed, conversion/backfill_gate_transcripts.py prints what can still be gated and, with --run, gates it — preferring the published bundle out of the CoreAIKit cache over a local export, so the transcript describes the bytes apps download at the revision the catalog pins. Nothing reconstructs a transcript from a card's prose after the fact: a model that cannot be re-gated keeps a card that says what was gated, without a file claiming to prove it.

Results land in models/_INVENTORY.md; models/index.json is the same catalog machine-readable, which is where an agent should start. Each recipe entry there carries status (does the repository record what produced this bundle) and gate_transcript (is the numerical check against the original published, and where) — two different questions, kept as two fields so neither has to be inferred from prose.

Models

Community ports

Ported by people outside this repo, published under their own Hugging Face namespace, and carrying their name on the card, on the row below, and in the release notes:

Thank you both — each of these arrived gated, and each one found a bug in this repo on the way in. CONTRIBUTING.md is the path to the next row.

Community benchmarks

Measured by people outside this repo on their own devices, from the Bench tab of the CoreAI Zoo app, and credited here by name:

• @jarrodpr — iPhone 18 Pro Max (A20 Pro, iPhone19,7): qwen3.5-2b, minicpm5-1b
• @Lancelotbronner — MacBook Pro 16-inch 2024 (M4 Pro, Mac16,7): qwen3-0.6b, qwen3-4b, qwen3.5-0.8b, qwen3.5-2b, minicpm5-1b, minicpm5-2b, qwen3.6-27b, qwen3.8-27b
• @LinkedWrong — iPhone 17 (A19, iPhone18,3): minicpm5-1b
• @minato-devv — iPhone 17 Pro (A19 Pro, iPhone18,1): minicpm5-2b

The table they built: BENCHMARKS.md. Add your device from the Bench tab of CoreAI Zoo.

▸ Run in app — apps in apps/ live in this repo; ↗ links a CoreAIKit example app; ‡ = app wiring in progress. 🔧 = the bundle still carries coreai-torch 0.4.0-era IR, which every OS 27 build from beta 2 on refuses at load (measured through macOS 26A428, 2026-09-15); it is queued for the in-place strip_debug_info repair (see the recovery note at the end). Full app list: apps/README.md.

GA validation (the badge at the top) is staged, not assumed: on the day the release OS lands, the most-downloaded bundles are downloaded and loaded through the runtime on that build (python3 conversion/zoo_smoke.py --top 20), and the rest of the catalog follows over the next week. The badge counts only bundles checked on the current release build; per-bundle status and the build that checked it are in models/_INVENTORY.md. A bundle that fails there is repaired or re-exported, not relabelled.

Built with the zoo

Projects outside this repo that carry code ported from the zoo, read its model index, or follow one of its conversion recipes:

• RF-DETR — Roboflow's real-time object detection and segmentation model. Its RFDETR.export(format="coreai") (since 1.11.0) was ported from the zoo's RF-DETR conversion (pull request).
• Archon — a local-first Swift SDK for building AI features on Apple platforms. Its CoreAIModelZooCatalog fetches the zoo's models/index.json and turns the recipes marked verified into entries in its model catalog (source).
• Slurper — a macOS CLI that transcribes YouTube or audio files and splits them into stems. Its Mel-Band RoFormer conversion script follows the zoo's recipe: the STFT and inverse STFT become constant DFT matmuls inside the graph. The script targets Core ML (coremltools), not Core AI (source).

Built something? Open a showcase issue — a name, a link, and one line is all it takes.

Most downloaded

(auto-updated weekly from Hugging Face download counts)

Decode throughput (tok/s, greedy; output top-1 exact vs the Hugging Face reference)

Measured on the iOS 27 / macOS 27 developer betas (June–September 2026 builds; not yet re-measured on the release OS), Apple's coreai-pipelined GPU engine, zero custom kernels (ANE column + †/‡ excepted). † = MoE bundle using the custom gather_qmm Metal kernel (reads only the routed experts). ‡ = dense bundle whose full/global-attention SDPA is a custom flash-decode Metal kernel — the stock MPSGraph SDPA crashed on the ≥16-head × 512 Q on the OS 27 betas (a GPU scratch-heap overflow, not re-tested on the release OS, apple/coreai-models#27), so these models are unrunnable without it. Prefill, sizes, per-model caveats, and the Mac-only big models: models/.

CoreAIChat (apps/) — the zoo's models running on-device on iPhone.

Start here

• You're a coding agent (or you're pointing one here) → AGENTS.md — the porting contract in one file: why conversion isn't conversion, the two gates, the traps agents hit, and what isn't an agent's call. No install needed. One fetch for everything here: llms.txt.
• Looking something up about the runtime itself → john-rocky.github.io/coreai-model-zoo — the knowledge base as a page per topic. Apple documents the API surface well; what these notes add is what the runtime does when you run it — the thresholds, the failure modes, the measured numbers — which is not written down anywhere. Plain HTML, so a reader without JS, a search crawler and a coding agent all get the same words.
• Reading start to finish rather than looking one thing up → The Art of Core AI — a free book built from these same measurements (Japanese edition).
• Surveying the whole Core AI ecosystem, not just this catalog → awesome-core-ai — Apple's own tooling, other people's converters and runtimes, sample apps, benchmarks, and learning material.
• Try the app (iOS 27 / macOS 27; the model downloads in-app):
  • Demo app, no build → Mac: 2.0 (build 9) .dmg (signed and notarized; Apple silicon, macOS 27) · iPhone: CoreAI Zoo on the App Store Mac quick start: drag the app into Applications, open Chat → Qwen3 0.6B → Download & Load, wait for Ready, then send a message. Release notes and tested beta environment.
  • Build it → apps/ — Xcode 27 + xcodegen, the coreai-models patch stack + tokenizer.json
• Use a model in your own app → add CoreAIKit (SPM) and load the catalog id; the model's card has the complete snippet + a 5-line integration checklist (golden example: models/whisper-large-v3-turbo/README.md). Engine-level deep-dive: knowledge/swift-runtime.md
• Port a model, end to end → PORTING.md — the complete walk from HF checkpoint to a verified .aimodel on iPhone (oracle → export → gates → device → publish), with a vision and an LLM worked example. Start here to contribute a port.
• Rebuild a published bundle → models/<model>/recipe.toml via python3 conversion/zoo_convert.py run <name> — see Rebuild a bundle
• Convert a model (export API + gotchas) → knowledge/conversion-guide.md
• Compress → knowledge/compression.md
• Make it fast → knowledge/custom-metal-kernels.md · knowledge/performance-ceiling.md
• Known issue, still present on 26A428 (in-graph KV-write crash; workarounds + the input-mask escape) → knowledge/coreai-beta-mpsgraph-kvwrite-bug.md — FB23024751 / apple/coreai-models#5
• Hit an error string (LLVM ERROR: …, failed assertion …, failedToSpecialize, NSPOSIXErrorDomain Code=2, …) → knowledge/coreai-error-index.md — every exact string this project has observed, verbatim as a heading, with the verified cause, the fix, and the log or Apple issue behind it
• Still stuck → conversion clinic — paste the error, get an answer

Repository layout

Agent Skills

This repo ships a plugin so a coding agent can use the zoo without being told how: pick a model from the catalog, reproduce its published bundle with the recorded recipe, and verify the result against the model it came from. With no plugin mechanism at all, point the agent at AGENTS.md — the same contract, zero install.

Install

Claude Code

/plugin marketplace add https://github.com/john-rocky/coreai-model-zoo
/plugin install coreai-zoo-skills@coreai-model-zoo

Codex CLI

codex plugin marketplace add https://github.com/john-rocky/coreai-model-zoo

then /plugins → coreai-model-zoo → coreai-zoo-skills → Install.

Gemini CLI

gemini extensions install /path/to/coreai-model-zoo/skills

Apple's own coreai-skills covers the toolchain itself (authoring, export, compression). These two cover this catalog; install both.

Contributing

Every model in the table is a conversion recipe anyone could have written — and some are, by people who are not me. Nanbeige4.2-3B (PR #6, by @ukint-vs) is the reference for what a contributed port looks like, and pocket-tts (PR #12, by @RahulRachuri) is the reference for how far the gates can be taken — an ASR round trip and a 302-sentence sweep, because tensor cosine can pass while the audio is unintelligible. The shape of both: pinned checkpoint + immutable bundle revision, the overlay/recipe/gates in the PR, the bundle published under the contributor's own HF namespace (you keep ownership and credit), and the maintainer runs the iPhone hardware gate for you if you don't have the device.

• Port a model — PORTING.md walks the whole path (oracle → export → gates → publish); PRs welcome.
• Conversion requests — a model you'd like to see here? Open an issue with the Hugging Face link and what you'd use it for.
• Stuck converting? Open a conversion clinic issue. The error text alone is enough to start; we ask for the rest. On the clinic day after the OS 27 release every ticket gets a same-day answer — a fix, or the reason it cannot be done yet. Search your error string first in knowledge/coreai-error-index.md; if it is there, so is the fix.
• No code needed — run the Bench tab in CoreAI Zoo (App Store) and submit the result: your device becomes a row in BENCHMARKS.md.

Recovery note — the coreai-torch 0.4.0 incident

Every model broken by the coreai-torch 0.4.0 debug-location issue has been re-published: re-converted with 0.4.1 (verification gates re-run), or repaired in place with strip_debug_info (debug locations removed, weights byte-identical). Catalog-served apps just re-download. The few 🔧 rows above are the remaining re-export queue. If you have your own 0.4.0-converted assets, strip_debug_info fixes them in minutes — no re-conversion needed. (One port, FastContext-1.0-4B, was retired instead of recovered: Microsoft removed its upstream weights on 2026-06-30, so it cannot be rebuilt.) Details: knowledge/coreai-torch-041-ir-incident.md.

Maintainer

Daisuke Majima (MLBoy) — the converted models live at huggingface.co/mlboydaisuke; the same maintainer runs devicemark (on-device LLM leaderboard, where zoo ports are measured) and wrote the Japanese textbook The Art of Core AI, drawn from these ports.

License

BSD-3-Clause (LICENSE). Re-authored model code derives from Apple's BSD-3-Clause coreai_models and retains its notices. Model weights follow their own licenses (see each Hugging Face repo).