nace-ai/kapitsa · 上手攻略

  • 仓库：nace-ai/kapitsa
  • 链接：https://github.com/nace-ai/kapitsa
  • 分类：llm-infra（本地推理引擎 / 编码 Agent 运行时）
  • 作者：spark
  • 更新：2026-10-21

一、它是什么

Kapitsa 是 Nace AI（nace.ai）团队做的 Apple Silicon 专用本地大模型推理引擎，用 C++ 写，Apache-2.0 许可，最近一次提交是 2026-10-20，155 star（周增 +175，增速很快但仍是早期项目）。

它的定位一句话讲清：把你 Mac 上的大模型，变成一个 OpenAI / Anthropic API 兼容的本地服务，然后直接喂给 Claude Code、Codex、opencode、Pi 这些编码 Agent。

这意味着它不是又一个"聊天壳"，而是把「MacBook 本地跑模型」这条路上最烦的两件事——装环境、接 Agent——打包成一个 brew 命令。README 首屏给的四行就是全部承诺：

brew install nace-ai/tap/kapitsa
kapitsa opencode --model 35b

二、它解决什么问题

在 Apple Silicon 上做本地推理，你已有的选项都不算轻：

  • LM Studio / Ollama：图形友好，但作为编码 Agent 的后端时接口细节要自己抠。
  • llama.cpp / MLX / mlx-lm：底层库，自己写服务代码。
  • 云端 API：快，但要花钱、要联网、代码出境。

Kapitsa 切的是中间这块：只做 Apple Silicon，只做编码 Agent 场景，把"选模型 → 量化 → 起服务 → 接 Agent"做成一条命令。

三个具体解决的痛点：

  1. 量化与投机解码的组合拳。它下载模型时会一并拉下配套的 MTP head 和 draft model（35B/27B 用 DFlash2，4B 用 z-lab 的 DFlash，Bolt/Super-VL 用 NVIDIA 的 LiLiCorr，Lightning 用 DSpark），跑推测解码。这是它速度优势的来源。
  2. Nemotron 全家桶的原生支持。别家的引擎对 NVIDIA 系模型支持是零散补丁，Kapitsa 把 Nemotron Dory1.0 4B、Nemotron 3 Nano 4B、Nemotron Nano 9B v2、Nemotron 3.5 Lightning 30B-A3B / Bolt 74B-A9B / Super-VL 120B-A12B 都做成了正式条目，README 的对比表里其他引擎那一列直接写 "no support"。
  3. 按机器选模型。kapitsa doctor 会告诉你这台 Mac 的 GPU、内存，以及哪些模型跑得动；kapitsa serve 不带 --model 时自动挑内存装得下的最优模型。

三、快速安装

硬件门槛很硬：M1 或更新的 Apple Silicon Mac + macOS 14 Sonoma 及以上。Intel Mac 完全不行。

# 方式一：Homebrew tap（推荐）
brew install nace-ai/tap/kapitsa

# 方式二：官方安装脚本
curl -fsSL https://raw.githubusercontent.com/nace-ai/kapitsa/main/install.sh | bash

装完先体检一下：

kapitsa doctor

它会输出这台 Mac 的 GPU、内存，以及每个模型的哪个精度能塞进内存。16 GB Mac 用 4b / 9b，24 GB 想跑 35B 要用它的 16gb 变体（10.8 GB），32 GB 起步才舒服。

四、核心用法

4.1 起一个 API 服务

kapitsa serve --model 35b

起来之后：聊天页面在 http://127.0.0.1:8000，API 在 /v1 下，同时兼容 OpenAI 和 Anthropic 两套协议。命令行不带 --model 时它会弹交互式选择器，列出模型、下载大小、是否已下载、★ 标记本机最优项，Tab 切上下文长度（默认 / 32K / 128K / 256K / max）。

4.2 启动编码 Agent

这是它最核心的差异化功能：

kapitsa claude     # Claude Code 跑在 Kapitsa 上
kapitsa codex      # 同理 Codex
kapitsa opencode   # 同理 opencode
kapitsa pi         # 同理 Pi

--model 同时决定模型和精度，比如 --model 35b:6bit。文档里写：编码 Agent 命令如果发现目标端口上已有服务在跑，会直接复用它并提示你。

4.3 模型管理

kapitsa pull 27b           # 只下载不启动
kapitsa list               # 已下载模型 + 磁盘占用
kapitsa rm 27b             # 删除并报告释放了多少空间
kapitsa import model.gguf  # 导入 LM Studio / Ollama / llama.cpp 的 GGUF
kapitsa update             # 自更新

kapitsa pull 支持 --dry-run --json 先看会解析成什么、实际不下载。--model 参数很灵活：可以是别名、可以是 35b:6bit 这种带变体的、可以是 Hugging Face repo id（org/name[@revision]）、可以是本地目录、也可以是 .gguf 文件。

4.4 跑基准

kapitsa bench              # 本机跑一遍
kapitsa bench --submit     # 结果加进社区榜单 RESULTS.md

README 的编码速度对比表（以下均为仓库自报数字，非我方独立复现）：

模型 精度 Kapitsa 头号对手
Qwen3.5 4B 4-bit 🟩 179 tok/s oMLX 102
Qwen3.8 27B 4-bit 🟩 63 tok/s mlx-serve 54
Qwen3.6 35B-A3B 4-bit 🟩 154 tok/s oMLX 127
Nemotron 3.5 Super-VL 120B-A12B NVFP4 🟩 85 tok/s oMLX 52

对比对象包括 oMLX、mlx-lm、mlx-serve、Ollama、LM Studio、llama.cpp、Rapid-MLX。

五、典型适用场景

  1. 离线 / 内网写代码。代码不能出院，要求本地推理，又要 Agent 体验——这是它最刚的场景。
  2. MacBook Air 16 GB 做随身开发机。4b（4.6 GB）或 9b（9.0 GB）能跑，9B 是文档明确说的"16 GB Mac 上能力最强的模型"。
  3. Claude Code 订阅太贵，想换成本地模型驱动同一套 Agent。kapitsa claude 就是干这个的。
  4. 跑 Nemotron 系列，特别是 Bolt 74B-A9B 这种 25.1 GB 就能上 32 GB Mac 的 agentic 模型——这是当前几家里独一份。

六、坑与注意

  1. 只有 Apple Silicon。Intel Mac 直接没戏，这是硬门槛不是软限制。
  2. 内存就是天花板，且别忘上下文。表格里的下载体积不含 KV cache 和 draft model 的占位，35B 4-bit 22.1 GB 是"刚好 32 GB Mac"的量级，实际还要看你要开多长上下文。
  3. 版本号会漂。本篇抓取的是 main 分支当前状态，最近提交 2026-10-20，⭐155。项目迭代极快（周增 +175），本文提到的模型条目、命令、tok/s 都可能过期——建议以 kapitsa --version 和 kapitsa doctor 的实测输出为准。（commit hash 待补：抓取时未取到具体 SHA。）
  4. Nemotron 模型的量化不是它自己做的。Bolt、Super-VL、Dory 用的是 NVIDIA 官方 checkpoint 原样加载，量化来自 NVIDIA 自己，不是 Kapitsa 的配方。宣传时别混淆。
  5. 4-bit 默认有质量代价。文档自己给了路径：--model 35b:6bit 比 4-bit 默认更接近 bf16（KL 对比见 docs/benchmarks.md），代价是内存和速度。
  6. Flash-Next 需要 128 GB Mac。105.9 GB 权重之外还有 32 GB n-gram 表放在 SSD 上靠 page cache 读，普通机器别指望。
  7. macOS 版本卡在 14 Sonoma，Sonoma 以下即使硬件够也不支持。
  8. 自更新会改自己的状态。kapitsa update 同时更新引擎和模型 revision pin，之后首次启动只拉变化的文件——这本身没问题，但如果你的环境是脚本托管的（brew services、KAPITSA_NO_PROMPT=1），更新会引入变量。

七、与同类对比

维度 Kapitsa LM Studio Ollama llama.cpp / mlx-lm
平台 仅 Apple Silicon 全平台 全平台 全平台
定位 推理引擎 + Agent 运行时 GUI 播放器 通用服务 底层库
OpenAI/Anthropic 兼容 API ✅ 部分 ✅ 需自写
一键起编码 Agent ✅（Claude Code / Codex / opencode / Pi） ❌ ❌ ❌
Nemotron 支持 全系 部分 部分 部分
认知负担 低（brew 一条命令） 低（GUI） 低 高（自己写代码）

取舍很清楚：如果你要「Mac 上本地跑模型给 Agent 用」，Kapitsa 省事最多；如果你要跨平台、GUI 调参、或者要完全掌控底层，那就是 LM Studio / llama.cpp 的地盘。Kapitsa 的短板是封闭且不透明——闭源二进制（虽有源码仓库，但核心是 C++），你很难像调 llama.cpp 那样自己改一个 kernel。

八、一句话推荐结论

如果你是 Apple Silicon 用户，需要离线/内网的编码 Agent 后端，Kapitsa 值得装；但请把它当"方便的实验台"而非"生产依赖"——项目太新（⭐155、周增 175），迭代极快导致命令和性能数字随时可能变，重活儿请先跑一遍 kapitsa bench 和 kapitsa doctor 拿自己的实测数据。

本文信息源：GitHub README（2026-10-20 main 分支）、docs/usage.md（raw 抓取）、organized/repo_cards/4475-nace-ai-kapitsa.md。benchmark 数字均为仓库自报，未独立复现。