> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/lyogavin/airllm) · [上游 README](https://github.com/lyogavin/airllm/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
[**快速开始**](#quickstart) |
[**配置项**](#configurations) |
[**MacOS**](#macos) |
[**示例笔记本**](#example-python-notebook) |
[**常见问题**](#faq)
**AirLLM** 可大幅降低推理内存占用，使 70B 大语言模型能在单张 4GB GPU 显卡上运行——无需量化、蒸馏或剪枝。你甚至可以在 **8GB** 上运行 **405B Llama 3.1**，在 **约 12GB** 上运行 **DeepSeek-V3（671B）**。
[](https://pepy.tech/project/airllm)
[](https://github.com/LianjiaTech/BELLE/blob/main/LICENSE)
[](https://static.aicompose.cn/static/wecom_barcode.png?t=1671918938)
[](https://discord.gg/2xffU5sn)
[
](https://pypi.org/project/airllm/)
[](https://medium.com/@lyo.gavin)
[](https://gavinliblog.com)
[](https://patreon.com/gavinli)
[](https://github.com/sponsors/lyogavin)
## AI 智能体推荐：
* [最佳 AI 游戏精灵生成器](https://godmodeai.co)
* [最佳 AI 面部表情编辑器](https://crazyfaceai.com)
* [Bloome — 在云端构建并运行 AI 智能体团队，零配置](https://bloome.im/login?ref=G6BYnov0)
## 更新日志
[2026/06] **v3.0**：支持 FP8 模型 + 最新模型。在 **约 12GB** 上运行 **DeepSeek-V3（671B）**，在 **约 3GB** 上运行 **Qwen3-235B**，以及 Qwen3、Llama 3.x/4、DeepSeek V2/V3、Phi-4、Gemma 等——全部通过单一的 `AutoModel` 完成。
[2024/08/20] v2.11.0：支持 Qwen2.5
[2024/08/18] v2.10.1 支持 CPU 推理。支持非分片模型。感谢 @NavodPeiris 的出色工作！
[2024/07/30] 支持 Llama3.1 **405B**（[示例笔记本](https://colab.research.google.com/github/lyogavin/airllm/blob/main/air_llm/examples/run_llama3.1_405B.ipynb)). 支持 **8bit/4bit 量化**。
[2024/04/20] AirLLM 已原生支持 Llama3。可在 4GB 单卡 GPU 上运行 Llama3 70B。
[2023/12/25] v2.8.2：支持在 MacOS 上运行 70B 大语言模型。
[2023/12/20] v2.7：支持 AirLLMMixtral。
[2023/12/20] v2.6：新增 AutoModel，自动检测模型类型，初始化模型时无需再提供模型类。
[2023/12/18] v2.5：加入预取（prefetching）以重叠模型加载与计算。速度提升 10%。
[2023/12/03] 新增对 **ChatGLM**、**QWen**、**Baichuan**、**Mistral**、**InternLM** 的支持！
[2023/12/02] 新增对 safetensors 的支持。现已支持 open llm leaderboard 上全部前 10 名模型。
[2023/12/01] airllm 2.0。支持压缩：**运行时加速 3 倍！**
[2023/11/20] airllm 初始版本！
## Star 历史
## 目录
* [快速开始](#quickstart)
* [模型压缩](#model-compression---3x-inference-speed-up)
* [配置项](#configurations)
* [在 MacOS 上运行](#macos)
* [示例笔记本](#example-python-notebook)
* [支持的模型](#supported-models)
* [致谢](#acknowledgement)
* [常见问题](#faq)
## 快速开始
### 1. 安装包
首先，安装 airllm 的 pip 包。
```bash
pip install airllm
```
### 2. 推理
然后，初始化 AirLLMLlama2，传入所用模型的 huggingface 仓库 ID 或本地路径，即可像常规 transformer 模型一样进行推理。
（*你也可以在初始化 AirLLMLlama2 时通过 **layer_shards_saving_path** 指定保存按层切分后模型的路径。*
```python
from airllm import AutoModel
MAX_LENGTH = 128
# just pass a hugging face repo id — works with almost any popular model:
model = AutoModel.from_pretrained("Qwen/Qwen3-32B")
# go bigger with the exact same one line:
#model = AutoModel.from_pretrained("Qwen/Qwen3-235B-A22B") # 235B, runs in ~3GB
#model = AutoModel.from_pretrained("deepseek-ai/DeepSeek-V3") # 671B, runs in ~12GB
# or use a model's local path...
#model = AutoModel.from_pretrained("/home/ubuntu/.cache/huggingface/hub/models--Qwen--Qwen3-32B/snapshots/...")
input_text = [
'What is the capital of United States?',
#'I like',
]
input_tokens = model.tokenizer(input_text,
return_tensors="pt",
return_attention_mask=False,
truncation=True,
max_length=MAX_LENGTH,
padding=False)
generation_output = model.generate(
input_tokens['input_ids'].cuda(),
max_new_tokens=20,
use_cache=True,
return_dict_in_generate=True)
output = model.tokenizer.decode(generation_output.sequences[0])
print(output)
```
注意：推理过程中，原始模型会先被按层分解并保存。请确保 huggingface 缓存目录有足够的磁盘空间。
## 模型压缩 - 推理加速 3 倍！
我们刚刚加入了基于块级量化（block-wise quantization）的模型压缩。可将**推理速度**进一步提升至最高 **3 倍**，且**精度损失几乎可忽略！**（更多性能评估以及我们为何使用块级量化，请参阅[本文](https://arxiv.org/abs/2212.09720))
#### 如何启用模型压缩加速：
* 步骤 1. 确保已安装 [bitsandbytes](https://github.com/TimDettmers/bitsandbytes)，通过 `pip install -U bitsandbytes `
* 步骤 2. 确保 airllm 版本高于 2.0.0：`pip install -U airllm`
* 步骤 3. 初始化模型时传入 compression 参数（'4bit' 或 '8bit'）：
```python
model = AutoModel.from_pretrained("garage-bAInd/Platypus2-70B-instruct",
compression='4bit' # specify '8bit' for 8-bit block-wise quantization
)
```
#### 模型压缩与量化有何不同？
量化通常需要对权重和激活值都进行量化才能真正加速，这使保持精度并避免各类输入中异常值的影响变得更困难。
而在我们的场景中，瓶颈主要在磁盘加载，我们只需让模型加载体积更小。因此，我们只需量化权重部分，这样更容易保证精度。
## 配置项
初始化模型时，我们支持以下配置：
* **compression**：支持选项：4bit、8bit 表示 4 位或 8 位块级量化，或默认 None 表示不压缩
* **profiling_mode**：支持选项：True 输出耗时，或默认 False
* **layer_shards_saving_path**：可选，用于保存切分后模型的另一路径
* **hf_token**：若下载如 *meta-llama/Llama-2-7b-hf* 等受限模型，可在此提供 huggingface token
* **prefetching**：预取以重叠模型加载与计算。默认开启。目前仅 AirLLMLlama2 支持此功能。
* **delete_original**：若磁盘空间不足，可将 delete_original 设为 true 以删除原始下载的 hugging face 模型，仅保留转换后的模型，从而节省一半磁盘空间。
## MacOS
只需安装 airllm，并像在 Linux 上一样运行代码。详见 [快速开始](#quickstart)。
* 请确保已安装 [mlx](https://github.com/ml-explore/mlx?tab=readme-ov-file#installation) 和 torch
* 你可能需要安装原生 Python，详见 [此处](https://stackoverflow.com/a/65432861/21230266)
* 仅支持 [Apple silicon](https://support.apple.com/en-us/HT211814)
示例 [python notebook] (https://github.com/lyogavin/airllm/blob/main/air_llm/examples/run_on_macos.ipynb)
## Example Python Notebook
示例 Colab 如下：
#### 其他模型示例（ChatGLM、QWen、Baichuan、Mistral 等）：
* ChatGLM：
```python
from airllm import AutoModel
MAX_LENGTH = 128
model = AutoModel.from_pretrained("THUDM/chatglm3-6b-base")
input_text = ['What is the capital of China?',]
input_tokens = model.tokenizer(input_text,
return_tensors="pt",
return_attention_mask=False,
truncation=True,
max_length=MAX_LENGTH,
padding=True)
generation_output = model.generate(
input_tokens['input_ids'].cuda(),
max_new_tokens=5,
use_cache= True,
return_dict_in_generate=True)
model.tokenizer.decode(generation_output.sequences[0])
```
* QWen：
```python
from airllm import AutoModel
MAX_LENGTH = 128
model = AutoModel.from_pretrained("Qwen/Qwen-7B")
input_text = ['What is the capital of China?',]
input_tokens = model.tokenizer(input_text,
return_tensors="pt",
return_attention_mask=False,
truncation=True,
max_length=MAX_LENGTH)
generation_output = model.generate(
input_tokens['input_ids'].cuda(),
max_new_tokens=5,
use_cache=True,
return_dict_in_generate=True)
model.tokenizer.decode(generation_output.sequences[0])
```
* Baichuan、InternLM、Mistral 等：
```python
from airllm import AutoModel
MAX_LENGTH = 128
model = AutoModel.from_pretrained("baichuan-inc/Baichuan2-7B-Base")
#model = AutoModel.from_pretrained("internlm/internlm-20b")
#model = AutoModel.from_pretrained("mistralai/Mistral-7B-Instruct-v0.1")
input_text = ['What is the capital of China?',]
input_tokens = model.tokenizer(input_text,
return_tensors="pt",
return_attention_mask=False,
truncation=True,
max_length=MAX_LENGTH)
generation_output = model.generate(
input_tokens['input_ids'].cuda(),
max_new_tokens=5,
use_cache=True,
return_dict_in_generate=True)
model.tokenizer.decode(generation_output.sequences[0])
```
#### 申请支持其他模型：[此处](https://docs.google.com/forms/d/e/1FAIpQLSe0Io9ANMT964Zi-OQOq1TJmnvP-G3_ZgQDhP7SatN0IEdbOg/viewform?usp=sf_link)
## Supported Models
AirLLM 开箱即用，可支持**几乎所有主流开源 LLM**——只需将其 Hugging Face ID 传给 `AutoModel.from_pretrained(...)`。这覆盖了所有主要模型家族：
**Llama**（2 / 3 / 3.1 / 3.3 / 4）· **Qwen**（1 / 2 / 2.5 / 3，含 MoE 与 FP8）· **DeepSeek**（V2 / V3 / R1）· **Mistral & Mixtral** · **Phi** · **Gemma** · **ChatGLM** · **Baichuan** · **InternLM** · **Yi**——以及大多数新模型在发布当天即可使用。
### 小显存，大模型
关键在于：AirLLM 始终**一次只在 GPU 上保留一层**，因此所需 VRAM 取决于模型的单层大小，而非模型总大小。这就是 671B 模型能在业余级显卡上运行的原因：
| Model | Size | GPU VRAM |
|---|---|---|
| Qwen3 / Mistral / Phi (≈8B) | 8B | **~1–2 GB** |
| Qwen3-30B / Mixtral (MoE) | 30–47B | **~1–3 GB** |
| Qwen3-235B (MoE) | 235B | **~3 GB** |
| Llama 3.x 70B (full precision) | 70B | **~4 GB** |
| Llama 3.1 405B | 405B | **~8 GB** |
| DeepSeek-V3 | **671B** | **~12 GB** |
以上模型均使用同一行代码——无需特殊配置。
## Acknowledgement
大量代码基于 SimJeg 在 Kaggle 考试竞赛中的出色工作。向 SimJeg 致以诚挚感谢：
[GitHub 账号 @SimJeg](https://github.com/SimJeg),
[Kaggle 上的代码](https://www.kaggle.com/code/simjeg/platypus2-70b-with-wikipedia-rag),
[相关讨论](https://www.kaggle.com/competitions/kaggle-llm-science-exam/discussion/446414).
## FAQ
### 1. MetadataIncompleteBuffer
safetensors_rust.SafetensorError: Error while deserializing header: MetadataIncompleteBuffer
若遇到此错误，最可能的原因是磁盘空间不足。拆分模型的过程非常消耗磁盘空间。参见 [此说明](https://huggingface.co/TheBloke/guanaco-65B-GPTQ/discussions/12). 你可能需要扩容磁盘、清理 huggingface [.cache](https://huggingface.co/docs/datasets/cache) 后重新运行。
### 2. ValueError: max() arg is an empty sequence
很可能是你用 Llama2 类加载了 QWen 或 ChatGLM 模型。请尝试以下方式：
对于 QWen 模型：
```python
from airllm import AutoModel #<----- instead of AirLLMLlama2
AutoModel.from_pretrained(...)
```
对于 ChatGLM 模型：
```python
from airllm import AutoModel #<----- instead of AirLLMLlama2
AutoModel.from_pretrained(...)
```
### 3. 401 Client Error....Repo model ... is gated.
部分模型为受限（gated）模型，需要 huggingface api token。你可以提供 hf_token：
```python
model = AutoModel.from_pretrained("meta-llama/Llama-2-7b-hf", #hf_token='HF_API_TOKEN')
```
### 4. ValueError: Asking to pad but the tokenizer does not have a padding token.
部分模型的 tokenizer 没有 padding token，因此你可以设置 padding token，或直接关闭 padding 配置：
```python
input_tokens = model.tokenizer(input_text,
return_tensors="pt",
return_attention_mask=False,
truncation=True,
max_length=MAX_LENGTH,
padding=False #<----------- turn off padding
)
```
## Citing AirLLM
If you find
AirLLM useful in your research and wish to cite it, please use the following
BibTex entry:
```
@software{airllm2023,
author = {Gavin Li},
title = {AirLLM: scaling large language models on low-end commodity computers},
url = {https://github.com/lyogavin/airllm/},
version = {0.0},
year = {2023},
}
```
## Sponsors
### 在云端运行 AI Agent 团队 — Bloome
Bloome 是一个 AI agent IM 平台：无需配置，即可在云端构建并运行 AI agent 团队。在群聊中将 skill 添加为 agent，从网页或移动端一键运行，并与团队共享——可以把它理解为一个群聊，你的 AI 助手就是队友，可以 @mention 并分配任务。
👉 试用 Bloome：https://bloome.im/login?ref=G6BYnov0
## Contribution
欢迎贡献、想法与讨论！
如果觉得有用，请给个 ⭐ 或请我喝杯咖啡！🙏
[](https://bmc.link/lyogavinQ)
