MinivLLM

用最小代码读懂 vLLM 推理内核

MinivLLM 是一个基于 Nano-vLLM 的教学型推理引擎，用 Python 从零复现 vLLM 的核心机制，目标是让开发者用最小代码量读懂大模型推理服务的关键设计。它不依赖 vLLM 官方实现，自己实现了 PagedAttention 与 FlashAttention，把 KV Cache 分页管理、连续批处理、注意力计算等环节拆成可读代码，解决“vLLM 源码庞大、难以入门”的问题。核心能力包括：分页注意力显存管理，减少碎片并提升吞吐；自包含的 FlashAttention 前向实现，便于对照原理；轻量调度与批处理流程，可跑通小模型推理。适合想深入理解推理引擎内部、做二次实验或教学演示的场景，而不是直接替代生产级 vLLM。

开源 free 基础设施

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1037

维护状态较活跃

是否开源是

定价模式 free

项目数据

分类基础设施

开发团队Wenyueh

所属国家

官网地址

GitHubhttps://github.com/Wenyueh/MinivLLM

定价模式free

价格说明开源免费，需自行部署

访问状态

是否开源是

开源协议Apache-2.0

主要语言Python

技术栈/模型

GitHub 星标★ 1037

30天Star增速

HF 下载量

上线时间2025-12-29 00:00:00

最近更新2026-09-18 00:00:00

维护状态较活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-09-16

浏览次数0

使用教程

难度：入门约 10 分钟部署方式：本地安装 5 步

环境要求

Python 环境（项目为 Python 编写，README 未指定具体版本）
uv 包管理器（README 通过官方脚本安装）
可运行 PyTorch 的机器；README 提到多 GPU 时可调整 world_size
网络可访问 astral.sh 以下载 uv 安装脚本

安装与启动步骤

1安装 uv 包管理器

README 指定用 uv 管理依赖，先通过官方脚本安装，安装后新开终端使 uv 命令生效。
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2同步项目依赖

在项目根目录执行 uv sync，按锁文件创建虚拟环境并安装全部依赖。
```
uv sync
```
3运行主推理引擎

执行 main.py 跑通完整推理流程：小尺寸 Qwen3 随机初始化 + 60 条对话提示 + 分页注意力解码。
```
uv run python main.py
```
4运行预填充基准

执行 benchmark_prefilling.py，测试 FlashAttention 在预填充阶段的表现。
```
uv run python benchmark_prefilling.py
```
5运行解码基准

执行 benchmark_decoding.py，测试 PagedAttention 在解码阶段的表现。
```
uv run python benchmark_decoding.py
```

关键配置

配置项	必填	说明	示例
`world_size`	否	在 main.py 的 config 中设置多 GPU 并行数量，大于 1 即多卡	`2`

如何确认成功

执行 uv run python main.py 后终端正常打印推理输出、无报错退出，即说明引擎启动成功。

常见问题

Q：如何启用多 GPU 运行？

A：按 README 说明，在 main.py 的 config 中把 world_size 改为大于 1 的数值即可，无需其他改动。

Q：需要自己下载模型权重吗？

A：不需要。main.py 使用随机初始化的小尺寸 Qwen3 演示推理流程，README 未要求下载任何权重文件。

Q：想系统理解实现原理看哪里？

A：README 指向 HowToApproachvLLM.md，其中按层、模型、分页注意力、CUDA graphs、调度等环节给出分步实现指南。

Q：三个脚本分别做什么？

A：main.py 是主推理引擎示例，benchmark_prefilling.py 与 benchmark_decoding.py 分别做预填充的 FlashAttention 和解码的 PagedAttention 基准测试。

注意事项

项目基于 Nano-vLLM 改造，自包含实现 PagedAttention 与 FlashAttention，不依赖 vLLM 官方代码。
main.py 会构造小尺寸 Qwen3 与 60 条提示（2 条基础提示各重复 30 次），最多生成 256 个 token，显存占用与真机部署模型不同。
README 未给出 Python 版本、CUDA 版本和显存要求，实际运行前请自行确认环境兼容性。

核心亮点

自实现 PagedAttention 与 FlashAttention，代码量小、可逐行对照原理
基于 Nano-vLLM 精简复现，适合教学与快速实验，上手门槛低
Python 实现，便于修改调度、缓存策略并观察性能变化

不足之处

功能与性能远不及生产级 vLLM，缺少量化、分布式等能力
社区与文档规模小，长期维护和生态支持待观察

适用场景

学习大模型推理引擎内部原理的教学演示
在小型模型上做注意力/缓存策略的对比实验
作为二次开发原型，验证自定义调度或显存管理想法

替代项目

vLLM、Nano-vLLM

项目介绍

MinivLLM 是一个基础设施领域的开源项目，官方简介：Based on Nano-vLLM, a simple replication of vLLM with self-contained paged attention and flash attention implementation。项目使用 Python 开发，在 GitHub 上获得 1033 星标。

上一篇：flashinfer

下一篇：1Cat-vLLM