lyogavin/airllm · 上手攻略

• 仓库：lyogavin/airllm
• 链接：https://github.com/lyogavin/airllm
• 分类：ai
• 作者：Tom
• 更新：2026-07-08

这是什么

AirLLM 是一个开源 Python 库，实现了一种层间加载（layer-wise）推理技术，让超大语言模型在显存极小的 GPU（甚至只有 4GB VRAM 的卡）上运行推理，无需量化、无需蒸馏、无需剪枝。

核心技术原理：用单层加载替代全量加载。传统推理需要把 130GB 的 70B 模型一股脑塞进显存；AirLLM 把模型按 transformer 层拆开，一次只在显存里放一层，算完结果后卸载，再加载下一层。这样显存需求从"全模型大小"变成"单层大小"，70B 模型的单层约 1.6GB，所以 4GB 显存的卡也能跑。

AirLLM v3.0（2026-06）新增 FP8 模型支持，并支持 DeepSeek-V3（671B）在约 12GB 显存运行、Qwen3-235B 在约 3GB 显存运行。

解决什么问题

运行 70B 以上的大模型，长期是"需要 A100/H100"的专利。AirLLM 打破了这个壁垒：

• 个人开发者：没有高端 GPU 的工程师，想本地跑大模型做实验
• 边缘部署：想在消费级机器上跑推理服务
• 成本敏感场景：不想为了一次实验性推理去云端租 H100
• 内存优化研究：学术界研究 layer-wise 推理的应用层

一句话：让"玩大模型"这件事，去掉了"必须买高端 GPU"的门槛。

快速安装

pip install airllm

⚠️ v3.0（2026-06）引入了大量新模型支持和 FP8，建议用最新版本：pip install -U airllm

可选：安装 bitsandbytes（用于量化加速）

pip install -U bitsandbytes

可选：Apple Silicon Mac 支持（需 mlx 和 torch）

# 仅支持 Apple silicon（M1/M2/M3/M4）
pip install airllm
# 然后参考 README 中 MacOS 专节

核心用法

最简示例（AutoModel，一行代码）

from airllm import AutoModel

MAX_LENGTH = 128

# 任何 Hugging Face 模型 ID，一行搞定
model = AutoModel.from_pretrained("Qwen/Qwen3-32B")

input_text = ['What is the capital of United States?']

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)

不同规模模型的显存需求（官方参考值）

⚠️ 实际显存需求因序列长度、batch size、模型变体有所浮动，上表为参考值，实测更准确。

量化加速（可选，3x 提速）

AirLLM v2.0+ 支持块级量化（block-wise quantization），可获得约 3 倍推理加速，几乎不影响精度：

from airllm import AutoModel

# 4bit 或 8bit 量化
model = AutoModel.from_pretrained(
    "garage-bAInd/Platypus2-70B-instruct",
    compression='4bit'  # 或 '8bit'
)

量化的原理：只量化权重（weight）部分，不量化激活（activation），因为 AirLLM 的瓶颈是磁盘加载而非计算，故只压权重体积即可保精度。

私有/本地模型路径

model = AutoModel.from_pretrained(
    "/home/ubuntu/.cache/huggingface/hub/models--Qwen--Qwen3-32B/snapshots/..."
)

Gated 模型（HuggingFace 需登录）

model = AutoModel.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    hf_token='YOUR_HF_TOKEN'  # 提供 HuggingFace API token
)

分层分片存储路径（节省默认缓存空间）

model = AutoModel.from_pretrained(
    "Qwen/Qwen3-32B",
    layer_shards_saving_path="/path/to/custom/storage"
)

推理过程中原始模型会被分拆并按层存储，首次运行会消耗较多磁盘空间，请确保 HuggingFace 缓存目录有足够空间。

MacOS 推理

# 确保安装了 mlx
# pip install mlx torch
# 仅 Apple Silicon
# 参考: air_llm/examples/run_on_macos.ipynb

核心原理（了解有助于避坑）

传统 LLM 推理的显存瓶颈： - 模型权重：130GB（70B 模型，FP16） - KV Cache：随序列长度线性增长 - activations：与 batch size、序列长度相关

AirLLM 的层间加载技术（layer-wise inference）： 1. 预处理阶段：将模型按 transformer 层拆分为独立的 shard 文件 2. 推理阶段：每次只把一层加载到 GPU，计算 attention，卸载 3. 循环直到所有层处理完毕

这意味着显存需求 ≈ 单层参数量，而非全量参数量。单层通常只有全模型的 1/80（以 70B / 80 层为例）。

典型适用场景

1. 本地实验和小规模推理

没有云端 A100，用 RTX 3060（12GB）或 Tesla T4（16GB）跑 70B 模型做实验。

2. 内存受限的边缘部署

在工作站、服务器集群上通过内存换显存的方式部署大模型。

3. 大模型评测流水线

用 vLLM / Text-generation-inference 以外的轻量方案跑基准测试。

4. Mac 本地推理（M 系列芯片）

开发者用 Mac M1/M2/M3 在本地跑 70B 模型做日常开发辅助（需 mlx）。

坑与注意

1. 磁盘空间是第二瓶颈：首次运行会把模型按层分片存到磁盘（HuggingFace 缓存目录），70B 模型可能需要 150GB+ 磁盘空间。如果出现 SafetensorError: MetadataIncompleteBuffer，大概率是磁盘空间不足。

2. 首轮加载慢：因为需要把模型逐层拆分并存储到磁盘，首次运行会比正常推理慢很多（预处理开销）。后续推理会复用这些分片文件。

3. HuggingFace 缓存清理问题：如果磁盘紧张，可以设 delete_original=True 删除原始模型文件，只保留分片（节省约一半磁盘空间）。

4. 部分模型的 tokenizer 没有 padding token：调用 tokenizer 时如果报错，需要设 padding=False。

5. AutoModel 会自动检测模型类型：但某些情况下仍需手动指定模型类（如早期版本用 AirLLMLlama2）；当前版本推荐统一用 AutoModel。

6. 序列长度受限于系统内存：虽然 GPU 显存需求低，但 CPU 内存（处理长序列）仍然需要足够容量。

7. Apple Silicon 仅部分模型支持：Mac 版支持情况与 mlx 库绑定，非所有模型均可在 Mac 上运行。

8. 不支持多 GPU 分片：AirLLM 专注于单卡层间加载，多卡并行场景建议用 vLLM 等方案。

与同类对比

核心差异：AirLLM 是唯一一个在不量化权重的前提下，让普通显卡跑 70B 的方案。它的意义不是"最快的方案"，而是"门槛最低的方案"。

一句话推荐结论

如果你只有一张消费级 GPU（4–8GB VRAM），又想在本地跑 70B 以上的大模型做实验或推理，AirLLM 是目前最简单、无需量化调参的直接解；如果追求极致速度或需要多卡并行，vLLM / llama.cpp 仍是首选。