每天一个开源项目#59 AirLLM：27.6K星，3.72GB显存跑2.8T模型

每天一个开源项目#59 AirLLM：27.6K星，3.72GB显存跑2.8T模型

GitHub Trending 第 1/16 名｜快照日期：2026-08-04 ｜27,656 Stars ｜3,002 Forks ｜主语言：Jupyter Notebook ｜许可证：Apache-2.0

项目地址：github.com/lyogavin/ai...

📋 项目概览

项目	信息
项目名	AirLLM
一句话定位	把大模型权重按层、对稀疏 MoE 按专家从磁盘流式送入 GPU，以极低显存完成超大模型推理
GitHub Trending	今日第 1 名，共抓取 16 个项目
Stars / Forks	27,656 / 3,002（2026-08-04 Trending 快照）
Open Issues	GitHub open_issues_count 为 123；拆分后为 94 个 Issue、29 个 PR
Watchers	261（同日 API 补充核验）
主语言	Jupyter Notebook 95.7%、Python 4.2%、Shell 0.1%
License	Apache-2.0
最新版本	v3.1.0，2026-07-29 发布
仓库规模	审计检出 88 个非 Git 文件、34 个 Python 文件，约 5,350 行非空非注释 Python 代码
核心亮点	README 报告 Kimi K3 2.8T 在 RTX 6000 Ada 上端到端峰值显存 3.72GB

🔥 为什么值得关注

大模型本地推理通常有一个看似不可跨越的前提：模型权重必须整体装进显存，或者至少装进"显存 + 内存"。AirLLM 选择改变这个前提------不让全部权重同时驻留 GPU 。它先把 Hugging Face checkpoint 拆成模块级 Safetensors 分片，创建一份参数位于 meta 设备的空壳模型，然后借助 PyTorch forward hook，在每层执行前加载权重、执行后立即释放。于是，显存需求更接近"最大单层权重 + KV Cache + 激活值"，而不是"整个模型权重"。

v3.1.0 又把这一思路推进到稀疏 MoE 的专家粒度。以 Kimi K3 为例，源码注释显示每层拥有 896 个专家 、每个 token 路由到 16 个专家。完整展开一层专家约需 55GB，而单个 token 实际触达的专家约 1GB。AirLLM 利用 Safetensors 可按 tensor 随机读取的特点，只物化被路由命中的专家，因此把 README 所称的端到端峰值显存压到 3.72GB。

但必须看清它解决的是容量问题，而不是吞吐问题。Dense 模型每生成一个 token，仍需依次读取所有层；磁盘带宽和 PCIe 传输会成为主瓶颈。2.8T 模型"能跑"也不等于下载轻松、响应迅速或适合在线服务：完整 checkpoint 仍可能达到 TB 级，首次拆分需要大量磁盘空间，KV Cache 也会随上下文增长。AirLLM 最有价值的场景是低频实验、模型兼容性验证和"用小显存访问大权重"，不是替代 vLLM 这类高吞吐推理引擎。

🏗️ 核心特性

1. 权重按层流式加载，显存上限与模型总参数量解耦

AirLLM 在 AirLLMBaseModel 中通过 accelerate.init_empty_weights() 创建 meta 模型。真实权重只在模块执行前进入 GPU：

磁盘上的分层权重
      │
      ▼
forward_pre_hook ── 加载当前层到 CPU/GPU
      │
      ▼
Transformers 原生 forward / generate
      │
      ▼
forward_hook ────── 参数迁回 meta，释放显存

源码实际注册了前后向 hook，并在结束后调用 set_module_tensor_to_device(..., "meta") 或 module.to("meta")。因此这不是简单的 Hugging Face device_map="auto"：后者通常让各层长期驻留在 GPU、CPU 或磁盘映射区，而 AirLLM 会在每次前向过程中反复装入和驱逐模块。

可用下面的近似式理解显存开销：

峰值显存 ≈ max(当前层权重, 当前命中专家权重)
         + KV Cache
         + 激活值与临时算子空间
         + 常驻模块

这里的"≈"很重要：上下文长度、batch size、注意力实现、量化格式和 CUDA kernel 临时空间都会改变实际峰值，不能只依据模型参数量推算。

2. Kimi K3 的按专家流式机制

Kimi K3 不是普通 Dense Transformer。AirLLM 为其提供了专用 AirLLMKimiK3 布局描述：

• 解码器路径位于 language_model.model.layers；
• 专家路径位于 block_sparse_moe.experts；
• Vision Tower、MM Projector 和两个 Attention Residual 模块不参与逐层流式，而是常驻；
• 通过 Safetensors 的 get_tensor(key) 只读取选中专家的 tensor；
• 每个专家前后分别挂载 hook，执行后立即把对应参数放回 meta。

Token / Token Batch
       │
       ▼
非专家部分：Norm + Attention + Router
       │
       ├── 路由命中 Expert 7  ── 读取该专家 tensor ── 执行 ── 释放
       ├── 路由命中 Expert 31 ── 读取该专家 tensor ── 执行 ── 释放
       ├── ...
       └── 路由命中最多若干专家
       │
       ▼
下一层

单 token 的理论选择是 16/896，但 batch 或多个 token 可能命中更多不同专家，所以"约 1GB 专家权重"不能机械套用到任意批量和上下文配置。源码的优化边界是"只读取实际调用的专家模块"，不是承诺任意负载下都维持 3.72GB。

3. 预取把磁盘 I/O 与当前层计算重叠

默认开启的单线程 ThreadPoolExecutor 会在当前层计算时提前读取下一层。README 给出的历史说法是约 10% 提速，但仓库未提供当前硬件、模型、batch 和存储介质下的完整可复现实验表，因此应把它视为维护者报告，而非通用性能保证。

预取也有两条源码级限制：

1. 开启 4bit/8bit compression 时，预取会被自动关闭；
2. 单层超过 2GB 时不使用 pinned memory，避免两个在途 MoE 层锁住数十 GB 主机内存。

这说明 AirLLM 的优化目标不是"无条件最快"，而是在磁盘、内存、PCIe 和 GPU 显存之间做可运行性优先的资源调度。

4. 面向存储瓶颈的 4bit / 8bit 压缩

AirLLM 的 compression="4bit" 或 "8bit" 主要压缩磁盘分片里的权重。运行时再解压到 GPU，因此它与"权重和激活都使用低比特 kernel 计算"的传统量化方案不同：

方案	主要目标	磁盘读取量	计算权重形态	AirLLM 中的意义
无压缩流式	最少精度改动	大	模型原生 dtype	简单，但 I/O 最重
AirLLM 4bit/8bit 分片	降低磁盘 I/O	小	加载后解压	针对 I/O 瓶颈，需 bitsandbytes
端到端低比特量化	降显存并加速矩阵计算	小	低比特 kernel	依赖硬件、算子和量化方案

README 宣称压缩最高可带来 3 倍运行时提升、精度损失很小；仓库测试仅对随机 tensor 做 RMSE 小于 0.1 的结构性检查，并不能替代模型级任务精度评估。生产选型应在自己的模型、提示集和硬件上复测。

5. 兼容 FP8、MXFP4 与新旧 Transformers

v3.x 源码不仅"搬运 tensor"，还处理了多个现实兼容问题：

• 普通高精度 tensor 才转换到运行 dtype，FP8、packed 4bit、scale、zero point 等保持原始类型；
• MXFP4 packed payload 先以压缩字节跨 PCIe，再在 GPU 侧展开，减少传输量；
• 优先使用 Transformers 原生模型实现，无法识别时才启用 trust_remote_code=True；
• 为 Transformers 5.x 中移动或移除的符号提供兼容层；
• 对模型配置与 checkpoint 参数 shape 不一致的 meta 参数，以 checkpoint shape 为准；
• 对缺少 GenerationMixin 的旧模型类动态恢复 generate() 能力。

这些工程细节解释了 AirLLM 的技术深度：真正困难的不只是"按层读取"，而是让不同架构、分片格式、量化元数据与生成 API 在动态装卸参数时仍能正确协作。

🔬 技术架构深度解析

整体数据路径

Hugging Face Repo / 本地 Checkpoint
                 │
                 ▼
      下载 config、tokenizer、权重索引
                 │
                 ▼
  split_and_save_layers / 分片直通优化
       │                     │
       │ 普通多层 shard      │ 已是一模块一 shard
       ▼                     ▼
重写为模块级 Safetensors    hardlink → symlink → copy
       └──────────┬──────────┘
                  ▼
        Meta Device 空壳模型
                  │
                  ▼
 embed → layer 0 → layer 1 → ... → norm → lm_head
   ▲        ▲          ▲                    ▲
   └── hook 按需加载 / 执行后驱逐 ──────────┘
                  │
                  ▼
        Transformers generate() + KV Cache

为什么不直接复制 Kimi K3 的 1.5TB+ 权重

Kimi K3 checkpoint 已接近"一层一个 Safetensors shard"。若再次拆分，会重复占用 README/测试注释所指的 1.5TB+ 存储。split_and_save_layers() 会检查某个原始 shard 是否只包含一个模块：若是，优先创建硬链接；跨文件系统失败再尝试软链接，最后才复制。结构测试还会比较 inode，确保单模块 shard 没有被复制。

这是一个关键但容易忽略的优化：显存可以只有几 GB，但完整模型文件仍必须存在于本地或可按需下载。AirLLM 降低的是"瞬时设备驻留"，并没有把 2.8T 参数凭空变小。

Dense 与 Sparse MoE 的成本差异

维度	Dense 模型按层流式	Sparse MoE 按专家流式
每层需要的权重	基本是完整层	非专家部分 + 路由命中的专家子集
磁盘访问频率	每 token × 每层	每 token × 每层 × 命中专家集合
显存节省来源	一次只驻留一层	一次只驻留一层中的少数专家
潜在瓶颈	SSD 顺序/随机读、PCIe	更细粒度随机读、专家切换开销
更适合	低频离线验证	专家稀疏度高、能接受延迟的超大 MoE 实验

AirLLM 本质上把"显存容量约束"换成"存储带宽和延迟约束"。如果 NVMe 实际持续读取速度是数 GB/s，而每个 token 要搬运几十 GB 权重，那么生成速度自然会远低于权重常驻 GPU 的方案。仓库没有发布 K3 的 tokens/s，因此不能从 3.72GB 显存数字推导交互体验。

源码与测试审计

本次对 main 分支提交 64a4e4fc（v3.1.0）做了浅克隆审计：

• 运行时代码中心是 airllm_base.py（约 568 行非空非注释代码）和 utils.py（约 384 行）；
• Kimi K3 专用类只有布局映射，核心逻辑复用通用 base；
• 仓库包含 4 个 Python 测试模块及多个 Notebook 测试；
• Kimi 结构测试覆盖模块完整性、硬链接而非复制、共享 shard 拆分、bit-for-bit round trip 和 packed uint8 dtype 保留；
• python -m compileall 通过；当前审计机未安装 PyTorch，单元测试因此未能执行，本文不把源码测试存在等同于本次独立运行通过；
• GPU 端到端 harness 支持 --compare 与完整加载模型进行贪心输出序列比对，并报告峰值显存，但它属于手动 GPU 测试，不是轻量 CI 证据。

📖 README 核心内容摘要

README 给出的能力范围

模型	README 报告的显存	说明
约 8B 的 Qwen3 / Mistral / Phi	约 1--2GB	维护者汇总值，未附统一 benchmark 环境
30--47B MoE	约 1--3GB	依赖层/专家尺寸与量化格式
Qwen3-235B MoE	约 3GB	v3.0 新支持
Llama 3.x 70B 全精度	约 4GB	经典卖点：不量化也可运行
Llama 3.1 405B	约 8GB	2024 年加入
DeepSeek-V3 671B	约 12GB	FP8 支持路径
Kimi K3 2.8T	3.72GB	README 指定 RTX 6000 Ada 端到端测量

这些数字来自项目 README，不是本文独立硬件复现；不同上下文长度、batch、软件版本和注意力实现会改变结果。

设计哲学

1. 保留模型本身：默认不蒸馏、不剪枝、不改模型结构；
2. 把容量换成时间：允许权重停留在磁盘，按执行顺序进入 GPU；
3. 复用 Transformers：前向和生成逻辑交给原生模型类，AirLLM 聚焦参数生命周期；
4. 用 AutoModel 收敛接口：标准 CausalLM 走通用 base，特殊布局通过小型 override 映射；
5. 显式暴露资源旋钮：分片目录、压缩、预取、HF Token、删除原始 checkpoint 均可配置。

必须注意的 README 边界

• 首次运行会先下载并处理完整模型，磁盘空间往往比显存更难满足；
• delete_original=True 可以边拆分边删除原 shard，但属于不可逆磁盘操作，使用前应确认缓存不再被其他程序共享；
• Kimi K3 需要 compressed-tensors、flash-attn、CUDA 12 对应的 PyTorch，以及 README 指定的 Transformers 4.56.x 兼容组合；
• setup.py 的通用依赖范围是 transformers>=4.49,<5.13，这不代表 K3 在整个范围内都可用，应以 K3 专用版本说明为准；
• macOS 路径要求 Apple Silicon、MLX 与 PyTorch；README 的超大 K3 指标来自 NVIDIA RTX 6000 Ada，不能直接外推到 Mac。

🚀 快速上手

1. 安装

建议创建隔离环境，并先从中小模型验证工作流：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install airllm

如启用 AirLLM 自己的磁盘分片压缩，再安装：

python -m pip install -U bitsandbytes

2. 最小推理示例

from airllm import AutoModel

model = AutoModel.from_pretrained(
    "Qwen/Qwen3-32B",
    layer_shards_saving_path="/path/to/large-fast-disk/airllm-shards",
    prefetching=True,
)

inputs = model.tokenizer(
    ["请用三句话解释什么是磁盘流式推理。"],
    return_tensors="pt",
    return_attention_mask=False,
    truncation=True,
    max_length=128,
    padding=False,
)

result = model.generate(
    inputs["input_ids"].cuda(),
    max_new_tokens=64,
    use_cache=True,
    return_dict_in_generate=True,
)

print(model.tokenizer.decode(result.sequences[0]))

3. 低磁盘空间模式

model = AutoModel.from_pretrained(
    "Qwen/Qwen3-32B",
    compression="4bit",
    delete_original=True,
)

注意：delete_original=True 会删除原始 checkpoint；4bit/8bit 压缩目前会自动关闭预取。第一次尝试应保留原文件，确认分片、模型输出和磁盘路径无误后再启用删除。

4. 推荐验证顺序

TinyLlama / 1B 级模型
    → 用 --compare 验证输出一致性
    → 7B/8B 验证显存与磁盘吞吐
    → 目标大模型小上下文测试
    → 再逐步提高 max_new_tokens、上下文和 batch

不要从 2.8T 模型开始"试安装"。对绝大多数个人开发者，下载时间、TB 级存储、依赖编译和端到端延迟会先于显存成为阻碍。

📊 增长速度与社区热度

关键数据

指标	数值	解读
Trending 排名	1 / 16	当日榜首
Stars	27,656	以预运行 Trending 快照为准
Forks	3,002	Fork / Star 约 10.85%，二次实验意愿较强
Open Issues	94	从 GitHub Search API 拆分，不含 PR
Open PRs	29	说明 123 个 open items 中约四分之一为 PR
Closed Issues	145	历史问题有一定消化量
Merged PRs	13	外部合并规模不算大
Watchers	261	有持续关注者，但不是大规模组织项目
贡献者结构	第一贡献者 290 次提交，其他公开贡献者多为个位数	维护明显集中，存在核心维护者风险
最新 Release	v3.1.0，2026-07-29	Kimi K3 支持发布后 6 天登顶 Trending

仓库创建于 2023-06-12，到快照日约 1,148.31 天；按 27,656 Stars 计算，全生命周期平均约 24.08 Stars/天。这个数字只是长期基线，不能代表近期速度。预运行快照未保留"今日新增 Stars"，因此本文不虚构日增量。稍后的同日 API 核验为 27,658 Stars，只能说明两个观测点之间增加 2 Stars，不能称为"今日增长 2 Stars"。

从时间线看，v3.0 在 2026 年 6 月加入 FP8、DeepSeek-V3 与 Qwen3-235B，v3.1.0 在 7 月 29 日加入 Kimi K3；当日登顶更可能是重大模型兼容事件带来的事件驱动增长，而不是仓库年龄所能解释的自然增长。浅克隆保留的最近 135 次提交中，2026 年 6 月有 13 次、7 月有 25 次，显示新版发布前后开发活跃度明显回升；不过其中多次为自动刷新 Star History 图，不能把全部提交都视为核心功能开发。

今日完整 Trending 榜单

排名	仓库	排名	仓库
1	lyogavin/airllm	9	antirez/ds4
2	zhaoxuya520/reverse-skill	10	shiyu-coder/Kronos
3	firecrawl/pdf-inspector	11	Panniantong/Agent-Reach
4	esengine/DeepSeek-Reasonix	12	Alishahryar1/free-claude-code
5	TencentCloud/TencentDB-Agent-Memory	13	iv-org/invidious
6	microsoft/AI-For-Beginners	14	livekit/agents
7	microsoft/generative-ai-for-beginners	15	usekaneo/kaneo
8	donnemartin/system-design-primer	16	jamiepine/voicebox

🎯 适用场景

场景	推荐度	原因与边界
小显存验证超大模型能否正确加载和生成	⭐⭐⭐⭐⭐	这是 AirLLM 的核心价值，重点是"能运行"
研究 MoE 路由与专家级权重流式	⭐⭐⭐⭐⭐	Kimi K3 路径展示了 tensor 级随机访问与 hook 生命周期
离线、低频、可容忍高延迟的文本生成	⭐⭐⭐⭐	容量收益明显，但需高速 NVMe 和充足磁盘
比较模型输出、做兼容性回归	⭐⭐⭐⭐	GPU harness 可与完整加载模型做贪心序列对比
Apple Silicon 上尝试较大 Llama 类模型	⭐⭐⭐	有 MLX 路径，但支持边界需按模型验证
实时聊天机器人	⭐⭐	每 token 反复加载权重，首选常驻式量化模型
高并发在线推理服务	⭐	缺少 continuous batching、PagedAttention 等吞吐优化
没有 TB 级磁盘却想跑 2.8T 模型	不推荐	显存降低不等于模型文件消失

💡 总结

AirLLM 的真正创新不是一句"4GB 显存跑大模型"，而是对参数生命周期的重新编排：模型结构留给 Transformers，权重驻留交给 hook 和 Safetensors；Dense 模型按层流式，Sparse MoE 再细化到按专家流式。 这让 GPU 显存从"必须容纳整个模型"变成"只容纳当前计算工作集"。

它同时也展示了系统工程中典型的资源交换：显存省下来了，代价转移到模型下载、磁盘容量、随机读取、PCIe 传输和生成延迟。3.72GB 跑 Kimi K3 是一个极具冲击力的可行性证明，但不是低成本、高吞吐部署方案。若你的目标是研究超大模型结构、验证兼容性或突破显存门槛，AirLLM 值得深入；若目标是生产服务，应把它与量化常驻、张量并行、专家并行和 vLLM 等方案按吞吐、延迟、存储和运维成本综合比较。