信息卡

一句话定位

一个推理优化库：不靠量化、蒸馏或剪枝，仅凭"一次只把一层模型权重搬上 GPU、其余留盘流式换入"的思路，让 70B 全精度模型在单张 4GB 显卡上完成推理，甚至宣称 DeepSeek-V3（671B）只需约 12GB、Kimi K3（2.8T）在 4GB 以内即可运行。

趋势解读：为什么火

显存墙始终是个人开发者与小型团队玩大模型的第一道门槛，主流方案都在卷量化与稀疏化，AirLLM 却换了个维度——用磁盘 IO 换显存，把不可能变成慢但可行。对离线批处理、隐私敏感本地推理等延迟不敏感场景，这种"零折损跑巨兽"的能力独一份。随着 DeepSeek 与 Kimi 级模型接连刷新参数纪录，项目价值被反复重新发现，长期保持榜单常客地位。

核心功能拆解

• 分层流式机制：任意时刻 GPU 上只驻留一层权重，显存占用取决于单层大小而非模型总规模。
• 首次推理时自动把原始模型切分为 layer shards 存盘，因此需要预留足够磁盘空间。
• Prefetching 预取让载入与计算重叠，带来约 10% 的速度增益，默认开启。
• 分块量化选项：4bit 或 8bit 仅压权重不做激活校准，因瓶颈本就在磁盘 IO 所以精度更易保住，官方称最高可再提速三倍。
• 统一 AutoModel API 兼容几乎全部主流开源系模型：Llama 全系、Qwen 1 到 3.8 含 MoE/FP8/VL、DeepSeek V2/V3/R1、Mistral 与 Mixtral、Phi、Gemma、ChatGLM、Baichuan、InternLM、Yi 及 Kimi K3。
• 硬件门槛表格化：8B 稠密约 1 至 2GB、MoE 约 1 至 3GB、Qwen3-235B 约 3GB、70B 全精度约 4GB、405B 约 8GB。

架构与技术栈浅析

实现核心是 layer-shard 化的加载器加预取流水线，配置项包括 compression（4bit/8bit/None）、profiling_mode、layer_shards_saving_path、hf_token（访问受限仓库）、prefetching 开关以及 delete_original（切分后删原件可省一半磁盘）。MacOS 仅支持 Apple Silicon 且需安装 mlx 与 torch。代码谱系源自 SimJeg 在 Kaggle 竞赛中的分层推理实践。注意 README 中并无 AGENT_MIX 这一特性。

安装与环境要求

一条命令安装：

pip install airllm

量化模式需额外安装 bitsandbytes 并要求 airllm 版本不低于 2.0。运行前确认磁盘剩余空间足以容纳切分产物，受限仓库需准备 Hugging Face token。

快速上手示例

from airllm import AutoModel

MAX_LENGTH = 128
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)

启用量化的写法是在 from_pretrained 里传 `compression='4bit'`（或 '8bit'）。

进阶使用要点

• 报 MetadataIncompleteBuffer 错基本是切层时磁盘空间不足，先清理再重试。
• QWen 与 ChatGLM 务必经 AutoModel 加载而非 AirLLMLlama2 类，否则会报 max() empty sequence。
• 遇到 gated 仓库 401 就传入 hf_token；tokenizer 报缺 padding token 时按示例设 padding=False。
• delete_original=True 可在分片完成后删除原始权重，磁盘紧张时的标准操作。

典型应用场景

• 消费级显卡离线批量翻译、摘要或打标——速度虽慢但一夜跑完全集毫无压力。
• 数据涉密的本地环境用 4bit 压缩版跑私有模型完成敏感文档处理。
• 学术实验里快速验证 70B 级模型的 zero-shot 能力而无需申请 A100。
• MoE 模型的低成本自托管推理：逐专家流式加载使 Qwen3-235B 也只要 3GB 显存。

同类生态位对比

llama.cpp 靠 GGUF 量化追求消费端速度，vLLM 用 PagedAttention 追求吞吐上限，两者都要求显存放得下目标精度模型；AirLLM 是唯一以"总量超显存的原始权重"为设计前提的主流方案，代价是 token 速率极低，因此在实时对话场景落败、在离线管线场景无可替代。

资源导航

仓库主页见 github.com/lyogavin/airllm，许可证 Apache 2.0；各模型完整支持表、硬件需求表与常见错误对照见 README 对应章节；PyPI 包名 airllm；致谢部分注明代码基础来自 SimJeg 的 Kaggle 方案，MacOS 运行依赖说明位于 README 平台小节。