蜡烛

Candle 是一个面向 Rust 的极简机器学习框架，专注于性能（包括 GPU 支持）和易用性。请尝试我们的在线演示： whisper, LLaMA2, T5, yolo, Segment Anything。

开始使用

请确保已按照 安装 中的说明正确安装了 candle-core。

让我们看看如何运行一个简单的矩阵乘法。将以下内容写入你的 myapp/src/main.rs 文件：

use candle_core::{Device, Tensor};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let device = Device::Cpu;

    let a = Tensor::randn(0f32, 1., (2, 3), &device)?;
    let b = Tensor::randn(0f32, 1., (3, 4), &device)?;

    let c = a.matmul(&b)?;
    println!("{c}");
    Ok(())
}

运行 cargo run 应该会显示一个形状为 Tensor[[2, 4], f32] 的张量。

如果你已经安装了支持 CUDA 的 candle，只需将 device 定义为 GPU 即可：

- let device = Device::Cpu;
+ let device = Device::new_cuda(0)?;

有关更高级的示例，请参阅下一节。

查看我们的示例

这些在线演示完全在您的浏览器中运行：

• yolo：姿态估计和目标识别。
• whisper：语音识别。
• LLaMA2：文本生成。
• T5：文本生成。
• Phi-1.5 和 Phi-2：文本生成。
• Segment Anything Model：图像分割。
• BLIP：图像描述。

我们还提供了一些基于命令行的示例，使用最先进的模型：

• LLaMA v1、v2 和 v3：通用 LLM，包括 SOLAR-10.7B 变体。
• Falcon：通用 LLM。
• Codegeex4：代码补全、代码解释器、网页搜索、函数调用、仓库级任务。
• GLM4：由 THUDM 发布的开放多语言多模态聊天 LLM。
• Gemma v1 和 v2：来自 Google Deepmind 的 2b 和 7b+/9b 通用 LLM。
• RecurrentGemma：Google 推出的基于 Griffin 架构的 2b 和 7b 模型，将注意力机制与 RNN 式状态相结合。
• Phi-1、Phi-1.5、Phi-2 和 Phi-3：1.3b、2.7b 和 3.8b 通用 LLM，性能可与 7b 模型媲美。
• StableLM-3B-4E1T：一个 3b 通用 LLM，在 1T 个英语和代码数据集上预训练而成。同时也支持 1.6b 的 StableLM-2，以及其代码变体。
• Mamba：仅用于推理的 Mamba 状态空间模型实现。
• Mistral7b-v0.1：一个 7b 通用 LLM，截至 2023 年 9 月 28 日，其性能优于所有公开可用的 13b 模型。
• Mixtral8x7b-v0.1：一种稀疏专家混合的 8x7b 通用 LLM，性能优于 Llama 2 的 70B 模型，且推理速度更快。
• StarCoder 和 StarCoder2：专门用于代码生成的 LLM。
• Qwen1.5：双语（英语/中文）LLM。
• RWKV v5 和 v6：一种具有 Transformer 级别 LLM 性能的 RNN。
• Replit-code-v1.5：一个 3.3b 专门用于代码补全的 LLM。
• Yi-6B / Yi-34B：两款双语（英语/中文）通用 LLM，分别拥有 6b 和 34b 参数。
• 量化 LLaMA：使用与 llama.cpp 相同的量化技术对 LLaMA 模型进行量化。
• 量化 Qwen3 MoE：支持 gguf 格式的 Qwen3 MoE 模型量化版本。

• Stable Diffusion：文本到图像生成模型，支持 1.5、2.1、SDXL 1.0 和 Turbo 版本。

• Wuerstchen：另一种文本到图像生成模型。

• yolo-v3 和 yolo-v8：目标检测和姿态估计模型。

• segment-anything：带有提示的图像分割模型。

• SegFormer: 基于Transformer的语义分割模型。
• Whisper: 语音识别模型。
• EnCodec: 使用残差向量量化技术的高质量音频压缩模型。
• MetaVoice: 文本到语音的基础模型。
• Parler-TTS: 大型文本到语音模型。
• T5、Bert、JinaBert：适用于句子嵌入。
• DINOv2: 自监督训练的计算机视觉模型（可用于ImageNet分类、深度估计、分割）。
• VGG、RepVGG：计算机视觉模型。
• BLIP: 图像到文本模型，可用于为图像生成标题。
• CLIP: 多模态视觉与语言模型。
• TrOCR：Transformer OCR模型，具有专门用于手写和印刷体识别的子模型。
• Marian-MT：神经机器翻译模型，根据输入文本生成翻译后的文本。
• Moondream：小型计算机视觉模型，能够回答关于图像的实际问题。

可以通过类似以下命令运行这些模型：

cargo run --example quantized --release

若要使用CUDA，请在示例命令行中添加 --features cuda。如果已安装cuDNN，则可使用 --features cudnn 以获得更高的加速效果。

此外，还有针对Whisper和llama2.c的一些Wasm示例。你可以使用trunk构建它们，或在线试用： Whisper、 llama2、 T5、 Phi-1.5和Phi-2、 Segment Anything Model。

对于LLaMA2，运行以下命令以获取权重文件并启动测试服务器：

cd candle-wasm-examples/llama2-c
wget https://huggingface.co/spaces/lmz/candle-llama2/resolve/main/model.bin
wget https://huggingface.co/spaces/lmz/candle-llama2/resolve/main/tokenizer.json
trunk serve --release --port 8081

然后访问 http://localhost:8081/。

有用的外部资源

• candle-tutorial：一个非常详细的教程，展示如何将PyTorch模型转换为Candle。
• candle-lora：高效且易用的Candle LoRA实现。candle-lora为Candle中的许多模型提供了开箱即用的LoRA支持，相关示例可在这里找到。
• candle-video：基于Candle构建的Rust库，用于文本到视频生成（LTX-Video及相关模型），专注于快速、无需Python的推理。
• optimisers：一系列优化器，包括带有动量的SGD、AdaGrad、AdaDelta、AdaMax、NAdam、RAdam和RMSprop。
• candle-vllm：高效的本地大语言模型推理和服务平台，包含兼容OpenAI API的服务器。
• candle-ext：Candle的扩展库，提供目前Candle中尚未实现的PyTorch功能。
• candle-coursera-ml：Coursera《机器学习专项课程》中ML算法的实现。
• kalosm：Rust中的多模态元框架，用于对接本地预训练模型，支持可控生成、自定义采样器、内存中向量数据库、音频转录等功能。
• candle-sampling：Candle的采样技术。
• gpt-from-scratch-rs：Andrej Karpathy在YouTube上发布的“让我们构建GPT”教程的Rust移植版，展示了Candle API在玩具问题上的应用。
• candle-einops：纯Rust实现的Python einops库。
• atoma-infer：Rust库，用于大规模快速推理，利用FlashAttention2进行高效的注意力计算、PagedAttention进行高效的KV缓存管理，并支持多GPU。它兼容OpenAI API。
• llms-from-scratch-rs：Sebastian Raschka的《从零开始构建LLM》一书代码的全面Rust翻译。
• vllm.rs：基于Candle的极简Rust vLLM实现。

如果您有其他补充，请提交拉取请求。

特性

• 简单的语法，使用起来感觉就像 PyTorch 一样。
  • 模型训练。
  • 可以嵌入用户自定义的操作/内核，例如 flash-attention v2。
• 后端支持。
  • 针对 x86 的优化 CPU 后端，可选 MKL 支持；针对 Mac 的 Accelerate 后端。
  • CUDA 后端，可在 GPU 上高效运行，并通过 NCCL 实现多 GPU 分布式计算。
  • WASM 支持，可以在浏览器中运行模型。
• 内置模型。
  • 语言模型。
    • LLaMA v1、v2 和 v3，以及 SOLAR-10.7B 等变体。
    • Falcon。
    • StarCoder、StarCoder2。
    • Phi 1、1.5、2 和 3。
    • Mamba、Minimal Mamba。
    • Gemma v1 2b 和 7b+，v2 2b 和 9b。
    • Mistral 7b v0.1。
    • Mixtral 8x7b v0.1。
    • StableLM-3B-4E1T、StableLM-2-1.6B、Stable-Code-3B。
    • Replit-code-v1.5-3B。
    • Bert。
    • Yi-6B 和 Yi-34B。
    • Qwen1.5、Qwen1.5 MoE、Qwen3 MoE。
    • RWKV v5 和 v6。
  • 量化语言模型。
    • Llama 7b、13b、70b，以及聊天和代码版本。
    • Mistral 7b 和 7b 指令版。
    • Mixtral 8x7b。
    • Zephyr 7b a 和 b（基于 Mistral-7b）。
    • OpenChat 3.5（基于 Mistral-7b）。
    • Qwen3 MoE（16B-A3B、32B-A3B）。
  • 文本到文本。
    • T5 及其变体：FlanT5、UL2、MADLAD400（翻译）、CoEdit（语法修正）。
    • Marian MT（机器翻译）。
  • 文本到图像。
    • Stable Diffusion v1.5、v2.1、XL v1.0。
    • Wurstchen v2。
  • 图像到文本。
    • BLIP。
    • TrOCR。
  • 音频。
    • Whisper，多语言语音转文本。
    • EnCodec，音频压缩模型。
    • MetaVoice-1B，文本到语音模型。
    • Parler-TTS，文本到语音模型。
  • 计算机视觉模型。
    • DINOv2、ConvMixer、EfficientNet、ResNet、ViT、VGG、RepVGG、ConvNeXT、 ConvNeXTv2、MobileOne、EfficientVit（MSRA）、MobileNetv4、Hiera、FastViT。
    • YOLO-v3、YOLO-v8。
    • Segment-Anything Model (SAM)。
    • SegFormer。
• 文件格式：支持从 safetensors、npz、ggml 或 PyTorch 文件加载模型。
• 无服务器（在 CPU 上），小型且快速的部署。
• 支持使用 llama.cpp 的量化类型进行量化。

使用方法

速查表：

	使用 PyTorch	使用 Candle
创建	torch.Tensor([[1, 2], [3, 4]])	Tensor::new(&[[1f32, 2.], [3., 4.]], &Device::Cpu)?
创建	torch.zeros((2, 2))	Tensor::zeros((2, 2), DType::F32, &Device::Cpu)?
索引	tensor[:, :4]	tensor.i((.., ..4))?
操作	tensor.view((2, 2))	tensor.reshape((2, 2))?
操作	a.matmul(b)	a.matmul(&b)?
算术	a + b	&a + &b
设备	tensor.to(device="cuda")	tensor.to_device(&Device::new_cuda(0)?)?
数据类型	tensor.to(dtype=torch.float16)	tensor.to_dtype(&DType::F16)?
保存	torch.save({"A": A}, "model.bin")	candle::safetensors::save(&HashMap::from([("A", A)]), "model.safetensors")?
加载	weights = torch.load("model.bin")	candle::safetensors::load("model.safetensors", &device)

结构

• candle-core：核心操作、设备以及 Tensor 结构的定义。
• candle-nn：用于构建实际模型的工具。
• candle-examples：库在实际场景中的使用示例。
• candle-kernels：CUDA 自定义内核。
• candle-datasets：数据集和数据加载器。
• candle-transformers：与 Transformer 相关的工具。
• candle-flash-attn：Flash Attention v2 层。
• candle-onnx：ONNX 模型评估。

常见问题解答

为什么应该使用 Candle？

Candle 的核心目标是 实现无服务器推理。像 PyTorch 这样的完整机器学习框架体积庞大，导致在集群上创建实例的速度较慢。而 Candle 则允许部署轻量级的二进制文件。

其次，Candle 能够让你 将 Python 从生产工作负载中移除。Python 的开销会严重降低性能，而 GIL 更是出了名的麻烦来源。

最后，Rust 很酷！HF 生态系统中已经有很多 Rust crate，比如 safetensors 和 tokenizers。

其他 ML 框架

• dfdx 是一个功能强大的 crate，它将形状信息纳入类型系统中。这样可以避免很多因形状不匹配而导致的问题，编译器会在第一时间报错。不过，我们发现某些功能仍然需要 nightly 版本，而且对于非 Rust 专家来说，编写代码可能会有些困难。

我们正在利用并为其他核心 crate 提供支持，希望这两个 crate 能够互相受益。

• burn 是一个通用的 crate，可以利用多种后端，从而让你根据工作负载选择最合适的引擎。

• tch-rs 是 Rust 中对 torch 库的绑定。它非常灵活，但会将整个 torch 库引入运行时环境。tch-rs 的主要贡献者也参与了 candle 的开发。

常见错误

使用 mkl 功能编译时缺少符号。

如果你在使用 mkl 或 accelerate 功能编译二进制文件或测试时遇到一些缺失的符号，例如对于 mkl 你会看到：

  = note: /usr/bin/ld: (....o): in function `blas::sgemm':
          .../blas-0.22.0/src/lib.rs:1944: undefined reference to `sgemm_' collect2: error: ld returned 1 exit status

  = note: some `extern` functions couldn't be found; some native libraries may need to be installed or have their path specified
  = note: use the `-l` flag to specify native libraries to link
  = note: use the `cargo:rustc-link-lib` directive to specify the native libraries to link with Cargo

或者对于 accelerate：

Undefined symbols for architecture arm64:
            "_dgemm_", referenced from:
                candle_core::accelerate::dgemm::h1b71a038552bcabe in libcandle_core...
            "_sgemm_", referenced from:
                candle_core::accelerate::sgemm::h2cf21c592cba3c47 in libcandle_core...
          ld: symbol(s) not found for architecture arm64

这很可能是由于缺少启用 mkl 库所需的链接器标志。你可以尝试在你的二进制文件顶部添加以下内容以解决 mkl 的问题：

extern crate intel_mkl_src;

或者对于 accelerate：

extern crate accelerate_src;

无法运行 LLaMA 示例：访问源需要登录凭证

Error: request error: https://huggingface.co/meta-llama/Llama-2-7b-hf/resolve/main/tokenizer.json: status code 401

这很可能是因为你没有 LLaMA-v2 模型的权限。要解决这个问题，你需要在 huggingface-hub 上注册，接受 LLaMA-v2 模型条款，并设置你的认证令牌。更多详情请参阅 issue #350。

Docker 构建

在 Dockerfile 中构建 CUDA 内核时，nvidia-smi 无法用于自动检测计算能力。

你必须显式设置 CUDA_COMPUTE_CAP，例如：

FROM nvidia/cuda:12.9.0-devel-ubuntu22.04

# 安装 git 和 curl
RUN set -eux; \
  apt-get update; \
  apt-get install -y curl git ca-certificates;

# 安装 Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

# 克隆 candle 仓库
RUN git clone https://github.com/huggingface/candle.git

# 设置构建的计算能力
ARG CUDA_COMPUTE_CAP=90
ENV CUDA_COMPUTE_CAP=${CUDA_COMPUTE_CAP}

# 使用显式计算能力进行构建
WORKDIR /app
COPY . .
RUN cargo build --release features cuda

使用 flash-attention 编译失败

/usr/include/c++/11/bits/std_function.h:530:146: error: parameter packs not expanded with ‘...’:

这是由 Cuda 编译器触发的 gcc-11 中的一个 bug。要修复这个问题，可以安装一个受支持的其他版本的 gcc，例如 gcc-10，并将编译器路径指定到 NVCC_CCBIN 环境变量中。

env NVCC_CCBIN=/usr/lib/gcc/x86_64-linux-gnu/10 cargo ...

在 Windows 上运行 rustdoc 或 mdbook 测试时出现链接错误

Couldn't compile the test.
---- .\candle-book\src\inference\hub.md - Using_the_hub::Using_in_a_real_model_ (line 50) stdout ----
error: linking with `link.exe` failed: exit code: 1181
//very long chain of linking
 = note: LINK : fatal error LNK1181: cannot open input file 'windows.0.48.5.lib'

确保链接所有可能位于项目目标之外的原生库。例如，要运行 mdbook 测试，你应该执行以下命令：

mdbook test candle-book -L .\target\debug\deps\ `
-L native=$env:USERPROFILE\.cargo\registry\src\index.crates.io-6f17d22bba15001f\windows_x86_64_msvc-0.42.2\lib `
-L native=$env:USERPROFILE\.cargo\registry\src\index.crates.io-6f17d22bba15001f\windows_x86_64_msvc-0.48.5\lib

WSL 下模型加载时间极慢

这可能是由于模型从 /mnt/c 加载导致的，更多详细信息请参阅 stackoverflow。

跟踪错误

你可以设置 RUST_BACKTRACE=1，以便在 candle 报错时提供完整的调用栈信息。

CudaRC 错误

如果你在 Windows 上遇到类似 called Result::unwrap()on anErr value: LoadLibraryExW { source: Os { code: 126, kind: Uncategorized, message: "The specified module could not be found." } } 的错误，可以通过复制并重命名以下 3 个文件来解决（确保它们在系统路径中）。具体路径取决于你的 CUDA 版本。 c:\Windows\System32\nvcuda.dll -> cuda.dll c:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin\cublas64_12.dll -> cublas.dll c:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin\curand64_10.dll -> curand.dll

Candle 快速上手指南

Candle 是一个由 Hugging Face 推出的极简 Rust 机器学习框架，专注于高性能（支持 GPU）和易用性。它允许开发者在 Rust 环境中高效运行大语言模型（LLM）、计算机视觉模型及语音识别模型。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows。
• Rust 工具链: 需安装最新稳定版 Rust。

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  source $HOME/.cargo/env
  rustc --version # 建议版本 1.70+
  

• GPU 支持 (可选):
  • 若需使用 NVIDIA GPU 加速，请确保已安装 CUDA Toolkit (通常建议 11.8 或 12.x) 和对应的显卡驱动。
  • 若需极致性能，可额外安装 cuDNN。
• 构建工具: 确保 cargo 可用。

国内开发者提示: 如果下载 Rust 组件或 crates 依赖速度较慢，建议配置国内镜像源：

# 配置 Rustup 镜像 (USTC)
export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static
export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup

配置 Cargo 注册表镜像 (在 ~/.cargo/config.toml 中添加)
[source.crates-io]
replace-with = 'ustc'
[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"

安装步骤

Candle 的核心库是 candle-core。你可以通过创建一个新的 Rust 项目并添加依赖来开始。

1. 创建新项目:

   cargo new my_candle_app
   cd my_candle_app
   

2. 添加依赖: 编辑 Cargo.toml 文件，添加 candle-core。

   基础 CPU 版本:

   [dependencies]
   candle-core = "0.6" # 请使用 crates.io 上的最新版本
   

   启用 CUDA GPU 加速版本:

   [dependencies]
   candle-core = { version = "0.6", features = ["cuda"] }
   

   启用 cuDNN 加速 (需预先安装 cuDNN):

   [dependencies]
   candle-core = { version = "0.6", features = ["cuda", "cudnn"] }
   

基本使用

以下是一个最简单的示例，演示如何创建两个随机张量并执行矩阵乘法。

1. 编写代码: 将以下内容写入 src/main.rs：

   use candle_core::{Device, Tensor};
   
   fn main() -> Result<(), Box<dyn std::error::Error>> {
       // 选择设备：CPU 或 CUDA
       // 如果启用了 cuda 特性，可以使用 Device::new_cuda(0)?
       let device = Device::Cpu;
   
       // 创建两个随机张量 (形状分别为 2x3 和 3x4)
       let a = Tensor::randn(0f32, 1., (2, 3), &device)?;
       let b = Tensor::randn(0f32, 1., (3, 4), &device)?;
   
       // 执行矩阵乘法
       let c = a.matmul(&b)?;
       
       // 打印结果，预期形状为 [2, 4]
       println!("{c}");
       
       Ok(())
   }
   

2. 运行程序:

   CPU 模式:

   cargo run
   

   GPU 模式 (需在 Cargo.toml 中开启 cuda 特性):

   cargo run --release
   

   输出应类似如下内容，显示计算后的张量数据：

   Tensor[[2, 4], f32]
   [[0.1234, -0.5678, ...],
    [...]]
   

进阶示例运行

Candle 官方提供了大量预置示例（如 LLaMA, Whisper, YOLO, Stable Diffusion 等）。你可以直接克隆仓库并运行这些示例。

1. 获取源码:

   git clone https://github.com/huggingface/candle.git
   cd candle
   

2. 运行示例: 例如，运行量化版的 LLaMA 示例：

   CPU 运行:

   cargo run --example quantized --release
   

   GPU 加速运行:

   cargo run --example quantized --release --features cuda
   

   使用 cuDNN 进一步加速:

   cargo run --example quantized --release --features cudnn
   

更多模型示例（如 Mistral, Gemma, Phi-3 等）位于 candle-examples/examples/ 目录下，可根据具体模型目录查看对应的权重下载和运行说明。