GeeeekExplorer/nano-vllm · 上手攻略

  • 仓库：GeeeekExplorer/nano-vllm
  • 链接：https://github.com/GeeeekExplorer/nano-vllm
  • 分类：AI 推理 / LLM 框架 / 高性能推理引擎
  • 作者：Jay
  • 更新：2026-07-13

这是什么

nano-vllm 是一个从零实现的高效 vLLM 复刻项目，作者希望用约 1200 行干净可读的 Python 代码展示 vLLM 的核心原理。它不是 vLLM 的分支或包装，而是一个独立的精简实现，API 设计与 vLLM 保持高度兼容，同时内置了 Prefix Caching、Tensor Parallelism、Torch Compilation、CUDA Graph 等主流优化技术。

在 RTX 4070 Laptop（8GB）+ Qwen3-0.6B 的测试中，nano-vllm 吞吐量达到 1434 tokens/s，优于官方 vLLM 的 1361 tokens/s。

简单说：这是一个学习 + 备选的轻量推理引擎——想理解 vLLM 怎么工作的可以读源码，实际使用中也可以作为小场景的替代。

解决什么问题

  • vLLM 代码太重：官方 vLLM 是几十万行级别的工程量，学习门槛高。nano-vllm 用 1200 行展示核心逻辑。
  • 需要轻量推理引擎：不是所有场景都需要完整的 vLLM，小规模部署或特定实验场景下，nano-vllm 可以减少依赖和运维复杂度。
  • 教学与实验：作为 LLM 推理优化的教学材料，或用于验证新想法的快速原型。
  • 备选推理后端：在特定硬件/模型组合下，nano-vllm 可能比 vLLM 更快（参见 benchmark 数据）。

快速安装

环境要求

  • Python（项目未声明最低版本，推测 3.9+）
  • PyTorch
  • CUDA（需 GPU 支持）
  • 足够显存（实测 RTX 4070 Laptop 8GB 可跑 Qwen3-0.6B）

安装

pip install git+https://github.com/GeeeekExplorer/nano-vllm.git

下载模型权重（以 Qwen3-0.6B 为例）

需要提前安装 huggingface-cli（pip install huggingface_hub）：

huggingface-cli download --resume-download Qwen/Qwen3-0.6B \
 --local-dir ~/huggingface/Qwen3-0.6B/ \
 --local-dir-use-symlinks False

⚠️ 模型权重文件较大（Qwen3-0.6B 约数 GB），确保磁盘空间充足。国内用户建议配置 HF 镜像源。

核心用法

基础推理（example.py）

from nanovllm import LLM, SamplingParams

# 初始化模型（本地路径）
llm = LLM("/YOUR/MODEL/PATH", enforce_eager=True, tensor_parallel_size=1)

# 设置采样参数
sampling_params = SamplingParams(temperature=0.6, max_tokens=256)

# 输入 prompt
prompts = ["Hello, Nano-vLLM."]

# 推理
outputs = llm.generate(prompts, sampling_params)

# 取结果
print(outputs[0]["text"])

参数说明

参数 类型 说明
enforce_eager bool 强制不使用 CUDA graph（默认 True，调试时可开）
tensor_parallel_size int Tensor 并行数，多卡时增大（默认 1）
temperature float 采样温度，0 = 确定性（默认 1.0）
max_tokens int 最大生成 token 数
top_p float Nucleus 采样阈值（默认 1.0）

📌 API 与 vLLM 基本一致，但 llm.generate() 返回结构略有不同，结果通过 outputs[0]["text"] 取文本。

性能基准测试（bench.py）

仓库内置 benchmark 脚本，实测数据：

推理引擎 输出 Token 数 耗时 (s) 吞吐量 (tokens/s)
vLLM 133,966 98.37 1361.84
nano-vllm 133,966 93.41 1434.13

测试条件：RTX 4070 Laptop 8GB，Qwen3-0.6B，256 sequences，输入/输出各 100-1024 token 随机。

⚠️ 这是特定硬件/模型下的数据，其他组合未必优于 vLLM，实际情况请自行 benchmark。

典型适用场景

场景 说明
学习 vLLM 内部原理 1200 行可读代码，远比官方 50 万行容易消化
小规模本地推理 单卡或双卡小模型场景，依赖更少、启动更快
推理优化实验 想验证某个优化点，先在 nano-vllm 改，快速迭代
特定硬件/模型组合 在 RTX 4070 + Qwen3-0.6B 组合下，吞吐量实测更优
轻量部署 不想装整个 vLLM 生态，小项目直接 pip install 即可

坑与注意

  1. 不是 vLLM 替代品：这是一个实验性/教学性质的项目，不建议在生产环境直接替代 vLLM。vLLM 有着多年的工程打磨和广泛的社区验证。

  2. 显存需求：虽然实测 Qwen3-0.6B 能在 8GB 跑，但更大模型（如 7B 以上）需要更多显存。务必确保 GPU 显存足够，否则 OOM。

  3. 功能覆盖范围：1200 行代码无法覆盖 vLLM 的全部功能（如 continuous batching 的某些边界情况、PagedAttention 的完整实现等）。复杂需求（如大量并发、 speculative decoding）仍需 vLLM。

  4. 仅 GPU 推理：不支持 CPU 推理，必须有 NVIDIA GPU。

  5. 模型格式：仅支持 HuggingFace 格式的模型（本地路径加载），暂不支持 AWQ、GPTQ 等量化格式的直接加载（需先转换）。

  6. 国内下载模型：HuggingFace Hub 在国内可能访问受限，建议配置 HF 镜像（如 HF_ENDPOINT=https://hf-mirror.com）或使用科学上网。

  7. 版本稳定性：这是一个个人维护项目（Star 14k+），更新节奏取决于作者，API 可能随版本变化，学习使用时请注意 commit 历史。

与同类对比

维度 nano-vllm 官方 vLLM llm.c (llama.cpp) Ollama
代码量 ~1200 行 50 万+ 行 C/CUDA Go 封装
学习价值 ✅ 极高 低 中 低
生产就绪 ❌ ✅ 成熟 ✅ 成熟 ✅
功能完整度 基础推理 完整 量化优化强 一键模型
部署复杂度 低 中 中 极低
适用规模 小规模/实验 大规模生产 本地量化 全场景

nano-vllm 最大差异化：极低的理解门槛 + 与 vLLM 兼容的 API。如果你用 vLLM 但从没读过源码，nano-vllm 是理解它工作原理的最佳起点。

一句话推荐结论

想理解 vLLM 怎么实现 LLM 高效推理的、或在特定小规模场景下需要一个轻量替代，nano-vllm 值得一看；但生产级部署请继续用官方 vLLM。