From c943d3968b6a21a5a5ffe47014af18744f90a727 Mon Sep 17 00:00:00 2001 From: KakaruHayate Date: Sun, 16 Aug 2026 15:42:01 +0800 Subject: [PATCH] chore: absorb ggml-metal-binary-archive doc into game.cpp (eco dissolution) ggml-patch's Metal binary-archive PSO-cache patch is identical to the copy already vendored here; this PR folds its purpose/re-apply doc into cmake/patches/ and marks ownership in-game.cpp, so game.cpp no longer references ggml-patch for this content. --- README.md | 4 +- README_CN.md | 1 + cmake/patches/ggml-metal-binary-archive.md | 53 ++++++++++++++++++++++ 3 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 cmake/patches/ggml-metal-binary-archive.md diff --git a/README.md b/README.md index ebbb9fa..8fb55be 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,9 @@ Apple Silicon), CUDA, or Vulkan. Drop-in replacement for - **End-to-end CLI** — WAV in, MIDI/TXT/CSV out (mirrors Python `extract`). - **Small footprint** — ~50 MB GGUF for the 1.0-medium checkpoint, ~50 M params. - **Fast startup** — Metal binary-archive patch keeps first-run latency under a - second on Apple Silicon. + second on Apple Silicon. (The patch is kept in-repo at + `cmake/patches/ggml-metal-binary-archive.{patch,md}`; see the `.md` for + design and re-apply notes.) - **Third-party integration** — clean PIMPL C++ API; `add_subdirectory` and link `game_ggml::game_ggml`. - **Parity-tested** — full pipeline output matches the PyTorch reference bit-for-bit diff --git a/README_CN.md b/README_CN.md index f878c3d..61dcc02 100644 --- a/README_CN.md +++ b/README_CN.md @@ -9,6 +9,7 @@ - **端到端 CLI** — WAV 输入，MIDI/TXT/CSV 输出（镜像 Python `extract`） - **体积小** — 1.0-medium checkpoint 约 50 MB GGUF，约 50M 参数 - **启动快** — Metal binary-archive 补丁使 Apple Silicon 首次运行延迟低于 1 秒 + （补丁随生态解散收编于本仓库 `cmake/patches/ggml-metal-binary-archive.{patch,md}`） - **第三方集成** — 干净的 PIMPL C++ API；`add_subdirectory` 后链接 `game_ggml::game_ggml` - **逐位对齐** — 注入相同 RNG 时全流水线输出与 PyTorch 参考逐位一致 diff --git a/cmake/patches/ggml-metal-binary-archive.md b/cmake/patches/ggml-metal-binary-archive.md new file mode 100644 index 0000000..91cb423 --- /dev/null +++ b/cmake/patches/ggml-metal-binary-archive.md @@ -0,0 +1,53 @@ +# ggml-metal-binary-archive（本仓库所有权） + +> 本 patch 原属 KakaruHayate/ggml-patch 的「生态」扩张内容，现随生态解散 +> 收编回 game.cpp（即本仓库），由本仓库全权维护、随 ggml 升级重打。 + +## Purpose + +Cache compiled Metal pipeline state objects (PSOs) to disk via +`MTLBinaryArchive` so subsequent launches skip the expensive +`newComputePipelineState` compilation. On a fresh launch metal rebuilds +thousands of kernels, adding seconds-per-model to load time; this reduces it +to a single archive load. + +## Change + +`src/ggml-metal/ggml-metal-device.m` — add `MTLBinaryArchive` PSO cache: + +- `ggml_metal_archive_url()` reads `GGML_METAL_ARCHIVE_PATH` (falls back to + ~/.cache/ggml-metal archive path). +- At pipeline creation, try `newBinaryArchiveWithDescriptor` / completion + handler; on first run nothing is cached so it compiles normally. +- After compiling, capture the pipeline state into the archive via + `storeRenderPipelineState` and `commit` it to the archive file. + +Controlled by the same `GGML_METAL_ARCHIVE_PATH` env var; disable with +`GGML_METAL_DISABLE_ARCHIVE`. + +## Baseline + +Applied against **ggml v0.19.0** (`ggml-metal-device.m`). Verify with the +same command used in `cmake/Dependencies.cmake`: + +``` +git -C apply --check cmake/patches/ggml-metal-binary-archive.patch +``` + +Test: + +``` +GGML_METAL_ARCHIVE_PATH=/tmp/game-mtl-archive game_ggml_cli extract ... +# second run should show near-zero PSO compile; compare GAME_GGML_PROFILE +``` + +## Origin + +Internal Shenzhen branch derived from Metal submission overhead experiments. +Kept out-of-line from ggml main; re-apply per ggml upgrade (see +`cmake/Dependencies.cmake` `game_ggml_apply_patch`). + +## Ownership (2026-08) + +`ggml-patch` 已弃用；本 patch 收编于 game.cpp `cmake/patches/`（本目录）。 +改动本 patch 只改本目录，不改 ggml-patch 历史形态。