lyogavin--airllm/README.md at main

wehub/lyogavin--airllm

Fork 0

Files

T

wehub-resource-sync f715cdee49 docs: make Chinese README the default

2026-07-13 10:36:47 +00:00

15 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

快速开始 | 配置项 | MacOS | 示例笔记本 | 常见问题

AirLLM 可大幅降低推理内存占用，使 70B 大语言模型能在单张 4GB GPU 显卡上运行——无需量化、蒸馏或剪枝。你甚至可以在 8GB 上运行 405B Llama 3.1，在 约 12GB 上运行 DeepSeek-V3（671B）。

AI 智能体推荐：

更新日志

[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（示例笔记本). 支持 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 历史

快速开始

1. 安装包

首先，安装 airllm 的 pip 包。

pip install airllm

2. 推理

然后，初始化 AirLLMLlama2，传入所用模型的 huggingface 仓库 ID 或本地路径，即可像常规 transformer 模型一样进行推理。

（你也可以在初始化 AirLLMLlama2 时通过 layer_shards_saving_path 指定保存按层切分后模型的路径。

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 倍，且精度损失几乎可忽略！（更多性能评估以及我们为何使用块级量化，请参阅本文)

如何启用模型压缩加速：

步骤 1. 确保已安装 bitsandbytes，通过 pip install -U bitsandbytes
步骤 2. 确保 airllm 版本高于 2.0.0：pip install -U airllm
步骤 3. 初始化模型时传入 compression 参数（'4bit' 或 '8bit'）：

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 上一样运行代码。详见快速开始。

请确保已安装 mlx 和 torch
你可能需要安装原生 Python，详见此处
仅支持 Apple silicon

示例 [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：

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：

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 等：

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])

申请支持其他模型：此处

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, Kaggle 上的代码, 相关讨论.

FAQ

1. MetadataIncompleteBuffer

safetensors_rust.SafetensorError: Error while deserializing header: MetadataIncompleteBuffer

若遇到此错误，最可能的原因是磁盘空间不足。拆分模型的过程非常消耗磁盘空间。参见此说明. 你可能需要扩容磁盘、清理 huggingface .cache 后重新运行。

2. ValueError: max() arg is an empty sequence

很可能是你用 Llama2 类加载了 QWen 或 ChatGLM 模型。请尝试以下方式：

对于 QWen 模型：

from airllm import AutoModel #<----- instead of AirLLMLlama2
AutoModel.from_pretrained(...)

对于 ChatGLM 模型：

from airllm import AutoModel #<----- instead of AirLLMLlama2
AutoModel.from_pretrained(...)

3. 401 Client Error....Repo model ... is gated.

部分模型为受限（gated）模型，需要 huggingface api token。你可以提供 hf_token：

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 配置：

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},
}

Contribution

欢迎贡献、想法与讨论！

如果觉得有用，请给个 ⭐ 或请我喝杯咖啡！🙏

15 KiB

Raw Permalink Blame History

AI 智能体推荐：

更新日志

Star 历史

目录

快速开始

1. 安装包

2. 推理

模型压缩 - 推理加速 3 倍！

如何启用模型压缩加速：

模型压缩与量化有何不同？

配置项

MacOS

Example Python Notebook

其他模型示例（ChatGLM、QWen、Baichuan、Mistral 等）：

申请支持其他模型：此处

Supported Models

小显存，大模型

Acknowledgement

FAQ

1. MetadataIncompleteBuffer

2. ValueError: max() arg is an empty sequence

3. 401 Client Error....Repo model ... is gated.

4. ValueError: Asking to pad but the tokenizer does not have a padding token.

Citing AirLLM

Sponsors

在云端运行 AI Agent 团队 — Bloome

Contribution

15 KiB Raw Permalink Blame History Unescape Escape

AI 智能体推荐：

更新日志

Star 历史

目录

快速开始

1. 安装包

2. 推理

模型压缩 - 推理加速 3 倍！

如何启用模型压缩加速：

模型压缩与量化有何不同？

配置项

MacOS

Example Python Notebook

其他模型示例（ChatGLM、QWen、Baichuan、Mistral 等）：

申请支持其他模型：此处

Supported Models

小显存，大模型

Acknowledgement

FAQ

1. MetadataIncompleteBuffer

2. ValueError: max() arg is an empty sequence

3. 401 Client Error....Repo model ... is gated.

4. ValueError: Asking to pad but the tokenizer does not have a padding token.

Citing AirLLM

Sponsors

在云端运行 AI Agent 团队 — Bloome

Contribution

15 KiB

Raw Permalink Blame History