TensorFold：让 Apple Silicon 和 NVIDIA GPU 直接运行语言模型
一个用 Zig 在 Apple Silicon 和 NVIDIA GPU 上跑 Qwen3.5-2B 等语言模型的本地推理引擎，不依赖 Python 或 MLX。
GitHub ashhart/TensorFold 更新 2026-11-13 分支 main 星标 1.9K 分叉 391
Zig LLM推理 Metal/CUDA Qwen3.5-2B Apple Silicon NVIDIA GPU

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你要在 Apple Silicon Mac 上用 Metal 服务 Qwen3.5-2B 4-bit 模型。
    README 的 Quick start / Mac with Apple Silicon：Qwen3.5-2B 是在 Metal 和 GB10 上检查过的模型。
  • 你需要一个不安装 Python 或 MLX 的本地 LLM 服务进程。
    README 开头明确写明 Serving needs no Python or MLX installation。
  • 你要测试 Nemotron 3.5 Lightning 的可写模型权重实验。
    README 的 Living Weights（experimental）章节提供 --slide、/v1/slide/learn 和 slide rollback。
  • 你关心并发草稿推理的确定性，并使用 Flash Next、Metal 或 Qwen3.8-27B。
    README 的 Exact decoding 章节说明 accepted draft、并发 stream 和 shared lane rounds 的一致性规则。

不适合，如果你

  • 你需要把 Living Weights 当作稳定的长期记忆系统，因为实验章节说明数十条事实后召回会下降。
    README 的 Living Weights（experimental）章节及 Known issues。
  • 你要求不同量化或 Metal/CUDA 后端产生完全相同的输出。
    README 的 Exact decoding 明确写明不同 quantizations 和不同 backends 可能产生不同输出。
  • 你需要移动端生产能力，因为 app/mobile/ 仍被 README 标为 preview software。
    README 的 Mac app 章节。
  • 你希望仅依据 /v1/models 的 context_length 保证所有请求都能装入内存。
    README 的 Model discovery 章节明确说 advertised context 不是每个 workload 都能满足的保证。

前置条件

  • Apple Silicon Mac 或 NVIDIA GPU；README 的核心描述覆盖 Metal、CUDA 和 Vulkan，Quick start 已验证 Apple Silicon 与 GB10。
  • 使用 Qwen3.5-2B 时需要先下载 pinned revision；README 的 Quick start 提供对应 tensorfold pull 命令。
  • Living Weights 需要 Nemotron 3.5 Lightning、--slide 和 slide key；README 说明 --slide starts only with a key。
  • 模型权重有独立许可证；README 的 Quick start 要求 Review model weights' own licenses。
  • Serving 使用 Zig binary，不需要 Python 或 MLX installation。

第一步命令（README 原文）

brew install ashhart/tensorfold/tensorfold

要注意

  • Living Weights 必须使用模型副本，否则 lessons 会改写 checkpoint 文件。
    README 的 Living Weights 命令注释写明 always teach a copy。
  • APFS 上的 cp -cRL 共享原始数据，课程修改后才产生变化。
    README 的 Living Weights 章节说明 cp -cRL 的 APFS clone 行为。
  • 默认关闭 Context compaction；启用 --compact-at 后旧对话会变成 memory note。
    README 的 Context compaction 章节。
  • Metal 的 Flash Next 并发路径需要显式 --parallel N，且 N 个会话必须能装入硬件。
    README 的 Exact decoding 章节说明 shared target rounds 和 --parallel N。

材料未说明

  • README 摘要没有给出 Linux with an NVIDIA GPU 的安装命令和支持范围。
  • README 摘要没有给出不同模型、量化和 GPU 的吞吐、延迟或显存数字。
  • README 摘要没有说明 Vulkan 的具体安装步骤、可用 GPU 型号或验证结果。
  • README 摘要没有说明 API 请求格式的完整示例；Send a request 章节被省略。
  • README 摘要没有说明构建所需的 Zig、TypeScript、Python 或 CUDA 版本。
  • README 摘要没有给出 10 位贡献者各自的活跃程度或未来维护计划。

💡 深度解析

6
不适合 我需要在 Mac、Linux GPU 服务器和 Windows 机器组成的节点池上提供统一的 OpenAI/Anthropic 兼容入口，并要求 OIDC 或 SAML、SCIM、模型授权、预算和 token 统计；只部署 TensorFold 核心仓库是否足够？
适合读者： 需要 OIDC/SAML、SCIM、节点调度、预算和审计的企业平台负责人

不适合只部署 TensorFold 核心仓库，因为 README 将企业身份、节点编排和预算治理明确放在独立的 TensorFold Starlight 项目中。

  • Starlight 才提供统一的 OpenAI/Anthropic 兼容 endpoint，以及 OIDC、SAML、SCIM 身份能力。
  • 它负责决定谁能使用哪个模型、模型运行在哪个节点，并对每个 token 进行核算。
  • Starlight 可管理 Macs、Linux GPU servers 和 Windows machines，但它位于独立仓库，并会固定所测试的 TensorFold release。
  • 因此 TensorFold 核心可作为受控推理节点，不能单独满足题述的企业治理边界；Starlight 本身仍标注为新项目，部分资格门槛需要真实 GPU 集群或身份提供商租户。
  • TensorFold Starlight（enterprise）："one governed OpenAI- and Anthropic-compatible endpoint"
  • TensorFold Starlight：OIDC、SAML、SCIM、模型授权、节点放置和 token accounting
  • TensorFold Starlight：覆盖 Macs、Linux GPU servers 和 Windows machines
  • TensorFold Starlight："Starlight lives in its own repository"
材料未说明：README 摘选未说明 Starlight 当前版本、生产 SLA、租户隔离细节或审计日志保留策略。；未说明 TensorFold 核心自身是否提供认证、TLS、限流和多租户隔离。
适合 我使用 Apple Silicon Mac，只想运行 README 已验证的 Qwen3.5-2B 4-bit 模型，并且不希望维护 Python 或 MLX 环境，TensorFold 是否适合？
适合读者： 在 Apple Silicon Mac 上离线运行量化模型、且不想安装 Python 或 MLX 的个人开发者

适合，因为该组合正是 README Quick start 明确验证的路径，而且服务端不需要安装 Python 或 MLX。

  • TensorFold 以 Zig 二进制读取 checkpoint，并直接执行 Metal kernel，适用于 Apple Silicon。
  • README 指定 Qwen3.5-2B-MLX-4bit 为在 Metal 和 NVIDIA GB10 上检查过的小型 4-bit checkpoint。
  • pull 使用固定 revision，便于复现；serve 还可以显式设置 8192 上下文并关闭 thinking。
  • 需要注意，模型权重有独立许可证，不能只依据 TensorFold 的 Apache License 2.0 判断权重使用权。
  • Quick start："Start with Qwen3.5-2B, the small 4-bit checkpoint checked on Metal and a GB10."
  • 项目说明："Serving needs no Python or MLX installation."
  • Mac with Apple Silicon：固定 revision 的 pull 与 `tensorfold serve ... --context 8192 --no-thinking` 命令
  • 项目数据：main_language 为 Zig；license 为 Apache License 2.0
brew install ashhart/tensorfold/tensorfold
材料未说明：README 摘选未给出该模型在具体 Apple Silicon 芯片和内存容量上的实际速度与峰值内存。；README 未说明该路径是否支持所有 Apple Silicon 型号的相同 Metal 性能。
不适合 我在 Apple Silicon Mac 或 NVIDIA GB10 上运行 Nemotron 3.5 Lightning 30B-A3B 4-bit，想把少量事实写回模型并支持 rollback；Living Weights 是否适合生产知识库？
适合读者： 想让 Nemotron 3.5 Lightning 学习几十条事实、并接受实验性 checkpoint 写回的 Apple Silicon 或 NVIDIA GB10 用户

不适合把 Living Weights 当作生产知识库，因为 README 明确将其标为 experimental，并报告事实互相干扰、几十条事实后召回下降以及 thinking 开启时的额外影响。

  • --slide 会把通过 lesson 检查的事实写入 checkpoint 文件，而不是写入独立的标准知识库。
  • README 说相关事实可能互相干扰，超过几十条后 recall 会下降；Mac 上学习到的事实还会牺牲部分解码速度。
  • 使用前必须复制模型目录并生成 slide key；服务启动后会保存隐藏快照，slide rollback 可撤销 lessons。
  • 它支持 Apple-silicon Mac 与 NVIDIA GB10，且学习过的目录可跨两者服务，但这些可移植性说明不能消除实验功能的可靠性限制。
  • Living Weights：标题标注为 experimental
  • Living Weights："related facts can disturb each other, recall drops past a few dozen facts"
  • Living Weights：学习事实会在 Mac 上消耗部分 decode speed
  • Living Weights：Apple-silicon Macs 与 NVIDIA GB10 可运行，并提供 rollback 流程
tensorfold pull TensorFold/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit
材料未说明：README 摘选未给出不同事实类型的准确召回率、可接受事实数量或回滚耗时。；未说明 checkpoint 写回失败、磁盘损坏或进程中断时的恢复保证。
视情况 我负责接入多个 Hugging Face checkpoint，不想因为仓库名称看起来兼容就直接启动；我需要先检查 model_type、模型族、格式、context 和 memory floor，TensorFold 是否适合这套流程？
适合读者： 需要加载任意 Hugging Face checkpoint、但希望先确认模型族、格式、上下文和内存下限的模型集成工程师

视情况：TensorFold 对已适配模型提供了较好的检查与发现流程，但它不是任意 Hugging Face checkpoint 的通用执行器。

  • pull 会校验下载文件，并拒绝 model_type 没有原生 family 的 checkpoint；这能在加载前暴露一部分兼容性问题。
  • info 展示 checkpoint 的 family、format、context 和 memory floor，models --json 则输出供程序消费的 repo、family 与 model_type。
  • serve REPO 依赖缓存中的已知 checkpoint，因此仅凭仓库名不能推断能否运行。
  • 如果你的模型正属于项目支持的原生 family，这套流程适合；如果需要快速接入未适配的新模型，README 没有承诺自动支持。
  • Models on disk：`pull` 会拒绝没有 native family 的 `model_type`
  • Models on disk：`info` 展示 family、format、context 和 memory floor
  • Models on disk：`models --json` 输出 repo、family 和 model_type
  • Models on disk：`tensorfold serve REPO` 服务缓存 checkpoint
tensorfold info TensorFold/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit
材料未说明：README 摘选未列出完整支持的模型 family、model_type 与量化格式清单。；未说明遇到兼容 checkpoint 时是完全拒绝、部分 API 可用，还是仅缺少特定功能。
适合 我有 NVIDIA GB10（DGX Spark），希望运行 README 验证过的 Qwen3.5-2B 4-bit 模型，并通过 HTTP 服务提供给本地应用，TensorFold 是否适合？
适合读者： 拥有 NVIDIA GB10（DGX Spark）并希望以原生服务方式运行模型的 GPU 工程师

适合，因为 README 明确把 NVIDIA GB10 与 Apple Silicon 列为 Qwen3.5-2B 4-bit 的检查平台，并且 serve 会启动 HTTP 模型服务。

  • TensorFold 通过 Zig 原生二进制直接调用 CUDA kernel，不要求 Python 或 MLX。
  • 同一个 checkpoint 可以先由 pull 下载，再以模型名启动服务；模型服务暴露 /v1/models 等发现接口。
  • 但“在 GB10 上已检查”不等于所有 NVIDIA GPU 都有相同兼容性或性能，README 摘选也没有给出 CUDA 版本、显存峰值和吞吐数据。
  • 如果要管理多台 Mac、Linux GPU 服务器或 Windows 节点，治理能力应看独立的 Starlight，而不是把它归入核心引擎。
  • Quick start：Qwen3.5-2B 是在 Metal 和 GB10 上检查的 4-bit checkpoint
  • 项目说明："runs Metal or CUDA kernels directly"
  • Model discovery：`GET /v1/models`（也支持 `/models`）
  • TensorFold Starlight：治理 Mac、Linux GPU servers 和 Windows machines 的独立仓库
tensorfold pull mlx-community/Qwen3.5-2B-MLX-4bit@93760be4f1f69842a46bc13dbdc0f19e291392a3
材料未说明：README 摘选未提供 GB10 上的吞吐、首 token 延迟、显存占用或并发上限。；未说明目标 NVIDIA 驱动、CUDA 版本与 TensorFold v1.2.7 的具体要求。
视情况 我正在做一个 OpenAI 风格的编程助手，客户端需要读取 `/v1/models` 的 context_length、max_model_len 和 reasoning 字段；TensorFold 是否能满足接口发现需求？
适合读者： 正在构建 OpenAI 兼容编程助手、需要发现模型上下文窗口与 reasoning 元数据的应用开发者

视情况：TensorFold 能提供这些发现字段，但客户端仍必须处理请求级内存拒绝，不能把广告中的上下文长度当成每次请求都能成功的保证。

  • /v1/models 会公布服务名和 alias；当引擎具有有限上下文窗口时，会返回 context_length 与 max_model_len。
  • thinking 模型可携带 reasoning.default_enabled、default_effort 和 supported_efforts，适合客户端展示推理能力。
  • README 明确说上下文值是 prompt 加 reply 的有效限制，并包含启动时内存适配；每个工作负载仍可能因内存不足被拒绝。
  • 因此，如果应用只要求 OpenAI 风格发现接口，匹配度较高；如果要求所有模型拥有完整 reasoning 元数据，则需要接受字段可能缺失。
  • Model discovery：`GET /v1/models`（也支持 `/models`）
  • Model discovery："each entry includes equal `context_length` and `max_model_len` integer extensions"
  • Model discovery：thinking 模型携带 `reasoning` 元数据
  • Model discovery："clients should still handle per-request memory refusals"
tensorfold models --json
材料未说明：README 摘选未列出完整的 OpenAI chat、Responses 和 streaming 请求字段兼容矩阵。；未说明上下文压缩在 OpenAI 兼容请求中的具体触发条件和错误格式。

✨ 核心亮点

  • Zig 二进制直接运行 Metal 或 CUDA 推理
  • 无需安装 Python 或 MLX 即可启动服务
  • Qwen3.5-2B 4-bit 模型提供 Metal 验证路径
  • 精确解码保证草稿结果等于原生引擎结果
  • Living Weights 实验功能会降低召回和 Mac 解码速度

🔧 工程化

  • tensorfold serve 可按 Hugging Face 仓库名提供模型服务
  • tensorfold pull 用 sha256 和 git blob sha1 校验模型文件
  • Living Weights 可用 --slide 将事实写入 checkpoint 文件
  • Context compaction 用 --compact-at 压缩超限对话

⚠️ 风险

  • Living Weights 会改写模型目录，需依赖 slide rollback 恢复
  • Living Weights 关联事实会互相干扰，数十条后召回下降
  • 不同量化和后端可能产生不同输出结果
  • 模型上下文公告值不保证每个请求都能满足内存

👥 适合谁？

  • 需要在 Apple Silicon Mac 上运行本地 LLM 的开发者
  • 使用 NVIDIA GPU 或 GB10 测试 Metal/CUDA 推理的团队
  • 需要 Qwen3.5-2B 或 Nemotron 本地服务的工程师