TensorFold Recipe Book 实战解读:模型配方索引、能力下限与精确性验收契约
TensorFold Recipe Book 实战解读:模型配方索引、能力下限与精确性验收契约
TensorFold 是一个面向 Metal、CUDA 与 Vulkan 的 LLM 推理引擎,而 docs/recipes/README.md 是它所有模型适配页(family page)的总入口:每一行指向一篇配方,注明该模型支持的 checkpoint、所用 kernel、运行限制,以及它属于原生引擎(native engine)还是冻结在 0.6.6 的 Python 引擎。本文以这份索引文档为主线,逐节拆解它的三类硬信息——配方矩阵、能力下限(capability floor)、精确性契约与测量规范——并结合仓库中的基准脚本、一致性验收工具与源码,说明如何把这些条目真正用起来:怎样选模型、怎样判断某张卡是否被“资格认证”、怎样测出的数字才算证据。
一页一模型:Recipe Book 的组织逻辑
索引开头就把写作口径定死了:每篇 family page 必须描述四件事——supported checkpoint(支持的权重)、kernels(内核实现)、operating limits(运行限制)、以及它覆盖哪台引擎。docs/recipes/README.md 用一句话区分了这两台引擎:
the native engine, or the Python engine frozen at 0.6.6.
这不是文字游戏,而是整个仓库的分水岭。原生引擎的代码位于 Zig 侧(例如 27B 的 Metal 实现放在 zig/src/families/qwen27/,CUDA 侧在 zig/src/families/qwen3_5/cuda_*.zig,见 Qwen3.8-27B 配方),Python 引擎则固定停在 0.6.6,只保留历史配方与贡献指南。因此阅读任何一篇配方时,第一件事是判断当前章节属于哪台引擎;把 Python 的单机命令套到原生发布上,是这类文档最常见的误用。
索引还规定了两条入口规则:
- 代理辅助贡献先读技能文档:
For agent-assisted contributions, read the TensorFold contributor skill before implementing a native family, kernel or serving change.对应 docs/recipes/SKILL.md,它要求贡献者在动手前写清“请求行为、复现、目标 commit、family、backend、checkpoint revision、量化、精度模式、GPU 类别、rank 数、以及验收阈值”。 - 索引本身不是教程:它只负责分发。真正的操作命令、环境变量与限制说明都在各自的 family page 里。
模型配方全表
下面完整保留索引中的配方矩阵,并把所有相对链接转换为以仓库根目录为起点的路径,便于直接跳转核查。
索引末尾还单列了 Persisted serving-state identities,它记录磁盘状态的所有者(disk owner)、兼容键(compatibility key)以及陈旧状态的 host 检查。这一条容易被忽略,但它决定了“重启后还能不能复用 prompt 缓存”——详见后文的持久化状态一节。
从这张表可以读出三条工程事实(均为文档显式给出的限定,而非推测):
- 同一模型可能有多份配方,因为后端不同。例如 dots.mocr 有 HIP 与 CUDA 两份,且 CUDA 版明确“只服务文本 prompt”,不支持视频、MTP head 或 Metal。
- 配方标题里常带限制语:
synthetic only、experimental、qualification pending、research checkpoint。这些词是资格声明,不是营销修辞。 - Draft(草稿/推测解码)能力是分级提供的:有的配方带 MTP drafts,有的带 DFlash2,有的明确“copy drafts, no EAGLE-3/neural drafter”。
两条引擎路线与贡献入口
索引在讲完表格后立刻给出“新模型该往哪写”的分流:
New families go on the Zig engine: adding a Zig family has the steps in order,
what each one gained, and which code owns it.
For the Python engine, frozen at 0.6.6, the contributor guides cover
adding an MLX family, adding a CUDA family and CUDA implementation rules.
即:
| 目标 | 指南 | 适用引擎 |
|---|---|---|
| 新增 Zig family、上满所有已知加速 | adding a Zig family | 原生引擎 |
| 新增 MLX family | adding an MLX family | Python 0.6.6 |
| 新增 CUDA family | adding a CUDA family | Python 0.6.6 |
| CUDA 实现规则 | CUDA implementation rules | Python 0.6.6 |
docs/recipes/adding-a-zig-family.md 的写法值得单独一提:它把一次 bring-up 拆成有序步骤,每一步都是一次“已知收益”,并列出该步由哪个 core block 承载。文档用三台机器的实测对比说明这条路线有效(Flash Next 6-bit 于 M5 Ultra、Nemotron 3.5 Lightning 于 M5 Max、Kimi K3 于四台 M3 Ultra),同时明确了两条纪律:
- 每一步都必须跑该步对应的 exactness check,而不是先“探一探”;
- 任何速度声明前,必须在同一台机器上与当前 release 做 served 侧对比,覆盖 generation、prefill、TTFT、0.5k 到 256k tokens、代码/散文/编辑三类负载,并且全部 greedy。
配套的代码归属表把 family 与共享块对应起来,例如 lanes/engine.zig 被 24 个 family 调用,prompt_cache.zig 被 CUDA 与 Metal 上的多个 host 使用。对文章读者最有用的一点是这条规则:
对表中没有使用的每个 block,PR 必须点名该 block 并解释为什么需要自己的代码,或者按名字拒绝该特性直到 block 覆盖它。
这意味着“自研一套缓存/调度”不是不能做,但必须显式付账。工程约束也被量化:源码文件不超过 600 行(CONTRIBUTING.md),设置项一律经 zig/src/platform/environment.zig 读取,策略开关放在 zig/src/core/profile.zig。
索引同时指向两条专题线:
- Drafter 训练:Training a drafter,从目标的
--record输出训练 learned block drafter,并记录每一步在 Kolibri-1 上的收益。 - EXL3 权重:EXL3 weights 与 universal EXL3 experts,描述为 Python 引擎 CUDA family 编写的共享 EXL3 模块:任意 codebook、每个 tensor 任意位宽、每个 MoE 投影一次 grouped launch。
Capability floor:能力下限表的正确读法
这是整个索引里最容易被误读的一节。原文先立规矩:
The native release includes CUDA kernels for sm_80, sm_86, sm_120 and sm_121. This is a build target list, not per-card model qualification.
也就是说,构建目标列表 ≠ 逐卡模型认证。四条事实必须分开记:
- Nemotron MLX 4-bit 已被检查的机器是 GB10、RTX 3090 与 RTX PRO 6000。
- A100(sm_80)只有 kernel-check 证据(来自 #846,记录在 CHANGELOG 1.0.12),没有已服务的 checkpoint 记录,因此“未获模型资格”。
tensorfold info REPO会打印 checkpoint 的内存下限(memory floor):权重加上 2 GiB 运行时余量。- 在 macOS 上,Flash Next(
qwen4_exp)checkpoint 不打印内存下限,而是打印 startup 与 cold pack 预算。
第 3、4 条可以直接在源码里验证。tensorfold info 的输出实现在 zig/src/cli/info.zig:普通路径打印 memory floor: {d:.2} GiB (weights plus a {d:.2} GiB runtime margin),Flash Next 路径打印 startup budget: ... both prompt planes/selectors, KV/state, keepalive and {d} GiB runtime reserve; trained window。而那个余量常量就在 zig/src/platform/memory_policy.zig:
pub const margin: u64 = 2 << 30;
2 << 30 正是 2 GiB。这也解释了为什么“权重能装下”并不等于“能服务”:上下文长度、并发请求数(streams)、prompt cache 与 drafter 都要在权重之外另占内存。索引另一处给出同类证据:27B 在 Metal 上启动时,slot 需要“权重与 8 GiB 余量之外的可用空间”(zig/src/native/qwen27_served.zig),这与 info 的 2 GiB 口径并不冲突——前者是服务准入时的策略余量,后者是 info 报告的统一口径。
能力下限表全文如下:
| Engine | Floor |
|---|---|
| Native CUDA, NVFP4 / FP8 | Nemotron 与 dense Qwen 对 sm_80 到 sm_89 有 non-cluster fallback 代码(#901、#1470)。没有任何 NVFP4/FP8 模型在 sm_80 到 sm_89 上运行的记录;不主张 A100 的模型资格。其他 family 保留各自的 gate。 |
| Flash Next, native CUDA | MLX 4-bit 在 GB10 上服务过;ModelOpt / two-local-rank 路径为实验性。多 rank 上做 drafting 必须关闭 prompt cache。不暗示在每个 release SM 上都获得资格。 |
| Intel GPU (XPU), Nemotron | 实验性。权重需要 17.3 GiB 设备显存(4k 到 128k 上下文时实际占用 18 到 19.4 GB);在 Arc Pro B70(32 GB)上测量。低于 24 GB 的卡未测,16 GB 卡装不下权重。 |
| Python 0.6.6 MLX, Apple Silicon | 历史 family page 的机器类别,不是实测下限:GLM-5.3-Flash 写给 256 GB Mac,约 151 GiB 常驻;DeepSeek-V4-Flash 相同,约 151 GiB;Flash Next 默认命令按 128 GiB M4 Max 配置;32 GB Mac 上的 Qwen3.8-27B 需要超过默认的 22.4 GiB。 |
读这张表时最该带走的判断是:“有 fallback 代码”是编译与内核层面的兼容性,“有模型资格”是有人真的把这套权重跑起来并留下 token 级证据。索引刻意把两者分开陈述,A100 就是典型样本——34 个 kernel 能为 compute_80 构建、16 项 kernel check 通过,但依然“not model-qualified”。
The contract:三条不可协商的等价关系
索引中篇幅最短、约束最强的一节是 “The contract”,它给出三条等价关系:
- 草稿输出必须等于同一引擎的串行输出(Drafted output must equal the same engine's serial output);
- 恢复的 prompt 必须等于全新服务的同一 prompt(A resumed prompt must equal that prompt served fresh);
- 每条并发流必须等于它单独运行时的结果(every concurrent stream must equal its solo run)。
并立即限定适用范围:只在相同权重、相同 runtime、相同设置之内成立;换后端或换量化,算术可以不同。这一点必须写进任何对比结论,否则“换了量化后 token 变了”会被误判为 bug。
采样键:seed + 绝对位置 + token ID
契约的实现基础是采样器的键设计:
The sampler keys each draw by seed, absolute position and token ID.
一个 draft 只有在与目标模型对同一键的抽样结果一致时才被接受。这解释了为什么“draft 看起来合理”不够——它必须与串行路径逐 token 相同。
校验行必须复用串行行的算术
Each verify row must use the serial row's arithmetic, including attention boundaries, routing ties and recurrence updates.
三个限定词都是实践中真正出事的地方:
- attention boundaries:分块/窗口边界改变了 softmax 的求和顺序,就会改变 bf16 结果;
- routing ties:MoE 路由打分并列时,选择顺序必须与串行一致;
- recurrence updates:线性注意力/循环状态(如 DeltaNet 类更新)的更新次数与顺序必须一致。
回滚必须恢复所有状态
Rollback must restore all state after the accepted path, including draft-head state.
这条覆盖了草稿被拒后的状态清理。漏掉 draft head 的状态,会让下一个 token 的 proposal 分布偏离,从而在两个本应相同的请求之间产生差异。
prompt 复用的精确规则
索引对 prompt cache 给出了可核对的算法描述,这是全文最具体的实现细节之一:
- MLX 的 planner 从 rendered tokens 计算 chunk,只缓存兼容的边界;
- resume 点是 assistant message 的起点,以及 tokenizer 暴露相应标记时的第二条消息起点;
- 距离上一个起点不足 256 token 的 resume 点被跳过;
- 否则 chunk 在第一个合格点结束,或超过 2,048 token 时结束;
- 没有识别到标记时,按 2,048 token 网格切分;
- 重写更早的模板文本会使复用失效;
- 复用已存前缀前,chunk 方案与 kernel/runtime identity 必须一致。
把这段规则与 tensorfold info、持久化键放在一起看,结论很清晰:prompt 复用的命中条件是“token 序列 + 切分方案 + 运行时身份”三者同时相符,而不是“提示词看起来一样”。
用 7 个 gate 把契约变成可执行验收
仓库把这套契约实现成了一个可直接运行的验收器:tools/conformance.py。它的文件头列出了全部 gate,与索引的三条等价关系一一对应:
| Gate | 检查内容 |
|---|---|
drafted |
每个 prompt(greedy 与带种子的采样)都等于其 "draft": false 回复;且至少要有一个 draft 被接受,否则判为 vacuous(空泛通过)而失败 |
repeat |
再跑一次 drafted 回复,逐个等于首次结果 |
concurrent |
在每个并发级别上,该数量的同时请求(drafted 与 plain)各自等于其 solo 回复;混在三条解码流中的长 prompt 不得改变它们,且自身等于 solo |
resumed |
缓存服务器上的多轮对话等于关闭 prompt cache 的服务器上的同一对话;fresh 侧必须报告 cached_tokens == 0,其后每一轮 resumed 必须 cached_tokens > 0 |
refusals |
profile 列出的每个请求都以指定状态码与错误文本被拒绝 |
cancel、evict |
中途截断的回复、被挤出缓存的 prompt,都让服务器回到与新启动时一致的状态(见 conformance_lifecycle.py) |
几个值得注意的设计细节:
- 等价性判据是完整 token-id 哈希(
tensorfold.token_sha256)。没有哈希的回复视为“未验证”,直接判该 gate 失败。 cancel与evict是唯一可跳过的 gate,且跳过必须写理由(打印SKIP);--plant会拒绝跳过。--plant GATE是负控制:人为种入一个故障,该 gate 必须变红,否则验收工具本身不可信。--stream让所有等价性回复走流式读取,用与基准客户端相同的 reader 解析,哈希、计数与文本必须一致;流在[DONE]前出错或结束即视为未验证。
profile 就是一份可复制的验收配置。以 tools/conformance_profiles/qwen35-cuda.json 为例,它固定了:
"serve": ["--backend", "cuda", "--context", "16384", "--parallel", "8", "--no-thinking", "--drafter", "{drafter}"],
"sampled": { "temperature": 0.8, "top_p": 0.95, "top_k": 20 },
"tokens": 64,
"seed": 7,
"levels": [1, 2, 4, 8],
"prompt_cache_gib": 2,
"ignore_eos": true
再加上 5 条短 prompt、一条 500 项的 long prompt、3 轮对话(首轮插入 900 项上下文),以及若干拒绝用例(如 n=2 必须返回 400 与 n must be 1; multiple choices are not supported)。这意味着验收不是“跑一条命令看看”,而是把并发级别、缓存预算、采样参数、拒绝语义全部钉死后重复执行。
运行方式(文件头给出的形式):
python3 tools/conformance.py tools/conformance_profiles/qwen35-cuda.json --binary BIN --model-dir DIR \
--drafter DRAFTER --output receipt.json
--binary 会按 profile 的 flags 自行拉起两台服务器(先关缓存的那台,再开缓存的那台);如果服务器已由你自己启动,则用 --url 与 --fresh-url。仓库现有 profile 还有 gemma4-cuda.json、qwen27-metal.json、qwen27-xpu.json。
Measurements:怎样测,才配叫证据
索引的测量一节先给了固定的公开 fixture:tools/bench_openai.py 内含一个裸的 Fibonacci 函数 prompt,以及一个询问“矩阵乘法如何使用 GPU”的 chat prompt,后者禁用 thinking。
标准命令(在启动 --name bench 的服务器后,从仓库根目录执行):
python3 tools/bench_openai.py http://127.0.0.1:8080 bench \
--tokens 64 --reps 5 --temperatures 1.0,0 --output bench.json
索引列出的方法学要点:
- 客户端先 warm 每个 cell;
- 使用 seed 1234 到 1238(默认
--reps 5正好五颗种子); - 报告首 token 之后的 decode 速率中位数;
- 采样 cell 使用 temperature 1、top-k 20、top-p 0.95;
- 客户端发送
ignore_eos: true:MLX、GLM CUDA、Qwen3.8-27B 与 Qwen3.6 CUDA 引擎会遵守,而 Flash Next 与 Nemotron CUDA 引擎可能在到达请求上限前于 EOS 停止; - 它测的是吞吐,本身并不证明 token 相等。
这些说法都能在源码中对上。看 tools/bench_openai.py:
- 头注释给出的公式是
Decode tok/s = (completion tokens - 1) / (last token time - first token time),并明确“与 CUDA 引擎的 bench 计时同一区段,排除第一个被采样 token”(第 3-4 行)。 - 请求体在第 39-44 行构造:
max_tokens、temperature、stream: true、stream_options: {include_usage: true}、ignore_eos: true;仅当temperature > 0时追加top_k=20, top_p=0.95。 - chat fixture 通过
chat_template_kwargs: {"enable_thinking": false}关闭思考(第 48-49 行)。 - 主循环先跑一次 warm-up,再跑
--reps次(第 115-116 行);种子为1234 + i(第 113 行)。 - 输出行包含
decode_tps_median、ttft_s_median,以及itl_mean_ms、itl_p50_ms、itl_p95_ms、tpot_ms、chunk_tpot_estimate_ms、round_gap_p50_ms、round_gap_p95_ms、tokens_per_chunk等 ITL/TPOT 指标(第 73-75 行),并附带bench_stream的边界指标。
更有价值的是它落盘的 evidence 字段(第 125-126 行):prompt_tokens、cached_tokens、tokens、cache_state、complete、token_sha、output_sha256、completion、tool_sha256。索引要求的“随结果记录 checkpoint 与 tokenizer revision、runtime 版本、后端、rank 数、启动命令与输出哈希”正对应这些字段——哈希是把吞吐数字变成可复核证据的关键。
同一节还给了两条纪律:
- 在并发场景使用
tools/bench_concurrent.py,加--alone --serial:--alone先让每个请求单独跑一遍,再校验并发回复的 token-id 哈希与之相同;--serial再把那些单独运行校验到"draft": false。这实际上是把索引的前两条契约接成了自动化流程。 - 长上下文与内存测量同样需要公开 prompt fixture 与精确的 rendered-token 数,并且要分开 cold、resumed 与 post-restart 三类请求。
bench_concurrent.py 的文件头还主动交代了一个容易被忽视的偏差来源:默认 cell 里所有流发送同一个 prompt,MoE 模型会把它们路由到同一批专家,从而美化多流速率;要避免这一点需用 --prompts FILE(例如 tools/bench_prompts.json)跑一个 “distinct” cell。默认四个 cell 是“代码/对话 × 采样/贪心”,每 cell 内 N 个同 prompt 请求同时起跑,第 i 条流用 seed + i(贪心则全部用同一 seed)。
最后是关于历史数字的一句硬话:All 0.3.5 decode, prefill, concurrency and peak-memory results are TBD [release-0.3.5]. Older public-fixture results in the CUDA family pages are historical measurements, not release qualification. 早期公开 fixture 的结果只是历史测量,不能当发布资格使用。
Kernel checks:等价性证明与“模型质量”证明是两件事
索引最后把内核校验分成两类用途,这一区分非常关键。
第一类:承诺机器码不变的重构。 对 CUDA 重构(包括改动共享头文件),使用 five-SM SASS identity runner:
tools/zig/sass_compare.sh BASE_TREE NEW_TREE --repo . --output sass-proof --zig /path/to/pinned/zig
该指南的要点是可直接执行的:
- 两个输入可以是本地 Git revision 或 checkout 目录;目录输入会包含未提交的源码字节,receipt 既记录 HEAD 也对快照取哈希;
- 基线应选在完整重构之前、终点选在最终固定头上,不要拿中间破树当基线;
- 输出目录必须是新的,运行器会保留快照、日志、命令、生成源码、fatbin 与 dump;
- 若 CUDA 不在
/usr/local/cuda/bin,需同时覆盖--nvcc与--cuobjdump; - 最多两个编译 job、nice 19;
--jobs 1串行; - 在 Mac 上还需
--cache-guard /path/to/cache_guard.sh; - 选择镜像的依据是“源码或其 quoted-include 闭包与改动文件相交”,且忽略预处理条件以保持闭包保守;改全局编译 flag 会选中所有目录内镜像;
- 每个选中镜像在两棵树上各编译两次,覆盖 sm_80、sm_86、sm_89、sm_120、sm_121(受镜像自身最低 SM 限制);
cuobjdump输出的每个 Function 都在每个受支持 SM 上比较,包括 outlined 函数、模板特化与植入的控制内核;指令文本与完整指令编码(含调度字)都必须一致;- 判定合格需要
exit 0且summary.json中mode: "sass"、qualified: true; --plan-only、--generate-only只做检查,qualified保持 false;--no-controls、--no-recheck仅用于诊断,即使比较一致也返回 exit 2;- 两个强制负控制:改变 FP4 的 pair 常量、反转 warp-sum 顺序,各自必须至少改变一个函数。
第二类:等价性与模型质量的分离。 索引的原话是:
Use exact equality for serial versus multi-row kernels and committed caches. Use a separate trusted forward for model-quality checks; agreement with one's own serial implementation does not establish model fidelity.
这条非常容易被踩:“多行 kernel 与串行 kernel 逐位相同”只证明实现一致性,不证明模型本身正确。要判断模型质量,必须拿一个独立的、可信的 forward 做参照。索引还列出四个覆盖要求:真实的 head 维度、稀疏注意力边界、partial keeps、以及不同长度的并发流;并且改动 kernel 或运行时之后,必须重新生成串行参考。
同一节还有一句常被忽略的测量纪律:
Measure dependent operations and complete requests. Independent microbenchmarks can hide launch cost, weight-cache effects and lost overlap with other work.
独立微基准会掩盖 launch 开销、权重缓存效应与重叠损失,所以要看依赖链和完整请求。
持久化状态:为什么“重建二进制”会让缓存变冷
索引用一行指向 Persisted serving state identities,而那份文档解释了 The contract 里“kernel/runtime identity 必须一致”的实际含义:原生磁盘存储用流式 SHA256 指纹把运行中的服务二进制与状态绑定,覆盖编译后的 host 代码、内嵌 shader、编译器选项与快照布局。因此:
- 重建或改动二进制会让可选的磁盘缓存冷启动;
- 旧文件留在原命名空间,并遵循既有的缓存预算与淘汰规则;
- 指纹使用 32 KiB 读缓冲,并在读取过程中检查文件戳;checkpoint、可执行文件与 kernel 资源在模型打开与服务期间必须保持稳定;
- checkpoint 键覆盖每个通过校验的索引分片路径(含子目录与 loader 接受的任何后缀)以及顶层辅助 safetensors 文件,绑定其名称、大小、inode 与修改/变更时间戳;
- 索引点名但目录缺失的分片会被以
IndexedShardMissing拒绝而不是打开旧命名空间。
不同 family 绑定的键粒度不同:Nemotron/Metal 绑定二进制、kernel 文本、精度模式、prompt step、coop K-slice 切分与其 scratch 行、probe、OS build 与 GPU;Flash Next/CUDA 还绑定 prompt 分块高度(TF_FLASHNEXT_CHUNK、_CHUNK_SOLO 或 --parallel 1 取更大 pass 都会冷启动)、NVFP4 prompt-tile 阈值、K32 tile、SM 数等。
条目里还交代了哪些设置不被计入键,例如 Flash Next 的 draft、window、round、graph、lane-parts、load-thread、I/O 与 dense-split 设置,理由是“保留的状态只来自 prompt pass,而这些设置要么到不了那里,要么以相同 launch 到达,要么在 --tp 2 时拒绝磁盘”。这种“逐项说明为何不入键”的写法,正是这份文档可信的原因。
对应的 host 检查:
zig build test-persistence-identity-host test-cuda-persistence-source-host compile-persistence-host -j1
zig build test-checkpoint-identity test-cuda-disk-open-host test-sessions test-frame-cache-identity-host -j1
zig build test-disk-identity-host -j1
其中第一条命令的 Metal consumer 编译与 checkpoint fixture 需要 macOS host,但不执行任何 GPU 调用。文档结尾同样收紧了结论:这些检查覆盖陈旧命名空间、真实的同 header 分片重写、二进制与被捕获 cubin 的变异、加载 variant 绑定、分配失败、规范 token 匹配与整文件指纹覆盖,但真正的 checkpoint/设备资格仍需要精确的 drafted/plain、resumed/fresh、concurrent/solo token 数组。
CUDA 加载路径的补充
索引在契约一节末尾给出一个具体入口:
For CUDA checkpoint loading, see load-time prefetch.
这说明“加载时间”被当作一等公民对待:它既影响冷启动的可测指标(见上文的 cold / resumed / post-restart 三分法),也影响 prompt cache 与磁盘状态的判定时机——索引要求 checkpoint、可执行文件与 kernel 资产在模型打开与服务期间保持稳定,任何加载期的重写都会打乱身份。
一份可直接照做的操作清单
把上面各节压成可执行顺序:
- 定位配方:在 docs/recipes/README.md 的表中找到模型行,打开对应 family page,先确认它讲的是原生引擎还是 Python 0.6.6。
- 确认内存:
tensorfold info REPO,读memory floor: X GiB (weights plus a 2.00 GiB runtime margin);macOS 上的 Flash Next 则改读 startup / cold pack 预算。上下文、并发、缓存与 drafter 都要在权重之外另算。 - 划清资格边界:查
Capability floor。sm_80 只是构建目标;A100 有 kernel-check 证据但无服务记录;XPU 路径为实验性且 16 GB 卡装不下 17.3 GiB 权重。 - 启动服务:示例用
tensorfold serve ... --name bench,需要草稿时显式--drafter(不带即 plain decode,见 Qwen3.8-27B 配方 的命令)。 - 测吞吐并留证:
python3 tools/bench_openai.py http://127.0.0.1:8080 bench --tokens 64 --reps 5 --temperatures 1.0,0 --output bench.json,保存evidence中的token_sha与output_sha256;注意 Flash Next 与 Nemotron CUDA 可能提前在 EOS 停止。 - 测并发等价性:
python3 tools/bench_concurrent.py http://127.0.0.1:8080 MODEL --levels 1,2,4,8 --alone --serial --output out.json;需要避免同 prompt 造成的专家路由偏差时,加--prompts tools/bench_prompts.json。 - 跑完整验收:选一个 conformance profile(如 qwen35-cuda.json),用
--binary或--url/--fresh-url跑 7 个 gate,并用--plant验证 gate 会变红。 - 改内核时加 SASS 门禁:
tools/zig/sass_compare.sh必须给出qualified: true才算机器码同一;否则只是“看起来一样”。 - 改内核或运行时之后:重新生成串行参考,重跑 exact equality;模型质量另用独立可信 forward 判断。
- 注意状态失效:重建二进制、改动 kernel 文本、改分块高度或权重文件被重写,都可能让磁盘缓存与 prompt 复用冷启动。
结语
这份 Recipe Book 的价值不在“列了 23 个模型”,而在它把三件事同时钉住了:哪份配方对应哪台引擎、哪张卡上到底有什么证据、以及什么才算通过。它的每条限制语(synthetic only、qualification pending、not model-qualified)都能在仓库里找到对应实现或检查;它的每条契约(drafted = serial、resumed = fresh、concurrent = solo)都能用 tools/conformance.py 的 gate 复现;它的每个数字都要求带上 checkpoint revision、runtime 版本、后端、rank 数与输出哈希。按这套流程读文档、取证据、报结果,才算是真正“用了”TensorFold 的配方。