TensorFold#

TensorFold 通过一个 Zig 二进制文件在 Apple Silicon 和 NVIDIA GPU 上提供语言模型服务。该引擎读取检查点、对请求分词，并直接运行 Metal 或 CUDA 内核。提供服务不需要安装 Python 或 MLX。

使用编程智能体进行构建？让它在编写任何代码之前先加载贡献者技能。

使用智能体参与贡献#

在编辑 TensorFold 之前，请使用 Agent Traffic Control，以便贡献者和智能体避免重复工作和冲突变更。 在选择 issue 之前查看实时智能体雷达，并遵循 CONTRIBUTING.md 和 ATC 贡献者说明。

将 ATC 安装或升级到 0.9.4 或更高版本，然后在更新后的 TensorFold 克隆中运行：

npm install -g github:ashhart/ATC
atc check ISSUE --json
atc claim ISSUE --json

将 ISSUE 替换为 issue 编号，并且只有在完整检查表明该工作空闲后才认领。 TensorFold 启用了自动公开签到：成功的新认领会启动雷达上的匿名会话并返回其会话编号。 保留该编号，不要启动重复会话。 对于已经属于你的工作，使用 atc start ISSUE --json 启动会话。 只有在希望显示已验证的 GitHub 名称时，才向 claim 或 start 添加 --github-name；--local 会将新会话保留在你的机器上。 看板显示 issue、活动状态和最后签到；GitHub 仍会将验证评论与其作者关联。 确认发布是公开的；unavailable 表示公开更新失败，即使本地认领或会话成功。

仅在智能体工作期间、在其五分钟签到过期之前发送心跳：

atc pulse ISSUE SESSION working --json
atc who path/to/file --json
atc overlap --json
atc land ISSUE SESSION --json
atc release ISSUE --json

在适当的时候使用 reviewing 或 blocked，在会话停止时落地（land），并在打开 pull request 之前解决重叠。 在打开 pull request 之前，让智能体运行 pull request 技能；支持技能的智能体可以将其安装为 tensorfold-pull-request。

快速开始#

从 Qwen3.5-2B 开始，这是在 Metal 和 GB10 上检查过的小型 4 位检查点。以下命令会下载其 固定修订版，然后将其作为 local-model 提供服务。模型权重有自己的许可证。 正在审查或基准测试 TensorFold？评估 TensorFold 涵盖固定、签名检查、 容器以及无需 GPU 的测试。

搭载 Apple Silicon 的 Mac#

使用 Homebrew 安装，然后启动服务器：

brew install ashhart/tensorfold/tensorfold
tensorfold pull mlx-community/Qwen3.5-2B-MLX-4bit@93760be4f1f69842a46bc13dbdc0f19e291392a3
tensorfold serve mlx-community/Qwen3.5-2B-MLX-4bit --name local-model --context 8192 --no-thinking

搭载 NVIDIA GPU 的 Linux#

使用适用于你的 CPU 的发布归档：GB10 上使用 linux-aarch64，x86_64 主机上使用 linux-x86_64。 它需要 glibc 2.28 或更新版本，以及 NVIDIA 驱动 R580 或更新版本（CUDA 13.0），并提供 libcuda.so.1。请保持归档中的目录在一起。 其内核使用 CUDA 13 构建，因此 TensorFold 在启动时会拒绝较旧的驱动；nvidia-smi 会显示已安装的驱动版本。 参见 CUDA 运行手册，了解运行时库和支持的 GPU。

V=1.2.7
case "$(uname -m)" in
  aarch64|arm64) PLATFORM=linux-aarch64 ;;
  x86_64) PLATFORM=linux-x86_64 ;;
  *) echo 'No release archive for this CPU' >&2; exit 1 ;;
esac
curl -fLO "https://github.com/ashhart/TensorFold/releases/download/v$V/tensorfold-$V-$PLATFORM.tar.gz"
curl -fLO "https://github.com/ashhart/TensorFold/releases/download/v$V/tensorfold-$V-$PLATFORM.tar.gz.sha256"
sha256sum -c "tensorfold-$V-$PLATFORM.tar.gz.sha256"
tar -xzf "tensorfold-$V-$PLATFORM.tar.gz"
export PATH="$PWD/tensorfold-$V-$PLATFORM/bin:$PATH"
tensorfold() { command tensorfold-native "$@"; }
tensorfold pull mlx-community/Qwen3.5-2B-MLX-4bit@93760be4f1f69842a46bc13dbdc0f19e291392a3
tensorfold serve mlx-community/Qwen3.5-2B-MLX-4bit --name local-model --context 8192 --no-thinking

发送请求#

让服务器保持运行。在另一个终端中，在任一平台上运行：

curl -fsS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"local-model","messages":[{"role":"user","content":"Say hello in one sentence."}],"max_tokens":128,"temperature":0}'

该 API 还提供 completions、Responses 和 Anthropic Messages。/v1/models 列出所提供的名称。 在搭载 NVIDIA GPU 的 Windows 上，请遵循原生 Windows 构建指南。 使用 tensorfold --help、tensorfold capabilities --json 和 tensorfold serve REPO --help 来检查你的二进制文件。 你也可以提供完整的本地检查点目录或现有的 Hugging Face 缓存。

tensorfold web [ARGS...] 会打开 TensorFold Web，这是一个用于选择、运行模型并与之聊天的小型本地 Web 应用。 如果需要安装，交互式发布二进制文件会在你同意后，提出使用 uv 安装其匹配版本。 有关手动安装和无人值守使用，请参见 Web 启动器。

--parallel N 将活动请求上限设为 N；额外的请求会等待空闲槽位。 省略该标志会使用 --parallel auto，它会在内存和引擎允许的范围内请求最多八条流。 如果引擎无法容纳那么多流，显式数字会被拒绝。 阅读引擎启动时的容量行，例如 CUDA 上的「8 streams at once」，了解它接受的计数。 关闭 API 认证时，/health 会将 live.connections 报告为活动请求加等待请求， 将 live.waiting 报告为排队数量。例如，8 个连接中有 4 个等待，意味着 4 个活动请求。 完成或取消活动请求会释放其槽位；取消等待请求会将其从队列中移除。

Mac 应用#

TensorFold 桌面工作区捆绑了本地引擎、模型下载、硬件建议、实时生成指标、编程工作器和文档编辑。 下载 Apple Silicon beta 9 DMG，或从 app/ 构建。 桌面应用会直接启动捆绑的 tensorfold-native 可执行文件。 app/mobile/ 中的移动客户端仍是预览软件。

TensorFold Starlight（企业版）#

TensorFold Starlight 为组织提供一个受治理的 OpenAI 和 Anthropic 兼容端点，用于管理 Mac、Linux GPU 服务器和 Windows 机器上的 TensorFold 引擎集群。 它通过组织的身份提供商（OIDC 或 SAML，支持 SCIM 预配）让人登录，决定谁可以使用哪个模型以及模型在哪里运行，在节点上放置并监督模型，并核算每一个词元。 它可以完全离线运行，也可以在相同的身份、策略和预算下代理经批准的前沿提供商；安装指南涵盖 Docker、Kubernetes 和 Linux 服务。 Starlight 位于自己的仓库 ashhart/tf-starlight 中：它固定其测试所用的 TensorFold 发布版本，并在 CI 中针对该发布版本检查其节点传递给 tensorfold serve 的每个标志。 Starlight 是新产品：仍需真实 GPU 集群或身份提供商租户的关卡列在其资格说明中。

Living Weights（实验性）#

Living Weights 教会一个正在运行的模型在其自身权重中学习新事实。使用 --slide 启动 Nemotron 3.5 Lightning 服务器，并告诉它一些事情：每个通过课程检查的事实都会写入检查点文件夹的 文件中。这是实验性的：相关事实可能相互干扰，过去几十个事实以及开启思考后，回忆会下降，而且学到的事实在 Mac 上会损失一些解码速度。已知问题 中有详细信息。

tensorfold pull TensorFold/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit
hub="${HF_HUB_CACHE:-${HF_HOME:-$HOME/.cache/huggingface}/hub}/models--TensorFold--NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit"
src="$hub/snapshots/$(cat "$hub/refs/main")"
mkdir -p ~/models && cp -RL "$src" ~/models/nemotron-living # always teach a copy
(umask 077; openssl rand -hex 24 > ~/models/slide-key) # --slide starts only with a key
tensorfold serve ~/models/nemotron-living --slide --api-key-file ~/models/slide-key

让该服务器保持运行，并从另一个终端发送课程：

curl -N http://127.0.0.1:8080/v1/slide/learn -H "Authorization: Bearer $(cat ~/models/slide-key)" \
  -H 'Content-Type: application/json' -d '{"text": "I like blue."}'

改为发送一份文档，它会找出其中的事实并逐一学习。打开 http://127.0.0.1:8080/slide 以 3D 形式观看：事实、每个事实在模型层中占用的神经元、保存它们的分片 文件，以及当前正在运行的课程。

学习可在 Apple Silicon Mac 和 NVIDIA GB10（DGX Spark）上运行，在一个设备上学习过的文件夹可以在另一个设备上提供服务。在 APFS 卷上，cp -cRL 会创建一个克隆，在课程修改它之前共享原始文件的数据。它会重写文件夹中的文件： 在第一课之前，服务器会将原始文件保存在隐藏快照中，而 tensorfold slide rollback ~/models/nemotron-living 会将它们放回，撤销每一课。Living Weights 指南涵盖密钥、教学文件和网页、omp 的 /learn 命令、 3D 视图、撤销课程以及预期情况。

选择一个模型#

以下是原生发布版的提供路径。一个配方也可能描述较旧的 Python 0.6.6 引擎； 请将其原生部分与当前变更结合使用。 下方硬件记录的是已记录的适用范围，而不是未经测量的最低要求。上下文、并行请求、提示缓存 和草稿器都需要权重之外的内存。tensorfold info REPO 报告检查点的内存下限。 如果没有发布 RAM 容量，请在为大型检查点提供服务之前检查该下限。 CUDA 发布镜像包含 sm_80、sm_86、sm_120 和 sm_121。A100（sm_80）有内核检查证据 （#846），但没有记录在案的已服务检查点，因此未进行模型资格认证。 Nemotron 和稠密 Qwen 有针对 sm_80 到 sm_89 的 NVFP4/FP8 回退代码（#901、#1470）；没有记录显示此类模型在 sm_80 到 sm_89 上运行过。

安装后运行表格中的命令。在 Linux 归档安装中，使用快速开始中的 tensorfold shell 函数。 REPO@revision 会固定一次拉取；拉取后，在提供服务时使用不带修订版的仓库名。 转换会被明确标记：其上游权重需要先经过链接的转换，才能原生提供服务。

GLM-5.3：一台机器还是两台？#

原生发布版未对单机上的 GLM-5.3 进行资格认证。GLM-5.3 EXLR8 home 需要两台 256 GB M5 Ultra Mac； 其配方给出了拉取和服务命令。GLM-5.3-Flash 是另一个模型： 其原生 Metal 配置需要两台 M5 Ultra。原生 CUDA 有记录的 TP=2 和 TP=3 配置，包括 在两台和三台 GB10 上的 FP4-Local 和 XSFP4。旧配方中的单台 256 GB Mac GLM-5.3-Flash 命令适用于 Python 0.6.6，而不是此发布版。 关于 NVFP4 路径，请参见 CUDA 上的 GLM-5.3-Flash 以及 两台 GB10 上的贡献运行覆盖了什么。

DeepSeek 检查点尚未由任何发布版二进制文件提供服务：全模型关卡 #827 仍然开放。 MiMo 的原生后端尚未进入发布版。Bonsai 的三元打包和 Gemma 4 26B-A4B 仍仅支持 Python； 它们不是原生下载推荐。已知问题列出了当前限制， 包括 Flash Next 的共享会话缓存/性能行为以及 27B 的草稿器限制。

精确解码#

每个被接受的草稿必须等于同一原生引擎在 "draft": false 时产生的词元。 恢复的请求必须等于全新执行，每条并发流必须等于其单独运行。 比较会固定检查点、后端、设置和运行时。 不同的量化和不同的后端可能产生不同的输出。 Metal 上的 Flash Next 在显式 --parallel N 大于 1 且能容纳那么多会话时，使用共享目标轮次。 那里的单个贪心请求使用 GPU 侧轮次，并在第二个请求到达时移交。 --parallel auto（默认值）和 --parallel 1、学习以及双 Mac 服务使用单回复驱动。 FZ_BATCH_MTP_SERIAL=1 在共享主机上恢复串行 MTP 草稿。 较早的 MTP 链回执记录了自己的固定提交。 Nemotron、GLM、2B 模型和 Qwen3.8-27B 使用共享车道轮次（shared lane rounds）。 在 Metal 上，27B 共享轮次中的最多 128 条流各自绘制自己的 DFlash2 树。

磁盘上的模型#

tensorfold pull TensorFold/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit
tensorfold models
tensorfold models --json
tensorfold info TensorFold/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit

pull 会将检查点下载到 Hugging Face 缓存，并与 Hub 核对下载内容：大文件按 sha256，小文件按 git blob sha1。 大文件通过最多 16 个连接分块下载，中断的拉取会利用缺失的分块续传。 它会拒绝 model_type 没有原生家族的检查点，并为 --drafter 获取 27B 的 DFlash2 草稿器。models 会列出它认识的模型类型的缓存检查点，info 显示一个检查点的家族、格式、上下文和内存下限。 models --json 将同一列表作为一个文档输出给程序：schema 为 1，每个检查点包含 repo、family 和 model_type；family 是显示标题，model_type 是用于匹配的键。 tensorfold serve REPO 按仓库名提供缓存的检查点。

上下文压缩#

压缩默认关闭，关闭时每个回复都保持不变。 使用 --compact-at 时，会溢出的对话会被压缩，而不是被拒绝。 服务器逐字保留系统提示和最近的轮次，并且绝不会将工具调用与其结果分开。 较旧的轮次会变成一条记忆笔记：目标、约束、进展、决策、下一步、确切的名称和数字，以及工具调用读取或更改的文件。 之后的每次压缩会更新之前的笔记，而不是从头开始。发送回压缩后对话的客户端会保留其笔记。 回复会在 tensorfold.compaction 下携带笔记和压缩计数，每个回复都会报告 context_window 和 context_used。 相同的请求会得到相同的压缩和相同的回复。使用 --compact-memory 时，存储的笔记会在请求之间保留。

Cortheon 模式#

默认关闭。--cortheon 会为每个聊天请求提供 Cortheon 的推理程序和由服务器运行的网络研究，因此任何 OpenAI 兼容客户端无需设置即可获得该能力。 模型会按其任务类型经历 Cortheon 的各个阶段，并且可以调用 cortheon_search 和 cortheon_fetch，服务器运行这些调用而客户端看不到它们。 关于当前事实的问题，或使用外部库进行构建的请求，会在模型开始之前进行研究。 更改了文件的编程任务会被要求在完成之前运行其测试。 网络文本会被过滤掉针对模型的指令，且读取只访问公共地址。 启用该标志后，根据对话编写的搜索查询会发送到 DuckDuckGo，或在设置 BRAVE_SEARCH_API_KEY 时发送到 Brave，页面从此机器获取；不启用时，服务器不进行搜索，也不读取页面。 参见 Cortheon 模式。

模型发现#

GET /v1/models（以及 /models）会公布每个提供的名称和别名。当引擎报告有限的 上下文窗口时，每个条目都会包含相等的 context_length 和 max_model_len 整数扩展字段。这些 是已加载引擎的有效提示加回复词元限制，包括任何启动内存适配； 它们不是默认回复限制。未指定引擎窗口时会省略这两个字段。客户端应 仍然处理按请求的内存拒绝：公布的上下文并不保证每个工作负载都能容纳。

会思考的模型还带有 OpenRouter 风格的 reasoning：default_enabled、default_effort（仅在 使用 --reasoning-effort 时），以及 supported_efforts——其模板命名的级别，从高到低，当模板有思考开关时最后是 none。不给级别命名的模板会省略 supported_efforts。这些描述的是 chat 和 Responses 请求。

服务标志#

只读的 /memory 诊断会报告进程占用和生命周期峰值、 可用的后端分配计数器，以及应用的保留前缀计划，而不改变内存策略。

二进制文件的 capabilities --json 响应会列出其支持的标志和平台特定值。 serve MODEL --help 会打印用法而不加载模型。

--prompt-cache-gib 适用于 Nemotron、Flash Next、GLM、Qwen3.8-27B 和 LFM2.5-24B-A2B， --prompt-cache-over-cap 适用于相同模型，但 GLM 除外。 --learn 将共享提示前缀（例如系统提示及其工具）保留在磁盘上，以便新对话在重启或升级后恢复它们，只要计算出相同的比特。它涵盖单台 Mac 上的 GLM-5.3-Flash、Nemotron 和 Flash Next；Qwen3.8-27B、Qwen3.5-2B、LFM2.5-24B-A2B、GLM-5.3（EXLR8）和 CUDA 服务器会在启动时拒绝它。 Metal 上的 Qwen3.8-27B 还会从服务器第一个槽位中上次回复留下的状态恢复后续轮次，当提示缓存没有保存到那么远时：该轮次只读取其新词元，即使在缓存无法保留长对话的 Mac 上也是如此。当缓存无法保留整个上下文时，服务器还会在每个提示历史结束处保留该槽位的 DeltaNet 状态，因此模板丢弃上一条回复推理的轮次可以从那里恢复。回复与全新提示传递的词元相同；TF_QWEN27_SLOT_RESUME=0 会同时关闭两者。

采样默认值来自检查点的 generation_config.json，然后由服务标志和请求字段覆盖。 --context 0 是家族特定的；对 GLM 使用正限制，并检查启动时报告的容量。 支持的环境变量列在 capabilities --json 中，包括 API 密钥、请求日志和 Hugging Face 缓存路径。 TF_Q27_PROFILE=N 使原生 Metal Qwen3.8-27B 服务器每 N 个解码轮次记录一次按类别的 GPU 时间明细（1 表示 64），并在其回复中添加 gpu_seconds；这仅用于诊断，被分析的轮次运行会更慢。

社区基准#

tensorfold benchmark MODEL 在缓存的模型上运行公共代码和聊天测试夹具，并保存可移植的回执； --publish 可选地将其提交到 tensorfold.dev 进行审查。参见基准命令和测量定义。

构建与贡献#

使用 .zig-version 中固定的 Zig 版本，目前是 0.17.0。 .metal 源文件需要 Xcode 的 Metal 编译器。安装完整 Xcode 及其 Metal Toolchain 组件 （xcodebuild -downloadComponent MetalToolchain）；仅安装 Command Line Tools 会使每次内核编译失败，并提示 unable to find utility "metal"。

zig build native -Dcpu=apple_m1
zig build test test-golden -Dcpu=apple_m1

结构化输出和必需的工具调用需要发布归档中的 lib/ 或 zig build grammar -Dxgrammar=DIR；使用 git clone --branch v0.2.8 --recurse-submodules https://github.com/mlc-ai/xgrammar 准备 DIR（使用原生构建相同的 --prefix 作为 grammar）。

要为单个 GPU 构建一个精简服务器（zig build -Dgpu=spark -Dnvcc=...，比四目标服务器小约 69%），参见为单个 GPU 构建服务器。

在 macOS 上，测试还会运行可用的 Metal 设备检查。主机测试子集参见 CONTRIBUTING.md。

服务器是 zig-out/native/bin/tensorfold-native。 发布归档包含原生可执行文件、运行时资产和许可证通知；打包描述了经过资格认证的 CUDA 输入。 关于缓存感知的性能回执，请参见已观察的缓存基准证据。 客户端保留服务器使用情况和输出指纹，并验证冷/重用状态，而不是推断它们。

阅读 CONTRIBUTING.md 了解精确性、精度和性能关卡。 编程智能体还应加载 docs/recipes/SKILL.md；支持技能的智能体可以将其安装为 tensorfold-contributor。 TensorFold 采用 Apache-2.0 许可证；参见 LICENSE、NOTICE 和 THIRD_PARTY_NOTICES.md。

贡献者#

感谢每一位向 TensorFold 发送 pull request、测量结果或 bug 报告的人：

@0mao0、@321sssrt-bit、@AbrahamCete、@aditya1503、@AdrianBinDC、@ajensenwaud、@akol1、@alenperic、@Alexbob0、@alexderz、@anvilsong、@Arminova、@b-ostrov、@BadAd84、@barelyworkingcode、@Benjamin-Wegener、@benthecarman、@benwilson、@BHCC2025、@Bizuayeu、@BlivionIaG、@BobClawblaw、@borodach23、@Boscoeuk、@boxabirds、@brandonmmusic-max、@bunnyfu、@CanadaApollo6、@CerebralCoding、@cesarswong、@chadhurley25075-png、@chaog992、@Charlie-Louis、@Chedrian07、@chris247474、@christrade215、@crescit、@cshintov、@cwschroeder、@DakotaTexas、@danyo1399、@Deesha08、@Defilan、@DevRico003、@di37、@diwakergupta、@drowzeys、@easthambuilds、@ecohash-co、@edurdias、@eleqtrizit、@ericlsimplifi、@EugeneClaw、@fche、@feni6、@florianbrede-ayet、@gbgbgbg、@GDACONSULT、@gecobattya、@gilby、@Gogo6969、@gprot42、@GraithSecurity、@grantoverton、@grearjake-star、@greatyingzi、@GustavBlack、@harrisonfriia、@haxudev、@heitke、@hichaiuse、@ivanfioravanti、@jasontitus、@javierbits、@jayleaton、@jeffpeng3、@jeidbugs404、@Jenpo、@jerryfane、@jetnet、@jishnuvenugopal、@jkuepker、@joeynyc、@johnymoo、@JordiPosthumus、@joshuaswarren、@JRaxworthy、@jrb-ai、@jschmied、@juliankang4、@justincasey、@kelchm、@kieranscotney、@kingjamez、@kky42、@laudney、@lcgutierrez、@LECYWZA、@lijian1999、@liumorrisclaw、@LXD-8、@m-naoki-m、@mapamalu、@mcclanahanaman、@MESevenJourney、@mgoldwasser、@MiaAI-Lab、@mikolaj92、@millaguie、@Mirrdhyn、@Moutonc、@MovieMaker93、@mrpmorris、@mrv777、@MV10、@NeoAiLabs、@Nipale-ai、@nmcbride、@nood-co1、@nullburn、@olexale、@omar16100、@optimisme、@otarkhan、@outcastofmusic、@paragontasx、@peacockesq、@philip-pentatonic、@plotarmordev、@pmeenan、@ppardus、@pulseandthread、@quigles1977、@rafafortes、@raymondkpwong、@robertpitt、@rootsbymenda、@RoscoeTT、@RS91Dev、@russellmm、@salmanarshad321、@samwang0041-star、@sanjaibalajee、@satindergrewal、@scottleimroth、@sethforprivacy、@sfxnz、@shantanugoel、@simon-lin88、@simonmd、@spenchey、@squarrier、@ss-cong、@Stephane-Eden、@styles01、@SvangenStudios、@swbiggart、@SxMShaDoW、@sxuff、@taussoe、@tfolkman、@ThinkOffApp、@ThomasHalwax、@Thotheris、@tinyapps、@tolewis、@tomByrer、@tonydehnke、@tournierjc、@tovereast、@tpischke、@urtho、@valacroix、@vcruz305、@vinicius-symetrix、@wojo、@xjqx2z、@yguanrong、@Yuepixel、@YvesLaRose、@ZackSample、@zweck。

docs/credits.md 说明了原生引擎各部分承载了谁的 Python 引擎工作。

可用内存配置说明了如何记录已应用的预算、上下文、缓存状态和进程峰值。