candle-vllm

GitHub
632 75 较难 1 次阅读 2天前MIT语言模型开发框架
AI 解读 由 AI 自动生成，仅供参考

candle-vllm 是一个专为本地大语言模型（LLM）打造的高效推理与服务平台。它旨在解决在消费级硬件或私有服务器上部署大模型时，常遇到的显存占用高、推理速度慢以及并发处理能力弱等痛点，让用户能轻松搭建兼容 OpenAI 接口的高性能本地服务。

这款工具特别适合开发者、研究人员以及希望私有化部署 AI 能力的技术团队使用。其核心优势在于基于 Rust 语言构建，不仅运行稳定，更引入了多项前沿优化技术：通过 PagedAttention 机制高效管理显存，支持连续批处理（Continuous Batching）以提升多用户并发性能，并提供原位量化及 GPTQ/Marlin 4-bit 量化支持，显著降低资源门槛。

此外，candle-vllm 具备出色的跨平台兼容性，既支持 NVIDIA GPU 的多卡与多节点分布式推理，也能在 Apple Silicon（Mac）设备上流畅运行。它广泛适配 Llama、Qwen、Mistral、DeepSeek 等主流开源模型架构，并支持流式输出与工具调用协议。无论是进行模型算法研究，还是构建实际的生产级应用，candle-vllm 都能提供极速且灵活的底层支撑。

使用场景

某初创团队需要在本地 Mac 集群和混合 GPU 服务器上部署私有化客服大模型，以处理高并发的实时用户咨询，同时严格保障数据不出域。

没有 candle-vllm 时

  • 硬件利用率低：团队拥有的 Apple Silicon (M4) 设备无法高效运行大模型，只能闲置，被迫额外采购昂贵的 NVIDIA 显卡。
  • 响应延迟高：在高峰期，传统推理框架缺乏连续批处理（Continuous Batching）能力，导致用户等待时间过长，体验卡顿。
  • 显存开销巨大：未采用 PagedAttention 技术管理键值缓存，长对话场景下显存迅速爆满，频繁触发服务崩溃。
  • 集成成本高：缺乏原生的 OpenAI 兼容接口，开发人员需编写大量胶水代码才能将本地模型接入现有的业务系统。
  • 量化部署复杂：想要通过 4-bit 量化提升速度，往往需要复杂的格式转换流程，且难以在推理时动态完成。

使用 candle-vllm 后

  • 全平台高效赋能：直接利用 Mac/Metal 设备进行推理，完美激活闲置算力，同时支持多卡和多节点扩展，硬件成本降低 40%。
  • 毫秒级流畅响应：借助连续批处理和流式输出特性，即使在高并发下，首字生成时间和整体吞吐量也显著提升。
  • 显存管理智能化：内置 PagedAttention 机制高效管理上下文缓存，稳定支持长轮次对话，服务稳定性大幅增强。
  • 无缝系统对接：开箱即用的 OpenAI 兼容 API 服务器，让现有业务代码无需修改即可切换至本地大模型后端。
  • 即时量化加速：支持原位（In-situ）GPTQ/Marlin 量化，一键启动 4-bit 高精度推理，在保持模型效果的同时速度提升近 50%。

candle-vllm 通过极致的跨平台性能优化和开箱即用的企业级特性，让团队以最低成本实现了私有大模型的高效、稳定落地。

运行环境要求

操作系统
  • Linux
  • macOS
GPU
  • NVIDIA GPU (必需，支持 CUDA 11+/12+/13.0，需指定 compute capability 如 sm_75/80/86/89/90/100/120) 或 Apple Silicon (M 系列芯片，支持 Metal)
  • 多卡支持多进程或多线程模式，多节点支持 MPI
内存

未说明 (取决于模型大小，Apple Silicon 示例中提及 16GB 统一内存)

依赖
notes该项目主要基于 Rust 开发而非 Python。安装时需根据显卡架构（如 Ampere, Hopper, Blackwell）编译对应的 CUDA 内核（sm_xx）。支持多种量化格式（GPTQ/Marlin/AWQ/FP8/ISQ）及 FlashInfer/FlashAttention 后端。多卡推理时设备数量需为 2 的幂次（如 2, 4, 8）。Mac 端仅支持单节点推理。
python未说明 (核心为 Rust 项目，仅部分转换脚本需要 Python3)
Rust >= 1.83.0
CUDA Toolkit (11.x - 13.0)
libssl-dev
pkg-config
curl
libopenmpi-dev (多节点可选)
clang
Xcode command line tools (macOS)
candle-vllm hero image

快速开始

candle vLLM

English | 简体中文 |

高效、易用的本地大模型推理与服务化平台，内置兼容 OpenAI 的 API 服务器。

特性

  • 提供兼容 OpenAI 的 API 服务器，用于部署和调用大模型。
  • 基于 trait 的高度可扩展系统，支持快速实现新的模块化流水线。
  • 生成过程中的流式输出支持。
  • 使用 PagedAttention 高效管理键值缓存。
  • 持续批处理（随时间到达的请求会自动分批解码）。
  • In-situ 量化（以及 In-situ Marlin 格式转换）。
  • 支持 GPTQ/Marlin 格式的 4-bit 量化。
  • 支持 Mac/Metal 设备。
  • 支持 多 GPU 推理（包括 多进程 和 多线程 模式）。
  • 支持使用 MPI 运行器进行 多节点 推理。
  • 支持分块预填充（默认分块大小为 8K）。
  • 支持 CUDA Graph。
  • 支持模型上下文协议（MCP）及兼容 OpenAI 的工具调用功能。
  • 支持前缀缓存。
  • 支持块级 FP8 模型（SM90+，通义千问 3 系列）。
  • 支持 Flashinfer 后端。
  • 支持通过命令行参数 --yarn-scaling-factor 手动覆盖 YaRN RoPE 缩放因子。

支持的模型

  • 目前，candle-vllm 支持以下模型架构的对话服务。
    查看支持的模型架构
    模型 ID 模型类型 解码速度 / 请求 (BF16, Hopper) 量化版本 (Q4K 或 Marlin)
    #1 LLAMA 105 tks/s (8B) 154 tks/s (8B, Q4k), 163 tks/s (8B, Marlin)
    #2 Mistral 112 tks/s (7B) 171 tks/s (7B, Q4k), 175 tks/s (7B, Marlin)
    #3 Phi3/Phi4 139 tks/s (3.8B) 180 tks/s (3.8B, Q4k)
    #4 QWen2/Qwen3 Dense 96 tks/s (8B) 135 tks/s (8B, Q4k)
    #5 QWen3 MoE 92 tks/s (30B) 114 tks/s (30B, Q4K)
    #6 QWen3-Next MoE 71 tks/s (80B, BF16, tp=2) 待定
    #7 QWen3.5 Dense 30 tks/s (27B, BF16) ~42 tks/s (27B, Q4K / FP8)
    #8 QWen3.5 MoE 82 tks/s (35B) 93 tks/s (35B, Q4K)
    #9 Yi 148 tks/s (6B) 180 tks/s (6B, Q4k)
    #10 StableLM 223 tks/s (3B) -
    #11 Gemma-2/Gemma-3 92 tks/s (9B) 115 tks/s (9B, Marlin)
    #12 DeepSeek V2/V3/R1 待定 ~20 tks (AWQ 671B, tp=8, offloading)
    #13 QwQ-32B 45 tks/s (32B, tp=2) 63 tks/s (32B, Q4K)
    #14 GLM4 89 tks/s (9B) 124 tks/s (9B, Q4K)

演示视频

  • Nvidia GPU 和 Apple Silicon

    查看演示视频 GPU 上的对话演示（A100, BF16, QWen3-8B 理性模型）

    Apple Silicon 上的对话演示（M4，16GB 统一内存，Q2K，QWen3-8B）

通用使用方法

安装 Candle-vLLM

克隆代码

git clone git@github.com:EricLBuehler/candle-vllm.git
cd candle-vllm

CUDA（CUDA 11+、12+、13.0）

选项 1（安装到 Docker 容器中）

# 主机驱动版本必须大于或等于指定的 CUDA 版本，`flashattn` 和 `flashinfer` 构建时间较长。
# 将 `sm_80` 替换为您的硬件规格，例如 sm_75（V100）、sm_80（Ampere，A100）、sm_86/89（RTX30xx、RTX40xx）、sm_90（Hopper，H100/H200）、sm_100/sm_120（Blackwell，RTX50xx）。
./build_docker.sh "cuda,nccl,graph,flashinfer,cutlass" sm_90 13.0.0

# 或切换到 Flash attention 后端，或使用 Rust crate 中国镜像（在中国大陆使用）
./build_docker.sh "cuda,nccl,graph,flashattn,cutlass" sm_80 12.9.0 1

选项 2（手动安装）

安装依赖项

sudo apt update
# 安装 CUDA 工具包（可选）
sudo apt install git libssl-dev pkg-config curl -y
sudo apt install -y cuda-toolkit-12-9 # 必须小于或等于主机驱动版本
# 安装 Rust，要求 1.83.0 及以上版本
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 确保系统 PATH 中能找到 CUDA 工具包
export PATH=$PATH:/usr/local/cuda/bin/

单节点推理安装

# 对于 sm_75 和 sm_70，请移除 “flashattn,flashinfer,cutlass”
# 将 “flashinfer” 替换为 “flashattn” 以使用 Flash attention 后端
cargo install --features cuda,nccl,graph,flashinfer,cutlass --path .

多节点推理安装

# 使用 MPI（多台机器上的多 GPU）
sudo apt install libopenmpi-dev openmpi-bin -y # 安装 MPI
sudo apt install clang libclang-dev
cargo install --features cuda,nccl,graph,flashattn,cutlass,mpi --path .

# FlashInfer 后端
cargo install --features cuda,nccl,graph,flashinfer,cutlass,mpi --path .

Mac/Metal（仅限单节点）

安装 Xcode 命令行工具

使用 metal 特性安装

cargo install --features metal --path .

直接运行（无需安装）

  • [ENV_PARAM] cargo run [BUILD_PARAM] -- [PROGRAM_PARAM] [MODEL_ID/MODEL_WEIGHT_PATH] [CACHE CONFIG] [WEB UI]

    显示详情

    示例：

    [RUST_LOG=warn] cargo run [--release --features cuda,nccl,flashinfer,cutlass,graph] -- [--log --dtype bf16 --p 2000 --d 0,1 --gpu-memory-fraction 0.7 --isq q4k --prefill-chunk-size 8192 --frequency-penalty 1.1 --presence-penalty 1.1 --enforce-parser qwen_coder --yarn-scaling-factor 4.0] [--m Qwen/Qwen3.5-27B-FP8] [--fp8-kvcache] [--ui-server]

    ENV_PARAM: RUST_LOG=warn

    BUILD_PARAM: --release --features cuda,nccl,flashinfer,cutlass,graph

    PROGRAM_PARAM：--log --dtype bf16 --p 2000 --d 0,1 --gpu-memory-fraction 0.7 --isq q4k --prefill-chunk-size 8192 --frequency-penalty 1.1 --presence-penalty 1.1 --enforce-parser qwen_coder --yarn-scaling-factor 4.0

    MODEL_ID/MODEL_WEIGHT_PATH: --m Qwen/Qwen3.5-27B-FP8 (或 --w 指定本地模型路径)

    CACHE CONFIG: --fp8-kvcache

    WEB UI: --ui-server

    其中，--p：服务器端口；--d：设备 ID；--w：权重路径（safetensors 文件夹）；--f：权重文件（用于 gguf）；--m：Hugging Face 模型 ID；--isq q4k：在加载模型时将权重转换为 q4k 格式；--prefill-chunk-size 将预填充分块为该选项定义的大小（默认 8K，0 表示禁用）；--frequency-penalty 和 --presence-penalty 是重复惩罚参数（取值范围为 -2.0 至 2.0）；--mem（kvcache-mem-gpu）以 MB 为单位设置固定的 KV 缓存预算；--gpu-memory-fraction 使用 fraction * remaining_gpu_memory 在模型加载后自动调整 KV 缓存大小；--enforce-parser 强制使用特定的工具解析器后端，如 qwen_coder、qwen、json 或 mistral；--yarn-scaling-factor 手动注入 YaRN RoPE 缩放因子，例如 4.0，以扩展支持模型的有效上下文窗口；--fp8-kvcache 用于启用 fp8 KV 缓存；--prefix-cache 启用前缀缓存复用；--prefix-cache-max-tokens 限制前缀缓存大小；--ui-server 则启动内置的类似 ChatGPT 的 Web UI 服务器。若要使用 Flash attention 后端，可将 BUILD_PARAM 中的 flashinfer 替换为 flashattn。

📚 文档

如何部署模型？

  • 注意： 对于 Docker 构建，执行以下命令进入容器：
docker run --rm -it --gpus all --network host -v /home:/home -v /data:/data candle-vllm:latest bash

  • 运行 未压缩 模型

    显示命令

    本地路径（含端口、设备）

    candle-vllm --p 8000 --d 0,1 --w /home/Qwen3-30B-A3B-Instruct-2507/ --prefix-cache

    本地路径（ISQ，+UI 服务器）

    candle-vllm --p 8000 --d 0,1 --w /home/Qwen3.5-27B/ --isq q4k --ui-server --prefix-cache

    模型 ID（从 Hugging Face 下载）

    candle-vllm --m Qwen/Qwen3.5-35B-A3B --ui-server --prefix-cache

    手动 YaRN 缩放

    candle-vllm --m Qwen/Qwen3.5-35B-A3B --yarn-scaling-factor 4.0 --ui-server --prefix-cache

    FP8 模型（分块量化，使用 cutlass 特性构建）

    candle-vllm --m Qwen/Qwen3.5-27B-FP8 --ui-server --prefix-cache

     # MacOS/Metal（密集型）
candle-vllm --m Qwen/Qwen3-4B-Instruct-2507-FP8 --ui-server --prefix-cache

  • 运行 GGUF 模型

    显示命令

    本地路径

    candle-vllm --f /home/data/Qwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server

    模型 ID（从 Hugging Face 下载）

    candle-vllm --m unsloth/Qwen3-30B-A3B-Instruct-2507-GGUF --f Qwen3-30B-A3B-Instruct-2507-Q4_K_M.gguf --ui-server

  • 运行 GGUF 模型于 Apple Silicon 上

    显示命令

    本地路径（假设模型已下载至 /home）

    candle-vllm --f /home/qwq-32b-q4_k_m.gguf --ui-server

    模型 ID（从 Hugging Face 下载）

    candle-vllm --m Qwen/QwQ-32B-GGUF --f qwq-32b-q4_k_m.gguf --ui-server

  • 运行 任何未压缩模型，通过原位量化将其量化

    显示命令

    只需在运行未量化模型时添加 isq 参数

    candle-vllm --p 2000 --m Qwen/Qwen3.5-27B --isq q4k

    原位 isq 参数的可选值有：["q4_0", "q4_1", "q5_0", "q5_1", "q8_0", "q2k", "q3k","q4k","q5k","q6k"]

  • 运行 与 Marlin 兼容的 GPTQ 模型（4-bit GPTQ，128 组，desc_act=False）

    显示命令

    本地路径

    candle-vllm --w /home/DeepSeek-R1-Distill-Qwen-14B-GPTQ_4bit-128g

    模型 ID（从 Hugging Face 下载）

    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

  • 运行 与 Marlin 兼容的 AWQ 模型

    显示命令

    将 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

    运行转换后的 AWQ 模型

    candle-vllm --d 0 --w /home/Meta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin/

  • 运行 Marlin 格式的模型

    显示命令 
    candle-vllm --w /home/DeepSeek-R1-Distill-Qwen-14B-GPTQ-Marlin/

  • 运行 大型模型，采用多进程模式（多 GPU）

    显示命令

    QwQ-32B BF16 模型在两块 GPU 上

    candle-vllm --d 0,1 --w /home/QwQ-32B/

    QwQ-32B 4-bit AWQ 模型在两块 GPU 上

    1. 将 AWQ 模型转换为 Marlin 兼容格式
    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
    1. 运行转换后的 AWQ 模型
    candle-vllm --d 0,1 --w /home/QwQ-32B-AWQ-Marlin/

注意： 所使用的 GPU 数量（--d）必须是 2 的幂次方（例如，2、4 或 8）。

  • 使用多线程模式运行大型模型（多 GPU，用于调试）

    显示命令

    只需添加 --multithread 参数即可。

    在两块 GPU 上运行 QwQ-32B BF16 模型

    candle-vllm --multithread --d 0,1 --w /home/QwQ-32B/

    如果在多线程多 GPU 模式下遇到问题，可以尝试：

    export NCCL_P2P_DISABLE=1 # 禁用 p2p，因为在某些环境中此功能可能导致非法内存访问

  • 在较低 GPU 显存条件下运行 DeepSeek-R1（671B/685B）（CPU offloading）

    显示命令

    1. 将 DeepSeek-R1-AWQ 模型转换为与 Marlin 兼容的格式

    python3 examples/convert_awq_marlin.py --src /data/DeepSeek-R1-AWQ/ --dst /data/DeepSeek-R1-AWQ-Marlin/

    2. 在 8 块 A100（40GB）上运行 DeepSeek-R1 模型

    candle-vllm --log --d 0,1,2,3,4,5,6,7 --w /data/DeepSeek-R1-AWQ-Marlin/--num-experts-offload-per-rank 15

    注意： 此设置会将每个 Rank 上的 15 个专家（总共 256 个中的 120 个）卸载到 CPU（大约需要额外 150GB 的主机内存）。在推理过程中，这些被卸载的专家会根据需要交换回 GPU 内存。如果您可用的 GPU 显存更少，请考虑增加 --num-experts-offload-per-rank 参数值（在此情况下，每个 Rank 最多可卸载 32 个专家）。

  • 在多节点上运行 DeepSeek-R1（671B/685B）

    显示命令

    1. 安装 MPI 并启用 MPI 功能进行构建

    sudo apt update
sudo apt install libopenmpi-dev openmpi-bin -y # 安装 MPI
sudo apt install clang libclang-dev
# 在两台节点的同一目录下克隆仓库并构建
cargo install --features cuda,nccl,mpi # 启用 MPI 功能进行构建

    2. 将 AWQ DeepSeek 转换为 Marlin 兼容格式

    python3 examples/convert_awq_marlin.py --src /data/DeepSeek-R1-AWQ/ --dst /data/DeepSeek-R1-AWQ-Marlin/

    3. 配置多节点环境

    MPI 运行器要求所有节点具有“完全相同”的硬件和软件配置，请确保权重文件和 candle-vllm 二进制文件在不同节点上的路径完全一致。此外，节点之间需要免密 SSH 登录（使用 root 用户时需启用 --allow-run-as-root）。%NET_INTERFACE% 是通过 ifconfig -a 命令获取的活动网络接口。如果节点上没有 InfiniBand 网络，可以通过设置环境变量 -x NCCL_IB_DISABLE=1 来禁用它。hostfile 文件的示例如下：

    示例（两台节点，每台有 8 个 GPU）

    192.168.1.100 slots=8
192.168.1.101 slots=8

    4. 使用 MPI 运行器在两台节点上运行模型

    sudo mpirun -np 16 -x RUST_LOG=info -hostfile ./hostfile --allow-run-as-root -bind-to none -map-by slot --mca plm_rsh_args "-p 22" --mca btl_tcp_if_include %NET_INTERFACE% candle-vllm --log --d 0,1,2,3,4,5,6,7 --w /data/DeepSeek-R1-AWQ-Marlin/

  • 使用 NUMA 绑定运行

    显示命令

    先决条件 确保您的机器拥有多个 NUMA 节点（即多于一个物理 CPU），并安装 numactl：

    sudo apt-get install numactl

    假设您的机器有 8 个 GPU 和 2 个 NUMA 节点，每组 4 个 GPU 分别绑定到不同的 NUMA 节点。为了在使用全部 GPU 进行推理时获得最佳性能，可以采用以下 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，可以应用如下 NUMA 绑定：

    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-Marlin

    其中 上述 numactl --cpunodebind=0 --membind=0 表示主 Rank（主进程）的 NUMA 绑定，应与 MAP_NUMA_NODE 设置相匹配。

    注意：具体的 NUMA 绑定顺序可能因您的硬件配置而异。

如何向后端发送请求？

在启动后端服务后运行聊天前端

聊天前端（任何兼容 OpenAI API 的前端，以下提供简单选项）：

  • 选项 1：使用 Chat.py 进行聊天（适用于简单测试）

    显示选项 1

    安装 API 和聊天机器人依赖项（openai 包仅用于本地与 candle-vllm 的聊天）

    python3 -m pip install openai rich click

    使用迷你聊天机器人进行纯文本聊天：

    python3 examples/chat.py

    传递生成参数（对带有 --thinking True 的推理模型）：

    python3 examples/chat.py --temperature 0.7 --top_k 64 --top_p 0.9 --thinking True --system_prompt "Thinking big!"

    使用迷你聊天机器人进行 Markdown 实时更新的聊天（可能会出现闪烁）：

    python3 examples/chat.py --live

  • 选项 2：使用 naive ChatUI（或流行的 dify 前端）进行聊天

    显示选项 2

    安装 naive ChatUI 及其依赖项：

    git clone git@github.com:guoqingbao/candle-vllm-demo.git
cd candle-vllm-demo
apt install npm # 如果需要，安装 npm
npm install n -g # 如果需要，更新 Node.js
n stable # 如果需要，更新 Node.js
npm i -g pnpm # 安装 pnpm 包管理器
pnpm install # 安装 ChatUI 的依赖项

    启动 ChatUI：

    pnpm run dev # 运行 ChatUI

    Node.js 错误排查 ENOSPC: 系统文件监视器数量限制已达到

    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

  • 选项 3：使用 HTTP POST 发送聊天完成请求

    显示选项 3 
    curl -X POST "http://127.0.0.1:2000/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
        "model": "llama7b",
        "messages": [
            {"role": "user", "content": "解释如何最好地学习 Rust。"}
        ],
        "temperature": 0.7,
        "max_tokens": 128,
        "stop": {"Single":"</s>"}
    }'

    示例响应：

    {"id":"cmpl-53092967-c9cf-40e0-ae26-d7ac786d59e8","choices":[{"message":{"content":" 学习任何编程语言都需要理论、实践和专注相结合。以下是帮助你有效学习 Rust 的一些步骤和资源：\n\n1. 从基础开始：\n\t* 理解 Rust 程序的语法和基本结构。\n\t* 学习变量、数据类型、循环和控制结构。\n\t* 熟悉 Rust 的所有权系统和借用机制。\n2. 阅读 Rust 官方书籍：\n\t* Rust 官方书籍是全面介绍该语言的权威资源。\n\t* 它涵盖了诸如","role":"[INST]"},"finish_reason":"length","index":0,"logprobs":null}],"created":1718784498,"model":"llama7b","object":"chat.completion","usage":{"completion_tokens":129,"prompt_tokens":29,"total_tokens":158}}

  • 选项 4：使用 openai 包进行聊天完成

    显示选项 4

    在终端中运行 pip install openai 来安装 openai Python 包。我使用的是版本 1.3.5。

    然后，创建一个新的 Python 文件并编写以下代码：

    import openai

openai.api_key = "EMPTY"

openai.base_url = "http://localhost:2000/v1/"

completion = openai.chat.completions.create(
    model="llama",
    messages=[
        {
            "role": "user",
            "content": "解释如何最好地学习 Rust。",
        },
    ],
    max_tokens = 64,
)
print(completion.choices[0].message.content)

    在 candle-vllm 服务运行后，运行该 Python 脚本，即可享受与 OpenAI 兼容的 API 服务器带来的高效推理！

    批量请求

    首先安装 openai API：

    python3 -m pip install openai

    运行基准测试：

    python3 examples/benchmark.py --batch 16 --max_tokens 1024

    参考 examples/benchmark.py

    async def benchmark():
    model = "mistral7b"
    max_tokens = 1024
    # 16 个请求
    prompts = ["解释如何最好地学习 Rust。", 
            "请用 100 字谈谈深度学习。", 
            "你知道中国的首都吗？详细说说你所知道的。", 
            "世界上最好的女演员是谁？为什么？",
            "如何应对抑郁症？",
            "如何在短时间内赚钱？",
            "大型语言模型的未来趋势是什么？",
            "世界上著名的科技公司有哪些。",
            "解释如何最好地学习 Rust。", 
            "请用 100 字谈谈深度学习。", 
            "你知道中国的首都吗？详细说说你所知道的。", 
            "世界上最好的女演员是谁？为什么？",
            "如何应对抑郁症？",
            "如何在短时间内赚钱？",
            "大型语言模型的未来趋势是什么？",
            "世界上著名的科技公司有哪些。"]
    
    # 同时发送 16 个聊天请求
    tasks: List[asyncio.Task] = []
    for i in range(len(prompts)):
        tasks.append(
            asyncio.create_task(
                chat_completion(model, max_tokens, prompts[i]))
        )

    # 获取每个请求对应的流对象
    outputs: List[Stream[ChatCompletionChunk]] = await asyncio.gather(*tasks)

    # 处理聊天响应的流任务
    tasks_stream: List[asyncio.Task] = []
    for i in range(len(outputs)):
        tasks_stream.append(
            asyncio.create_task(
                stream_response(i, outputs[i]))
        )

    # 汇总响应文本
    outputs: List[(int, str)] = await asyncio.gather(*tasks_stream)

    # 打印结果，你可以在后端服务器（即 candle-vllm）中找到聊天完成的统计信息
    for idx, output in outputs:
        print("\n\n 回复 {}: \n\n {}".format(idx, output))

asyncio.run(benchmark())

原位量化

  • 以 GGUF 量化或 Marlin 格式加载未量化模型

    显示量化配置

    Candle-vllm 支持原位量化，允许在加载模型时将默认权重（F32/F16/BF16）转换为任意 GGML/GGUF 格式，或将 4-bit GPTQ/AWQ 权重转换为 marlin 格式。此功能有助于节省 GPU 内存并加速推理性能，使其对消费级 GPU（例如 RTX 4090）更加高效。要使用此功能，只需在运行 candle-vllm 时提供 isq 参数。

    对于未量化模型：

    candle-vllm --p 2000 --w /home/Meta-Llama-3.1-8B-Instruct/ --isq q4k

    isq 参数的选项有：["q4_0", "q4_1", "q5_0", "q5_1", "q8_0", "q2k", "q3k","q4k","q5k","q6k"]

    对于已量化 4-bit GPTQ 模型：

    candle-vllm --p 2000 --w /home/mistral_7b-int4/

    请注意关于 marlin 的几点：

    1. 将 F32/F16/BF16 模型加载为量化格式可能需要几分钟时间；

    2. Marlin 格式的原位转换仅支持 4-bit GPTQ（sym=True、groupsize=128 或 -1、desc_act=False）以及 4-bit AWQ（需使用提供的脚本进行转换，参见“其他用法”）；

    3. Marlin 格式仅在 CUDA 平台上受支持。

其他用法

  • KV 缓存配置、采样参数等

    显示详情 `--mem`（`kvcache-mem-gpu`）参数用于设置固定的 KV 缓存预算，单位为 MB。默认值为 `4096` MB。

    --gpu-memory-fraction 参数是一种更轻量级的自动模式。若省略，则默认值为 0.7。模型加载完成后，candle-vllm 会探测每个已加载的 CUDA 或 Metal 设备，并按以下公式计算 KV 缓存预算：

    gpu_memory_fraction * 模型加载后剩余的 GPU 内存

    这意味着该分数直接控制了模型加载后剩余的空闲 GPU 内存中可用于组合 GPU 缓存预算的比例。各进程检测到的最低预算将被用作每个进程的 KV 缓存预算。例如：

    candle-vllm --w /home/Qwen3-Coder-30B-A3B-Instruct-FP8 --d 0,1 --gpu-memory-fraction 0.7

    当您希望设定明确的固定预算时，请使用 --mem；当您希望服务器根据模型加载后的当前可用 GPU 内存自动调整时，则使用 --gpu-memory-fraction。

    --enforce-parser 参数可强制指定特定的工具调用解析器后端，而非由模型自动选择的默认解析器。这在模型与某个解析器兼容但未能正确自动检测到时非常有用。常见值包括 qwen_coder、qwen、json 和 mistral。例如：

    candle-vllm --w /home/Qwen3-Coder-30B-A3B-Instruct-FP8 --enforce-parser qwen_coder

    无效的解析器名称将在启动时被拒绝。

    对于聊天历史设置，将 record_conversation 设置为 true 可让 candle-vllm 记录聊天历史。默认情况下，candle-vllm 不会记录聊天历史；相反，客户端会同时发送消息和上下文历史给 candle-vllm。如果将 record_conversation 设置为 true，则客户端仅向 candle-vllm 发送新的聊天消息，而 candle-vllm 负责记录之前的聊天消息。然而，这种方法需要按会话记录聊天，目前尚未实现，因此建议采用默认方式 record_conversation=false。

    在聊天流式传输中，聊天请求中的 stream 标志需设置为 True。

    candle-vllm --p 2000 --w /home/mistral_7b/

    --max-gen-tokens 参数用于控制每次聊天回复的最大输出 token 数。默认值为 max_sequence_len 的 1/5。

    对于 消费级 GPU，建议以 GGML 格式（或 Marlin 格式）运行模型，例如：

    candle-vllm --p 2000 --w /home/Meta-Llama-3.1-8B-Instruct/ --isq q4k

    其中 isq 是 ["q4_0", "q4_1", "q5_0", "q5_1", "q8_0", "q2k", "q3k","q4k","q5k","q6k", "awq", "gptq", "marlin", "gguf", "ggml"] 中的一个。

  • 使用 Marlin 内核加速 GPTQ/AWQ 模型

    显示详情

    Candle-vllm 现在支持 GPTQ/AWQ 的 Marlin 内核，您可以直接运行这些模型，例如：

    candle-vllm --dtype f16 --w /home/Meta-Llama-3.1-8B-Instruct-GPTQ-INT4-Marlin/

    或者，将现有的 AWQ 4bit 模型转换为 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 --dtype f16 --d 0 --w /home/Meta-Llama-3.1-8B-Instruct-AWQ-INT4-Marlin/

    您也可以使用 GPTQModel 通过提供的脚本 examples/convert_marlin.py 将模型转换为 marlin 兼容格式。

    注意： 目前，只有 4-bit GPTQ 量化支持使用 Marlin 快速内核。

报告问题

安装 candle-vllm 非常简单，只需按照以下步骤操作即可。如果您遇到任何问题，请创建一个 issue。

贡献

计划实现以下功能，但我们特别欢迎贡献：

资源

常见问题

相似工具推荐

openclaw

OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。 这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。 OpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你

★ 349.3k|★★★☆☆|今天
Agent开发框架图像

stable-diffusion-webui

stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。 无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。

★ 162.1k|★★★☆☆|昨天
开发框架图像Agent

everything-claude-code

everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。 通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。 这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上

★ 141.5k|★★☆☆☆|今天
开发框架Agent语言模型

ComfyUI

ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。 这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。 无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。

★ 107.9k|★★☆☆☆|今天
开发框架图像Agent

markitdown

MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。 在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。 这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器

★ 93.4k|★★☆☆☆|今天
插件开发框架

LLMs-from-scratch

LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。 该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。 LLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备

★ 90.1k|★★★☆☆|今天
语言模型图像Agent