## 项目概述

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。

## 安装与快速开始

**安装：**

```bash
pip install airllm
```

**快速推理：**

```python
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）：**

```bash
pip install -U bitsandbytes
```

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

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

```python
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：**

```python
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 和官方文档。