recursive-oss/rec · 上手攻略

• 仓库：recursive-oss/rec
• 链接：https://github.com/recursive-oss/rec
• 分类：llm-infra / 本地推理引擎
• 作者：spark
• 更新：2026-10-23

§0 自检（三证 checklist）

• [x] GitHub URL 已 fetch：README 全文经 web_fetch 拉取（2026-10-23，HTTP 200）
• [x] README 子模块 anchor：命令表 11 条（rec launch / rec serve / rec auth token / rec doctor …）、安装脚本 install.sh、Apache-2.0 LICENSE 均已核对
• [ ] 顶会 venue + 年份：⚠️ 本仓库无相关论文/顶会 anchor。README 只链接了 Recursive 博客 introducing-recursive-flint 与 docs.recursive.com，无 arXiv ID、无会议名。按 W41 G1 指引，此项缺失已在正文开头标注 ⚠️，不作为「顶会背书」使用。
• 性能数字（verbatim）：README 称「Compared to llama.cpp, rec delivers 1.4–2.6× the token throughput」，测试条件为「Flint on Apple M4 Pro (48 GB), 4-bit weights, 1K–252K-token prompts and 1,024 output tokens. Five runs per context; prefill excluded」。
• ⚠️ 关键限制（verbatim）：「rec is optimized for single-session usage. To run multiple agents at a time, see our documentation for other ways to run our models.」

§1 是什么 / 解决什么问题

rec 是 Recursive AI 开源的自研大模型推理引擎，专为在 Apple Silicon Mac 上本地跑自家模型 Flint 而写。

要解决的核心问题有三个：

1. llama.cpp 太慢。README 直接点名对比：同样的 Flint + 4-bit 权重 + M4 Pro 机器上，rec 的 token 吞吐是 llama.cpp 的 1.4–2.6 倍。llama.cpp 的设计目标是通用跨平台 + 极低门槛，在 Apple Silicon 上留给专用优化引擎的空间很大。
2. 本地方案太琐碎。装 llama.cpp、找 GGUF、转换量化权重、写 server、接客户端——rec 用一条 curl 把「引擎 + 模型下载 + 服务启动 + harness 拉起」全包了：rec launch pi 一条命令跑通。
3. API 兼容性。它同时暴露 OpenAI 兼容（/v1/chat/completions）和 Anthropic 兼容（/v1/messages）两套接口，你已有的任何客户端基本改个 base_url 就能接。

注意定位：这是厂家的自家引擎——它只加载 Recursive 的 Flint 模型（model id 固定为 flint），不是通用推理引擎，不能拿它跑 Llama/Qwen/Mistral。

§2 快速安装

硬性硬件门槛（README verbatim）： - Apple Silicon Mac，M4 Pro / M5 Pro / M5 Max - 至少 48 GB 统一内存 - 约 30 GB 可用磁盘

安装：

curl -fsSL https://raw.githubusercontent.com/recursive-oss/rec/main/install.sh | bash

装完 rec 在 ~/.local/bin，数据在 ~/.local/share/rec。用 pi harness 还需要 Node.js 22 + npm。

装完先体检：

rec doctor      # 检查硬件与安装
rec pull        # 只下载模型，不启服务（推荐先做这步，约 30GB）

§3 核心用法

3.1 一键跑 harness（最常用）

rec launch pi          # 推荐，作者称与自家模型搭配性能最佳
rec launch opencode

首次运行会自动下载模型和 harness。模型服务器在关掉终端后继续运行，要停就 rec stop。harness 与你系统里已有的安装完全隔离（类似 npx 的沙箱思路）。

用自己装的 pi / OpenCode：

rec launch --args pi
rec launch --args opencode

这条命令只打印 rec launch 会用的环境变量和命令行，不实际执行；把 harness 路径换成你自己的即可。注意它同时会把你指向 rec 自己的 settings 和 sessions，想保留自己的配置需要删掉那几个环境变量。

在隔离环境里装插件：

rec exec pi install npm:PACKAGE

3.2 纯起服务（接自己的客户端）

rec serve     # 保持这个终端开着

看到 When flint is ready. 之后，从另一个终端打请求：

curl -fsS http://127.0.0.1:11500/v1/chat/completions \
  -H "Authorization: Bearer $(rec auth token)" \
  -H 'Content-Type: application/json' \
  -d '{"model":"flint","messages":[{"role":"user","content":"Say hello."}],"max_tokens":128}'

响应里生成文本在 choices 字段。

• OpenAI 兼容：base URL http://127.0.0.1:11500/v1，model flint，key 用 rec auth token
• Anthropic 兼容：把 ANTHROPIC_BASE_URL 指到 http://127.0.0.1:11500，token 走 bearer 或 x-api-key，model flint

3.3 命令速查

每条命令支持 rec COMMAND --help。

§4 典型适用场景

• Apple Silicon 高端机 + 想跑本地模型做编码助手。你有 M4 Pro 48G 或 M5 Max，内存够，又不想为云 API 付费，pi / OpenCode 是现成的 coding harness——这是最贴合 README 意图的用法。
• 长上下文场景。README 的吞吐测试覆盖到 252K-token prompt，对比图也按 1K–252K 逐段画。长文档分析/大 repo 问答是它的宣称强项区。
• 隐私敏感任务。模型完全本地，代码不出机器；API 只监听 127.0.0.1:11500。
• 想试 Flint 但不想折腾环境。不接受 llama.cpp 那种手动流程的话。

不适用：多 agent 并发（见 §5）、非 Apple Silicon、非 Flint 模型、团队共享服务。

§5 坑与注意（三段式：现象 / 影响 / 修复）

坑 1｜单会话限制，最容易踩 - 现象：README 明确警告「rec is optimized for single-session usage」，多 agent 同时跑要走官方文档里的另一套方案。 - 影响：拿它当共享推理服务、或同时开三个 pi 会话，会遇到争抢/不支持——而这不是配置问题，是设计边界。 - 修复：先按单会话用；要并发就去 docs.recursive.com/getting-started 找官方推荐路径，别硬改。

坑 2｜硬件门槛不是「建议」是「要求」 - 现象：README 列的 M4 Pro / M5 Pro / M5 Max + 48GB 统一内存 + 30GB 磁盘，是支持列表，不是参考配置。 - 影响：M1/M2/M3 或 16GB 机器用户照着装完才发现跑不动，白下 30GB。 - 修复：装之前先 rec doctor（若已装），或直接核对自己的机器型号和统一内存。

坑 3｜curl | bash 装法需自行把关 - 现象：官方只给 curl -fsSL .../install.sh | bash 这一条路，没有 pip/brew 之类的更安全选项。 - 影响：管道执行远端脚本，主流发行版已默认拦截；对供应链有顾虑的用户无法绕过。 - 修复：可以先 curl -fsSL .../install.sh -o install.sh 落到本地读一遍再执行——脚本在公开 GitHub 上可审。

坑 4｜PATH 只对「新终端」生效 - 现象：README 写「installs rec in ~/.local/bin and adds it to your PATH for new terminals」。 - 影响：装完在当前终端敲 rec 报 command not found，误以为装失败。 - 修复：新开一个终端，或手动 export PATH="$HOME/.local/bin:$PATH"。

坑 5｜服务端常驻，关终端不关进程 - 现象：「The model server continues to run after you close the terminal」，只能 rec stop。 - 影响：误以为终端关了服务就停了，实际模型还占着 30GB+ 内存；下次 rec launch 可能撞上旧实例。 - 修复：养成 rec status / rec stop 习惯；rec launch 前先看状态。

坑 6｜基准数字的口径不能丢 - 现象：1.4–2.6× 的前提是「M4 Pro (48 GB) + 4-bit weights + prefill excluded」，每档 5 次运行。 - 影响：拿这个倍率去推 M5 Max 或长 prompt prefill 阶段的收益，会高估。 - 修复：引用时把口径一起写上；对比自己的场景要另测。

坑 7｜版本/子命令可能漂移 - 现象：本次核对基于 2026-10-23 的 main 分支 README（仓库卡记录最近提交同日）。命令表齐全但未见显式 release tag 锚点。 - 影响：后续版本新增/改名子命令时，旧教程里的 rec <cmd> 可能失效。 - 修复：⚠️ 用前先 rec update + rec --help；本文未锁定 commit hash，落地前建议对 main HEAD 复核一次。

坑 8｜harness 隔离有代价 - 现象：rec launch 拉起的是 rec 自带的 pi/OpenCode，与系统安装隔离（需 rec exec 才能操作）。 - 影响：你在系统里熟悉的插件、配置、快捷键在 rec 环境里全都没有，第一次用要重新配。 - 修复：接受隔离，或用 rec launch --args pi 指向自己的安装（记得按 README 删掉指向 rec settings/sessions 的环境变量）。

坑 9｜只能跑 Flint 这一家模型 - 现象：所有命令与 API 示例里 model 硬编码为 flint；定位是「inference engine for running Recursive's language models」。 - 影响：想用它当通用本地推理后端（比如跑 Qwen 3）会完全落空——这是厂商模型配套引擎，不是 llama.cpp 那种通用底座。 - 修复：需要跑开源权重仍用 llama.cpp / MLX；需要 Flint 的极致速度才上 rec。

坑 10｜卸载会删模型 - 现象：rec uninstall 描述为「Remove rec, its models and its settings」。 - 影响：把 30GB 已下载的模型一起删掉，重装要重下。 - 修复：只想换版本用 rec update；确需清理前确认不再需要本地模型。

§6 与同类对比

一句话定位差异：Ollama 管「装得省事」，llama.cpp 管「跑得通用」，MLX 管「贴着 Apple」，rec 管「把 Flint 跑到最快」。它们的交集其实很小——如果你不是 Flint 用户，rec 基本不在你的候选集里。

§7 一句话推荐结论

有 M4 Pro 48GB 及以上、又恰好想跑 Recursive 的 Flint 追求极限本地速度的，用 rec，它把 llama.cpp 那一套繁琐流程压成了一条 rec launch pi；除此之外的人，请老实回去用 llama.cpp 或 Ollama——因为 rec 不是通用引擎，且明写着只优化单会话。

来源：GitHub README（web_fetch，2026-10-23 拉取，HTTP 200）+ repo card organized/repo_cards/4572-recursive-oss-rec.md。未 clone、未运行代码。版本相关处均已标注 ⚠️。