TensorFold：面向 Apple Silicon 与 NVIDIA GPU 的本地 LLM 推理引擎

项目简介

TensorFold 是一款开源的本地大语言模型推理引擎，由独立开发者 ashhart 维护，采用 Apache 2.0 许可协议发布。项目目标是让开发者在自己的硬件上以接近商业云服务的速度运行大模型——核心卖点是"Run LLMs, Fast"（跑 LLM，就是要快）。

与通用推理框架不同，TensorFold 同时面向两类主流硬件生态：Apple Silicon（通过 MLX 后端）和 NVIDIA CUDA GPU（要求 compute capability 8.9 及以上，即 Ada 架构 RTX 40 系列、Hopper、Blackwell 及 DGX Spark GB10）。两条后端路径共享同一套 OpenAI 兼容 API，客户端在 Mac 和 NVIDIA 服务器之间切换时几乎无需改动代码。

项目自 2026 年 6 月创建以来持续活跃，目前在 GitHub 上获得 1042 星、183 个 fork，2026 年 10 月 6 日仍在推送代码，官方文档完整覆盖 API 参考、量化支持、视觉输入、运行手册等章节。

核心功能

1. OpenAI 兼容 API 全家桶：内置 /v1/chat/completions、/v1/completions、/v1/responses（OpenAI Responses API）、/v1/messages（Anthropic Messages API）四套接口，同时兼容流式与非流式调用，原生支持函数调用（tools）、推理（reasoning/thinking）与图片输入。已有的 OpenAI 或 Anthropic 客户端代码改一下 base URL 就能直接接入。

2. 并行解码（Draft & Verify）加速：通过投机解码实现数倍吞吐提升。针对不同模型家族提供三种草稿机制——Nemotron 使用自带 MTP（Multi-Token Prediction）头、Qwen3.8 系列可选用 DFlash2 草稿模型或上下文副本（context copies）、GLM-5.3-Flash 在 CUDA 上可叠加 DFlash2。验证内核保证每一行的采样算术与串行解码完全一致（exact decoding），用户可以用 "draft": false 参数对比验证草稿与串行输出是否完全相同。

3. 多模型家族支持：开箱支持 Nemotron 3.5 Lightning 30B-A3B、Qwen3.8-27B、Qwen3.8 Flash Next、GLM-5.3-Flash、Gemma 4 26B-A4B、DeepSeek-V4-Flash 等主流模型，涵盖 MLX 2/4/5/6/8-bit、NVFP4、FP8、EXL3/TR3 等多种量化格式，甚至支持三值（ternary）Bonsai 2 27B 这样的极限量化模型。

4. 多模态视觉输入：通过 --vision 选项开启图片输入，GLM-5.3-Flash、Qwen3.5/3.8 dense 模型与 Flash Next（CUDA 需 --parallel 2 以上）均支持图文混合理解，与文本共用同一条 lane 引擎。

5. 生产级运维能力：内置 API Key 认证（支持 CLI/环境变量/文件三种来源，SHA-256 摘要比对，文件权限 0600 校验）、Prometheus 指标（/v1/metrics 输出请求数、KV 占用、草稿命中率、延迟）、TUI 控制台（tensorfold tui）、服务化安装（tensorfold service install）、前缀快照持久化与磁盘溢写（--spill-gib）等企业级特性。

技术实现

TensorFold 的核心技术差异点在于"精确解码"（exact decoding）与"共享轮次"（shared rounds）两个设计。精确解码要求：一条请求的草稿只有在与同一引擎串行解码产出的 token 完全相等时才会被接受，采样依赖于 prompt、显式种子、绝对位置和 token ID——这意味着投机解码不会引入任何数值漂移。CUDA 内核在多行并行验证时保持每行算术独立，MLX 引擎则允许一轮计算被多条请求共享，但每条流维护自己的状态与采样键，并发输出必须与单跑输出一致。

在内存管理上，MLX 侧实现了相当精细的预算控制：默认按物理内存 70% 划拨进程预算（GLM-5.3-Flash 在 256GB 以内 Mac 上可提到 85%），保留 3 GiB 给进程其余部分，通过 TENSORFOLD_MEMORY_LIMIT_GB 环境变量可手动覆盖。服务器会区分"权重+窗口请求+共享轮次"剩余空间，据此自动缩减上下文窗口或拒绝过大的请求，并给出可调整的建议值。CUDA 侧则按显存的 9/10（至少 4 GiB）划拨预算，启动时会报告原生容量与实际分配容量的差异。

解码调度上，--decode-share 参数控制"prompt 预填充期间回复继续解码的时间占比"（MLX 默认 0.25），实现长 prompt 与短回复的交错推进；--prefill-fp8 允许 prompt 阶段使用 FP8（e4m3）激活换取更低延迟；--kv-dtype int8/int4 可压缩 KV 缓存以延长可容纳的上下文长度。这些参数在 README 与 docs/recipes 目录下均有实测数据支撑。

快速上手

1. 安装：三选一——python -m pip install git+https://github.com/ashhart/TensorFold.git（通用）、brew install ashhart/tensorfold/tensorfold（macOS）、curl -fsSL https://tensorfold.dev/install.sh | sh（官方一键脚本）。需要 Python 3.11 及以上，Mac 上 MLX 0.32.2 及以上（pip 会自动装）。

2. 拉取模型：tensorfold pull TensorFold/Qwen3.8-27B-MLX-4bit z-lab/Qwen3.8-27B-DFlash2（提前下载权重与草稿模型），tensorfold models 列出可用家族，tensorfold info MODEL 在不下载权重的前提下检查配置。

3. 启动服务：tensorfold serve TensorFold/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit --name tensorfold，默认监听 127.0.0.1:8080，首次 serve 会自动下载缺失的 checkpoint。

4. 发送请求：客户端 base URL 设为 http://127.0.0.1:8080/v1，用任意 OpenAI SDK 或 curl 调用 /v1/chat/completions，模型 ID 从 /v1/models 获取。配置 API Key 后带上 Authorization: Bearer *** 头即可。

适用人群

• Mac 本地部署者：M 系列芯片用户希望在本机跑 27B~30B 级别量化模型，又不想折腾推理框架的配置细节；
• NVIDIA 开发者：持有 Ada/Hopper/Blackwell 架构显卡（RTX 40/50 系列、H100、B200、DGX Spark），需要高吞吐本地推理且希望与云端 OpenAI API 保持代码兼容；
• AI Agent 应用开发者：在构建 Claude Code、Cursor 类智能体工具时需要一个可靠的本地模型后端，同时希望统一接入 Anthropic Messages 与 OpenAI Responses 两套协议；
• 推理性能研究者：对投机解码（draft & verify）、MTP、DFlash2、NVFP4/FP8/EXL3 量化等技术感兴趣，希望有一个实测数据透明、文档完备的参考实现；
• 对数据敏感的企业团队：模型与数据全部留在本地或内网，通过内建的 API Key 认证与指标暴露满足基本的安全与可观测需求。

官方链接

• 官网：https://tensorfold.dev
• GitHub 仓库：https://github.com/ashhart/TensorFold
• 许可证：Apache License 2.0
• 安装脚本：curl -fsSL https://tensorfold.dev/install.sh | sh
• 运行手册：https://github.com/ashhart/TensorFold/blob/main/RUNBOOK.md
• API 参考：https://github.com/ashhart/TensorFold/blob/main/docs/api.md