高效、易用的本地大语言模型（LLM）推理与服务平台，提供 OpenAI 兼容的 API 服务。
English | 简体中文
| 特性 | 详情 | |
|---|---|---|
| ⚡ | 极致性能 | 原生 Flash Attention、FlashInfer、CUDA Graphs、持续批处理、前缀缓存。 |
| 🗜️ | 极致 KV 压缩 | TurboQuant（2–4 位 KV 缓存）以极小的质量损失将上下文扩展至 4.7 倍 |
| 🌍 | 跨平台 | CUDA（Linux）、Metal（macOS），统一代码库，统一 API |
| 🏭 | 生产就绪 | OpenAI 兼容 API 服务、内置 ChatGPT 风格 Web UI、MCP 工具调用、流式输出 |
| 📦 | 部署简单 | 一键安装脚本、Docker 镜像或源码编译 |
| 🔧 | 高度可扩展 | 基于 trait 的架构，支持快速实现新的模型 |
| 🖥️ | 多 GPU & 多节点 | 多进程及多线程张量并行，TCP 多节点推理 |
方案 1 — 一键安装（DEB 或二进制）
curl -sSL https://ericlbuehler.github.io/candle-vllm/install.sh | bash方案 2 — 从源代码构建
git clone git@github.com:EricLBuehler/candle-vllm.git
cd candle-vllm
# CUDA（11+, 12+, 13.0）— sm_70/sm_75 需去除 flashinfer,cutlass
cargo install --features cuda,nccl,flashinfer,cutlass --path .
# macOS/Metal
cargo install --features metal --path .方案 3 — Docker
# 可指定 SM 版本和 CUDA 版本：./build_docker.sh "cuda,nccl,flashinfer,cutlass" sm_90 13.0.0
./build_docker.sh "cuda,nccl,flashinfer,cutlass"使用 HuggingFace 模型 ID：
candle-vllm --m Qwen/Qwen3.6-27B-FP8 --ui-server
candle-vllm --m unsloth/Qwen3.5-122B-A10B-GGUF --f Q3_K_S --d 0,1 --ui-server
candle-vllm --m zai-org/GLM-5.2-FP8 --d 0,1,2,3,4,5,6,7 --ui-server使用本地模型路径：
# 本地 Safetensors 目录
candle-vllm --d 0,1,2,3,4,5,6,7 --m /home/data/GLM-5.2-FP8/ --ui-server
# 本地 GGUF 文件（单文件或分片）
candle-vllm --d 0,1 --m /home/data/model-Q4_K_M.gguf --ui-server
# 本地目录（自动检测 GGUF 文件）
candle-vllm --d 0,1 --m /home/data/Qwen3.5-35B-A3B-GGUF/ --ui-server提示： 添加
--ui-server可启动内置 ChatGPT 风格 Web UI。UI 服务端口为 API 端口减一（例如 API 为2000，UI 为1999）。
单请求解码速度（输入 4k，输出 1k，
Hopper80G）
| # | 模型 | BF16（解码速度 / 单请求） | 量化 |
|---|---|---|---|
| 1 | LLAMA | 119 tks/s (8B) | 163 tks/s (8B, Q4K), 171 tks/s (8B, Marlin) |
| 2 | Mistral | 122 tks/s (7B) | 181 tks/s (7B, Q4K), 190 tks/s (7B, Marlin) |
| 3 | Phi3/Phi4 | 153 tks/s (3.8B) | 196 tks/s (3.8B, Q4K) |
| 4 | QWen2/Qwen3 Dense | 127 tks/s (8B) | 154 tks/s (8B, Q4K) |
| 5 | QWen3 MoE | 102 tks/s (30B) | 124 tks/s (30B, Q4K) |
| 6 | QWen3-Next MoE | 80 tks/s (80B, BF16, tp=2) | 89 tks/s (AWQ, tp=1) |
| 7 | QWen3.5/3.6/3.8 Dense | 36 tks/s (27B, BF16) | 49/58 tks/s (27B, Q4K / FP8) |
| 8 | QWen3.5/3.6 MoE | 90 tks/s (35B) | 118 tks/s (35B, FP8) |
| 9 | Yi | 168 tks/s (6B) | 199 tks/s (6B, Q4K) |
| 10 | StableLM | 251 tks/s (3B) | - |
| 11 | Gemma-2/Gemma-3 | 103 tks/s (9B) | 130 tks/s (9B, Marlin) |
| 12 | DeepSeek V2/V3/V3.2/R1 | TBD | ~20 tks (AWQ 671B, tp=8, offloading) |
| 13 | QwQ-32B | 51 tks/s (32B, tp=2) | 70 tks/s (32B, Q4K) |
| 14 | GLM4 | 96 tks/s (9B) | 139 tks/s (9B, Q4K) |
| 15 | GLM4.7 Flash | TBD | 82 tks/s (31B, Software NVFP4) |
| 16 | LLama4 | TBD | 47 tks/s (107B, Software NVFP4) |
| 17 | Gemma4 | (26B) 83 tks/s | 82 tks/s (26B, Software NVFP4) |
| 18 | MiniMax-M2.5/M2.7 | TBD | 72 tks/s (229B, Software NVFP4, TP=2) |
| 19 | GLM-5.2 | TBD | 支持 (FP8, tp=8) |
演示视频 — GPU 与 Apple Silicon
GPU（A100, BF16, QWen3-8B 推理模型）上的聊天演示
Apple Silicon（M4, 16GB 统一内存, Q2K, QWen3-8B）上的聊天演示
- 提供 OpenAI 兼容的 API 服务，用于部署 LLM
- 生成过程中支持流式（stream）传输
- 使用 PagedAttention 高效管理 KV 缓存
- 持续批处理（continuous batching，不同时间段的请求 decoding 阶段聚合为批量处理）
- 原位（In-situ）量化（及原位 Marlin 格式转换）
- 支持
GPTQ/Marlin格式量化（4 位） - 支持
Mac/Metal设备 - 支持
多 GPU推理（包括多进程和多线程模式） - 支持
多节点推理（基于 TCP 协调） - 支持分块 Prefilling（默认块大小 8K）
- 支持 CUDA Graph
- 支持 Qwen3.5 MTP 投机解码，并通过
--mtp使用 CUDA Graph - 支持 Model Context Protocol（MCP）和 OpenAI 兼容工具调用
- 支持 Prefix Caching
- 支持硬件 FP8 模型推理加速（SM90+, Qwen3 系列，Block-wise FP8 量化）
- 支持 FP8 KV Cache（兼容 FlashInfer、FlashAttention 及 Prefix Cache，适用于所有 CUDA 和 Metal 平台）
- 支持 TurboQuant KV Cache（turbo8/turbo4/turbo3），使用原生 Flash 注意力内核实现高压缩比 KV 缓存
- 支持 Flashinfer 后端
- 支持通过命令行参数
--yarn-scaling-factor手动设置 YaRN RoPE 缩放因子 - 支持 MXFP4/NVFP4 模型
- 支持 GPTQ/AWQ/Marlin 模型，包括 pack-quantized AWQ MoE
- 支持 DeepSeek V3.2 和 GLM-5.2 FP8 模型
提示： 默认启动 OpenAI 兼容 API 服务（
http://localhost:2000）。添加--ui-server可同时启动内置 ChatGPT 风格 Web UI。
# FP8 模型 + Web UI
candle-vllm --m Qwen/Qwen3.8-27B-FP8 --ui-server
# Hopper 上加速 GDN 预填充，精度略有损失
SM90_LOWER_PRECISION_GDN_PREFILL=1 candle-vllm --m Qwen/Qwen3.5-35B-A3B-FP8
# Qwen3.5 MTP 投机解码（每步 2 个 draft token）
candle-vllm --w /data/Qwen3.5-35B-A3B-FP8/ --mtp 2 --ui-server
# GLM-5.2 FP8 模型
candle-vllm --d 0,1,2,3,4,5,6,7 --m zai-org/GLM-5.2-FP8 --ui-server
# 未量化 Safetensors（多 GPU）
candle-vllm --d 0,1 --w /home/Qwen3-30B-A3B-Instruct-2507/
# ISQ 即时量化
candle-vllm --m Qwen/Qwen3.8-27B --isq q4k
# FP4 模型
candle-vllm --m GadflyII/GLM-4.7-Flash-NVFP4 --ui-server
# GGUF 模型
candle-vllm --m unsloth/Qwen3-30B-A3B-Instruct-2507-GGUF --f Qwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server
# 手动 YaRN 缩放
candle-vllm --m Qwen/Qwen3.6-35B-A3B --yarn-scaling-factor 4.0 --ui-serverFP8 / FP4 模型
# FP8 模型（block-wise 量化，需启用 cutlass 特性）
candle-vllm --m Qwen/Qwen3.6-27B-FP8 --ui-server
# GLM-5.2 FP8 模型
candle-vllm --d 0,1,2,3,4,5,6,7 --m zai-org/GLM-5.2-FP8 --ui-server
# MacOS/Metal 上的 FP8（Dense）
candle-vllm --m Qwen/Qwen3-4B-Instruct-2507-FP8 --ui-server
# FP4 模型（MXFP4/NVFP4，暂不支持 MLX 量化格式）
candle-vllm --m GadflyII/GLM-4.7-Flash-NVFP4 --ui-server
# MXFP4
candle-vllm --m nm-testing/Qwen3-30B-A3B-MXFP4A16 --ui-serverGGUF 模型
# 本地 GGUF 文件（推荐使用 --m）
candle-vllm --m /home/data/Qwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server
# 本地 GGUF 文件（--f 传统方式）
candle-vllm --f /home/data/Qwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server
# 本地目录（自动检测 GGUF，按需加载 mmproj 视觉文件）
candle-vllm --m /home/data/Qwen3.5-35B-A3B-GGUF/ --ui-server
# 从 HuggingFace 下载（精确文件）
candle-vllm --m unsloth/Qwen3-30B-A3B-Instruct-2507-GGUF --f Qwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server
# 从 HuggingFace 下载（子文件夹 — 下载远程路径下所有 GGUF 文件）
candle-vllm --m unsloth/Qwen3.5-122B-A10B-GGUF --f Q3_K_S --d 0,1 --ui-server
# 本地多分片 GGUF（从本地路径自动发现分片文件）
candle-vllm --m /home/data/model-00001-of-00003.gguf --d 0,1 --ui-server
# Apple Silicon 上的 GGUF
candle-vllm --m /home/qwq-32b-q4_k_m.gguf --ui-server
candle-vllm --m Qwen/QwQ-32B-GGUF --f qwq-32b-q4_k_m.gguf --ui-server多分片 GGUF： 分片 GGUF 文件（如 model-00001-of-00005.gguf）支持自动发现 — 本地（从同一目录）和远程（从 HuggingFace 仓库）均可。当 --f 为子文件夹名（不以 .gguf 结尾）时，会下载该远程子文件夹中的所有 GGUF 文件。视觉塔辅助文件（mmproj*.gguf）在多模态模型中按需加载。
ISQ 原位量化
运行未量化模型时只需添加 --isq 参数：
candle-vllm --m Qwen/Qwen3.6-27B --isq q4k可选值：q4_0, q4_1, q5_0, q5_1, q8_0, q2k, q3k, q4k, q5k, q6k
GPTQ / AWQ / Marlin 模型
# Marlin 兼容的 GPTQ（4 位，128 分组，desc_act=False）
candle-vllm --m thesven/Llama-3-8B-GPTQ-4bit
# 将未压缩模型转换为 Marlin 兼容格式
python3 examples/convert_marlin.py --src /home/DeepSeek-R1-Distill-Qwen-14B/ --dst /home/DeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g
candle-vllm --w /home/DeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g
# 将 AWQ 转换为 Marlin 兼容格式
python3 examples/convert_awq_marlin.py --src /home/Meta-Llama-3.1-8B-Instruct-AWQ-INT4/ --dst /home/Meta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin/ --bits 4 --method awq --group 128 --nk False
candle-vllm --d 0 --w /home/Meta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin/
# AWQ MoE（pack-quantized），例如 Qwen3-Coder-Next
candle-vllm --m cyankiwi/Qwen3-Coder-Next-AWQ-4bit
# 直接使用 Marlin 格式模型
candle-vllm --w /home/DeepSeek-R1-Distill-Qwen-14B-GPTQ-Marlin/TurboQuant 通过 Walsh-Hadamard 变换压缩 KV 缓存，实现更高吞吐量和更长上下文：
| 模式 | 描述 | KV 缓存压缩比 | 推荐用途 |
|---|---|---|---|
turbo8 |
FP8 K + 4-bit V | ~2.6x | 最佳质量-压缩比平衡 |
turbo4 |
4-bit K + 4-bit V | ~3.7x | 质量与显存节省兼顾 |
turbo3 |
3-bit K + 4-bit V | ~4.7x | 最大限度节省显存 |
# Turbo4（4-bit KV 缓存，约 3.7 倍压缩）
candle-vllm --w /data/Qwen3.5-27B-FP8/ --kvcache-dtype turbo4
# Turbo8（FP8 K + 4-bit V，约 2.6 倍压缩）
candle-vllm --w /data/Qwen3.5-27B-FP8/ --kvcache-dtype turbo8
# Turbo3（3-bit K + 4-bit V，约 4.7 倍压缩）
candle-vllm --w /data/Qwen3.5-27B-FP8/ --kvcache-dtype turbo3
# FP8 KV Cache
candle-vllm --w /data/Qwen3.5-35B-A3B-FP8/ --kvcache-dtype fp8注意：TurboQuant 使用原生 Flash 注意力内核（flashinfer 自动禁用）。支持 CUDA（SM70+）和 Metal（Apple Silicon）两种平台。MLA 模型（DeepSeek、GLM4/GLM-5.2）因 KV 压缩布局不兼容会自动回退到标准 KV 缓存。
多进程模式（推荐）
# 两块 GPU 运行 QwQ-32B BF16
candle-vllm --d 0,1 --w /home/QwQ-32B/
# 两块 GPU 运行 QwQ-32B 4 位 AWQ
python3 examples/convert_awq_marlin.py --src /home/QwQ-32B-AWQ/ --dst /home/QwQ-32B-AWQ-Marlin/ --bits 4 --method awq --group 128 --nk False
candle-vllm --d 0,1 --w /home/QwQ-32B-AWQ-Marlin/注意： GPU 数量（--d）必须为 2 的幂次方（例如 2、4 或 8）。
多线程模式（调试用途）
# 添加 --multithread 参数
candle-vllm --multithread --d 0,1 --w /home/QwQ-32B/
# 问题排查
export NCCL_P2P_DISABLE=1 # 禁用 P2P 以避免非法内存访问跨多台机器分布式推理，基于 TCP 的 NCCL 引导，无需 MPI。
# 在主节点 (192.168.1.100) 上运行：
candle-vllm --d 0,1,2,3,4,5,6,7 --w /data/DeepSeek-R1-AWQ-Marlin/ \
--num-nodes 2 --node-rank 0 --master-addr 192.168.1.100 --master-port 29500
# 在工作节点 (192.168.1.101) 上运行：
candle-vllm --d 0,1,2,3,4,5,6,7 --w /data/DeepSeek-R1-AWQ-Marlin/ \
--num-nodes 2 --node-rank 1 --master-addr 192.168.1.100 --master-port 29500所有节点需本地存放模型权重，并通过 TCP 连接 --master-port（默认 29500）。
| 参数 | 说明 |
|---|---|
--num-nodes N |
集群中的节点总数 |
--node-rank R |
本节点的排名（0 = 主节点） |
--master-addr ADDR |
主节点的 IP 地址 |
--master-port PORT |
NCCL ID 交换端口（默认：29500） |
显示命令
sudo apt-get install numactl
# 8 张 GPU，2 个 NUMA 节点
MAP_NUMA_NODE=0,0,0,0,1,1,1,1 numactl --cpunodebind=0 --membind=0 candle-vllm --d 0,1,2,3,4,5,6,7 --w /home/data/DeepSeek-V2-Chat-AWQ-Marlin
# 4 张 GPU
MAP_NUMA_NODE=0,0,0,0 numactl --cpunodebind=0 --membind=0 candle-vllm --d 0,1,2,3 --w /home/data/DeepSeek-V2-Chat-AWQ-Marlinnumactl --cpunodebind=0 --membind=0 指定 master 进程的 NUMA 绑定，必须与 MAP_NUMA_NODE 相匹配。
| 参数 | 说明 |
|---|---|
--h |
绑定地址（默认 0.0.0.0），支持 host、host:port、[ipv6]:port、tcp://host[:port]、file:///path、socket:///path、unix:///path |
--p |
当 --h 未包含端口时使用的 TCP 服务端口（默认 2000） |
--d |
设备 ID（如 --d 0,1） |
--m |
模型来源：HuggingFace 模型 ID、本地目录或本地 .gguf 文件。目录中自动检测 GGUF 或 Safetensors |
--w |
本地权重目录（Safetensors 或 GGUF）。新命令建议使用 --m <本地目录> |
--f |
GGUF 文件或子文件夹：--m 仓库 --f 文件.gguf（精确文件），--m 仓库 --f 子文件夹（下载路径下所有 GGUF），或本地 GGUF 路径 |
--dtype |
数据类型（bf16, f16） |
--isq |
原位量化：q4_0, q4_1, q5_0, q5_1, q8_0, q2k, q3k, q4k, q5k, q6k |
--kvcache-dtype |
KV 缓存量化：auto, fp8, turbo8, turbo4, turbo3 |
--kv-fraction |
模型加载后按剩余显存比例自动计算 KV 缓存大小（默认 0.6） |
--mem |
固定 KV 缓存预算（MB） |
--prefill-chunk-size |
预填充分块大小（默认 8K，0 为禁用） |
--max-gen-tokens |
每次响应最大输出 token 数（默认：max_sequence_len 的 1/5） |
--frequency-penalty |
频率惩罚（−2.0 到 2.0） |
--presence-penalty |
存在惩罚（−2.0 到 2.0） |
--yarn-scaling-factor |
YaRN RoPE 上下文扩展因子 |
--enforce-parser |
强制指定工具解析器后端：qwen_coder, qwen, json, mistral |
--ui-server |
启动内置 ChatGPT 风格 Web UI |
--multithread |
使用多线程模式（调试用途） |
--num-nodes |
集群中节点总数（多节点推理） |
--node-rank |
本节点排名（0 = 主节点） |
--master-addr |
主节点 IP 地址 |
--master-port |
NCCL ID 交换端口（默认 29500） |
--disable-prefix-cache |
禁用前缀缓存（默认开启） |
--prefix-cache-max-tokens |
前缀缓存大小上限 |
--disable-cuda-graph |
禁用 CUDA Graph 捕获（CUDA 构建默认开启） |
绑定示例：
candle-vllm --h 127.0.0.1 --p 8000 --m Qwen/Qwen3.6-27B-FP8
candle-vllm --h 127.0.0.1:8000 --m Qwen/Qwen3.6-27B-FP8
candle-vllm --h '[::1]:8000' --m Qwen/Qwen3.6-27B-FP8
candle-vllm --h unix:///tmp/candle-vllm.sock --m Qwen/Qwen3.6-27B-FP8| 指南 | 说明 |
|---|---|
| Rust Crate 用法 | 作为 Rust 库使用 |
| Embedding 模型 | 文本嵌入 API |
| MCP & 工具调用 | Model Context Protocol 集成 |
| 工具调用解析 | 工具调用检测与解析 |
| Prefix Cache | 自动 KV 缓存复用 |
| 多模态模型 | 视觉语言模型 |
在 Candle-vLLM 后端下使用 Agent： xbot · OpenCode · Kilo Code
- OpenAI 兼容 API 服务器（流式输出）
- 持续批处理
- Flash Attention（CUDA）
- FlashInfer 后端
- CUDA Graph
- 分块预填充
- 前缀缓存（CUDA 和 Metal）
- 多 GPU 推理（多进程及多线程）
- 多节点张量并行推理（基于 TCP 的 NCCL，无需 MPI）
- 原位量化（GGML/GGUF + Marlin）
- FP8 KV Cache（CUDA 和 Metal，所有后端）
- TurboQuant KV Cache（2–4 位压缩）
- FP8 模型（Block-wise，SM90+）
- MXFP4/NVFP4 模型支持
- DeepSeek V3.2 和 GLM-5.2 FP8 模型支持
- MCP 集成与工具调用
- 内置 ChatGPT 风格 Web UI
- Python 实现：
vllm-project vllm论文
如果遇到任何问题，请创建 issue。