TensorFold 是一个纯原生的 LLM 推理引擎，用 Zig 编写、直接运行 Metal 与 CUDA 内核，无需安装 Python 或 MLX。本文将带你走完第一个请求的全流程：用tensorfold pull一键下载并校验模型，再发一条curl请求，约 5 分钟在本地部署一个 OpenAI 兼容的 Chat 服务。

1️⃣ TensorFold 是什么：无 Python 依赖的本地推理引擎

TensorFold 1.0.5 以单个可执行文件的形式提供大语言模型服务：引擎直接读取模型 checkpoint、处理 tokenize 请求、在 GPU 上运行推理内核。

项目结构上，模型管理子命令（models、info、pull）实现在 zig/src/cli/cli.zig，下载与校验逻辑在 zig/src/cli/pull.zig，HTTP 服务实现在 zig/src/server/ 目录中。

2️⃣ TensorFold 安装步骤：macOS 与 Linux 两种方法

方法一：macOS Homebrew 安装（最简单）

brew install ashhart/tensorfold/tensorfold tensorfold --version tensorfold capabilities --json

Homebrew 会把原生二进制注册为tensorfold命令，capabilities --json可以查看当前二进制支持的参数与平台值。

方法二：Linux / 发布包安装（CUDA 用户）

从项目发布页下载对应平台的发布包（arm64 选linux-aarch64，x86_64 选linux-x86_64），连同附带的 sha256 校验文件一起下载并验证：

V=1.0.5 curl -fLO "发布页地址/tensorfold-$V-linux-x86_64.tar.gz" sha256sum -c tensorfold-$V-linux-x86_64.tar.gz.sha256 tar -xzf tensorfold-$V-linux-x86_64.tar.gz cd tensorfold-$V-linux-x86_64 bin/tensorfold-native --version

发布包要求 glibc 2.28 以上，以及提供libcuda.so.1的 NVIDIA 驱动。CUDA 内核已内嵌在可执行文件中，无需额外安装。详细步骤见 RUNBOOK.md。

3️⃣ 三步下载模型：tensorfold pull 一键获取并校验

以 Nemotron 3.5 Lightning 30B-A3B（MLX 4-bit 量化）为例，一条命令即可完成下载：

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

pull命令背后做了不少"保险工作"：

• 全文件校验：大文件逐段做 sha256，小文件用 git blob sha1 校验，防止下载损坏；
• 高速下载：大文件切成多段，最多 16 条连接并行拉取；
• 断点续传：中断后重新执行pull，只补齐缺失的片段；
• 拒绝不兼容模型：1.0.5 不支持的模型家族会直接拒绝下载。

模型会落到 Hugging Face 缓存目录（~/.cache/huggingface/hub/）。下载完成后用两个子命令确认：

tensorfold models # 列出缓存中可服务的 checkpoint tensorfold info TensorFold/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit

info会展示该 checkpoint 的模型家族、量化格式、上下文窗口和内存下限，帮你判断本机能否跑得动。

4️⃣ tensorfold serve 常用参数速查

在确认模型可用后，启动本地 Chat 服务（注意：服务是常驻进程，保持终端运行）：

tensorfold serve "$HOME/models/nemotron-lightning" \ --name local-model --parallel 1 --context 8192 --temperature 0 --no-thinking

新手只需关注这几个高频参数：

服务默认只监听127.0.0.1，本机访问无需鉴权；如需远程访问，加--host 0.0.0.0 --api-key-file ...，客户端通过Authorization: Bearer KEY携带密钥。完整参数表见 README.md。

5️⃣ curl 第一个对话：3 个请求验证服务

新开一个终端，先用健康检查和模型列表确认服务就绪：

curl -fsS http://127.0.0.1:8080/health curl -fsS http://127.0.0.1:8080/v1/models

然后发出第一个 Chat 对话请求：

curl -fsS http://127.0.0.1:8080/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"local-model","messages":[{"role":"user","content":"用一句话打个招呼"}],"max_tokens":128,"temperature":0}'

成功时会收到类似这样的 JSON 响应（内容为示例）：

{ "model": "local-model", "choices": [ { "message": { "role": "assistant", "content": "你好！我是一个运行在你本地机器上的语言模型。" } } ], "usage": { "prompt_tokens": 23, "completion_tokens": 15, "total_tokens": 38 }, "tensorfold": { "tokens_per_second": 118, "time_to_first_token": 0.31 }

tensorfold字段是原生服务独有的运行统计，包含解码速率、首 token 延迟、草稿接受率等指标——这也是它比通用推理框架更有"工程师味道"的地方。

想要流式输出？在请求体里加上"stream": true，回复将以 SSE 逐段推送，最后一个事件携带 token 用量。

多轮对话则只需把上一轮的assistant回复追加进messages数组再发一次即可，后续轮次会自动复用已缓存的前缀状态，响应更快。请求字段与路由的完整说明见 docs/api.md。

6️⃣ 选对模型：按硬件匹配官方认证清单

不是任意模型都能跑——TensorFold 只服务经过认证的"模型 + 硬件"组合。1.0.5 的认证清单如下：

各模型的完整使用配方（checkpoint 来源、版本 revision、启动参数）都在 docs/recipes/ 下，例如 docs/recipes/nemotron-3.5.md、docs/recipes/qwen3.8-27b.md。

7️⃣ 常见问题速查：部署卡住了怎么办

更多排查细节见 RUNBOOK.md。

写在最后

回顾一下这条 5 分钟路线：brew install（或解压发布包）→tensorfold pull下载校验模型 →tensorfold serve启动服务 →curl发出第一个 Chat 请求。全程只用了四条命令，没有一行 Python。

接下来你可以试试：

• 加--dashboard参数启动，打开本地/dashboard页面实时查看服务状态；
• 把 OpenAI 客户端的 base URL 指向http://127.0.0.1:8080/v1，直接复用现有工具链；
• 阅读 README.md 了解上下文压缩（--compact-at）与 Living Weights 等进阶能力。

本地跑通第一个请求，只是起点——这个 Chat 服务已经完全兼容 OpenAI 协议，你的应用代码几乎无需改动。