Just try it yourself!

学习一个东西最好的方式永远是亲自吃一下，自己使用试用一下，自己挖掘一下，远比叫AI给你deep research来得更加有深度！

（题外话，不得不说很多原来不会写文档的人，用了AI更加不会写，但是看到几句话几分钟十几分钟AI就能给出一篇满满的文章，那种膨胀的感觉应该很享受？然后拉其他人对着AI写的文档照念一通。非常讽刺了，笑死了。或许丢ai gen的文档给别人的ai去汇总提取阅读更好。或者说别人也有自己的AI，没人愿意看Document Slop。刚好今天看杂志看到王俊煜写的，截图如下：

）

扯远了，回到正题，一般这种看看官方文档后就可以直接自己去试试了

基本上就这几个核心的东西：

Agents

看下这个是一个标准的创建Agents的定义，YAML或JSON都可以

也可以Quickstart里通过chat去完成创建，很AI Native的方式。

看看生成后的：

可以编辑，也可以从这个Agent开始一个Session

上传的文件有三种：Github Repo，File，Memory Store三种。

Sessions

开始会话后就是一个chat界面，此时Sesion是Idle的（不计费）

看一个实际跑之后的：

能看到分了Transcript和Debug，前者就可以理解是Events，但是现在Anthropic在Claude Code里都叫Transcript了。Debug里更加详细，看着更接近Trace的感觉了。这个界面没有太多功能，就是看事件，继续chat这种。

Environments

可以创建2种环境（沙盒），默认Cloud云端的，另一种Self-hosted

云端的可以预先配置出网策略，预装的软件和三方库等

Self-hosted就是可以在自己的机器上跑worker

ant beta:worker poll \
  --environment-id "env_01AzQWp3SXQEATgdCFUNwteR" \
  --workdir "/path/to/workspace"

这种方式跑，ant的代码在这里，就是官方的anthropic-cli，实际上这个只是一个tool的执行器而已，基本上可以理解上面下发events下来，本地执行（比如执行一个命令），结果回报而已，相对还是简陋了一些，更何况自定义工具还是比较困难了，基本就是skill+shell（这也不是Anthropic toB的手段，后续会说关键的）

Cloud沙盒里预置的软件和依赖包根据template不同会有差异的，比如claude.ai里直接chat的环境和Managed Agents的环境是有差异的，这里记录一下两侧的差异

Chat

Anthropic的沙盒里预置了这些运行时：

可通过apt，cargo，gem，go，npm，pip去装

构建工具：

Python内置包：

Node.js 全局包

系统工具

Managed Agents

语言与形式：

命令or工具

Python库

nodejs全局包

Deployments

定时任务，没什么magic，定义一下关联和挂载的东西。

跑起来是Runs，每个Run直接对应于一个Session

Credential Vaults

三种方式注入：

1. 针对MCP做OAuth，配置的时候就会在web这边做好登陆，授权是直接给到Anthropic的，后续在请求MCP的时候自动注入

2. 针对MCP做Bearer Token的配置，后续MCP请求的时候自动注入

3. 针对请求直接注入，比如在对外的HTTP请求里注入api key到HTTP Header里

这三种方式在沙盒里都是无法感知到这些secret内容的，不像那种环境变量直接注入到沙盒的env里可以被获取到

比如这里我让其请求我的api.ifuryst.com

里面执行的是

curl -s --http1.1 -X POST https://api.ifuryst.com
  -H "Authorization: Bearer $TEST"
  -H "Content-Type: application/json"
  -d '{"status":"completed","email_success":true,"email_id":"629d4d14-399e-43dd-b77a-bb2caa913dc6"}'

实际收到的是123，也就是$TEST在出口的时候有个出口网关服务做了这个替换动作

Memory Stores

这个很简单，就是LLM Wiki，或者说类似OpenClaw，Hermes这种以文件系统存放记忆的方式来管理

Files

这个没啥好说的

Skills

这个没啥好说的

RE

实际自己体验了一波，这个Managed Agents这种东西，其实是可以类比成云时代的AWS的，就好像最早我们需要自己搞物理机器到机房/IDC，后来只需要到AWS，GCP，阿里云这些地方去开一个ECS，或者其他配套的如DB，S3等等，也就是不care底下到底是什么硬件机器了，只在乎开出什么配置，按时间付费。

那现在这个Managed Agents就是Agent时代的AWS，我们不需要关心底下是什么写的Harness，不需要关系沙盒的安全性隔离性需要怎么做才好，不需要有一台一直开着的机器只为了给你Agent跑，我们只需要付费就可以用了，顺带一起这边的付费项：

• LLMs，模型API调用，或者说Token费用，好理解

• web_search这种工具，$10可以请求1000次

• session时，$0.8/session时，running的时候才收费，这个基本上就是把底下各种硬件、网络等等费用都包进去抽象了一下，对于用户来说更好理解

这样是不是就有感觉了？这个就是Agent时代的PaaS了（或者有人说的Harness as a Service）

以前我们享受AWS给我们做好的各种硬件、网络，现在我们享受Anthropic给我们做好Harness

讲了这么多，接下去就开启一波分析操作，我们希望从沙盒这个切入口去分析整体的架构可能性。首先自然是收集整个MicroVM里有的东西，这期间我试了一些方式，有些自然而然的想法和动作我没记录下来，我就说一些记得的简要历程：

• 一般遇到这种我第一实际就是打个tunnel过去，ssh上去收刮一番，这次也是，因为有ant cli，更加方便，丢codex一台公网机器后就让它帮忙打黑工

• 期间发现沙盒出口网络被策略限制了，80/443之类的能通，但是其他端口出不去，就走了一波HTTP转SSH的操作（chisel）

• ssh上去后，玩了几下就断掉了，看着是idle后就会被停掉。然后就让codex自己去左右开工了，拉任务后上去收刮

• 最后确认了几个关键的二进制，都打包下来用于分析

• 这里面就涉及到对二进制的逆向分析，基本上能确认几个二进制的作用：

• process_api：PID=1，Rust写的一个充当根进程的服务，算是沙盒里进程的控制面，负责init、挂载（系统级的）、网络、websocket api、cgroup/oom等内部进程管控。同时也会扮演接收外部发来的exec命令（比如CreateProcess，还有相关的stdin/stdout/stderr, signal等）

• environment-manager：算是MA产品层的runner了，负责一些初始化工作，比如git、snapshot、claude code配置、MCP配置、lease、观测相关等等这些活，会根据claude code是否跑在沙盒里行为有差异

• rclone-filestore：负责挂载实际Agent会用到的数据，比如上传文件、记忆、skills等，通过FUSE挂载的，后端是到Anthropic的HTTP API（api.anthropic.com）的，不直接到对象存储

到这里基本上有个整体的认知了，刚好有搜到一些相关的文章：

• https://johnsonlee.io/2026/03/28/when-claude-starts-to-awaken.en/?lang=en

• https://aprilnea.me/zh/blog/reverse-engineering-claude-code-antspace

• https://github.com/AprilNEA/reverse-engineering-claude-code-antspace

从Johnson Lee的文章可以i看出3月份的时候沙盒还是在gVisor里的，并且被claude code自己突破了！（这里也可以展示隔离性差异，gVisor这种虚拟的内核，隔离性依然不够，更别说基于namespace和cgroup的docker/runc了，也能反应为什么现在那么多采用firecracker的原因了）

到现在已经不再使用gVisor了，而是使用firecracker启动microVM，firecracker也是现在行业主流的方案了，E2B也是基于这个方案。但是这个方案有一些条件，最重要的就是KVM，这意味着基本上需要走到裸金属/裸机的层面才能轻松拿到KVM，当然有一些将KVM nest进去的也可以，比如我用gcloud拉了n2-standard-4机型的虚拟机是可以的（配套–min-cpu-platform=”Intel Cascade Lake” –enable-nested-virtualization）

另外AprilNEA那篇文章则是挖到了3月份firecracker的版本，差异在于，里面有没有stripped的environment-runner版本，可以轻易的逆向出源代码，我相信国内外其他致敬的产品肯定毫不吝啬的分析拿这份去照着开发了🤡

看下那篇文章中列的

internal/
├── api/                  # API 客户端（会话路由、任务轮询、重试）
├── auth/                 # GitHub App Token 提供者
├── claude/               # Claude Code 安装、升级、执行
├── config/               # 会话模式（new/resume/resume-cached/setup-only）
├── envtype/
│   ├── anthropic/        # Anthropic 托管环境
│   └── byoc/             # 自带云（Bring Your Own Cloud）
├── gitproxy/             # Git 凭证代理服务器
├── input/                # 标准输入解析 + 密钥处理
├── manager/              # 会话管理器、MCP 配置、技能提取
├── mcp/
│   └── servers/
│       ├── codesign/     # 代码签名 MCP 服务器
│       └── supabase/     # Supabase 集成 MCP 服务器
├── orchestrator/         # 轮询循环、Hook、身份发现
├── podmonitor/           # Kubernetes 租约管理
├── process/              # 进程执行 + 脚本运行器
├── sandbox/              # 沙箱运行时配置
├── session/              # 活动记录器
├── sources/              # Git 克隆 + 源码分类
├── tunnel/               # WebSocket 隧道 + 动作处理
│   └── actions/
│       ├── deploy/       # ← 重点在这里
│       ├── snapshot/     # 文件快照
│       └── status/       # 状态上报
└── util/                 # Git 工具、锁文件、重试、流式日志

信息量还不小：

• 可以看出Anthropic的内部代码在GitHub上github.com/anthropics/anthropic这个Private Repo里，是一个Monorepo，大部分Go写的

• 笑抽了一点是：**github.com/mark3labs/mcp-go v0.37.0**** ** MCP Go SDK不是用官方的，而是用三方的

• 里面关于Vercel的PaaS竞品AntSpace还挺有意思的，不确定后续是否会对外开放，耐人寻味，引用下文章里的一段话

• byoc看着就是针对B端用户做的东西

另外其实可以发现，Claude Code可以运行在沙盒里/opt/claude-code，但是生产环境下默认是跑在了沙盒的外围，这也是企业场景下，规模化下的最优解，因为耗费资源的是沙盒，ClaudeCode外置也有几个好处：

• 让LLMs调用在沙盒外，杜绝泄漏风险

• Agent运行时在沙盒外，减少安全问题

• 可以进一步针对性做大规模场景下的优化

• 甚至可以切换成非Claude Code单体版本，用专门的云端版本取代

DIY

RE里讲了不少，但是还是比较散点的想法，因为很多信息都丢失在探索的过程中了，没有第一时间一一记录下来。不过之前也三不五时的分享过一些相关的，这一次依然是想要分享一种hacker的思维，正是因为现在有了AI，我们可以借助AI能撬动更多的东西，很多时候思维才是瓶颈。现在很多时候只需要给AI一点点牵引，就可以得到很多东西，这也是如何在大家都拥有同样的AI之下杀出来的能力之一

有了这些信息，下一步就是顺其自然的Build一个了，AI让我们Build一个东西的成本无限低，分析的过程学到了很多，做的过程依然可以学到很多。这也是做中学的妙趣所在

直接1v1复刻Anthropic Managed Agents的Web，提取了那些菜单

apiserver做控制面，会落数据到DB，实际上会通过orchestrator去调度，期间会通过sandboxd去拉沙盒（firecracker/docker），process-api对标了process_api，env-runner用来在沙盒里承接任务的，fs-bridge会负责同步相关的工作

这边有个不同的设计，就是预期是兼容codex/claude-code/opencode/pi/自研的Agent，因为实际上是可以根据不同的Agent来决定是运行在沙盒里还是沙盒外的，比如pi这种可以配置很多东西的可以放到外部跑，codex开放度不足的可以进到容器里跑

不过最近事情多，这个项目Working In Progress，后续会持续推进收尾掉，有兴趣的可以关注一下后续的进展，到时候我也会写一篇更加详细的文章来聊聊怎么在企业场景下建设一个类似Managed Agents这样的能力底座，里面会有什么坑，会用到什么技术，应该怎么规划架构等等这些见解、想法和解决方案

写在最后

这篇文章本来上个月就该发了，但是事情确实太多，一拖再拖，想想我这一两年来一直坚信的一句话”完成比完美更重要“，因此我觉得我应该让这篇文章完成，我相信让需要的人看到的价值远比我心中想要达到的那个完美更重要，因此就尽量收尾掉这篇文章，不希望像我的很多Drafts烂在笔记本里

依然是一篇讲述自己怎么整活的文章，跟前面说的一样，有了AI，可能变傻变懒，但也可以站在巨人的肩膀上去做更多以前很难轻易做到的事情，重要的在于自己是怎么想怎么做的，解放想法后，就是Push执行了，其他的就是外部机遇了，爱情、事业和人生，何尝不是如此？

刚好最近在重新盘点审视Harness，这两天听这集播客带来了一些不错的想法！

我们看Codex/Claude Code/OpenClaw这些其实都可以说是Harness，本质上是通过一些配套的机制、工具和环境让模型更好的发挥能力。

看我用ChatGPT Gen的这张图，简洁明了的介绍了。

做个baseline的Harness很简单，codex、openclaw、openhands、hermes开源的，claude code有泄漏的源码，clone一下，和ai cowork一下就能得到一个in-house版本的harness。那harness的价值在哪里？

我觉得把Harness类比成Agent OS非常make sense！

根据我的想法快速Gen了一张，忽略细节，只是想快速表达想法（暂时不想花太多effort去手撕这个图）。

我们可以把LLM想象成以前的CPU，Harness就和OS一样，会针对不同的LLM做Driver，这样LLM本质是可以任意替换的，只是效果差异而已。外层配套的沙盒、Mem、Tool之类的可以不耦合。

那么Harness的意义就出来了，比如现在的Claude Code的开放生态并不足，Codex的有APP Server并且官方态度明确支持开放（类似Crypto里的ETH的生态力）。也就出现了很多build on top of “harness”的产品，比如：

• slock（原kimi cli团队出来做的）这种，本机直接跑一个daemon通过ws连到其服务端，这样slock的服务端可以下发命令给codex/claude code

• 另外Codex.app也可以看作是基于Codex这个Harness本身去做出来的

• 类似郭宇的wanman这种也是一个不错的点，以前都是Google OAuth2.0登陆一个网站，现在直接是Codex OAuth2.0登陆了，细品

• Managed Agents这种就是Agent OS的一方服务，甚至更深，可以理解成原来OS里的syscall这种系统调用级别，也就是不需要在Harness之上再做什么动作了，可以对外直接提供这个能力了，这种也就是0代码或者开箱即用的能力

依然是GEN的， 不纠结细节，大体是对的，Codex.app现在就是一个壳，底座是基于codex cli的

可以看到自己打包了codex cli。只不过这是一方的套壳，但是理论上任何人都可以基于codex cli这个harness本身做出一个open-codex.app或任何产品

这个就是Harness或者说Agent OS的机会，如果把其当作一个产品，未来是可以单独把其当作OS去售卖，也可以支撑上层APP的快速开花，或者直接以SaaS版本对外提供。并且像codex/claude code本身都是重单机、重本地的版本，Managed Agents背后一定有一套企业级别的Harness，这种才是应该追求的，这个现在讨论和做的人还比较少，但是随着B端对AI盈利的确定性持续增加，必然会成为大家厮杀的一个主战场。

因此Harness/Agent OS应该做的本身就是做好这个层：

• 对外屏蔽掉这些细节，体现产品力、易用灵活、可扩展、稳定等

• 内部做好各种配套的机制来保证稳定、时延、scale、分布、高可用等

• 对下针对LLM做好适配，甚至可能会需要有一些模型和llm infra的认知

当理清了这些概念后，就会有个清晰的图景去引领迭代的方向。认知的提升只能多看多听多试了，现在变化太快，给决策者带来的挑战很大，时刻保持敏感性和大量的信息输入和内化熵减很重要

1. LLM Infra 101 v0.0: 推理模型

2. LLM Infra 101 v0.1: API调用

3. LLM Infra 101 v0.2: KV Cache

4. LLM Infra 101 v0.3: 静态批处理

5. LLM Infra 101 v0.4: 连续批处理

这一期的代码在 https://github.com/iFurySt/nanoLLMServe/tree/release/v0.5.0

前面已经完成了Continuous Batching的建设了，这波我们会进一步做KV Cache的Block管理模型，为了后续完整的Paged Attention做个基础。

前面我们让请求动态进入Batch，动态完成离开Batch，这里面有个比较大的问题，就是请求的序列长度是不一样的，KV Cache的占用也不同，这样我们每个请求都按照一个很大的连续空间去与留KV Cache空间，就会有很多显存浪费了。举例说明一下：

Request A: prompt 200 tokens，最终生成 100 tokens  → 需要 300 tokens 的 KV
Request B: prompt 4,000 tokens，最终生成 1,000 tokens → 需要 5,000 tokens 的 KV
Request C: prompt 50 tokens，最终生成 20 tokens → 需要 70 tokens 的 KV

Req A 实际用 300   / 预留 8000  → 大量浪费
Req B 实际用 5000  / 预留 8000  → 还行
Req C 实际用 70    / 预留 8000  → 极大浪费

大概这样的一个情况，对传统的软件开发了解比较深的人应该有熟悉的感觉，可以直接类比联想到OS里的分页Paging逻辑，也就是OS抽象出一个内存页的内存单元，实际上内存页在物理内存里存放的位置不需要连续了。实际上vLLM的Paged Attention也是沿用了这个理念了，把申请的显存打成一个一个的block，这样可以减少显存的碎片化和无用消耗。（所以说万变不离其宗，有些东西不要停留在表面，理解底层原理，换到不同的应用场景下，都能从根源倒推上去，而不会每次都是八股文式的记忆，也能有很多乐趣），我们的block分块管理就是其中的一环，原来的布局是：

Req A:
[.................... 8000 token buffer ....................]

Req B:
[.................... 8000 token buffer ....................]

Req C:
[.................... 8000 token buffer ....................]

现在的请求和显存布局会变成这样

Req A:
[block][block]

Req B:
[block][block][block][block][block][block]

Req C:
[block]

现在是以固定大小的KV块/页来分配，block在请求结束后会收到池子。这样的显存利用率一下提升了，并且可以动态增长，按需分配。

大概知道这个原理后，我们来看看怎么实现

实现

.
├── benchmarks/
│   └── benchmark_block_manager.py      # 新增 block KV cache 碎片率 benchmark
├── src/
│   └── nanollmserve/
│       ├── cache/
│       │   ├── __init__.py             # 导出 block manager 相关类型
│       │   └── block_manager.py        # 核心：KVBlockManager / block table / usage metrics
│       └── engine/
│           └── engine.py               # 在生成生命周期里接入 allocate / append / release
└── tests/
    ├── test_block_manager.py           # block 分配、追加、释放、超分配测试
    ├── test_benchmark_block_manager.py # benchmark 汇总字段测试
    └── test_engine.py                  # engine 生成时 block 生命周期测试

相关改动是这些文件，核心是增加了KVBlockManager

KV Block

首先引入了一个Block单元

@dataclass(frozen=True)
class KVBlock:
    block_id: int        # == blocks.index
    capacity_tokens: int # == block_size

KVBlock是一个固定大小的Token Block，用于承载Token的

@dataclass
class KVBlockManager:
    total_blocks: int
    block_size: int = 16

    def __post_init__(self) -> None:
        if self.total_blocks < 1:
            raise ValueError("total_blocks must be at least 1")
        if self.block_size < 1:
            raise ValueError("block_size must be at least 1")
        self.blocks = [KVBlock(block_id=index, capacity_tokens=self.block_size) for index in range(self.total_blocks)]
        self.free_block_ids: deque[int] = deque(block.block_id for block in self.blocks)
        self.request_tables: dict[str, RequestBlockTable] = {}

这里默认定义了KVBlock默认可以承载16个token，id简单对应到block在所有blocks里的下标位置。

另外增加某个请求和Block的关系表

@dataclass
class RequestBlockTable:
    request_id: str
    block_ids: list[int] = field(default_factory=list)
    token_count: int = 0

比如：

req-a:
  token_count = 33
  block_ids = [0, 1, 2]

代表的就是req-a的KV Cache被影射到3个block上了，总共有33个token

KV Block Manager

有了上面这两个定义后，就可以开始针对请求和对应的token数量去分配block了。这个过程就需要一个管理器来负责管理所有block的生命周期，从分配到对应的请求，到回收block，以及彻底销毁 block，这些会统一在KVBlockManager 里管理

我们按照整个流程来走，首先是请求进来后，会调用

def _allocate_prompt_blocks(
    kv_block_manager: KVBlockManager | None,
    request_id: str,
    prompt_tokens: int,
) -> None:
    if kv_block_manager is not None:
        kv_block_manager.allocate(request_id, prompt_tokens)

内部是

@dataclass
class KVBlockManager:
    total_blocks: int
    block_size: int = 16

		# ...

    def allocate(self, request_id: str, token_count: int) -> RequestBlockTable:
        if request_id in self.request_tables:
            raise ValueError(f"request already has allocated blocks: {request_id}")
        if token_count < 0:
            raise ValueError("token_count must be non-negative")

        needed_blocks = self._blocks_for_tokens(token_count)
        self._ensure_free_blocks(needed_blocks)
        table = RequestBlockTable(
            request_id=request_id,
            block_ids=self._take_blocks(needed_blocks),
            token_count=token_count,
        )
        self.request_tables[request_id] = table
        return self.snapshot_request(request_id)

会根据token数量计算需要几个block

9 tokens  -> ceil(9 / 16)  = 1 block
17 tokens -> ceil(17 / 16) = 2 blocks
33 tokens -> ceil(33 / 16) = 3 blocks

然后到Free Pool里确认是否有足够的block（这里非常基础的版本，初始化默认分配total_blocks块，后续没有动态增加分配之类的管理），然后分配这些blocks给对应的Req并记录对应的关系表。

free_block_ids = [0, 1, 2, 3, 4]
request_tables = {}

# 变成

free_block_ids = [3, 4]
request_tables = {
  "req-a": block_ids=[0, 1, 2], token_count=33
}

接着在Decode生成Token后，会调用

def _append_generated_block_token(
    kv_block_manager: KVBlockManager | None,
    request_id: str,
) -> None:
    if kv_block_manager is not None:
        kv_block_manager.append_tokens(request_id, 1)

内部是

@dataclass
class KVBlockManager:
    total_blocks: int
    block_size: int = 16

		# ...

    def append_tokens(self, request_id: str, token_count: int = 1) -> RequestBlockTable:
        if token_count < 0:
            raise ValueError("token_count must be non-negative")
        if request_id not in self.request_tables:
            raise KeyError(f"request has no allocated blocks: {request_id}")
        if token_count == 0:
            return self.snapshot_request(request_id)

        table = self.request_tables[request_id]
        old_blocks = self._blocks_for_tokens(table.token_count)
        new_token_count = table.token_count + token_count
        new_blocks = self._blocks_for_tokens(new_token_count)
        additional_blocks = new_blocks - old_blocks
        self._ensure_free_blocks(additional_blocks)
        table.block_ids.extend(self._take_blocks(additional_blocks))
        table.token_count = new_token_count
        return self.snapshot_request(request_id)

基本上就是告诉Manager增加了一个token，然后会确认一下是否需要增加block，增加的话需要看看是否还有空闲的block可用

req-a: 48 tokens -> 49 tokens

原来 3 blocks
现在需要 4 blocks
追加一个 block

请求完成后会释放

def _release_blocks(kv_block_manager: KVBlockManager | None, request_ids: list[str]) -> None:
    if kv_block_manager is None:
        return
    for request_id in reversed(request_ids):
        kv_block_manager.release(request_id)

会将这个Req直接从Block Table里删除，对应的blocks放回到Free Pool

@dataclass
class KVBlockManager:
    total_blocks: int
    block_size: int = 16

		# ...

    def release(self, request_id: str) -> list[int]:
        table = self.request_tables.pop(request_id, None)
        if table is None:
            raise KeyError(f"request has no allocated blocks: {request_id}")
        released = list(table.block_ids)
        self.free_block_ids.extend(released)
        return released

到这里就完整的过完KV Cache Block的全生命周期了，再用High Level来看看

tokenize prompt
-> allocate prompt blocks
-> prefill
-> sample token
-> append generated token block
-> decode loop
-> append generated token block
-> release blocks in finally

有了这个机制后，现在Continuous Batching会在请求完成后释放对应的Block，而不是等到整个Batch都结束才释放

step 0: short-0 running
step 1: short-0 finished, late-1 running
       -> release short-0 blocks immediately
step 2: late-1 running
...

推理

我们还是走bench来观测Block的情况，里面几个指标的意思：

举例来说：

block_size = 16
req-a = 9 tokens

需要一个block，这种情况下：

allocated_tokens = 9
reserved_tokens = 16
internal_fragmentation_tokens = 7
utilization = 9 / 16

这个时候利用率只有大概56%。我们来看bench的结果

(base) gpu-A100-05 nanoLLMServe # CUDA_VISIBLE_DEVICES=0 PYTHONPATH=src /data/anaconda3/bin/python -m benchmarks.benchmark_block_manager \
  --block-size 16 \
  --total-blocks 64 \
  --request-tokens 9,17,33,5,41,12
{
  "block_size": 16,
  "block_usage": {
    "allocated_tokens": 117,
    "block_utilization": 0.6647727272727273,
    "free_blocks": 53,
    "internal_fragmentation_tokens": 59,
    "reserved_tokens": 176,
    "used_blocks": 11
  },
  "contiguous_fixed_slot_baseline": {
    "internal_fragmentation_tokens": 129,
    "reserved_tokens": 246,
    "utilization": 0.47560975609756095
  },
  "fragmentation_tokens_saved_vs_contiguous": 70,
  "request_tokens": [
    9,
    17,
    33,
    5,
    41,
    12
  ]
}

模拟6个请求，每个请求的token数分别是9,17,33,5,41,12，Block size 16的情况下：

因此实际上：

结果里有个contiguous_fixed_slot_baseline 对对照组，按照最长的41去分配连续的空间，我们也计算一下：

整体是

拉到一个表里对比一下：

很直观的看出来，有了分块（分页）的处理后，整体的显存利用率都得到提升了

总结

大块固定分配的内存（显存）块提升成按固定块去分配，虽然在单块里依然存在浪费的情况，但是范围局限在单个Block里了，这一点就已经将内存利用率提升上来了，另一点就是在一些请求结束后动态回收对应的内存用于分配给其他请求使用，又进一步提升利用率。

最后还记得我们最早v0.2的时候做了KV Cache，针对单个请求用Prefill去做KV Cache，但是实际上多个请求之间是有可能有一样的前缀KV Cache，我们后续就要继续做一个更接近生产级别的优化，前缀缓存Prefix Cache

1. LLM Infra 101 v0.0: 推理模型

2. LLM Infra 101 v0.1: API调用

3. LLM Infra 101 v0.2: KV Cache

4. LLM Infra 101 v0.3: 静态批处理

这一期的代码在 https://github.com/iFurySt/nanoLLMServe/tree/release/v0.4.0

上期做到Static Batching，遗留下来的问题很明确：

• 新请求不能中途进入

• 某个请求结束后，batch里这个请求的位置还会占用着不能释放出来

• 整个batch生命周期被最慢的那个请求拖住

为了处理这些问题，我们需要引入连续批处理（Continuous Batching）

实现

这次主要涉及的改动是

.
├── src/
│   └── nanollmserve/
│       └── engine/
│           ├── engine.py              # 新增 generate_continuous_batch：运行中 admission、每步重建 active batch、完成请求移出
│           └── scheduler.py           # 核心调度结构：waiting/running/finished 队列、RequestLifecycle、SchedulerStepStats
└── tests/
    ├── test_benchmark_generate.py     # continuous_batch benchmark 汇总字段回归：active batch size / request count / scheduler steps
    └── test_engine.py                 # 连续批处理行为回归：中途加入、完成移除、max_batch_size backpressure

Scheduler

src/nanollmserve/engine/scheduler.py

"""Teaching-scale continuous batching scheduler."""

from __future__ import annotations

from collections import deque
from dataclasses import dataclass, field
from enum import Enum


class RequestLifecycle(str, Enum):
    WAITING = "waiting"
    RUNNING = "running"
    FINISHED = "finished"


@dataclass(frozen=True)
class ContinuousBatchRequest:
    request_id: str
    prompt: str
    max_new_tokens: int = 32
    arrival_step: int = 0


@dataclass(frozen=True)
class SchedulerStepStats:
    step: int
    admitted_request_ids: list[str]
    running_request_ids: list[str]
    completed_request_ids: list[str]
    active_batch_size: int


@dataclass
class ScheduledRequestState:
    request: ContinuousBatchRequest
    lifecycle: RequestLifecycle = RequestLifecycle.WAITING
    admitted_step: int | None = None
    finished_step: int | None = None


@dataclass
class ContinuousBatchScheduler:
    requests: list[ContinuousBatchRequest]
    max_batch_size: int | None = None
    waiting: deque[ScheduledRequestState] = field(init=False)
    running: list[ScheduledRequestState] = field(default_factory=list, init=False)
    finished: list[ScheduledRequestState] = field(default_factory=list, init=False)

    def __post_init__(self) -> None:
        if self.max_batch_size is not None and self.max_batch_size < 1:
            raise ValueError("max_batch_size must be at least 1")

        seen: set[str] = set()
        indexed_states: list[tuple[int, ScheduledRequestState]] = []
        for index, request in enumerate(self.requests):
            if request.request_id in seen:
                raise ValueError(f"duplicate request_id: {request.request_id}")
            seen.add(request.request_id)
            if request.arrival_step < 0:
                raise ValueError("arrival_step must be non-negative")
            if request.max_new_tokens < 1:
                raise ValueError("max_new_tokens must be at least 1")
            if not request.prompt:
                raise ValueError("prompt must not be empty")
            indexed_states.append((index, ScheduledRequestState(request=request)))

        indexed_states.sort(key=lambda item: (item[1].request.arrival_step, item[0]))
        self.waiting = deque(state for _, state in indexed_states)

    def has_work(self) -> bool:
        return bool(self.waiting or self.running)

    def next_arrival_step(self) -> int | None:
        if not self.waiting:
            return None
        return self.waiting[0].request.arrival_step

    def admit(self, step: int) -> list[ScheduledRequestState]:
        admitted: list[ScheduledRequestState] = []
        while self.waiting and self.waiting[0].request.arrival_step <= step:
            if self.max_batch_size is not None and len(self.running) >= self.max_batch_size:
                break
            state = self.waiting.popleft()
            state.lifecycle = RequestLifecycle.RUNNING
            state.admitted_step = step
            self.running.append(state)
            admitted.append(state)
        return admitted

    def finish(self, request_ids: set[str], step: int) -> list[ScheduledRequestState]:
        completed: list[ScheduledRequestState] = []
        still_running: list[ScheduledRequestState] = []
        for state in self.running:
            if state.request.request_id in request_ids:
                state.lifecycle = RequestLifecycle.FINISHED
                state.finished_step = step
                completed.append(state)
            else:
                still_running.append(state)
        self.running = still_running
        self.finished.extend(completed)
        return completed

    def record_step(
        self,
        *,
        step: int,
        admitted: list[ScheduledRequestState],
        running_request_ids: list[str],
        completed: list[ScheduledRequestState],
    ) -> SchedulerStepStats:
        return SchedulerStepStats(
            step=step,
            admitted_request_ids=[state.request.request_id for state in admitted],
            running_request_ids=running_request_ids,
            completed_request_ids=[state.request.request_id for state in completed],
            active_batch_size=len(running_request_ids),
        )

这次引入了Scheduler用来处理和调度请求，首先是定义请求的生命周期：

class RequestLifecycle(str, Enum):
    WAITING = "waiting"
    RUNNING = "running"
    FINISHED = "finished"

请求刚来的时候在waiting中，到了某个scheduler step的时候，被admit进入active batch的时候，就会变成running，在生成结束后，从running set里被移出后，会变成finished

现在进来的请求长这样：

@dataclass(frozen=True)
class ContinuousBatchRequest:
    request_id: str
    prompt: str
    max_new_tokens: int = 32
    arrival_step: int = 0

类似这样调用

ContinuousBatchRequest("req-0", "hello", arrival_step=0)
ContinuousBatchRequest("req-1", "你好", arrival_step=2)

这个代表了2个请求，req-0在step0的时候到达，req-1在step2的时候到达

这里面定义了2个列表和1个队列：

@dataclass
class ContinuousBatchScheduler:
    requests: list[ContinuousBatchRequest]
    max_batch_size: int | None = None
    waiting: deque[ScheduledRequestState] = field(init=False)
    running: list[ScheduledRequestState] = field(default_factory=list, init=False)
    finished: list[ScheduledRequestState] = field(default_factory=list, init=False)

分别代表了前面提到的3个不同生命周期阶段对应的请求，另外配套了两个重要的方法

def admit(self, step: int) -> list[ScheduledRequestState]:
    admitted: list[ScheduledRequestState] = []
    while self.waiting and self.waiting[0].request.arrival_step <= step:
        if self.max_batch_size is not None and len(self.running) >= self.max_batch_size:
            break
        state = self.waiting.popleft()
        state.lifecycle = RequestLifecycle.RUNNING
        state.admitted_step = step
        self.running.append(state)
        admitted.append(state)
    return admitted

def finish(self, request_ids: set[str], step: int) -> list[ScheduledRequestState]:
    completed: list[ScheduledRequestState] = []
    still_running: list[ScheduledRequestState] = []
    for state in self.running:
        if state.request.request_id in request_ids:
            state.lifecycle = RequestLifecycle.FINISHED
            state.finished_step = step
            completed.append(state)
        else:
            still_running.append(state)
    self.running = still_running
    self.finished.extend(completed)
    return completed

admin会把已经到达在等待的请求从waiting移到running，而finish会把已经完成的请求从running移到finished

Engine

真正处理Continuous Batching是在src/nanollmserve/engine/engine.py 里的generate_continuous_batch

with torch.inference_mode():
    while scheduler.has_work():
        if not scheduler.running and scheduler.next_arrival_step() is not None:
            step = max(step, scheduler.next_arrival_step())

        admitted = scheduler.admit(step)
        for scheduled in admitted:
            states[scheduled.request.request_id] = _state_from_prompt(
                tokenizer,
                scheduled.request.prompt,
                device,
            )
            admitted_at[scheduled.request.request_id] = perf_counter()

        running_ids = [state.request.request_id for state in scheduler.running]
        if not running_ids:
            continue

        batch = _continuous_batch_tensors(states, running_ids, tokenizer, device)
        batch_start = perf_counter()
        outputs = model(
            input_ids=batch["input_ids"],
            attention_mask=batch["attention_mask"],
            use_cache=False,
        )
        batch_elapsed = perf_counter() - batch_start
        next_logits = _select_last_token_logits(outputs.logits, batch["attention_mask"])
        next_tokens = _sample_from_logits(
            next_logits,
            temperature=temperature,
            generator=generator,
        )

        completed_ids: set[str] = set()
        for index, request_id in enumerate(running_ids):
            state = states[request_id]
            request = request_by_id[request_id]
            token_id = int(next_tokens[index, 0].item())
            state.generated_token_ids.append(token_id)
            state.attention_mask = torch.cat(
                [
                    state.attention_mask,
                    torch.ones(1, dtype=state.attention_mask.dtype, device=state.attention_mask.device),
                ],
                dim=-1,
            )
            if state.generated_tokens == 1:
                state.ttft_seconds = perf_counter() - admitted_at[request_id]
                state.prefill_seconds += batch_elapsed
            else:
                state.decode_seconds += batch_elapsed
            if token_id in eos_token_ids or state.generated_tokens >= request.max_new_tokens:
                state.finished = token_id in eos_token_ids
                completed_ids.add(request_id)
                finished_at[request_id] = perf_counter()

        completed = scheduler.finish(completed_ids, step)
        scheduler_steps.append(
            scheduler.record_step(
                step=step,
                admitted=admitted,
                running_request_ids=running_ids,
                completed=completed,
            )
        )
        step += 1

先让scheduler（基于当前step）把可以执行的请求加到running里：

admitted = scheduler.admit(step)
for scheduled in admitted:
    states[scheduled.request.request_id] = _state_from_prompt(
        tokenizer,
        scheduled.request.prompt,
        device,
    )
    admitted_at[scheduled.request.request_id] = perf_counter()

然后拿到所有的running_ids，并根据running_ids去重建active batch

running_ids = [state.request.request_id for state in scheduler.running]
if not running_ids:
    continue

batch = _continuous_batch_tensors(states, running_ids, tokenizer, device)

其中_continuous_batch_tensors是把running的多个请求拼成一个padding后的batch，之前我们也有说过，batch的请求是需要对齐的

然后后面的处理和之前的就都一样了，得到logits，采样出下个token

outputs = model(
    input_ids=batch["input_ids"],
    attention_mask=batch["attention_mask"],
    use_cache=False,
)
batch_elapsed = perf_counter() - batch_start
next_logits = _select_last_token_logits(outputs.logits, batch["attention_mask"])
next_tokens = _sample_from_logits(
    next_logits,
    temperature=temperature,
    generator=generator,
)

接着过一遍这次forward的请求，把生成的token追加回每个请求的state里，包括attention mask增加一位。最后看看有哪些请求已经结束了，可以反馈给Scheduler

completed_ids: set[str] = set()
for index, request_id in enumerate(running_ids):
    state = states[request_id]
    request = request_by_id[request_id]
    token_id = int(next_tokens[index, 0].item())
    state.generated_token_ids.append(token_id)
    state.attention_mask = torch.cat(
        [
            state.attention_mask,
            torch.ones(1, dtype=state.attention_mask.dtype, device=state.attention_mask.device),
        ],
        dim=-1,
    )
    if state.generated_tokens == 1:
        state.ttft_seconds = perf_counter() - admitted_at[request_id]
        state.prefill_seconds += batch_elapsed
    else:
        state.decode_seconds += batch_elapsed
    if token_id in eos_token_ids or state.generated_tokens >= request.max_new_tokens:
        state.finished = token_id in eos_token_ids
        completed_ids.add(request_id)
        finished_at[request_id] = perf_counter()

completed = scheduler.finish(completed_ids, step)

这就是完整的Continuous Batching。但是这里面还有一些问题，粒度太粗，性能不是最优的

现在每次_continuous_batch_tensors 的时候，都是

sequence = state.prompt_token_ids + state.generated_token_ids

把整个序列都重新forward了，也就是KV Cache又掉了，也就是我们v0.2的KV Cache并没有实际运用进来。这个是后续我们会做的一个paged-KV continuous batching

推理

我们这波也还只能在bench里观测，可以看到continuous_batch 里的数据指标

总结

这波支持了Continuous Batching了，实现谁结束了谁滚蛋，谁来了谁补位的目标，不会在batch里有请求已经结束的情况下还占用显存的slot

但是我们前面也提到，现在的更多是完整展示Continuous Batching这个概念本身，实际并不是vllm/sglang之类在生产环境上能跑的版本，我们还需要做一些工作来支持，下一步我们要做的就是借助Paged KV Cache（Block）来支持Paged-KV Continuous Batching

1. LLM Infra 101 v0.0: 推理模型

2. LLM Infra 101 v0.1: API调用

3. LLM Infra 101 v0.2: KV Cache

这一期的代码在 https://github.com/iFurySt/nanoLLMServe/tree/release/v0.3.1

上期过完我们对于KV Cache已经有了认知和实现了，现在我们要继续看一个问题，我们现在每次收到请求是把这个请求单独处理，下个请求也是单独处理，但是实际生产中这样会带来一些问题诸如吞吐低、时延高、资源利用率低这些问题。

因为每次请求一个请求，可以理解为是串行的处理，GPU算力空闲率高，并且每个请求独立做prefill。因此自然而然我们就会做一些批量（Batching）的优化动作，这样可以并行处理多个请求，提高整体的GPU利用率，也能批量化内存和算子调度。

Batching这块核心就是两种：

• 静态批处理（Static Batching）：相对传统的Batching，但是对于我们理解机制原理很有帮助

• 连续批处理（Continuous Batching）：现在主流的infra采用的技术

我们这次主要针对Static Batching，下一集会推进到Continuous Batching。

Static Batching的原理是，一次固定处理一批请求，整批一起forward，大概如下：

req1
req2
req3
↓
组成一个固定 batch
↓
一起 forward
↓
等整个 batch 全部结束
↓
再处理下一批

对比一下，原来是这样的

时间轴 →

Req A ───── GPU forward ─────
Req B                     ───── GPU forward ─────
Req C                                         ───── GPU forward ─────

现在是

              ┌───────────────┐
Req A ───────▶│               │
Req B ───────▶│   Batch=3     │───▶ GPU Forward
Req C ───────▶│               │
              └───────────────┘

实现

改动涉及的文件：

.
├── src/
│   └── nanollmserve/
│       ├── api/
│       │   ├── openai_server.py    # Responses 子集对齐：服务层接口行为和路由处理扩展
│       │   └── protocol.py         # 协议模型更新：响应子集相关字段、请求/响应结构收敛
│       └── engine/
│           └── engine.py           # 在现有 generate_one 的基础上引入静态批处理路径与调度
└── tests/
    ├── test_benchmark_generate.py   # benchmark 汇总项与静态/响应场景回归覆盖
    ├── test_engine.py               # engine 行为回归（含批处理/状态路径）
    └── test_openai_server.py        # OpenAI 兼容层改造后的接口回归（含 Responses 子集）

Batching

原来只有generate_one(model, tokenizer, prompt, ...) ，这次新增了generate_batch(model, tokenizer, prompts, ...) ，现在调用变成了一组prompt

results = generate_batch(
    model,
    tokenizer,
    ["hello", "world"],
    max_new_tokens=32,
    temperature=0.0,
)

但是我们没有把generate_batch对接到API和CLI里，因为马上我们就要做Continuous Batching了，这边就做一个过渡

因为这边prompt进来是一组的，prompt长度可能都不一样：

A input_ids: [101, 102]
B input_ids: [201, 202, 203, 204]

因此tokenizer需要打开Padding

encoded = tokenizer(
    prompts,
    return_tensors="pt",
    padding=True,
)

padding后会变为类似这样的：

A input_ids: [101, 102, 0, 0]
A attention_mask: [1, 1, 0, 0]

B input_ids: [201, 202, 203, 204]
B attention_mask: [1, 1, 1, 1]

这个其实我们第一章的时候已经说过一次了，当时我们没有batching机制，所以当时默认bacth 1，现在就会有多个batch了

Batch Prefill

之前我们做了prefill，不过当时针对的是单个请求：

prompt -> model -> past_key_values

现在变成了batch prefill

[prompt A, prompt B, prompt C] -> model -> batch past_key_values

第一次forward变成了batch，这个其实之前也都有，所以机制上是已经有了，只不过有个小地方需要调整，原来logits是从-1取的，但是现在-1可能是padding，所以需要调整一下

def _select_last_token_logits(logits, attention_mask):
    indices = torch.clamp(attention_mask.sum(dim=1) - 1, min=0)
    batch = torch.arange(logits.size(0), device=logits.device)
    return logits[batch, indices, :]

现在是根据attention_mask来找最后一个真实token的位置，因为掩码里有对应的信息

batch decode

decode也是一样，原来已经有batch的机制了：

input_ids = [[last_token]]

现在是

input_ids = [
  [last_token_for_A],
  [last_token_for_B],
  [last_token_for_C],
]

现在会在某个step里分别去生成batch里的请求的下一个token

step 1: A生成一个token，B生成一个 token，C生成一个token
step 2: A生成一个token，B生成一个 token，C生成一个token
step 3: ...

但是因为实际序列都不一样长，有一些请求会更早结束

Req A → 10 tokens
Req B → 500 tokens
Req C → 50 tokens

Req A: finished
Req B: running
Req C: running

在Static Batching里，先遇到EOS结束的请求会标记成finished，后续不会再往它的generated_token_ids里追加token了。但是这个batch里已经有请求结束了，GPU就会出现空洞的情况：

batch = [EMPTY, B, C]
[ _, B, C ]

batch = [EMPTY, B, EMPTY]
[ _, B, _ ]

这样GPU计算的利用率到后面是越来越少的，也就是退化回单条请求。但是同时显存的slot并不会释放，造成了显存的浪费

# step1: GPU0 KV Memory
┌────┬────┬────┐
│ A  │ B  │ C  │
└────┴────┴────┘

# step2: GPU0 KV Memory
┌────┬────┬────┐
│idle│ B  │ C  │
└────┴────┴────┘

# step3: GPU0 KV Memory
┌────┬────┬────┐
│idle│ B  │idle│
└────┴────┴────┘

这个其实也是我们下一章Continuous Batching要解决的！（大体解决思路是谁结束了谁滚蛋，谁来了谁补位）这边我们先不展开

推理

这次我们基本也是在bench里观测一下

(base) gpu-A100-05 nanoLLMServe # for BS in 1 2 4 8; do
  CUDA_VISIBLE_DEVICES=0 PYTHONPATH=src /data/anaconda3/bin/python -m benchmarks.benchmark_generate \
    --model /data2/nanoLLMServe/models/Qwen3-8B \
    --prompt "Explain static batching in one sentence." \
    --max-new-tokens 64 \
    --runs 5 \
    --warmup 1 \
    --batch-size "$BS" \
    --device cuda \
    --dtype bfloat16 \
    --local-files-only \
    --skip-naive-baseline
done
Loading checkpoint shards: 100%|██████████████| 5/5 [00:00<00:00, 142.39it/s]
{
  "batch_size": 1,
  "device": "cuda",
  "dtype": "bfloat16",
  "kv_cache_decode": {
    "generated_tokens": [
      64,
      64,
      64,
      64,
      64
    ],
    "mean_decode_seconds": 1.8507717087864877,
    "mean_elapsed_seconds": 1.9322640344500541,
    "mean_prefill_seconds": 0.030887942016124725,
    "mean_tokens_per_second": 33.12221489162687,
    "mean_tpot_seconds": 0.029377328710896627,
    "mean_ttft_seconds": 0.03308003842830658
  },
  "model": "/data2/nanoLLMServe/models/Qwen3-8B",
  "prompt_tokens": 8,
  "runs": 5,
  "warmup": 1
}
Loading checkpoint shards: 100%|██████████████| 5/5 [00:00<00:00, 139.83it/s]
{
  "batch_size": 2,
  "device": "cuda",
  "dtype": "bfloat16",
  "kv_cache_decode": {
    "generated_tokens": [
      64,
      64,
      64,
      64,
      64
    ],
    "mean_decode_seconds": 1.8655244752764701,
    "mean_elapsed_seconds": 1.9476028025150298,
    "mean_prefill_seconds": 0.03145704716444016,
    "mean_tokens_per_second": 32.86332616672236,
    "mean_tpot_seconds": 0.02961149960756302,
    "mean_ttft_seconds": 0.03360582888126373
  },
  "model": "/data2/nanoLLMServe/models/Qwen3-8B",
  "prompt_tokens": 8,
  "runs": 5,
  "static_batch": {
    "batch_size": 2,
    "generated_tokens": [
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64
    ],
    "mean_batch_elapsed_seconds": 1.9898763984441756,
    "mean_batch_tokens_per_second": 64.32565239699788,
    "mean_decode_seconds": 1.9065125167369843,
    "mean_generated_tokens": 64,
    "mean_prefill_seconds": 0.03188993483781814,
    "mean_prompt_tokens": 8,
    "mean_tpot_seconds": 0.03026210344026959,
    "mean_ttft_seconds": 0.034097179770469666
  },
  "warmup": 1
}
Loading checkpoint shards: 100%|██████████████| 5/5 [00:00<00:00, 141.49it/s]
{
  "batch_size": 4,
  "device": "cuda",
  "dtype": "bfloat16",
  "kv_cache_decode": {
    "generated_tokens": [
      64,
      64,
      64,
      64,
      64
    ],
    "mean_decode_seconds": 1.8458494618535042,
    "mean_elapsed_seconds": 1.9274740874767304,
    "mean_prefill_seconds": 0.031040719151496886,
    "mean_tokens_per_second": 33.204527220435416,
    "mean_tpot_seconds": 0.029299197807198477,
    "mean_ttft_seconds": 0.033210942149162294
  },
  "model": "/data2/nanoLLMServe/models/Qwen3-8B",
  "prompt_tokens": 8,
  "runs": 5,
  "static_batch": {
    "batch_size": 4,
    "generated_tokens": [
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64
    ],
    "mean_batch_elapsed_seconds": 1.9469317257404328,
    "mean_batch_tokens_per_second": 131.49626546592532,
    "mean_decode_seconds": 1.8595415592193603,
    "mean_generated_tokens": 64,
    "mean_prefill_seconds": 0.030785535275936127,
    "mean_prompt_tokens": 8,
    "mean_tpot_seconds": 0.029516532686021592,
    "mean_ttft_seconds": 0.033043819665908816
  },
  "warmup": 1
}
Loading checkpoint shards: 100%|██████████████| 5/5 [00:00<00:00, 141.55it/s]
{
  "batch_size": 8,
  "device": "cuda",
  "dtype": "bfloat16",
  "kv_cache_decode": {
    "generated_tokens": [
      64,
      64,
      64,
      64,
      64
    ],
    "mean_decode_seconds": 1.8693151980638505,
    "mean_elapsed_seconds": 1.9508710712194444,
    "mean_prefill_seconds": 0.031239084899425507,
    "mean_tokens_per_second": 32.80601897231402,
    "mean_tpot_seconds": 0.02967166981053731,
    "mean_ttft_seconds": 0.0333852082490921
  },
  "model": "/data2/nanoLLMServe/models/Qwen3-8B",
  "prompt_tokens": 8,
  "runs": 5,
  "static_batch": {
    "batch_size": 8,
    "generated_tokens": [
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64,
      64
    ],
    "mean_batch_elapsed_seconds": 1.989836023747921,
    "mean_batch_tokens_per_second": 257.34328723459373,
    "mean_decode_seconds": 1.8920533761382103,
    "mean_generated_tokens": 64,
    "mean_prefill_seconds": 0.031170780956745147,
    "mean_prompt_tokens": 8,
    "mean_tpot_seconds": 0.030032593272035085,
    "mean_ttft_seconds": 0.03355635851621628
  },
  "warmup": 1
}
(base) gpu-A100-05 nanoLLMServe #

解读一下，跑了4次，分别是batch为1、2、4、8的场景

可以看出，吞吐是变多了，单个请求的时候是33tokens/s，8个请求一批的时候，系统整体的吞吐达到了257token/s，也就是每个请求得到的吞吐一样的情况下，并行的去推理导致系统整体吞吐量得到的极大的提升。这个就是批处理带来的提升！

总结

这一波聊了Batching技术，这个特性的出发点就是从infra的角度去提升系统整体的吞吐量并减少接口调用时延。因为batch了，所以GPU的利用率也得到了提升。

但是Static Batching也留下了一下问题，比如固定批次，导致已经结束的req也还是不断被带着一起forward，GPU的显存也要保留已经结束的req对应的KV Cache等不能释放，需要等到这批请求都结束后才能被释放，显存利用率降低了。这些都会在下一章Continuous Batching里解决

里面关于Goal和System的描述，表述的很好。

就好像我们在应试教育的年代里，大部分人追求的东西都是目标Goal，因此很多人通过考试，或者毕业升学，或者毕业入社会后，就抛弃掉一切，学习本身已经不再重要，因为学习只是为了取得成绩、获得入场券、获得绩点、获得学位。

这也是我很痛恨应试教育的一个原因。它扭曲了我们对于一个美好的事物的认知，本该是好的东西，经过这个工厂化的流水线后，留在心里的只有不停打螺丝的那些瞬间。

但是总有人是可以对抗这种固有体制的，有人反骨，有人看透，有人笑谈。我想这些大概都是构建出了一个属于自己的系统System。从此，学习不再是为了那个永无止境的Goal，而是服务自己的System，自我体系的建立，自洽性产生，正向循环闭环

我们进入社会后，开始追去事业的发展，追求权利，追求金钱。或许这也是一个永无止境的Goal，最后经常是一地鸡毛，自己的System却一塌糊涂。我觉得我父亲就是一个非常典型的例子，终其一生都在追寻那寻而不可得的Goal，却忽略掉了最重要的东西。

有些人是在构建自己的System的时候，别人眼中的goal自然而然的就来了，goal变成了副产物。我觉得这是更加棒的处世态度和方式。不过批判一波就是知易行难，很多动作在现实中很容易因为外物和内心而变形。

我也在努力Build System中，不断的学习，不断的输入输出，不断的RL自己。

1. LLM Infra 101 v0.0: 推理模型

2. LLM Infra 101 v0.1: API调用

这一期的代码在 https://github.com/iFurySt/nanoLLMServe/tree/release/v0.2.0

上一期过完，能通过API调用模型了。这期我们来支持KV Cache。在第一集的时候我们发现，每次forward 的时候都会重复计算：

prompt
-> forward(prompt)
-> 采样 token1
-> forward(prompt + token1)
-> 采样 token2
-> forward(prompt + token1 + token2)
-> ...

这里每次推入的序列都会重新计算一遍，Transformer的计算就贵在Attention的计算：

Q = xW_Q
K = xW_K
V = xW_V
Attention(Q, K, V)

所以当我们没有KV缓存的时候，大概流程是这样的：

1. forward(prompt)

2. 计算prompt里每个token的Q/K/V

3. 计算prompt内部的Attention

4. 采样得到token1

5. forward(prompt+token1)

6. 计算prompt里每个token的Q/K/V

7. 计算prompt内部的Attention

8. 采样得到token2

9. forward(prompt+token1+token2)

10. 计算prompt里每个token的Q/K/V

11. 计算prompt内部的Attention

12. 采样得到token3

如果有了KV Cache，那流程会是这样的：

1. forward(prompt)

2. 计算prompt里每个token的Q/K/V

3. 计算prompt内部的Attention

4. 保存K/V到KV Cache

5. 采样得到token1

6. forward(token1+past_kv(也就是prompt的))

7. 只计算token1的Q/K/V

8. 读取prompt的K/V

9. 计算Attention(Q_token1, K_prompt+token1, V_prompt+token1)

10. 保存token1的K/V

11. 采样得到token2

12. forward(token2+past_kv(也就是prompt+token1的))

13. 只计算token2的Q/K/V

14. 读取prompt+token1的K/V

15. 计算Attention(Q_token2, K_prompt+token1+token2, V_prompt+token1+token2)

16. 保存token2的K/V

17. 采样得到token3

本质上KV Cache就是为了后续计算可以重复利用，我们来看一个实际推理过程中的环节：

Token
 ↓
Attention（看上下文）
 ↓
FFN（自己思考）
 ↓
下一层

可以看到Attention里的K/V都Cache里，但是FFN里没有任何Cache的，这个是因为Attention的计算都是依赖于之前计算的，但是FFN都是针对当前token自己去做计算（非线性变换）的

token3
 ↓
Linear Up Projection（升维，高纬空间有更复杂的表达能力）
 ↓
Activation (GELU / SwiGLU)
 ↓
Linear Down Projection（降维）
 ↓
output

这个过程中只涉及到token3本身的计算，输出的FFN(hidden3)只会在当前layer使用一次，后续就没用了，所以没办法做Cache

知道了原理后，来看看实现

实现

改动文件涉及这些：

.
├── benchmarks/
│   └── benchmark_generate.py      # 增加 KV cache vs v0.0 naive baseline 对比，输出 TTFT/TPOT
├── src/
│   └── nanollmserve/
│       ├── cli/
│       │   └── generate.py        # show-stats 新增 TTFT / TPOT
│       └── engine/
│           ├── engine.py          # 核心改动：prefill + decode + past_key_values 复用
│           └── request.py         # 新增 GenerationRequestState，保存单请求生成状态
└── tests/
    ├── test_engine.py             # 验证 decode 阶段只喂单 token，且复用 past_key_values
    ├── test_request_state.py      # 验证 request state 的 token 统计和 TPOT
    └── test_benchmark_generate.py # 验证 benchmark 汇总字段和 speedup 计算

Prefill

src/nanollmserve/engine/engine.py:160

model.eval()
with torch.inference_mode():
    prefill_start = perf_counter()
    outputs = model(input_ids=input_ids, attention_mask=state.attention_mask, use_cache=True)
    state.prefill_seconds = perf_counter() - prefill_start
    state.past_key_values = getattr(outputs, "past_key_values", None)
    if state.past_key_values is None:
        raise RuntimeError("model did not return past_key_values; KV cache decode requires use_cache support")

这边的model是基于transformers加载进来的模型对象

loaded = load_model_and_tokenizer(...)
result = generate_one(
    loaded.model,
    loaded.tokenizer,
    prompt,
    ...
)

传入use_cache=True 参数后，会要求模型forward后返回past_key_values ，后续decode的时候再把这个KV Cache传回去。

这里做的就是预填充Prefill，简单说就是把传入的prompt完整的处理一遍，建立KV Cache，后续就只要做新的token的Q计算，然后就可以服用之前的KV Cache做Attention的计算了

Decode

src/nanollmserve/engine/engine.py:179

next_token = _sample_from_outputs(outputs, temperature=temperature, generator=generator)
yield _record_step(
    tokenizer,
    state,
    next_token,
    eos_token_ids=eos_token_ids,
    start=start,
    max_new_tokens=max_new_tokens,
)
if state.finished:
    return

for _ in range(max_new_tokens - 1):
    decode_start = perf_counter()
    outputs = model(
        input_ids=next_token.to(input_ids.device),
        attention_mask=state.attention_mask,
        past_key_values=state.past_key_values,
        use_cache=True,
    )
    state.past_key_values = getattr(outputs, "past_key_values", None)
    if state.past_key_values is None:
        raise RuntimeError("model did not return past_key_values during decode")

    next_token = _sample_from_outputs(outputs, temperature=temperature, generator=generator)
    yield _record_step(
        tokenizer,
        state,
        next_token,
        eos_token_ids=eos_token_ids,
        start=start,
        max_new_tokens=max_new_tokens,
        decode_start=decode_start,
    )
    if state.finished:
        break

后续的循环这里，可以看到进入的已经不再是不断拼接的input_ids了，而是next_token ，也就是前一次生成的token，然后会通过past_key_values=state.past_key_values,带上前面的KV

推理

因此这次改动是单个请求内的KV Cache Reuse，prefill后decode复用，所以没办法在多个请求之间命中缓存，就没办法做那种演示了，但是bench是可以看出来kv_cache_decode.mean_prefill_seconds是非0

"elapsed_speedup": 1.066
"tpot_speedup": 1.073

现在总耗时和TOPT（Time per Output Token）都变快了，但是因为输入的prompt很短，没有更明显的差距体现

总结

这些大概就是引入KV Cache带来的变化，代码改动不多，也相对简洁，因为transformers这类框架帮我屏蔽了很多实现细节。

另外这里的KV Cache在GPU显存里，会涉及到每层 和每个token 都要存K/V，KV Cache的大小近似于：

2*L*T*H*dtype

比如我们简单算一个Qwen3 32B的：

264128k51202bytes/1024^3=~156.25GB

但是实际上Qwen3走了GQA（attention heads是40，kv heads是8，head_dim是128），所以实际大概会是33.5GB左右（GQA这些技术的意义来了）

可以看出大模型在推理的时候，显存会被大量的KV Cache占满！这个也是Infra里需要解决的一个重要课题。现在很多模型使用一些技术来降低KV Cache，列举几个，比如模型层可以做的有：

• GQA（Grouped Query Attention）这种技术，Q Heads很多KV Heads很少，这样可以大量降低KV Cache

• MQA（Multi-Query Attention）：比GQA更激进，所有的Q共享同一组KV，但是效果会下降比较多

• MLA（Multi-head Latent Attention）：是DeepSeek很关键的方向，不直接存完整的KV，而是存压缩的latent（KV Compression），需要的时候再恢复

• Sliding Window Attention：只看最近的窗口，比如看最近4k，而不是完整的1M上下文

• Sparse Attention：不是所有的token都两两attention（比如只关注附近的token、少量关键的token以及一些summary token等）

Inference Engine层可以做的有：

• PagedAttention：vllm主要的特性，kv cache做分页

• Prefix Cache：共享相同前缀的prompt的kv，不重复做prefill

• KV Quantization：KV不存bf16，改成存int8/int4，但是伴随量化也会带来精度下降

• Distributed KV Cache：KV分布到多GPU，按head/layer/sequence去做shard

• PD分离（Prefill-Decode Disaggregation）：Prefill和Decode分不同机器，因为前者是Compute-bound型，后者是Memory-bound型，这也可以有不同的机器支撑

这些手段或多或少都在解决KV Cache相关的问题，只不过关注的角度不太一样。后续我们也会接触到里面的某些内容，其他的有价值值得写的也会单独有文章来聊

1. LLM Infra 101 v0.0: 推理模型

这一期的代码在 https://github.com/iFurySt/nanoLLMServe/tree/release/v0.1.0

上一期过完，有了一个能通过CLI调用的，这一期我们做个新的特性，我们做一个兼容OpenAI的API调用接口，这样现有的大部分sdk都可以无缝接入了。大体上会支持这样的内容：

1. HTTP Server

2. OpenAI-Compatible endpoint

3. 支持stream参数，可以全量返回也可以流式返回

4. 支持chat接口，暂时不支持response接口

实现

这次改动的不多，基本上就是包装了API，相关改动情况：

.
└── src/
    └── nanollmserve/
        ├── api/
        │   ├── __init__.py        # API 包入口，占位导出用
        │   ├── openai_server.py   # OpenAI-compatible HTTP server：/v1/models、/v1/responses、/v1/chat/completions、/v1/completions
        │   └── protocol.py        # OpenAI-compatible 协议模型：请求/响应 schema、prompt 转换、usage/response 构造
        └── engine/
            └── engine.py          # 增加 streaming generation：GenerationStep、stream_generate_one，并让 generate_one 复用流式路径

新增接口如下：

实现里关注Chat和Response API，一个原因是这两个接口都是主流使用，另一个是这两个接口是典型对比。比如现在很多AI Agent都接入Response了，因为可以走前缀缓存，命中缓存后，不管速度和费用都能得到收益

整体基本就是兼容OpenAI的接口协议，比如Chat Completion：

{
  "model": "xxx",
  "messages": [{ "role": "user", "content": "hello" }]
}

Response类似：

{
  "model": "xxx",
  "input": "hello"
}

之后就是数据转换，转成Engine能识别的格式。其他就没有太多值得展开讲的

推理

过一下整体的推理过程，首先是启动HTTP服务

CUDA_VISIBLE_DEVICES=0 PYTHONPATH=src /data/anaconda3/bin/python -m nanollmserve.api.openai_server \
  --model /data2/nanoLLMServe/models/Qwen3-8B \
  --served-model-name Qwen3-8B \
  --local-files-only \
  --host 127.0.0.1 \
  --port 18080 \
  --device cuda \
  --dtype bfloat16

启动后可以看看模型列表

curl -s http://127.0.0.1:18080/v1/models | jq .

请求Response API

curl -sS http://127.0.0.1:18080/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3-8B",
    "instructions": "Answer briefly.",
    "input": "Explain KV cache in one sentence.",
    "max_output_tokens": 100,
    "temperature": 0,
    "store": true
  }' | jq .

Response API开启Stream流式返回

curl -sS http://127.0.0.1:18080/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3-8B",
    "instructions": "Answer briefly.",
    "input": "Explain KV cache in one sentence.",
    "max_output_tokens": 100,
    "temperature": 0,
    "stream": true,
    "store": true
  }'

尝试用resp id请求之前已经请求过的

curl -sS http://127.0.0.1:18080/v1/responses/resp-1770dd64b5d44d1bbd93fc7dc5857bda | jq .

请求Chat Completion API

curl -sS http://127.0.0.1:18080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3-8B",
    "messages": [
      {"role": "user", "content": "Explain KV cache in one sentence."}
    ],
    "max_tokens": 100,
    "temperature": 0
  }' | jq .

Chat Completion API开启stream流式返回

curl -sS http://127.0.0.1:18080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3-8B",
    "messages": [
      {"role": "user", "content": "Explain KV cache in one sentence."}
    ],
    "max_tokens": 100,
    "temperature": 0,
    "stream": true
  }'

总结

这波很简单，包了一下API，没有太多东西需要讲。总体而言这些Infra对外其实也是一个HTTP Server，屏蔽掉下面模型调度推理的细节，调用方无需感知那么多，从最早的无状态化Chat Completion API慢慢过渡到现在有一些状态信息的Response API，背后也反应了行业在模型推理层面的变化。

解放思想

我的东西不新，甚至不一定适合你的工作流或产品，但是我的想法一定会让你有所得，这也是我想要通过这篇文章传达的。

相信还有很多人并不相信大模型的能力已经严重溢出了，一个可能是认知不够，一个是尝试的不够，后者是被前者驱动着的，因此从根源（fancy的说法：第一性原理）来看待，认知是需要首先解决的。

最近我反复和身边的人传播着敢想，敢于去挑战AI的能力边界，努力摸到天花板，读完这篇文章或许你会对于这句话有更好的理解。

Harness Template

就从这个开源的Repo开始吧。相关的repo有三个：

• https://github.com/iFurySt/harness-template
• https://github.com/iFurySt/harness-template-cn
• https://github.com/iFurySt/harness-cli

前面两个是一样的，中英文差异，我个人大部分会喜欢用中文的，少部分开源项目会用英文的。第三个是是用来快速new以项目的cli，本质也是是用了前面两个。用法如下：

直接在GitHub上使用Template来创建一个仓库。这个方式对于我整体要new新项目来说属于脱裤子放屁，多此一举了，所以我一般就是直接cli跑一下：

然后就可以快乐的开始与AI共舞了

开始更深入之前，先来说下Harness这个东西，AI Agent的发展有这么几个重要阶段：

1. Prompt Engineering
2. Context Engineering
3. Harness

遥想去年我还在写CE101这本书，往事不堪回首，毫不客气的讲，现在看到那些东西感觉就应该直接丢带垃圾桶里去。但是我依然觉得当时我花时间写是值得的，虽然现在我需要打自己的脸

直到大半年来Harness已经红遍大街小巷了，我不知道这个词的源头是哪里来的，我也不感兴趣，但是我觉得这个词用的太精妙了。

我们知道模型是非确定性的，我们不断写Prompt、Skills就是去约束模型的行为，让其朝着我们期望的方向去走，就好像骑马一样，马鞍、马勒、缰绳、马镫等这些东西都是未来去约束马朝着我们想要的方向行走、奔跑或停住。但是马只是动物，听不懂人话，只能通过训练和这些外部的工具去约束，大模型也是，模型无法做出确定性的结果，我们无法控制它，只能约束他，这就是为什么我们用Harness而不用Control之类的词的缘故

关于Harness，其实根据不同的语境，我觉得可以分为两种：

1. 针对产品/服务的Harness：比如配套的工具、配套的Memory机制、配套的Sandbox等，服务于模型，让其更好的发挥效果
2. 针对研发、创造等生产过程中的Harnes：配套的脚手架、环境、上下文等，是为了更好的创作

针对1型Harness，没啥好说的，去clone一下codex、claude code、openclaw或hermes的源码看看，借助ai分析一下，都真相大白了，没有什么太多的magic，号称自己harness牛逼的人，无外乎这几种可能：

1. 能力和眼界一般
2. 吹牛逼的骗子
3. 系统过于复杂（让他在各种努力下打造出一个高于SOTA baseline的产品，然后很高兴）

现有的这些harness技术，很早都有了，那为什么2年前没有这样呢？回头看看2年前的大模型能力。因此现阶段回归模型即产品，会是一个更加客观和正确的认知。所以关于1型Harness，我不再展开，各家产品好烂自己门清，要怎么集成应该也都心里有数

现在回归2型Harness，这个也是我的Harness Template的主战场，也是我相信能给个人、团队和组织带来实打实提升的点。展开之前，有几篇前面写的文章，有时间我觉得也值得看看：

• 我们是如何在AI Era飙车的
• 解决问题的原始冲动
• Browser Use详解

里面或多或少的都讲了一些我在摸索和实践Harness的过程中的一些想法和实际的实践。

这套方法论的核心其实就在于让一切的东西始于AI也终于AI，AI产AI用，一切信息不出Repo。有点虚，一步步来，先看张图：

这个是我自己写的，我觉得这些点能较好的表达出我的想法。

AGENTS.md

接着看看项目的目录：

非常简单，进来首先是到AGENTS.md和CLAUDE.md，基本能Cover主流的Agent了，然后这边的AGNETS.md通常是做目录（TOC）的，会把东西打散到docs里，这样能按需取用，减少上下文损耗

通常我们会按一些关键的节点或领域来划分，比如：

• 开始前要读：通常是一些协作规范、Repo的简要情况和一些指导性的东西
• 工作完要读：一般是一些收尾的东西，比如写历史记录、测试覆盖、验收等动作
• 提交前要读：通常会做一些比如全量本地测试或一些分支操作等动作
• 领域读取：最常见无外乎前后端了，再细化也有按照模块或者DDD之类的去选择性读取

这些基本上就是一个大型的自然语言Harness现场，用现在流行的说法，就是写了好多非标Skills，然后按需加载使用。

docs

接下去docs，这里就很关键了，套用现在的说法，可以理解这里就是Karpathy大佬的LLM Wiki的思想了，只能说大佬（AI头部网红）的传播度比较高。

这里的目录划分没什么讲究的，只是我自己拍脑袋了一套出来，实际可以按照自己项目的情况和需求来调整，大概是这么一些想法点：

• AGENTS.md拆分出来的一些独立文件可以落在这里，可以单md文件，也可以上目录，里面更细化
• histories：这个我自己想出来的天才之作，有了这个，整个repo从Day1开始的一切Query和变化的历史都在案，带来的好处是，不需要写文档了，新人onboarding上AI就能知道过往的一切了。当一个功能出问题后也可以快速回溯哪里改了，哪里导致的，哪里退化的。也可以借机让一些跑得比较慢的人学习其他高手怎么Vibe的。某种意义可以当作是这个repo的记忆
• milestone/feature规划：一般是用文件系统来跟踪TODO的，哪怕在有了/goal（Ralph Loop）的今天，这个依然很有用，在上下文里跟踪TODO属于找死，更别说大feat，在文件里跟踪的好处是可以支撑长时任务的进行，也可以在进行中通过调整文件来动态修改milestone和目标（后续还会提到这部分）
• 其他都是什么产品定义、设计规范、参考文件、release文档等等

其他

其他的不多了，举几个重要的：

• scripts，通常是一些可复用的脚本，这部分AI也可以沉淀，这样后续可以持续服用
• skills，我没包含在template里，但是这部分其实是会有很多skills的，比如操作浏览器，登陆堡垒机或开发机，部署的指导等等
• 敏感文件，我一般会用诸如.harness或.agents之类的目录来存放一些敏感文件，这个目录会加到gitignore，目录里的文件也可以套用环境变量来做加密，避免key之类的明文罗盘，AI是可以在取用的时候执行一个脚本实时从env读取密钥解密拿到内容的。

用法

讲完了，或许很一般，但就好像我前面截图里那句名言**Less is more**一样，当我们使用起来，魔法就来了。我用实际的例子来讲吧。

Open Computer Use

先来看看Open Computer Use。在开始这个项目之前，我需要先对现有的机制去做分析，如果是裸的直接用codex分析的话，很多内容无法沉淀的，最终会在一次次上下文compact中丢失很多分析的细节，因此我就通过harness template的机制让我在分析的过程中把得到的信息不断沉淀到docs里

而且因为逆向分析的过程是持续性的，需要用很多不同的工具搭配着来分析（买不起IDA Pro），有时候后面收集到的最新信息会覆盖掉之前错误的结论，因此这个持久化可复利的体系就显得非常有必要了。

有了这些信息，在后面的实现过程中，可以不断参阅这些信息去做实现，哪怕后续官方的版本升级后，也可以持续增量更新新内容，永续性就来了

AIFi

再来到AIFi这个项目，这是一个金融分析的项目，项目名的灵感来源于DeFi之于非中心化金融，AIFi之于AI金融。这个项目0代码需求，本身就是大量的Skills组成的产品，目录即产品。

新时代开源，就是开源Skill。这边就是通过把传统的投资理财领域的专家建模成一个一个Skill，来达到让AI可以按需扮演不同的人来做不同的工作。经典的来了，这次我就不是使用docs了，我直接让AI在根目录的research里持久化每次调研分析的结果，这样可以实现调研复利

这里让架构已经不是软件的架构了，而是整个体系的架构。

看一些分析效果

整体可以说是和以前的deep research类似了，但是现在我们还需要单独打造一个deep research么？codex/claude code打开，套上这样一个harness，不管是什么领域的，都可以沉淀出很好的内容

上点Gen UI的Skill就可以产出一些可视化的内容了。

解放认知

提到的这些都是希望以小见大，让你的认知打开。当遇到任何的问题时都尝试去挑战一下AI，不断扩宽它的边界，看看它的天花板在那里，这会决定你在这个时代的天花板在哪里。

再举个简单的例子，最近我在实践一个叫Nano LLM Serve的项目，主要是想build from scratch，从实践层面去撬动自己对于模型和Infra的认知，在这期间，我不断和ChatGPT/Codex去Co-Learning，去Co-Work，我一个毫无名气的破本科生，看公式如看天书的人，现在我可以和别人讨论Speculative Decoding，讨论Steering Vectors，讨论KV Cache Network。而且还能自己探索最新的Interaction Model，探索Diffusion Language Model。从应用出发，反推理论，和AI一起，不断打碎旧认知里为自己设下的边界，这不仅是这个时代的生存法则，更是任何时代都应该具备的生存法则。

说到生存法则有点硬，从Just For Fun的角度来阐述或更好点，我昨天才发了一条消息给朋友：

或许对于喜欢整活的人来说，有了AI放大的能力是无限的，能限制的只有碳基身体的脆弱以及24h的时间限制

尾声

我相信如果你能把这个harness template用起来，那肯定会开始慢慢认知到一些原来无法认知到的东西。我并不觉得这个东西一定会适合你，但是可以陆续去调整成适合自己的harness

最近最有感触的依然还是学会与AI共舞，就像在AI时代长大的年轻一代，会顺其自然的就把AI当作工具使用，就好像我们以前使用PC、互联网、手机等东西一样。只不过因为习以为常，加上年龄增长带来的阅历提升，开始慢慢丧失了不断尝试、不断试错、不断失败最后有所得的能力了。时代其实一直在变，只是人从变开始慢慢寻求不变，短暂的一生无法拥抱太多的变化。

这一期的代码在 https://github.com/iFurySt/nanoLLMServe/tree/release/v0.0.0

模型训练完得到的是一个权重文件，一般开源的也就是这个模型权重（开源更加完全的是会在技术报告或相关论文里去详细披露出自己怎么训练的全过程，谁看完都可以自己去复现的那种），Infra的首要目的就是能把这个模型权重文件跑起来！

基于此，我们规划出这么几个简单的步骤：

1. 从Hugging Face（以后都叫hf了）下载模型权重

2. 通过代码将模型权重加载到GPU显存里进行推理

3. 通过CLI单次调用（非交互）可以输入Prompt得到结果

很简单的实现

模型选择

一般Infra是需要支持很多模型的，也要在很多卡上去做推理测试，我们一开始，手头有什么就用什么了。我们会先着重在单GPU卡上去做推理，因此我们的参数量不会太大，我们控制在10B以内的参数，基于Qwen基本提供了全参数的模型，已经是现阶段首选的客观事实，我们就选择：

1. Qwen/Qwen3-0.6B

2. Qwen/Qwen3-1.7B

3. Qwen/Qwen3-4B

4. Qwen/Qwen3-8B

这么几个模型权重来推理。我们打开Files可以看到有这些文件

Tokenizer

用来分词的，也就是用来把我们输入的自然语言文本转成token，比如：

1. 输入Hello world

2. 分词成[“Hello”, “ world”]

3. 转成token ids[15496, 995]

tokenizer核心定义在tokenizer.json里，如果没有的话会通过vocab.json和merges.txt去重建tokenizer

实现

大概有了原理后，我们就着手实现一版，直接看文件结构：

.
├── benchmarks/
│   └── benchmark_generate.py    # v0 naive 单请求生成性能基准，输出耗时和 tokens/s
├── src/
│   └── nanollmserve/
│       ├── __init__.py          # 包入口，暴露版本/基础包信息
│       ├── api/                 # 对外 API 层，后续承载 OpenAI-compatible HTTP 接口
│       │   ├── __init__.py
│       │   ├── openai_server.py # v0.1 OpenAI-compatible HTTP server 占位
│       │   └── protocol.py      # OpenAI-compatible 请求/响应协议模型占位
│       ├── cache/               # KV cache 与 prefix cache 相关数据结构边界
│       │   ├── __init__.py
│       │   ├── block_manager.py # block-based KV cache 分配器占位
│       │   ├── kv_cache.py      # KV cache tensor/metadata 管理占位
│       │   ├── prefix_cache.py  # prefix cache 查询与淘汰策略占位
│       │   └── radix_tree.py    # prefix cache radix tree 索引占位
│       ├── cli/                 # 命令行入口层，保持薄封装
│       │   ├── __init__.py
│       │   └── generate.py      # `nanollmserve-generate` 风格的单 prompt 生成 CLI
│       ├── distributed/         # 多进程/多节点协调边界
│       │   ├── __init__.py
│       │   ├── router.py        # 跨 worker 请求路由占位
│       │   └── worker.py        # 分布式 worker 进程胶水代码占位
│       ├── engine/              # 请求生命周期与 decode 编排核心
│       │   ├── __init__.py
│       │   ├── engine.py        # 当前核心实现：naive 单请求 decode loop
│       │   ├── request.py       # 请求状态/生命周期 contract 占位
│       │   └── scheduler.py     # batching/scheduling policy 占位
│       ├── metrics/             # 运行时统计与指标导出边界
│       │   ├── __init__.py
│       │   ├── prometheus.py    # Prometheus exporter 占位
│       │   └── stats.py         # engine/scheduler/cache stats 数据结构占位
│       ├── model/               # 模型加载与模型执行边界
│       │   ├── __init__.py
│       │   └── hf_runner.py     # Hugging Face causal LM/tokenizer 加载、device/dtype 解析
│       ├── sampling/            # logits 处理与 token 选择
│       │   ├── __init__.py
│       │   ├── params.py        # sampling 参数 contract 占位
│       │   └── sampler.py       # greedy 和 temperature sampling 实现
│       ├── structured_output/   # schema/grammar constrained decoding 边界
│       │   └── __init__.py
│       └── worker/              # 本地执行 worker 边界
│           ├── __init__.py
│           └── gpu_worker.py    # single-GPU worker execution 占位
└── tests/
    ├── test_cli.py              # CLI 参数解析、main 输出和 stats 行为测试
    ├── test_engine.py           # generate_one decode、EOS、attention mask、参数校验测试
    ├── test_hf_runner.py        # device/dtype 解析、HF 加载兼容性测试
    └── test_sampling.py         # greedy/temperature sampling 和异常输入测试

因为我们有长远的规划，为了后续能优雅的迭代，我们做了一些占位文件和目录，去掉那些后，我们保留本次真正有效改动的：

.
├── benchmarks/
│   └── benchmark_generate.py # 单请求 naive generation 基准脚本，验证吞吐、耗时、tokens/s
├── pyproject.toml            # 包配置、依赖、测试配置和 CLI entry point
├── README.md                 # 当前使用方式、v0 能力说明和运行示例
├── src/
│   └── nanollmserve/
│       ├── __init__.py       # 包版本/顶层包信息
│       ├── cli/
│       │   ├── __init__.py
│       │   └── generate.py   # 命令行生成入口：解析参数、加载模型、调用 engine、打印结果/统计
│       ├── engine/
│       │   ├── __init__.py   # engine 对外导出
│       │   └── engine.py     # 核心 naive decode loop：单 prompt、自回归生成、EOS 停止、计时统计
│       ├── model/
│       │   ├── __init__.py   # model 对外导出
│       │   └── hf_runner.py  # Hugging Face tokenizer/model 加载，device/dtype 解析与兼容处理
│       └── sampling/
│           ├── __init__.py   # sampling 对外导出
│           └── sampler.py    # token 选择逻辑：greedy decoding 和 temperature sampling
└── tests/
    ├── test_cli.py           # CLI 参数、main 调用链、stdout/stderr stats 测试
    ├── test_engine.py        # 生成循环、EOS、max token、attention mask、输入校验测试
    ├── test_hf_runner.py     # device/dtype 解析、HF 加载兼容 fallback、可选依赖隔离测试
    └── test_sampling.py      # greedy/temperature sampling 和异常 logits/temperature 测试

很简单的实现，基本满足了最小可运行链路：CLI→模型加载→Engine Decode循环→Sample。下面我们来看看实际的推理过程是怎样的

推理

这一次我们最需要关注的只有两个东西：

1. 模型

2. Tokenizer

我们用一次推理的过程来看看整体都发生了什么，我们通过以下命令来触发单次推理：

(base) gpu-A100-05 nanoLLMServe # export MODEL=/data2/nanoLLMServe/models/Qwen3-8B
(base) gpu-A100-05 nanoLLMServe # CUDA_VISIBLE_DEVICES=0 PYTHONPATH=src /data/anaconda3/bin/python -m nanollmserve.cli.generate \
  --model "$MODEL" \
  --local-files-only \
  --prompt "Explain KV cache in one sentence." \
  --max-new-tokens 100 \
  --temperature 0 \
  --device cuda \
  --dtype bfloat16 \
  --show-stats
Loading checkpoint shards: 100%|███████████████████████████████████████████████████████████████████████████████████████| 5/5 [00:00<00:00, 136.32it/s]
 KV cache is a technique used in transformer models to store the keys and values of previous attention computations, allowing the model to efficiently process sequential data by reusing these cached values instead of recalculating them for each new input token.
KV cache is a technique used in transformer models to store the keys and values of previous attention computations, allowing the model to efficiently process sequential data by reusing these cached values instead of recalculating them for each new input token.
Okay, I need to explain what a
prompt_tokens=8 generated_tokens=100 elapsed_seconds=3.932 tokens_per_second=25.43 device=cuda dtype=bfloat16

稍微解释一下这些参数都是什么意义

然后输出的结果是

 KV cache is a technique used in transformer models to store the keys and values of previous attention computations, allowing the model to efficiently process sequential data by reusing these cached values instead of recalculating them for each new input token.
KV cache is a technique used in transformer models to store the keys and values of previous attention computations, allowing the model to efficiently process sequential data by reusing these cached values instead of recalculating them for each new input token.
Okay, I need to explain what a

这就是推理过程，这个就是最原始最裸的模型输出，和我们平时感受差别很大，因为现在还没有任何的instruction，没有任何的system prompt来harness模型的输出，这些后续我们都会陆续加上

至于最后的

prompt_tokens=8 generated_tokens=100 elapsed_seconds=3.932 tokens_per_second=25.43 device=cuda dtype=bfloat16

就是相关的统计信息，输入的Explain KV cache in one sentence. 被tokenizer切成了8个token；然后实际生成了100个新token；耗时3.932秒；吞吐是每秒25.43个token

有了全局的认知，我们来看看这期间重要的阶段发生了什么

1. CLI入口

src/nanollmserve/cli/generate.py:31

loaded = load_model_and_tokenizer(
    args.model,
    device=args.device,
    dtype=args.dtype,
    local_files_only=args.local_files_only,
)
result = generate_one(
    loaded.model,
    loaded.tokenizer,
    args.prompt,
    max_new_tokens=args.max_new_tokens,
    temperature=args.temperature,
    seed=args.seed,
)

这边就做了2件事情：

1. 加载模型和tokenizer

2. 把模型和tokenizer交给generate_one去做单次推理

2. 加载模型和Tokenizer

src/nanollmserve/model/hf_runner.py:49

resolved_device = resolve_device(device) # resolve_device("cuda") -> cuda
resolved_dtype = resolve_dtype(dtype, device=resolved_device) # resolve_dtype("bfloat16") -> torch.bfloat16

tokenizer = AutoTokenizer.from_pretrained( # 加载tokenizer
    model_path, # /data2/nanoLLMServe/models/Qwen3-8B
    local_files_only=local_files_only,
)

model = AutoModelForCausalLM.from_pretrained( # 加载模型
    model_path,
    dtype=resolved_dtype,
    local_files_only=local_files_only,
)

model.to(resolved_device) # model.to("cuda") 把模型权重搬到GPU0卡显存内
model.eval() # 模型切换到推理模式，还有model.train()训练模式

我们这边采用了hf的transformers库来加载模型和Tokenizer（AutoTokenizer和AutoModelForCausalLM）。其中tokenizer会去读取

/data2/nanoLLMServe/models/Qwen3-8B/tokenizer_config.json
/data2/nanoLLMServe/models/Qwen3-8B/tokenizer.json

如果有需要fallback才会去读取vocab.json和merges.txt，否则这两个配置就足够了

模型加载则是读取对应的模型结构配置和safetensor文件：

config.json
model.safetensors.index.json
model-00001-of-00005.safetensors
model-00002-of-00005.safetensors
model-00003-of-00005.safetensors
model-00004-of-00005.safetensors
model-00005-of-00005.safetensors

在STDOUT我们可以看到有输出一行

Loading checkpoint shards: 100%|███████| 5/5 [00:00<00:00, 136.32it/s]

这个就是读取了5个权重分片。

另外这边我们手动制定了使用bfloat16，和float16一样都是占用2bytes（但是因为指数位和精度位更小，所以计算量更小，但是同时效果损失不大），这里我们可以估算大概（还有一些其他的消耗）的显存消耗为：

8B2Bytes=810^92Bytes/1024^3=~16G*

最后就是把已经加载到CPU内存的模型送到GPU显存里

model.to(resolved_device) # model.to("cuda") 把模型权重搬到GPU0卡显存内
model.eval() # 模型切换到推理模式，还有model.train()训练模式

也就是我们前面在做AutoModelForCausalLM.from_pretrained 的时候，模型已经从磁盘里的权重文件被加载到CPU内存里按模型结构和配置构建好了，所以整机的内存一般都很大，否则加载进来都是个问题。但是因为CPU计算并行度不够，太慢了，所以仍然需要把模型送到GPU显存里，在GPU的计算核心里并行的计算。

简单看这个表格，我们就能看到整机内存都是1T以上的这种级别，和我们认知里的电脑或者服务器里32GB/64GB/128GB已经不是一个纬度的了。另外这里值得留意的是PCIe、NVLINK和HBM的速度差异

         [ GPU Compute ]
                │
                │ 超高速
                ▼
        HBM3 ~3000 GB/s
                │
                │
      ┌─────────┴─────────┐
      │                   │
      ▼                   ▼
 NVLink 900 GB/s     PCIe 64 GB/s
      │                   │
      ▼                   ▼
 Other GPUs           CPU RAM

这个在成熟的Infra里尤其重要，因为Infra解决的正是通信问题，现在模型推理里最重要的问题不是算力，而是传输速度，很多时候都是在等待传输导致计算的利用率不能最大化拉满，效率不足就会有闲置。现在NVIDIA的护城河也是其做到诸如NVL72这种整机柜，让72张GPU尽可能像一张GPU一样协同工作

题外话，就当提前了解有个全局的认知。我们继续

3. Prompt编码并送到GPU

src/nanollmserve/engine/engine.py:68

encoded = tokenizer(prompt, return_tensors="pt")
encoded = _move_batch_to_device(encoded, device)
input_ids = encoded["input_ids"]
attention_mask = encoded.get("attention_mask")

这里基本上做的就是把输入的提示词去做tokenizer，然后送到GPU里，大概行为类似这样：

"Explain KV cache in one sentence."
  -> tokenizer
  -> input_ids: shape [1, 8]
  -> attention_mask: shape [1, 8]
  -> .to(cuda)

搬到GPU后，就可以和前面已经搬到GPU显存里的模型参数一起做推理计算了

4. 推理

src/nanollmserve/engine/engine.py:87

with torch.inference_mode():
    for _ in range(max_new_tokens):
        outputs = model(input_ids=input_ids, attention_mask=attention_mask)
        next_logits = outputs.logits[:, -1, :]
        next_token = sample_next_token(
            next_logits,
            temperature=temperature,
            generator=generator,
        )

大体流程是这样的，第三步最后拿到的是token ids，也就是这里第一次的input_ids

Explain KV cache in one sentence.
input_ids = [[849, 735, 6634, 304, 825, 11652, 13, 151645]] # 这边举例，实际的token ids不是这样

此时的shape是[1, 8] ，简单理解含义就是一条请求，请求里有8个token（attention_mask也是同理）

• 1 = batch size，当前只有一个请求（之后我们做到batch推理的时候会更详细展开说明）

• 8 = sequence length，这句话被切成了8个token（btw，模型上下文长度也是叫sequence length，或者说序列长度）

这里我们也会理解一下attention_mask这个东西，这个其实是Padding Mask，不是Decoder里的Causal Mask。假设现在有2个请求需要推理：

1. I love AI
2. Hello

我们走batch推理，为了GPU并行，需要补齐，变成：

1. ["I", "love", "AI"]
2. ["Hello", "[PAD]", "[PAD]"]

这个时候可以看到第二个请求的token数不够，被补齐成一样的长度了，但是实际推理中是不可能去关注补齐的那部分内容，所以需要一个填充掩码来标记

attention_mask = [
  [1, 1, 1],
  [1, 0, 0]
]

这样实际计算中就会把attention score做成负无穷，softmax后的概率约等于0，也就是完全忽略。这边比较算法细节，我暂时不继续深入展开

继续看

outputs = model(input_ids=input_ids, attention_mask=attention_mask)

这里就把token序列和填充掩码一起送入模型了，模型forward后会输出logits，这里的forward就是模型的一次前向计算，大概包含了：

1. token→embedding

2. 经过很多层（transformer layer）

3. attention/MLP不断计算

4. 最后输出logits

最后生成的logits其实就是得到的每个token的预测分数，shape是[batch, seq_len, vocab_size] ，词表vocab_size假设是151936，那么我么这边表现出来的是[1, 8, 151936] ，一个三维张量（tensor），白话讲就是：1个样本，每个样本里有8个token位置，每个token位置对151936个token（词表的所有token）都给出一个分数

第0个样本
  ├── 第0个位置 -> 151936个分数
  ├── 第1个位置 -> 151936个分数
  ├── 第2个位置 -> 151936个分数
  ...
  └── 第7个位置 -> 151936个分数


位置 0：Explain 后面可能是什么
位置 1：Explain KV 后面可能是什么
位置 2：Explain KV cache 后面可能是什么
...
位置 7：完整 prompt 后面可能是什么

所以哪怕我们原来用8个输入的token去生成第9个token，我们仍然要计算一次前面的8个token的logits，这是为了在生成第9个token的时候拥有完整的上下文，这也是Transformer的注意力机制所表达的能力。

然后我们只关系最后的那个token，所以我们只取最后一个位置的logits

next_logits = outputs.logits[:, -1, :]