怎么读这一卷

主线位置：三条主线的总览。本页把算子主线、求导主线、推理主线各列一遍，标出每一步落在哪个函数上、哪一页讲它；再讲 Cargo feature 怎么决定这三条线上有哪些代码：没开 metal / cuda 时，Storage 的那个变体由 dummy 类型占位，只会返回错误。「一次 matmul」和「生成一个 token」用实验把算子主线和推理主线各走一遍。

flowchart TB
  start[从这里开始] --> q{读这一卷为了什么}
  q -->|会用| use1[01 全景]
  use1 --> use2["02 张量 和 07 模型"]
  q -->|读懂实现| all[00 到 11 按顺序]
  q -->|只关心 Metal| gpu["一次 matmul 再到 03 Metal"]
  q -->|自己写一个| hands["06 量化 再到 11 动手"]

锁定版本

源码链接一律指向 tag：https://github.com/huggingface/candle/blob/0.11.0/...。crates.io 上发布的 candle-*-0.11.0 和 tag 是同一份代码。仓库的合并多是 squash，提交标题末尾的 (#NNNN) 就是 PR 号；CHANGELOG.md 停在 v0.3，近两年的改动只能从提交记录里查，本卷的「冷知识」都从这里来。

实测平台是 M2 Max、macOS 27、rustc 1.99.0。GPU 只实测了 Metal；CUDA 后端（cuda_backend/、candle-kernels）只读源码，凡是只读了源码的地方都会写明。

三条主线

全卷沿三条线展开，每页开头都会标出本页在哪条主线上。

算子主线：一次 a.matmul(&b)?

flowchart TB
  mm["Tensor matmul"] --> chk["形状检查 算 bmnk"]
  chk --> lock["storage 读锁"]
  lock --> st["Storage matmul"]
  st --> same["同设备 同 dtype"]
  same -->|Cpu Cpu| cpu["gemm 或 sgemm"]
  same -->|Metal Metal| mtl["编码 MLX gemm"]
  cpu --> out["新 Tensor 带 BackpropOp"]
  mtl --> out
  out --> read["to_vec2 读回"]
  read -->|Metal| wait["提交并等待"]

第 5 步和第 7 步的分界值得记住：在 Metal 上，a.matmul(&b)? 返回时内核只是编码进了命令缓冲区，GPU 可能还没开始算；读数据或 device.synchronize() 时才提交、等待。另一个时刻是攒够数：每取 50 次编码器提交一次。CPU 上第 4 步返回时结果已经算完。实验见一次 matmul。

求导主线：一次 loss.backward()?

flowchart TB
  var["Var new"] --> fwd["每个 op 记 Op"]
  fwd --> bw["Tensor backward"]
  bw --> topo["sorted_nodes 拓扑排序"]
  topo --> rev["倒序套求导规则"]
  rev --> gs["GradStore 按 TensorId"]
  gs --> opt["优化器按 Var 取梯度"]

求导不是单独的一层：图就是张量之间的 Arc 引用，和算子主线是同一批调用。

推理主线：生成一个 token

flowchart TB
  read["Content read"] --> build["ModelWeights from_gguf"]
  build --> fwd["forward input pos"]
  fwd --> emb["Embedding"]
  emb --> norm["RmsNorm"]
  norm --> attn["注意力 加 KV 缓存"]
  attn --> mlp["MLP 用 QMatMul"]
  mlp --> logits["logits"]
  logits --> pick["取样"]
  pick -->|下一个 token| fwd

safetensors 那条路换掉前两步：VarBuilder::from_mmaped_safetensors 按名字取张量，模型用 candle_transformers::models::llama 或 bert，见 VarBuilder、safetensors 与 mmap、BERT。分阶段计时见生成一个 token。

feature 各打开什么

candle-core 的默认 feature 是空的：不开任何 feature 时只有 CPU 后端，matmul 走纯 Rust 的 gemm crate。candle-nn、candle-transformers 有同名 feature，只是往下转发。candle-core/Cargo.toml 的 [features]：

两点从源码里能直接看到：

• accelerate 换掉的不只是速度。Accelerate 那份 f 只处理 F32 和 F64，遇到 F16 直接 bail!；gemm 那份接受 F16、F32、F64。BF16 两份都不接受。同一个 2×2 的 ones 矩阵乘，两种构建（intro-mm 开 accelerate，intro-mm-noacc 不开，release）：

  Copy

  intro-mm cpu F32: ok [[2.0, 2.0], [2.0, 2.0]]
  intro-mm cpu F64: ok [[2.0, 2.0], [2.0, 2.0]]
  intro-mm cpu F16: Err(the accelerate backend does not support f16 matmul)
  intro-mm cpu BF16: Err(unsupported dtype BF16 for op matmul)
  intro-mm-noacc cpu F32: ok [[2.0, 2.0], [2.0, 2.0]]
  intro-mm-noacc cpu F64: ok [[2.0, 2.0], [2.0, 2.0]]
  intro-mm-noacc cpu F16: ok [[2.0, 2.0], [2.0, 2.0]]
  intro-mm-noacc cpu BF16: Err(unsupported dtype BF16 for op matmul)
  

  打开一个 feature，F16 的 matmul 就从能用变成报错。速度上的差别（1024² f32 快约 4 倍）见一次 matmul 和 CPU 后端。

• README 的 Common Errors 一节写着：开 accelerate / mkl 时如果链接报 _sgemm_ 找不到，在二进制里加一行 extern crate accelerate_src;。candle-core 的 lib.rs 自己已经有 #[cfg(feature = "accelerate")] extern crate accelerate_src;，本卷的实验在 macOS 上开 accelerate 都没有额外设置就链接成功了。

没开 metal / cuda 时：dummy 后端

Storage 永远是 Cpu、Cuda、Metal 三个变体。没开 feature 时，lib.rs 把 dummy_metal_backend 里的单元结构体当作 MetalDevice / MetalStorage 导出，CUDA 同理。它们的方法要么返回 Err(NotCompiledWithMetalSupport)，要么调 fail!（unimplemented!）。细节见 Storage 与后端 trait。

intro-tree 只依赖 candle-core、不开任何 feature（debug）。正常的入口 Device::new_metal 返回 Err；但 dummy 的 MetalDevice 是公开的单元结构体，可以手写 Device::Metal(candle_core::MetalDevice) 绕过去，这时建张量仍然是 Err，问设备的 location() 就是 panic：

let fake = Device::Metal(candle_core::MetalDevice);
match Tensor::zeros((2, 2), DType::F32, &fake) { /* ... */ }
println!("is_metal = {}", fake.is_metal());
println!("location = {:?}", fake.location());

new_metal: Err(the candle crate has not been built with metal support)
new_cuda: Err(the candle crate has not been built with cuda support)
zeros on dummy: Err(the candle crate has not been built with metal support)
is_metal = true

thread 'main' (3735263) panicked at ~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/candle-core-0.11.0/src/dummy_metal_backend.rs:242:9:
not implemented: metal support has not been enabled, add `metal` feature to enable.

正常写法碰不到这个 panic；它说明的是 dummy 后端的设计：代码路径一条不少，只在运行期失败。好处是 storage.rs 里的 match 永远写三支、不用到处加 #[cfg]；代价是「没开 metal」要到运行期才知道。

错误风格：几乎处处 Result

candle-core 只有一个 Error 枚举和一个 Result<T> 别名。tensor.rs 里手写的 139 个 pub fn 方法中，121 个返回 Result；剩下的 18 个是 dtype、shape、dims、layout、id、is_contiguous 这类读字段的访问器，strided_index 这类遍历器的构造，加上 detach 和 from_storage。连运算符也不例外：bin_trait! 给 Tensor、&Tensor 实现的 Add、Mul 等，Output 都是 Result<Tensor>。所以 README 的速查表里写的是 &a + &b，用的时候是 (&a + &b)?。

形状不对是一个 Err 值，不是 panic（intro-tree 的 shape，debug）：

Err: shape mismatch in matmul, lhs: [2, 3], rhs: [2, 3]

错误在构造处调 Error::bt，它用 Backtrace::capture()，所以设了 RUST_BACKTRACE=1（或 RUST_LIB_BACKTRACE=1）时同一行后面会跟着整段调用栈，第 4、5 帧就是 Error::bt 和 Tensor::matmul。报错原文、bail!、Context 和 backtrace 的开销见错误。

let ok = (&a + &b + &a)?;
let chained = &a + &bad + &b; // bad 的形状是 [3]

ok = [12.0, 24.0]
chained = Err(shape mismatch in add, lhs: [2], rhs: [3])

和 burn 的对照只说一句：burn 的张量方法返回张量本身，形状和设备的错误是 panic，见 burn 卷的检查与报错；两种做法的取舍放在 08 设计取舍。

阅读路线

• 只想会用：读 01 全景；02 的 DType 与 Device 和错误；05 的 VarBuilder；07 的量化 llama 的一次前向和取样。
• 想读懂实现：按顺序读。02、03 讲清楚一次调用怎么从 Tensor 落到哪个后端之后，04 的求导和 06 的量化才好读。
• 只关心 Metal：一次 matmul → Metal 后端 → 自定义算子 → QTensor 与 QMatMul。
• 想自己写一个：读完 06 量化，去 11 动手，不依赖 candle 写 Q8_0 量化和 GGUF 头部解析。

前置知识

• Rust 的 trait、枚举和 ?：后端是枚举加两个 trait，见 Storage 与后端 trait。
• 一点深度学习：张量、矩阵乘、反向传播（backpropagation）、Transformer 的注意力和 KV 缓存。不需要会 PyTorch；README 的速查表把常用的 PyTorch 写法和 candle 写法一一对上了，见 candle 解决什么问题。
• serde：safetensors 的头部是 JSON，见 serde 卷。
• tracing：candle-transformers 的模型里到处是 tracing::span!，要配 subscriber 才看得到，见 tracing 卷。

小结

• 全卷对着 candle 0.11.0（tag 0.11.0，31f35b14，2026-06-26）写；GPU 只实测 Metal，CUDA 只读源码。
• 算子主线：Tensor::matmul → 读锁 → Storage::matmul 按设备对 match → gemm / sgemm 当场算完，或 MLX gemm 编码进命令缓冲区 → 新张量带 BackpropOp → Metal 读回时提交并等待。
• 求导主线：Var → 每个 op 视需要记 Op → sorted_nodes → 倒序求导 → GradStore → 优化器。
• 推理主线：Content::read → ModelWeights::from_gguf → forward（RmsNorm、注意力加 KV 缓存、QMatMul）→ logits → 取样。
• 默认 feature 只有 CPU；accelerate 换了 matmul 的实现，也让 F16 matmul 变成报错；没开的 GPU 后端由 dummy 类型占位，运行期报错。
• 几乎所有张量方法和运算符都返回 Result；Result<Tensor> 自己也实现了运算符，一条链只需要一个 ?。