GitShelf — GitHub 项目目录

项目概述

AirLLM 是一个开源的大语言模型推理引擎，其核心创新在于采用分层流式加载（layer-wise streaming）技术，每次仅将模型的一层加载到 GPU 上，从而大幅降低显存占用。该项目使得 70B 参数的大语言模型可以在单张 4GB 显存的 GPU 上运行，甚至能够运行 671B 的 DeepSeek-V3 和 2.8T 的 Kimi K3 等超大规模模型，整个过程无需量化、蒸馏或剪枝。

核心功能

极小显存运行超大模型：通过分层流式加载，让 70B 模型在 4GB 显存、405B 模型在 8GB 显存、671B DeepSeek-V3 在 12GB 显存、2.8T Kimi K3 在 4GB 显存下运行。
广泛的模型支持：支持 Llama 2/3/3.1/3.3/4、Qwen 1/2/2.5/3/3.5/3.8、DeepSeek V2/V3/R1、Mistral、Mixtral、Phi、Gemma、ChatGLM、Baichuan、InternLM、Yi 等几乎所有主流开源模型。
AutoModel 自动检测：通过 AutoModel.from_pretrained() 自动识别模型类型，无需手动指定模型类。
模型压缩加速：支持 4bit/8bit 块级量化压缩，可将推理速度提升最多 3 倍，且精度损失极小。
CPU 推理与 MacOS 支持：支持在 CPU 上运行，并支持 Apple Silicon Mac 上的本地推理。
FP8 模型支持：支持 FP8 格式模型，进一步降低显存和带宽需求。

适用与不适用场景

适用场景：

显存受限的环境（如单张 4GB/8GB 消费级显卡）下运行 70B 及以上级别的大模型。
需要快速体验、测试或部署大型开源语言模型的研究人员和开发者。
在 MacOS（Apple Silicon）上本地运行大模型。

不适用场景：

对推理速度要求极高的生产环境，因为分层流式加载可能比全模型常驻显存的方式慢。
需要高吞吐量并发服务的场景，磁盘 I/O 可能成为瓶颈。
对精度要求极高且无法接受任何精度损失的任务（尽管量化损失较小）。

技术架构与依赖

技术原理：采用分层流式加载（layer-wise streaming），模型权重按层分割，每次仅将当前计算所需的一层加载到 GPU，减少显存峰值。对于 MoE（混合专家）模型，进一步实现按专家（expert）粒度流式加载，只加载当前 token 路由到的专家。
主要依赖：Python、PyTorch、transformers、safetensors、bitsandbytes（用于模型压缩加速）、mlx（用于 MacOS 支持）。
模型压缩：基于块级量化（block-wise quantization）的模型压缩技术，参考论文 arXiv:2212.09720。
许可证：Apache-2.0。

安装与快速开始

安装：

pip install airllm

快速推理：

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)

首次运行时会将模型分解并分块保存，请确保 Hugging Face 缓存目录有足够的磁盘空间。

典型使用方法

使用模型压缩加速（需 bitsandbytes）：

pip install -U bitsandbytes

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

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

from airllm import AutoModel
MAX_LENGTH = 128
# ChatGLM
model = AutoModel.from_pretrained("THUDM/chatglm3-6b-base")
# QWen
# model = AutoModel.from_pretrained("Qwen/Qwen-7B")
# Baichuan
# model = AutoModel.from_pretrained("baichuan-inc/Baichuan2-7B-Base")
# Mistral
# model = AutoModel.from_pretrained("mistralai/Mistral-7B-Instruct-v0.1")

加载受限模型时需要提供 Hugging Face token：

model = AutoModel.from_pretrained("meta-llama/Llama-2-7b-hf", hf_token='HF_API_TOKEN')

配置与部署要点

模型初始化配置参数：

compression：模型压缩选项，可选 '4bit' 或 '8bit'，默认 None。
profiling_mode：是否输出时间消耗，默认 False。
layer_shards_saving_path：自定义分块模型保存路径。
hf_token：下载受限模型时提供的 Hugging Face token。
prefetching：预取机制，将模型加载与计算重叠以加速，默认开启。
delete_original：磁盘不足时可设为 True，删除原始下载模型以节省空间。

部署要点：

确保有足够的磁盘空间用于模型分块保存，建议至少为模型原始大小的两倍。
对于 MacOS，需安装 mlx 和 torch，且仅支持 Apple Silicon。
对于 Kimi K3 等特殊模型，可能需要特定的 transformers 版本或 CUDA 构建。

限制、风险与许可证

已知限制与风险：

首次运行需要将模型分解并保存，磁盘消耗较大，可能导致 MetadataIncompleteBuffer 错误。
某些模型的 tokenizer 可能没有 padding token，需要关闭 padding 或手动设置。
部分模型是 gated 模型，需要 Hugging Face token。
macOS 上需要安装原生 Python 以避免兼容性问题。
推理速度可能受磁盘 I/O 影响，在高速 SSD 上表现更好。

许可证：

代码基于 Apache-2.0 许可，详见仓库 LICENSE 文件。

官方链接

GitHub 仓库：https://github.com/lyogavin/airllm
PyPI 包：https://pypi.org/project/airllm/（示例徽章）
最新版本（v3.3.0）：https://github.com/lyogavin/airllm/releases/tag/v3.3.0
作者博客：https://gavinliblog.com
Discord 社区：https://discord.gg/2xffU5sn

信息来源和分析时间

仓库信息获取自 GitHub 公开仓库 lyogavin/airllm，分析时间基于仓库最新 Release（v3.3.0）的发布时间（2026-08-28）。
更多模型支持列表、示例和性能数据请参考仓库 README 和官方文档。

项目概览