ExLlamaV3

ExLlamaV3 是一款用于在现代消费级 GPU 上运行本地大模型的推理库。其主要特性包括：

• 基于 QTIP 的全新 EXL3 量化格式
• 针对消费级硬件配置的灵活张量并行与专家并行推理
• 通过 TabbyAPI 提供的 OpenAI 兼容服务器
• 连续动态批处理
• Hugging Face Transformers 插件（参见 此处）
• 支持 Hugging Face 模型（参见 支持的架构）
• 推测解码
• 2 至 8 位缓存量化
• 多模态支持

ExLlamaV3 官方推荐的后端服务器是 TabbyAPI，它提供了一个兼容 OpenAI 的 API，可用于本地或远程推理，并具备扩展功能，如 Hugging Face 模型下载、嵌入模型支持以及对 Hugging Face Jinja2 聊天模板的支持。

⚠️ 重要提示

• Qwen3-Next 和 Qwen3.5 可以利用 Flash Linear Attention，但此功能需要 Triton 支持，且由于其不稳定的 JIT 编译机制，性能可能不够稳定。causal-conv1d 是受支持且推荐的替代方案，但并非必需。
• Qwen3-Next 和 Qwen3.5 目前尚不支持张量/专家并行。

架构支持

• AFM (ArceeForCausalLM)
• Apertus (ApertursForCausalLM)
• Command-R 等（CohereForCausalLM）
• Command-A、Command-R7B、Command-R+ 等（Cohere2ForCausalLM）
• DeciLM、Nemotron（DeciLMForCausalLM）
• dots.llm1（Dots1ForCausalLM）
• ERNIE 4.5（Ernie4_5_ForCausalLM、Ernie4_5_MoeForCausalLM）
• EXAONE 4.0（Exaone4ForCausalLM）
• Gemma 2（Gemma2ForCausalLM）
• Gemma 3（Gemma3ForCausalLM、Gemma3ForConditionalGeneration）- 多模态
• GLM 4、GLM 4.5、GLM 4.5-Air、GLM 4.6（Glm4ForCausalLM、Glm4MoeForCausalLM）
• GLM 4.1V、GLM 4.5V（Glm4vForConditionalGeneration、Glm4vMoeForConditionalGeneration）- 多模态
• HyperCLOVAX（HyperCLOVAXForCausalLM、HCXVisionV2ForCausalLM）- 多模态
• IQuest-Coder（IQuestCoderForCausalLM）
• Llama、Llama 2、Llama 3、Llama 3.1-Nemotron 等（LlamaForCausalLM）
• MiMo-RL（MiMoForCausalLM）
• MiniMax-M2（MiniMaxM2ForCausalLM）
• Mistral、Ministral 3、Devstral 2 等（MistralForCausalLM、Mistral3ForConditionalGeneration）- 多模态
• Mixtral（MixtralForCausalLM）
• NanoChat（NanoChatForCausalLM）
• Olmo 3.1（Olmo3ForCausalLM）
• Olmo-Hybrid（OlmoHybridForCausalLM）
• Phi3、Phi4（Phi3ForCausalLM）
• Qwen 2、Qwen 2.5、Qwen 2.5 VL（Qwen2ForCausalLM、Qwen2_5_VLForConditionalGeneration）- 多模态
• Qwen 3（Qwen3ForCausalLM、Qwen3MoeForCausalLM）
• Qwen 3-Next（Qwen3NextForCausalLM）
• Qwen 3-VL（Qwen3VLForConditionalGeneration）- 多模态
• Qwen 3-VL MoE（Qwen3VLMoeForConditionalGeneration）- 多模态
• Qwen 3.5（Qwen3_5ForConditionalGeneration）- 多模态
• Qwen 3.5 MoE（Qwen3_5MoeForConditionalGeneration）- 多模态
• Seed-OSS（SeedOssForCausalLM）
• SmolLM（SmolLM3ForCausalLM）
• SolarOpen（SolarOpenForCausalLM）
• Step 3.5 Flash（Step3p5ForCausalLM）

我们仍在不断添加更多支持，请持续关注。

尚未实现的功能？

目前的待办事项包括：

• 大量优化
• LoRA 支持
• ROCm 支持
• 更多采样函数
• 更多量化模式（如 FP4 等）

至于已实现的部分，初期可能会存在一些小问题。请耐心等待，如有疑问或建议，欢迎提交 Issue 或参与贡献。👉👈

如何使用？

如果您希望快速在兼容 OAI 的客户端中开始推理，可以使用 TabbyAPI 提供的启动脚本，该脚本会自动管理并安装所需依赖。

否则，请先确保已安装适当版本的 PyTorch（CUDA 12.4 或更高版本），因为 pip 不会自动处理 Torch 的依赖关系。然后选择以下方法之一：

方法 1：从预编译的 wheel 安装（推荐给不确定如何操作的用户）

从 releases 页面 下载合适的 wheel 文件，例如：

pip install https://github.com/turboderp-org/exllamav3/releases/download/v0.0.6/exllamav3-0.0.6+cu128.torch2.8.0-cp313-cp313-linux_x86_64.whl

方法 2：从 PyPI 安装：

pip install exllamav3

请注意，PyPI 包不包含预编译的扩展，因此需要 CUDA 工具包及构建所需的依赖项（例如 Windows 上的 VS Build Tools、Linux 上的 gcc、python-dev 头文件等）。

方法 3：从源代码编译：

# 克隆仓库
git clone https://github.com/turboderp-org/exllamav3
cd exllamav3

# （可选）切换到 dev 分支以获取最新的开发中功能
git checkout dev

# 安装依赖项（请务必单独安装 Torch）
pip install -r requirements.txt

此时，您应该能够从主仓库目录运行转换、评估和示例脚本，例如 python convert.py -i ...。

要将库安装到当前的虚拟环境中，请在仓库目录下执行：

pip install .

与构建相关的环境变量：

• MAX_JOBS：默认情况下，ninja 可能会启动过多进程而导致系统内存不足。在这种情况下，可以将其设置为一个合理的值，例如 4。
• EXLLAMA_NOCOMPILE：设置此变量可在不编译 C++/CUDA 扩展的情况下安装库。Torch 将在运行时自行构建并加载该扩展。

模型转换

要将模型转换为 EXL3 格式，请使用以下命令：

# 转换模型
python convert.py -i <input_dir> -o <output_dir> -w <working_dir> -b <bitrate>

# 继续中断的量化任务
python convert.py -w <working_dir> -r

# 更多选项
python convert.py -h

工作目录是用于存储状态检查点以及量化张量的临时存储空间，直到转换后的模型可以完成编译。该目录应有足够的可用空间来存放整个输出模型的副本。需要注意的是，虽然 EXL2 转换默认会在指向现有文件夹时恢复中断的任务，但 EXL3 需要您显式地使用 -r/--resume 参数来恢复任务。

更多信息请参阅 这里。

示例

我们提供了一系列示例脚本，用于展示后端和生成器的各项功能。其中一些脚本硬编码了模型路径，您在运行之前需要进行编辑；不过，也有一个简单的 CLI 聊天机器人可供您立即上手：

python examples/chat.py -m <input_dir> -mode <prompt_mode>

# 例如：
python examples/chat.py -m /mnt/models/llama3.1-8b-instruct-exl3 -mode llama3

# 丰富的选项
python examples/chat.py -h

EXL3 量化

尽管取得了令人瞩目的成就，大多数最先进的量化技术仍然使用起来繁琐，甚至成本高昂到难以承受。例如，对一个700亿参数模型进行 AQLM 量化，在一台 A100 服务器上大约需要 720 GPU 小时，按撰写本文时的定价计算，费用高达850美元。ExLlamaV3 旨在通过 EXL3 格式来解决这一问题，该格式是康奈尔 RelaxML 团队的 QTIP 的一种精简变体。转换过程设计得简单高效，仅需输入一个 HF 格式的模型和目标比特率即可。通过实时计算海森矩阵，并借助融合的维特比内核，量化器可以在单步中完成模型转换：较小的模型只需几分钟，而较大的模型（700亿参数以上）则可能需要几小时（在单块 RTX 4090 或同等性能的 GPU 上）。

受 Marlin 启发的 GEMM 内核，在最佳条件下（4bpw，RTX 4090）能够达到接近内存带宽限制的延迟，不过它仍需进一步优化，以在 Ampere 架构的 GPU 上实现同样高效的性能，并在较低比特率下保持内存受限的状态。

由于转换后的模型基本保留了原始文件结构（不同于 EXL2，后者为了将所有模型统一为 Llama 变体而重命名部分张量），未来有望将 EXL3 支持扩展到其他框架，如 HF Transformers 和 vLLM。

一些基准测试结果可以在这里找到：[doc/exl3.md]，关于该格式的完整说明也将很快发布。

有趣的是：Llama-3.1-70B-EXL3 在 1.6 bpw 的情况下依然保持连贯性。如果将输出层量化至 3 bpw，并配备 4096 个 token 的缓存，推理所需的显存便可控制在 16 GB 以内。

社区

欢迎随时加入 ExLlama 的 Discord 服务器：[discord.gg/NSFwVuCjRq] ←🎮

🤗 HuggingFace 仓库

精选的 EXL3 量化模型已在此处提供：[huggingface.co/collections/turboderp/exl3-models-67f2dfe530f05cb9f596d21a]。同时也要感谢以下几位优秀的贡献者：

• ArtusDev
• MikeRoz
• MetaphoricalCode
• Ready.Art
• isogen

致谢

本项目得以实现，离不开一群优秀的开源开发者社区以及几位非常慷慨的支持者（🐈❤️！）。特别要感谢以下项目：

• TabbyAPI
• PyTorch
• FlashAttention
• QTIP
• Transformers
• Marlin
• Flash Linear Attention

ExLlamaV3 快速上手指南

ExLlamaV3 是一个专为现代消费级 GPU 设计的大语言模型（LLM）本地推理库。它引入了全新的 EXL3 量化格式，支持灵活的张量并行/专家并行、连续动态批处理、推测解码以及多模态模型推理。官方推荐的配套服务端是 TabbyAPI，可提供兼容 OpenAI 的 API 接口。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux (推荐) 或 Windows。
• GPU：支持 CUDA 的现代 NVIDIA 显卡（推荐 RTX 30/40 系列或更高）。
• Python：建议 Python 3.10+。
• PyTorch：必须预先安装 CUDA 12.4 或更高版本 的 PyTorch。pip 不会自动处理此依赖。
  • 安装命令示例（根据实际环境调整）：

    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
    

• 编译工具（仅源码安装需要）：
  • Linux: gcc, python-dev headers, ninja。
  • Windows: Visual Studio Build Tools。
  • 注：若内存有限，构建时可设置环境变量 MAX_JOBS=4 防止编译进程过多导致内存溢出。

安装步骤

推荐优先使用预编译包进行安装，以避免复杂的编译环境问题。

方法一：安装预编译 Wheel（推荐）

访问 Releases 页面 下载与您环境（CUDA 版本、Python 版本、系统架构）匹配的 .whl 文件，然后运行：

pip install https://github.com/turboderp-org/exllamav3/releases/download/v0.0.6/exllamav3-0.0.6+cu128.torch2.8.0-cp313-cp313-linux_x86_64.whl

(请将上述 URL 替换为您实际下载的文件链接)

方法二：从 PyPI 安装

此方法不包含预编译扩展，需要本地具备完整的 CUDA Toolkit 和编译环境。

pip install exllamav3

方法三：从源码构建

适用于需要最新开发版功能或自定义构建的用户。

# 克隆仓库
git clone https://github.com/turboderp-org/exllamav3
cd exllamav3

# (可选) 切换到 dev 分支获取最新功能
git checkout dev

# 安装依赖（确保已单独安装 Torch）
pip install -r requirements.txt

# 安装库到当前虚拟环境
pip install .

基本使用

ExLlamaV3 的核心工作流分为两步：模型量化转换 和 推理运行。

1. 模型量化转换 (EXL3 格式)

将 Hugging Face 格式的模型转换为高效的 EXL3 格式。您需要指定输入目录、输出目录、工作目录（用于临时存储）和目标比特率。

# 执行转换
# <input_dir>: 原始 HF 模型路径
# <output_dir>: 转换后模型保存路径
# <working_dir>: 临时工作目录（需足够空间存放完整模型副本）
# <bitrate>: 目标比特率 (例如 4.0)
python convert.py -i <input_dir> -o <output_dir> -w <working_dir> -b <bitrate>

# 如果转换中断，可使用 -r 参数恢复任务
python convert.py -w <working_dir> -r

注意：EXL3 格式转换不像 EXL2 那样自动检测断点，中断后必须显式添加 -r 或 --resume 参数才能继续。

2. 运行推理示例

库中提供了简单的命令行聊天脚本用于测试。

# 启动聊天机器人
# -m: 已转换好的 EXL3 模型路径
# -mode: 提示词模板模式 (如 llama3, qwen 等)
python examples/chat.py -m /mnt/models/llama3.1-8b-instruct-exl3 -mode llama3

# 查看可用选项
python examples/chat.py -h

3. 生产环境部署 (推荐)

对于需要 OpenAI 兼容 API、动态批处理或远程服务的场景，强烈建议搭配 TabbyAPI 使用：

1. 克隆并安装 TabbyAPI。
2. TabbyAPI 内置了启动脚本，可自动管理依赖并提供丰富的配置选项（如模型下载、Embedding 支持、Jinja2 模板等）。

---

更多高级功能（如多模态支持、张量并行配置）及支持的模型架构列表，请参阅项目官方文档。