万字深度解析 Nano-vLLM：当1200行Python代码重构大模型推理——从架构设计到性能超越vLLM的完整技术指南（2026）

前言：vLLM很好，但它太重了

2026年，大模型推理框架江湖里，vLLM是当之无愧的霸主。PagedAttention、Tensor Parallelism、Continuous Batching……这些名字每一个都代表着一群顶级工程师的心血，也让vLLM成为了生产环境的事实标准。

但vLLM有一个让人头疼的问题：太大了。

Docker镜像22GB，依赖树复杂得像一座迷宫，安装一次等半天不说，在内网环境里想要离线部署更是难如登天。更要命的是，22GB的庞然大物里，核心推理逻辑被层层抽象和优化包裹，对于想学习大模型推理内部原理的开发者来说，vLLM就像一本用加密语言写成的天书。

这就是Nano-vLLM诞生的背景。

GitHub上，一个叫GeeeekExplorer的开发者用约1200行Python代码实现了一个完整的vLLM替代方案。项目地址：

https://github.com/GeeeekExplorer/nano-vllm

截至2026年6月，这个项目已经收获了14.3k Stars、2.3k Forks，在GitHub Trending上多次登顶。而且它的性能Benchmark数据让人震惊：

Nano-vLLM不仅更轻量，还在benchmark中比vLLM快了5.3%。

本文将从架构设计、核心原理、代码实现、性能优化四个维度，对Nano-vLLM进行一次彻底的深度拆解。你不需要是CUDA专家，也不需要懂编译器——我会从最基本的概念出发，一步步带你理解这个"千行代码实现vLLM"背后的工程哲学。

一、背景：大模型推理的技术挑战

1.1 LLM推理的本质：Transformer的自回归生成

在深入Nano-vLLM之前，我们需要理解大模型推理的核心挑战。

大语言模型（LLM）的本质是一个自回归Transformer。给定一个输入序列（prompt），模型逐token地生成输出：

输入: "今天天气"
输出: "今天天气很好"  → 逐token生成：今/天/天/气/很/好

每生成一个token，都需要：

1. 将当前所有token（包括输入和已生成的部分）送入Transformer
2. 计算Attention（注意力机制），建立token之间的关系
3. 通过Linear层+Softmax得到下一个token的概率分布
4. 根据采样策略（greedy、temperature等）选择下一个token

这个过程看起来简单，但有两个致命的性能瓶颈。

1.2 瓶颈一：KV Cache的显存爆炸

Transformer的核心操作是Self-Attention，计算公式如下：

Attention(Q, K, V) = softmax(Q × K^T / √d) × V

其中，Q（Query）、K（Key）、V（Value）都是矩阵。在推理时，模型需要将之前所有token的K和V矩阵缓存起来（称为KV Cache），这样计算下一个token时就不需要重新计算历史token的K和V。

问题来了：对于一个100B参数的模型，假设上下文长度为4096 tokens，fp16精度下：

• 每个token的K/V矩阵大小：hidden_size × head_dim × 2 × 2字节(fp16) = 5120 × 128 × 2 × 2 = 约2.5MB
• 4096个token的KV Cache：2.5MB × 4096 ≈ 10GB

这只是KV Cache，还不算模型权重本身。一张8GB显存的RTX 4070 Laptop，模型权重+KV Cache就已经爆了。

1.3 瓶颈二：算力利用的低效

自回归生成的另一个问题是GPU利用率低。在生成第N个token时，前N-1个token的计算结果早已算好但被丢弃了，因为下一个token必须等当前token算完才能开始。

这就好比你要烤一批饼干，必须一个一个地烤——烤炉（GPU）在大部分时间里都是空闲的。

vLLM通过Continuous Batching（也叫Iteration-level Batching）解决这个问题：把多个不同请求的序列打包在一起，当一个序列生成结束时，立即插入新的请求。这样GPU在每一个step都能保持高利用率。

1.4 vLLM的解决方案与Nano-vLLM的取舍

vLLM是这么做的：

1. PagedAttention：把KV Cache管理得像操作系统的内存分页一样灵活。KV Cache不需要连续存储，可以按block分配，按需加载。
2. Tensor Parallelism：把大矩阵运算分散到多张GPU上。
3. Continuous Batching：最大化GPU利用率。
4. CUDA Graph：减少GPU kernel launch的开销。

这些优化都很棒，但代价是代码复杂度爆炸。vLLM的主仓库有几十个Python文件，加上C++/CUDA算子，学习门槛极高。

Nano-vLLM的思路是：保留核心优化，砍掉过度工程化。用更少的代码实现同等核心功能，同时保证可读性和可扩展性。

二、整体架构：Nano-vLLM的设计哲学

2.1 架构概览

Nano-vLLM的代码结构极为简洁：

nano-vllm/
├── nanovllm/
│   ├── __init__.py          # 对外API入口
│   ├── model.py             # 模型定义（Qwen2等）
│   ├── engine.py             # 推理引擎核心
│   ├── sampler.py            # 采样器（token选择逻辑）
│   ├── cache.py              # KV Cache管理
│   ├── scheduler.py          # 调度器（请求队列）
│   └── utils.py              # 工具函数
├── example.py               # 使用示例
├── bench.py                 # 性能测试脚本
└── pyproject.toml           # 项目配置

整个项目的核心逻辑集中在5个Python文件中，总计约1200行。这与vLLM的数十个模块形成了鲜明对比。

2.2 设计哲学：教育优先，工程其次

Nano-vLLM的README明确写道："Readable codebase - Clean implementation in ~1,200 lines of Python code"。

这不是一句营销口号。GeeeekExplorer在项目文档中提到，他写Nano-vLLM的初衷是"用代码学习vLLM的原理"——当你读完1200行代码，你就能完整理解vLLM的核心逻辑，而不需要在几十万行代码的汪洋大海里挣扎。

这种"教学优先"的设计哲学体现在：

• 纯Python实现：没有C++/CUDA算子，所有计算都在PyTorch的标准操作上完成
• 功能选择：只实现vLLM最核心的功能（离线推理、基本优化），不追求功能完整性
• 代码可读性：变量命名清晰，每个核心逻辑都有注释
• 文档即代码：README和example.py就是最好的教程

2.3 核心组件交互

Nano-vLLM的推理流程如下：

用户请求 (prompt + SamplingParams)
        ↓
    Scheduler（调度器）
        ↓ 决定下一个batch该处理哪些序列
    Cache（KV Cache管理器）
        ↓ 管理block分配和释放
    Model（Qwen2模型）
        ↓ 执行forward
    Sampler（采样器）
        ↓ 从logits中选择下一个token
        ↓
    输出到Engine，循环直到结束

让我们逐一拆解每个组件。

三、核心实现：逐行拆解关键技术

3.1 KV Cache管理：Block-based分配策略

Nano-vLLM的KV Cache管理采用了类似操作系统的block分配策略。

问题：传统的KV Cache管理要求为每个序列预分配一段连续的显存空间。但不同序列长度差异极大——有的序列只要100个token就结束了，有的需要8192个。如果为每个序列都预分配8192个token的空间，显存利用率会低得可怜。

解决方案：将KV Cache分成固定大小的block，每个block存储固定数量的tokens（比如64个）。当一个序列需要更多空间时，动态分配新的block；当序列结束时，释放这些block供其他序列使用。

# nanovllm/cache.py（概念性代码）

class Block:
    """KV Cache的物理存储单元"""
    def __init__(self, block_size: int = 64):
        self.block_size = block_size
        self.num_tokens = 0  # 当前block中存储的token数
        # 实际存储：key和value的tensor
        # 形状：[num_heads, block_size, head_dim]
        self.k_cache = None
        self.v_cache = None
    
    @property
    def is_full(self) -> bool:
        return self.num_tokens >= self.block_size
    
    def append(self, k_tensor, v_tensor):
        """向block追加新的KV"""
        pos = self.num_tokens
        self.k_cache[:, pos] = k_tensor
        self.v_cache[:, pos] = v_tensor
        self.num_tokens += 1


class KVCacheManager:
    """KV Cache的逻辑管理器"""
    def __init__(self, num_blocks: int = 1000, block_size: int = 64):
        self.block_size = block_size
        # 物理block池
        self.blocks: List[Block] = [
            Block(block_size) for _ in range(num_blocks)
        ]
        # 已分配的block索引集合
        self.allocated_blocks: Dict[int, List[int]] = {}  # seq_id -> block_ids
        
    def allocate(self, seq_id: int, num_tokens: int) -> List[int]:
        """为某个序列分配足够的block"""
        needed_blocks = (num_tokens + self.block_size - 1) // self.block_size
        
        # 从block池中找空闲的block
        free_blocks = [b for b in self.blocks if not b.is_full]
        if len(free_blocks) < needed_blocks:
            raise RuntimeError("KV Cache显存不足，需要更多物理block")
        
        block_ids = []
        for i in range(needed_blocks):
            block = free_blocks[i]
            block_ids.append(self.blocks.index(block))
        
        self.allocated_blocks[seq_id] = block_ids
        return block_ids
    
    def free(self, seq_id: int):
        """释放序列占用的所有block"""
        if seq_id in self.allocated_blocks:
            del self.allocated_blocks[seq_id]
    
    def get_kv_at_position(self, seq_id: int, position: int):
        """获取指定位置的KV值（用于Attention计算）"""
        block_id = position // self.block_size
        offset = position % self.block_size
        
        block = self.blocks[self.allocated_blocks[seq_id][block_id]]
        return block.k_cache[:, offset], block.v_cache[:, offset]

这段代码的核心思想是：逻辑上每个序列看到的是连续的KV序列，物理上这些KV被分散存储在不同的block中。这样就解决了显存碎片化的问题——无论哪个序列结束，释放的都是整块的block，不会产生内存碎片。

3.2 模型实现：Qwen2的Nano-vLLM版本

Nano-vLLM实现了一个简化版的Qwen2模型。Qwen2是阿里云开源的大语言模型，其核心架构是标准的GQA（Grouped Query Attention，分组查询注意力）。

3.2.1 GQA vs MHA vs MQA

标准Transformer使用Multi-Head Attention（MHA），每个head有独立的Q、K、V投影：

MHA: Q_heads × W_q → Q
     K_heads × W_k → K  
     V_heads × W_v → V
     num_heads通常 = 32或64

但当模型变大时，MHA的K、V投影矩阵非常大。**Multi-Query Attention（MQA）**让所有Q heads共享同一个K和V投影，大幅减少参数量和计算量。

**Grouped Query Attention（GQA）**是MHA和MQA的折中：Q分成多个groups，每个group共享一对K、V：

# nanovllm/model.py（概念性代码）

class Qwen2Attention(nn.Module):
    """Qwen2的GQA注意力实现"""
    def __init__(
        self,
        hidden_size: int = 3584,
        num_heads: int = 28,          # Q的head数量
        num_kv_heads: int = 4,         # K和V的head数量（GQA）
        head_dim: int = 128,
        max_position: int = 8192 * 4,
    ):
        super().__init__()
        self.hidden_size = hidden_size
        self.num_heads = num_heads
        self.num_kv_heads = num_kv_heads
        self.head_dim = head_dim
        
        # GQA关键：Q的heads数可以远大于K/V的heads数
        # 这样可以减少K、V的投影计算量
        self.q_proj = nn.Linear(hidden_size, num_heads * head_dim, bias=False)
        self.k_proj = nn.Linear(hidden_size, num_kv_heads * head_dim, bias=False)
        self.v_proj = nn.Linear(hidden_size, num_kv_heads * head_dim, bias=False)
        self.o_proj = nn.Linear(num_heads * head_dim, hidden_size, bias=False)
        
        # 计算Q和K/V之间的对应关系
        # 例如：28个Q heads，4个K/V heads
        # 那么每个K/V head对应 28/4=7 个Q heads
        self.num_kv_groups = num_heads // num_kv_heads
        
        # 注册旋转位置编码的缓存
        self.register_buffer(
            "cos_cached",
            torch.zeros(1, 1, max_position, head_dim),
            persistent=False,
        )
        self.register_buffer(
            "sin_cached",
            torch.zeros(1, 1, max_position, head_dim),
            persistent=False,
        )
    
    def forward(
        self,
        x: torch.Tensor,           # [batch, seq_len, hidden_size]
        position_ids: torch.Tensor, # [batch, seq_len]
        use_cache: bool = False,
    ) -> Tuple[torch.Tensor, Optional[torch.Tensor]]:
        B, L, _ = x.shape
        
        # 投影得到Q, K, V
        q = self.q_proj(x)   # [B, L, num_heads * head_dim]
        k = self.k_proj(x)   # [B, L, num_kv_heads * head_dim]
        v = self.v_proj(x)   # [B, L, num_kv_heads * head_dim]
        
        # reshape成多head格式
        q = q.view(B, L, self.num_heads, self.head_dim)
        k = k.view(B, L, self.num_kv_heads, self.head_dim)
        v = v.view(B, L, self.num_kv_heads, self.head_dim)
        
        # 应用旋转位置编码（RoPE）
        q = self._apply_rotary_emb(q, position_ids)
        k = self._apply_rotary_emb(k, position_ids)
        
        # GQA关键：将K、V扩展到Q的head维度
        # 每个KV head复制num_kv_groups次，对应到每个Q group
        k = k.repeat_interleave(self.num_kv_groups, dim=2)  # [B, L, num_heads, head_dim]
        v = v.repeat_interleave(self.num_kv_groups, dim=2)  # [B, L, num_heads, head_dim]
        
        # 3D变4D：处理batch和KV Cache
        # q: [B, L, num_heads, head_dim] 
        # k, v: 如果有cache需要拼接，否则直接用当前token

3.2.2 旋转位置编码（RoPE）

Qwen2使用旋转位置编码（Rotary Position Embedding，RoPE），它通过在Q和K向量上施加旋转矩阵来实现位置感知，而不需要额外的位置编码参数。

    def _apply_rotary_emb(self, x: torch.Tensor, position_ids: torch.Tensor):
        """应用旋转位置编码"""
        # 从缓存中获取cos和sin值
        cos = self.cos_cached[:, :, position_ids, :self.head_dim // 2].squeeze(0)
        sin = self.sin_cached[:, :, position_ids, :self.head_dim // 2].squeeze(0)
        
        # 将向量按维度分成两半
        x1, x2 = x[..., :self.head_dim // 2], x[..., self.head_dim // 2:]
        
        # 旋转公式：x' = x * cos(θ) + (-x2, x1) * sin(θ)
        # 复数乘法实现
        x_new = torch.cat([
            x1 * cos - x2 * sin,
            x1 * sin + x2 * cos,
        ], dim=-1)
        
        return x_new

RoPE的核心思想是：用旋转矩阵给位置编码，让"相对位置"信息自然融入Attention的计算中。两个token之间的Attention分数会因为它们的相对位置而产生相应的旋转。

3.3 采样器：从logits到token

采样器（Samper）是LLM生成的关键环节——给定模型输出的logits（每个词表中每个token的概率分布），如何选择下一个token？

Nano-vLLM实现了多种采样策略：

# nanovllm/sampler.py

@dataclass
class SamplingParams:
    """采样参数"""
    temperature: float = 0.0      # 温度参数，0=greedy
    top_p: float = 1.0           # Nucleus采样阈值
    top_k: int = -1              # Top-K采样
    max_tokens: int = 256         # 最大生成token数
    stop_strings: Optional[List[str]] = None


class Sampler:
    """从logits中选择下一个token"""
    
    def __init__(self, vocab_size: int):
        self.vocab_size = vocab_size
    
    def sample(
        self,
        logits: torch.Tensor,      # [vocab_size]，最后一层的raw输出
        sampling_params: SamplingParams,
    ) -> int:
        """将logits采样为单个token ID"""
        
        # 温度缩放
        if sampling_params.temperature > 0:
            # softmax前的温度缩放
            logits = logits / sampling_params.temperature
        
        # Top-K过滤
        if sampling_params.top_k > 0:
            # 把top_k以外的token概率设为-inf
            top_k_values, top_k_indices = torch.topk(logits, sampling_params.top_k)
            filtered_logits = torch.full_like(logits, float('-inf'))
            filtered_logits[top_k_indices] = top_k_values
            logits = filtered_logits
        
        # Top-P（Nucleus）采样
        if sampling_params.top_p < 1.0:
            # 按概率排序，从大到小累加
            sorted_logits, sorted_indices = torch.sort(logits, descending=True)
            probs = torch.softmax(sorted_logits, dim=-1)
            
            cumsum_probs = torch.cumsum(probs, dim=-1)
            
            # 找到概率和刚好超过top_p的位置
            # 在这个位置之后的token都会被过滤掉
            cutoff_idx = torch.searchsorted(cumsum_probs, sampling_params.top_p)
            
            # 把cutoff_idx之后的token概率设为-inf
            cutoff_sorted_indices = sorted_indices[cutoff_idx + 1:]
            logits[cutoff_sorted_indices] = float('-inf')
        
        # Greedy采样（temperature=0时）
        next_token = torch.argmax(logits, dim=-1).item()
        
        return next_token

采样器的逻辑非常清晰：先做温度缩放，再做Top-K过滤，最后做Nucleus（Top-P）采样，最后greedy地选择概率最高的token。

3.4 调度器：Continuous Batching的核心

调度器（Scheduler）是Continuous Batching的灵魂。Nano-vLLM的调度器负责：

1. 管理待处理的请求队列
2. 在每个生成step，将可运行的序列打包成batch
3. 检测序列是否结束（EOS token或达到最大长度），结束则释放资源
4. 把新请求插入batch

# nanovllm/scheduler.py（概念性代码）

class Scheduler:
    """请求调度器：实现Continuous Batching"""
    
    def __init__(self, max_num_seqs: int = 256, max_model_len: int = 8192):
        self.max_num_seqs = max_num_seqs      # 最大同时处理的序列数
        self.max_model_len = max_model_len    # 模型最大上下文长度
        
        # 三个队列模拟vLLM的调度逻辑
        self.waiting: List[Request] = []      # 等待调度的请求
        self.running: List[Sequence] = []     # 正在运行的序列
        self.finished: List[Sequence] = []    # 已完成的序列
    
    def schedule(self) -> Optional[Batch]:
        """调度函数：返回当前step应该处理的batch"""
        
        # 1. 把waiting队列中的请求新序列加入running
        while len(self.running) < self.max_num_seqs and self.waiting:
            req = self.waiting.pop(0)
            seq = Sequence(req)
            self.running.append(seq)
        
        if not self.running:
            return None
        
        # 2. 构建当前batch
        # 将running中所有序列拼接成批处理
        # 注意：不同序列的KV Cache是独立存储的
        # 这里拼接的只是Q（query）部分
        
        # 3. 检查是否需要扩展KV Cache（每个序列的token数增加了）
        for seq in self.running:
            seq.add_token()  # 扩展KV空间
        
        # 4. 找出已完成的序列
        still_running = []
        for seq in self.running:
            if seq.is_finished():
                self.finished.append(seq)
            else:
                still_running.append(seq)
        self.running = still_running
        
        return Batch(self.running)

Continuous Batching的关键创新在于：不是在请求级别做batching，而是在token级别做batching。当一个序列的某个token结束时，立即用新的请求替换它——这样GPU在每个step的利用率都接近100%。

四、性能优化：Nano-vLLM的提速秘诀

4.1 Torch.compile：Python代码的JIT编译优化

Nano-vLLM使用PyTorch 2.0引入的torch.compile对模型进行JIT编译优化：

# 从nanovllm/engine.py
llm = LLM("/YOUR/MODEL/PATH", enforce_eager=True, tensor_parallel_size=1)

# enforce_eager=True 表示不使用CUDA Graph
# 取而代之的是torch.compile进行JIT优化
model = auto_configure_for_causal_lm(model, ...)
model = torch.compile(model, mode="reduce-overhead")

torch.compile的reduce-overhead模式会：

1. 融合连续的element-wise操作，减少kernel launch次数
2. 减少Python解释器的调用开销
3. 对计算图进行优化和重排

4.2 CUDA Graph：消除kernel launch开销

vLLM大量使用CUDA Graph来消除小kernel launch的开销。Nano-vLLM在enforce_eager=False时也支持CUDA Graph。

CUDA Graph的工作原理是：预先记录一段GPU操作的执行图，然后一次性重放整个图，而不是一个个kernel地发射。

# CUDA Graph示例（概念性）
with torch.cuda.graph(cuda_graph):
    # 所有在这个context manager内的CUDA操作
    # 都会被捕获并记录到一个图中
    output = model(input)
    output = output * 2
    output = torch.relu(output)

第一次执行时，CUDA会记录所有kernel launch；后续执行时，直接重放预录制的图，避免了数千次kernel launch的调度开销。

4.3 前缀缓存：重复Prompt的秒级响应

Nano-vLLM支持前缀缓存（Prefix Caching）。在很多实际场景中，不同用户的请求往往共享相同的前缀：

请求A: "请翻译以下文章：xxxxx..."  （前缀："请翻译以下文章："）
请求B: "请翻译以下文章：yyyyy..."  （前缀："请翻译以下文章："）

这两个请求的prefix部分完全相同，计算一遍就够了。但传统实现中每次都重新计算，造成了浪费。

Nano-vLLM的KV Cache天然支持前缀缓存——因为block是按物理位置存储的，当新序列的prefix与已有序列相同时，KV Cache的前面部分可以直接复用：

# 前缀匹配的逻辑
def can_use_prefix_cache(new_seq_prefix_hash, existing_seq_prefix_hash):
    """检查两个序列的prefix是否相同"""
    return new_seq_prefix_hash.startswith(existing_seq_prefix_hash)

4.4 张量并行：多卡横向扩展

Nano-vLLM通过tensor_parallel_size参数支持张量并行（Tensor Parallelism）。当设置为大于1时，模型的线性层会被切分到多张GPU上：

# 张量并行示例
llm = LLM(
    "/YOUR/MODEL/PATH",
    tensor_parallel_size=2  # 使用2张GPU
)

张量并行的核心思想是：将一个大的矩阵乘法（A × B）按列（或行）切成多块，分别在不同的GPU上计算，最后通信汇总结果。

例如，一个[hidden_size, vocab_size]的output projection矩阵，如果切到2张GPU上：

• GPU 0: 计算前半部分
• GPU 1: 计算后半部分
• 每张GPU计算完后，通过NCCL通信汇总

Nano-vLLM使用PyTorch的parallel_state来管理分布式通信：

# 分布式线性层（概念性）
class RowParallelLinear(nn.Module):
    def forward(self, x):
        # 本地计算
        local_output = F.linear(x, self.weight, self.bias)
        
        # NCCL all-reduce：汇总所有GPU的本地结果
        if dist.is_initialized():
            torch.distributed.all_reduce(
                local_output, 
                op=dist.ReduceOp.SUM,
                group=dist.distributed_c10d._get_default_group()
            )
        return local_output

五、实战：用Nano-vLLM部署你的第一个推理服务

5.1 安装：一条命令搞定

Nano-vLLM的安装极其简单：

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

不需要CUDA Toolkit，不需要复杂的依赖树，一条pip命令就完成了安装。这与vLLM的22GB镜像形成了鲜明对比。

5.2 下载模型

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

0.6B的模型权重约1.2GB，在RTX 3060上也能流畅运行。

5.3 基础使用

from nanovllm import LLM, SamplingParams

# 初始化推理引擎
llm = LLM(
    "/YOUR/MODEL/PATH",
    enforce_eager=True,        # True=使用torch.compile，False=使用CUDA Graph
    tensor_parallel_size=1,     # GPU数量
)

# 配置采样参数
sampling_params = SamplingParams(
    temperature=0.7,            # 温度，越高越随机
    top_p=0.9,                 # Nucleus采样
    max_tokens=256,            # 最大生成长度
    stop_strings=["<|im_end|>", "\n\n"]  # 停止字符串
)

# 批量推理
prompts = [
    "请用Python写一个快速排序算法：",
    "解释一下什么是Transformer架构：",
    "给我写一首七言绝句：",
]

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    print(f"输入: {output['prompt']}")
    print(f"输出: {output['text']}")
    print("-" * 60)

5.4 服务化部署

Nano-vLLM天然支持OpenAI兼容的API接口，可以直接作为API服务使用：

# 简单的API服务示例（实际项目中有更完善的实现）
from nanovllm import LLM, SamplingParams
from fastapi import FastAPI

app = FastAPI()
llm = LLM("/YOUR/MODEL/PATH", enforce_eager=True)

@app.post("/v1/completions")
async def complete(request: dict):
    prompts = request.get("prompt")
    sampling_params = SamplingParams(
        temperature=request.get("temperature", 0.7),
        max_tokens=request.get("max_tokens", 256),
    )
    
    outputs = llm.generate(prompts, sampling_params)
    
    return {
        "choices": [
            {"text": output["text"]} 
            for output in outputs
        ]
    }

# 启动服务
# uvicorn app:app --host 0.0.0.0 --port 8000

5.5 Benchmark复现

Nano-vLLM的bench.py脚本可以复现官方公布的性能测试：

# 运行benchmark
python bench.py

# 测试配置
# 硬件: RTX 4070 Laptop (8GB)
# 模型: Qwen3-0.6B
# 总请求数: 256 sequences
# 输入长度: 随机100-1024 tokens
# 输出长度: 随机100-1024 tokens

输出结果格式如下：

Inference Engine | Output Tokens | Time (s) | Throughput (tokens/s)
-----------------|---------------|----------|----------------------
vLLM             | 133,966       | 98.37    | 1361.84
Nano-vLLM        | 133,966       | 93.41    | 1434.13

Nano-vLLM的吞吐量比vLLM高出约5.3%，主要原因：

1. 代码更简洁，减少了不必要的抽象层开销
2. torch.compile的JIT优化覆盖了核心计算路径
3. 纯Python实现避免了复杂的依赖链

六、与vLLM的对比：各有所长

Nano-vLLM不是vLLM的替代品，而是在不同场景下的不同选择：

什么时候选Nano-vLLM？

1. 学习目的：想理解vLLM的核心原理，从Nano-vLLM开始效率最高
2. 内网/离线部署：没有复杂的CI/CD流水线，pip install搞定一切
3. 边缘设备：嵌入式GPU、边缘服务器，没有足够的存储空间
4. 快速原型：在Jupyter Notebook里快速验证一个想法
5. 学术研究：论文实验、小规模对比测试

什么时候选vLLM？

1. 大规模生产：需要处理 thousands of QPS，需要PagedAttention的极致显存利用率
2. 高级特性：Prefix Caching的细粒度控制、自定义CUDA算子、投机解码（Speculative Decoding）
3. H100/B200等高端GPU：需要专门的硬件优化
4. 团队协作：需要成熟的监控、metrics、运维工具

七、技术细节进阶：Nano-vLLM的源码导读

如果你想深入理解Nano-vLLM的源码，以下是推荐的阅读顺序：

7.1 第一步：engine.py——理解整体流程

engine.py是整个系统的入口，包含LLM类和Engine类的实现。建议从这里开始，理解整个推理流程的编排逻辑。

7.2 第二步：cache.py——理解KV Cache管理

理解Block-based KV Cache的实现，这是vLLM PagedAttention的核心思想。虽然Nano-vLLM没有用自定义CUDA算子，但它用Python实现了相同的逻辑。

7.3 第三步：model.py——理解Qwen2架构

GQA、RoPE、SwiGLU激活函数……这些Qwen2的核心组件都在这里。读完这部分，你就能完整理解一个现代LLM是如何工作的。

7.4 第四步：scheduler.py——理解Continuous Batching

Continuous Batching是LLM推理工程的灵魂。理解了这个，你就理解了为什么2023年之后大模型推理成本骤降的原因。

7.5 第五步：sampler.py——理解token采样

采样策略直接影响生成质量。这里展示了从logits到token的完整概率处理链路。

八、总结与展望

Nano-vLLM是一个极其难得的工程教育项目。它用1200行Python代码，完整复现了大模型推理的核心流程：KV Cache管理、Continuous Batching、GQA注意力、RoPE位置编码、张量并行、采样策略……这些在vLLM中需要几十万行代码才能实现的功能，被浓缩成了一个简洁优雅的Python实现。

更重要的是，Nano-vLLM在benchmark中**超越vLLM 5.3%**的吞吐量，证明了"简洁"不等于"低效"——有时候，去掉过度工程化的抽象层，反而能让代码跑得更快。

展望未来，Nano-vLLM的潜力在于：

1. 自定义CUDA算子：当前纯PyTorch实现在高端GPU上的性能还有提升空间
2. 投机解码（Speculative Decoding）：用小模型预测、大模型验证的方式加速生成
3. Prefix Caching增强：更智能地识别和复用重复前缀
4. 更大的模型支持：当前测试基于Qwen3-0.6B，未来可以扩展到更大的模型

无论如何，Nano-vLLM已经证明了一点：有时候，最好的学习方式不是读一本厚厚的书，而是读懂一段精炼的代码。

参考链接：

• GitHub仓库：https://github.com/GeeeekExplorer/nano-vllm
• vLLM官方仓库：https://github.com/vllm-project/vllm
• Qwen2模型：https://huggingface.co/Qwen/Qwen3-0.6B
• PyTorch 2.0 torch.compile文档

相关标签：Nano-vLLM|大模型推理|LLM|Tensor Parallelism|KV Cache|Continuous Batching|Python|PyTorch|Qwen2|开源项目