注意

该项目目前已归档。开发工作将继续在 ExLlamaV3 上进行。

ExLlamaV2

ExLlamaV2 是一个用于在现代消费级 GPU 上运行本地大语言模型的推理库。

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

请参阅 wiki 以获取入门帮助。

v0.1.0+ 新特性：

• ExLlamaV2 现在通过 Flash Attention 2.5.7+ 支持分页注意力机制。
• 新增动态批处理生成器，具备智能提示缓存、K/V 缓存去重以及简化的 API。

动态生成器

动态生成器支持之前两个生成器的所有推理、采样和推测解码功能，并将这些功能整合到一个 API 中（除了 FP8 缓存之外，不过 Q4 缓存模式同样支持，且性能更好，请参阅 这里）。

关于该生成器的详细说明请参见 这里。

• 单次生成：

  output = generator.generate(prompt = "你好，我叫", max_new_tokens = 200)
  

• 批量生成：

  outputs = generator.generate(
      prompt = [
          "你好，我叫",
          "从前有一个人，",
          "大型语言模型是",
      ], 
      max_new_tokens = 200
  )
  

• 使用 asyncio 进行流式生成：

  job = ExLlamaV2DynamicJobAsync(
      generator,
      input_ids = tokenizer.encode("你可以把马带到水边"),
      banned_strings = ["让它喝水"],
      gen_settings = ExLlamaV2Sampler.Settings.greedy(),
      max_new_tokens = 200
  )  
  async for result in job:
      text = result.get("text", "")
      print(text, end = "")       
  

  完整的更新示例请参见 这里。

性能

以下是一些快速测试，用于对比 ExLlama V1 的性能。未来可能会有更多的性能优化，而且不同 GPU 的速度也会有所差异，其中较慢的 CPU 仍可能成为瓶颈：

模型	模式	大小	分组大小	激活函数	3090Ti	4090
Llama	GPTQ	7B	128	无	181 token/s	205 token/s
Llama	GPTQ	13B	128	无	110 token/s	114 token/s
Llama	GPTQ	33B	128	有	44 token/s	48 token/s
OpenLlama	GPTQ	3B	128	有	259 token/s	296 token/s
CodeLlama	EXL2 4.0 bpw	34B	-	-	44 token/s	50 token/s
Llama2	EXL2 3.0 bpw	7B	-	-	217 token/s	257 token/s
Llama2	EXL2 4.0 bpw	7B	-	-	185 token/s	211 token/s
Llama2	EXL2 5.0 bpw	7B	-	-	164 token/s	179 token/s
Llama2	EXL2 2.5 bpw	70B	-	-	33 token/s	38 token/s
TinyLlama	EXL2 3.0 bpw	1.1B	-	-	656 token/s	770 token/s
TinyLlama	EXL2 4.0 bpw	1.1B	-	-	602 token/s	700 token/s

使用方法

要从仓库安装，您需要 CUDA 工具包，以及 Linux 上的 gcc 或 Windows 上的 Visual Studio（构建工具）。同时，请确保已安装适当版本的 PyTorch，然后执行以下命令：

git clone https://github.com/turboderp/exllamav2
cd exllamav2
pip install -r requirements.txt
pip install .

运行以下命令进行测试推理：

python test_inference.py -m <模型路径> -p "从前有一个人，"
# 对于多 GPU 推理，可添加 '--gpu_split auto' 标志

项目中包含一个简单的控制台聊天机器人。可通过以下命令运行：

python examples/chat.py -m <模型路径> -mode llama -gs auto

-mode 参数用于选择使用的提示格式。raw 将生成一个简单的聊天记录风格的对话，适用于基础模型及其他微调模型。使用 -modes 可查看所有可用的提示格式列表。您还可以通过 -sp 提供自定义系统提示。

集成与 API

• TabbyAPI 是一个基于 FastAPI 的服务器，提供与 OpenAI 风格兼容的 Web API，可与 SillyTavern 等前端应用配合使用。

• ExUI 是一个简单、独立的单用户 Web UI，可直接为 ExLlamaV2 实例提供服务，支持聊天和笔记本模式。

• text-generation-webui 通过 exllamav2 和 exllamav2_HF 加载器支持 ExLlamaV2。

• lollms-webui 通过 exllamav2 绑定支持 ExLlamaV2。

安装

方法 1：从源码安装

要安装当前开发版本，克隆仓库并运行安装脚本：

git clone https://github.com/turboderp/exllamav2
cd exllamav2
pip install -r requirements.txt
pip install .

默认情况下，这还会编译并安装库所依赖的 Torch C++ 扩展 (exllamav2_ext)。您可以通过设置 EXLLAMA_NOCOMPILE 环境变量来跳过此步骤：

EXLLAMA_NOCOMPILE= pip install .

这样将安装“JIT 版本”的包，即仅安装 Python 组件，而不会在安装过程中构建 C++ 扩展。相反，该扩展将在首次使用库时被构建，并缓存在 ~/.cache/torch_extensions 目录中，以便后续使用。

方法 2：从发布版本安装（含预编译扩展）

发布版本可在 这里 获取，其中包含预编译的轮子文件，内含扩展二进制文件。请务必根据您的平台、Python 版本 (cp) 和 CUDA 版本选择合适的版本。关键是要确保预编译轮子与您的 PyTorch 版本匹配，因为每次 PyTorch 更新都会导致 Torch C++ 扩展的 ABI 发生变化。

您可以下载合适的轮子文件，或者直接从相应的 URL 安装：

pip install https://github.com/turboderp/exllamav2/releases/download/v0.0.12/exllamav2-0.0.12+cu121-cp311-cp311-linux_x86_64.whl

py3-none-any.whl 版本是 JIT 版本，在首次启动时会构建扩展。.tar.gz 文件也可以通过这种方式安装，并在安装过程中构建扩展。

方法 3：从 PyPI 安装

PyPI 上也提供了该软件包。这与上述的 JIT 版本相同。可通过以下命令安装：

pip install exllamav2

EXL2 量化

ExLlamaV2 支持与 V1 相同的 4 位 GPTQ 模型，同时还引入了一种新的“EXL2”格式。EXL2 基于与 GPTQ 相同的优化方法，支持 2、3、4、5、6 和 8 位量化。该格式允许在单个模型中混合使用不同的量化级别，从而实现每权重 2 到 8 位之间的任意平均比特率。

此外，还可以为每个线性层应用多种量化级别，从而产生类似稀疏量化的效果：更重要的权重（列）会以更多位数进行量化。与 ExLlama 能够高效处理激活顺序模型相同的重映射技巧，使得这种格式混合几乎不会对性能造成影响。

参数选择是自动完成的：针对每一层，会对每个矩阵进行多次量化，并基于所选的校准数据测量每次量化后的误差。最终，系统会选择一种组合方案，使整个模型的最大量化误差最小化，同时满足目标平均比特率的要求。

在我的测试中，这一方案使 Llama2 70B 模型能够在单张 24 GB 显存的 GPU 上以 2048 个 token 的上下文长度运行，每权重约为 2.55 位，输出连贯且基本稳定。13B 规模的模型则可在 8 GB 显存内以 2.65 位运行，不过目前这些模型均未采用 GQA 技术，这实际上将上下文长度限制在 2048 个 token。无论哪种情况，模型都很难与桌面环境共存。至少目前是这样。

转换

我们提供了一个用于量化模型的脚本。转换大型模型可能会比较缓慢，请提前知晓。有关转换脚本及其选项的详细说明，请参阅 此处。

评估

我们提供了若干评估脚本。详情请参阅 此处。

社区

我们在 Discord 上建立了一个测试社区：https://discord.gg/NSFwVuCjRq。#bot test 频道提供免费的量化服务。计算资源由 Lambda Labs 提供的支持 Bloke 平台慷慨捐赠。

Hugging Face 仓库

• 我已在 Hugging Face 上上传了几款 EXL2 量化的模型，供大家试用，地址在此。

• LoneStriker 在 Hugging Face 上提供了大量 EXL2 模型。

• bartowski 也在 Hugging Face 上发布了一些 EXL2 模型。

ExLlamaV2 快速上手指南

注意：ExLlamaV2 项目目前已归档，后续开发已转移至 ExLlamaV3。本指南仅针对 ExLlamaV2 版本。

ExLlamaV2 是一个专为现代消费级 GPU 设计的本地大语言模型（LLM）推理库，支持高效的量化模型运行。

环境准备

系统要求

• 操作系统：Linux 或 Windows
• GPU：支持 CUDA 的 NVIDIA 显卡（推荐 RTX 30/40 系列或更高）
• CUDA Toolkit：需安装与 PyTorch 版本匹配的 CUDA 工具包
• 编译器：
  • Linux: gcc
  • Windows: Visual Studio Build Tools

前置依赖

• Python: 建议 3.8+
• PyTorch: 需预先安装适配你硬件环境的版本。
  • 国内用户推荐使用清华源加速安装：

    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
    # 请将 cu121 替换为你实际需要的 CUDA 版本，如 cu118
    

安装步骤

你可以选择以下三种方式之一进行安装：

方法一：从源码安装（推荐开发者使用）

此方法会自动编译所需的 C++ 扩展。

git clone https://github.com/turboderp/exllamav2
cd exllamav2
pip install -r requirements.txt
pip install .

注：若不想在安装时编译，可设置环境变量 EXLLAMA_NOCOMPILE=1 pip install .，库将在首次运行时即时编译（JIT）。

方法二：从 PyPI 安装（最简便）

安装 JIT 版本，首次使用时自动构建扩展。

pip install exllamav2

方法三：安装预编译版本

访问 Releases 页面 下载匹配你平台、Python 版本和 CUDA 版本的 .whl 文件直接安装，适合生产环境以避免编译错误。

基本使用

1. 运行测试推理

确保你已准备好量化后的模型文件（支持 GPTQ 或 EXL2 格式），然后运行以下命令测试：

python test_inference.py -m <path_to_model> -p "Once upon a time,"

提示：如需多卡推理，请添加 --gpu_split auto 参数。

2. 启动简易聊天机器人

项目内置了一个控制台聊天示例：

python examples/chat.py -m <path_to_model> -mode llama -gs auto

• -mode: 选择提示词格式（如 llama, raw 等），输入 -modes 可查看支持列表。
• -sp: 可选参数，用于指定自定义系统提示词。

3. Python 代码调用示例

在 Python 脚本中调用动态生成器（Dynamic Generator）：

单次生成：

output = generator.generate(prompt="Hello, my name is", max_new_tokens=200)

批量生成：

outputs = generator.generate(
    prompt=[
        "Hello, my name is",
        "Once upon a time,",
        "Large language models are",
    ], 
    max_new_tokens=200
)

流式输出 (Asyncio)：

job = ExLlamaV2DynamicJobAsync(
    generator,
    input_ids=tokenizer.encode("You can lead a horse to water"),
    banned_strings=["make it drink"],
    gen_settings=ExLlamaV2Sampler.Settings.greedy(),
    max_new_tokens=200
)  
async for result in job:
    text = result.get("text", "")
    print(text, end="")

推荐集成方案

对于需要 API 服务或图形界面的用户，推荐配合以下工具使用：

• TabbyAPI: 提供兼容 OpenAI 格式的 API 服务端，支持 SillyTavern 等前端。
• text-generation-webui: 通过 exllamav2 加载器支持该后端。