刚好最近在重新盘点审视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, :]

对应到

[1, 8, 151936]
[:, -1, :]

得到

[1, 151936]

这个就是最后一个位置（从0开始，就是位置7）对于词表里所有的token的预测分数，有了这个我们就可以得到预测的下一个token了，这边我们要进入到一个叫做采样（sample）的阶段

  next_token = sample_next_token(
      next_logits,
      temperature=temperature, # 0
      generator=generator,
  )

  def sample_next_token(logits, *, temperature: float = 0.0, generator=None):
    """Return one next-token tensor from a `[batch, vocab]` logits tensor.

    `temperature <= 0` means greedy decoding. Positive temperatures sample from
    the softmax distribution, matching the first serving concept this milestone
    needs without adding top-k/top-p policy surface yet.
    """

    import torch

    if logits.ndim != 2:
        raise ValueError(f"expected logits with shape [batch, vocab], got {tuple(logits.shape)}")
    if not math.isfinite(temperature):
        raise ValueError("temperature must be finite")

    if temperature <= 0:
        return torch.argmax(logits, dim=-1, keepdim=True)

    probs = torch.softmax(logits / temperature, dim=-1)
    return torch.multinomial(probs, num_samples=1, generator=generator)

采样也就是对下一个token做采样，意思是从概率分布中采样一个token，有很多种采样方式，比如top1，概率最高的那个token，这是一种最基础的方式。这里我们temperature=0的时候就走贪心解码（greedy decoding），我们argmax(logis) 取概率最高的那个token（这里贪心的意思就是每次都拿最大的，完全不考虑后续或者长远的情况）。这里的dim=-1指明logits在最后那个纬度，然后keepdim=True表示为最后保留维度（shape保持不变，前面输入的next_logits是[1, 151936]，argmax处理后默认shape会变为[1]，保留后是[1, 1]），因为这样后续就可以继续把生成的token拼接到input_ids里了

input_ids = torch.cat([input_ids, next_token.to(input_ids.device)], dim=-1)
attention_mask = torch.cat([attention_mask, torch.ones_like(next_token)], dim=-1)

原来的[1, 8] ，生成一个token后next_token shape: [1, 1]，拼接后变成[1, 9] 了，这边有个next_token.to(input_ids.device) ，是把这个送到input_ids所在的GPU卡上，这是自回归生成（LLM autoregressive generation）的核心循环

之后就是再次把新的input_ids送入进行新一轮的forward，不断往复，直到生成100个token就结束了。然后这边我们可以注意到，在做forward的时候都是一次完整的forward：

第 1 轮：
[1, 8]

第 2 轮：
[1, 9]

第 3 轮：
[1, 10]

第 100 轮：
[1, 107]

也就是每轮都会重复计算整段序列的attention，可以轻而易举的想到，我们之前的计算不要重复计算，这样就可以节省大量的算力和时间了，没错，这个就是KV Cache的由来了：

第 1 次：输入完整 prompt，计算并保存 KV cache
第 2 次：只输入新生成的 1 个 token，复用前面的 KV cache
第 3 次：只输入新生成的 1 个 token，继续复用 KV cache
...

这个也是我们后面要去做的。

整个推理的过程大概如下：

prompt
  ↓
forward
  ↓
logits（每个token的分数)
  ↓
argmax（decoding strategy，解码策略，argmax只是一种，还有其他）
  ↓
选出next token
  ↓
拼回输入（input_ids）
  ↓
继续forward

实际的大模型推理中，比较成熟的推理引擎会是这样的流程：

input_ids
    ↓
Transformer forward
    ↓
logits
    ↓
temperature scaling
    ↓
top-k / top-p filtering
    ↓
sampling / argmax
    ↓
next token
    ↓
append to KV cache + input_ids
    ↓
next decoding step

后面随着我们持续深入去实现和迭代，我们也会慢慢往这个方向走的

总结

通过这样一个简单的实现，我们已经有一版勉强能跑的版本，虽然很基础，跑得效果很烂，但是这个已经能帮助我们完全理解一个Infra在帮助模型做推理的过程中需要做的事情，也帮我们埋了一些未来演进方向的点。

要知道vLLM/SGLang这种LLM Infra里的所有主要feature都不是平白无故的造出来的，背后都是有痛点和需求在推动，一批有想法有动手能力的人去做出不同的实现，本质还是服务于参数规模越来越的模型在多GPU、多设备上去做推理，且要持续获得更快、更经济和效果更好的推理

一切的源头还是源于前面我们开源的Open-Computer-Use，背后的故事可以看这篇解决问题的原始冲动。

这次是因为OpenAI的Codex.app上有release出了Browser Use的能力

分析了一下，又有很多收获，也补齐了一些之前未曾主动去了解的认知缺失部分。收获很大，我觉得值得写一篇文章聊一下。行文依然是关注过程重于结果，方法论或者思维的跃迁才是最重要的。

探索

整个探索过程依然和之前在解决问题的原始冲动里分析的是类似的，我们首先依然是拉Harness Template（PS：现在我会用更加便捷的方式harness-cli ：

➜ harness-cli open-browser-use
Select template language:
  1. English
  2. Chinese
Choice [1]: 2
Using Chinese template from https://github.com/iFurySt/harness-template-cn.git
copy 53 file(s)
Initialized git repository

然后开始分析官方的，这样可以把整个探索的过程不断留存下来，未来需要的时候可以不断查询和溯源。

这次的起手是：

➜  cd ~/.codex/plugins/cache/openai-bundled/browser-use
➜  browser-use tree -I 'node_modules'
.
└── 0.1.0-alpha2
    ├── assets
    │   ├── browser.png
    │   └── composer-icon.png
    ├── docs
    │   └── capabilities
    │       ├── browser
    │       │   ├── viewport.md
    │       │   └── visibility.md
    │       └── tab
    ├── scripts
    │   └── browser-client.mjs
    └── skills
        └── browser
            ├── agents
            │   └── openai.yaml
            └── SKILL.md

11 directories, 7 files

可以看到，主要是一个skill+browser-client.mjs这个client。所以我们可以快速从这里分析切入。话不多说，我直接丢一个架构图

总体而言iab（in-app browser）是Codex.app自己抽象的一个浏览器，用windowId+sessionId作唯一id，整体表现为单窗口单会话只有一个浏览器窗口。

展开之前，先聊一点浏览器相关的

Chrome

我们从下往上看，首先是Chromium，是一个开源的浏览器内核项目，Chrome就是基于这个项目构建的商业浏览器，现在市面上很多（AI）浏览器都是基于此二开的。后续我们都统一看待，表述为Chrome。理解好Chrome对于我们在上层构建Browser Use事半功倍，也能很清晰的知道现在各种操作浏览器的手法有什么差异

先丢一张全局的架构图：

里面细节比较多，感兴趣可以扫一眼，这个主要关注点事外围大框。有个大概概念，现在我们一路走下来看看：

首先Chrome是多进程架构的，按照不同的类型用不同的进程来承载。比如浏览器打开一个页面会涉及到诸如以下这些进程

这个我们在Chrome自带的任务管理器里可以看到对应的进程

我们也可以直接命令行统计一下现在的进程情况

这样做的好处是隔离和安全，比如一个tab爆炸对应的进程挂了，也不会影响别的tab页面

安全方面借助进程来实现沙盒隔离的能力，比如Renderer Process着重处理用户输入的进程会限制针对系统文件的访问，这样有助于提高安全性

其中我们最主要关心的还是Browser Process和Renderer Process了。Browser负责全局（进程）调度的大脑，能管理所有的进程。而Renderer Process是负责渲染的，通常情况下每个tab/iframe都是一个独立的进程，也就是所谓的站点隔离（Site Isolation）。因此平时最重要也是进程最多的就是Renderer ，比如一个tab有一个main frame，这个tab里还有2个iframe，这个情况下就会有3个Renderer Process（实际是会受same site影响的）

在此之外，我们需要了解的一个东西是Service Worker，普通的页面都会对应到tab，但是Service Worker是独立在页面之外的，现在的v3浏览器插件基于Service Worker的机制之上了，简单表示为：

Browser Process
 ├── Renderer Process (网页)
 │     ├── DOM
 │     ├── JS
 │     └── 页面逻辑
 │
 └── Service Worker Process
       ├── fetch 拦截
       ├── cache
       ├── push
       ├── background sync
       └── extension background logic

这个后续我们讲浏览器插件里会重点提到。

到这里我们对于Chrome的整体机制有个初步的认知了，我不打算完全讲到透，内容量比较多，对大部分人来说也不一定有价值，有兴趣的可以自己看我最后贴的一些链接自行深入去了解

Codex Browser Use

回归到Codex APP本身的Browser Use能力，主要由Browser Use（iab，应用内部浏览器页面）和Chrome（浏览器插件）组成，还是这张架构图：

两者各有优缺点。Codex通过抽象封装好的browser-client.mjs 去调用，等于对使用方屏蔽了，通过Skill的差异来控制。

这里值得注意的是，Codex内置了node runtime，因此实际使用中可以编排出类似这样的命令去调用：

await tab.goto('https://github.com/iFurySt/open-codex-computer-use/issues');
await tab.playwright.waitForLoadState({ state: 'domcontentloaded', timeoutMs: 15000 });
const snap3 = await tab.playwright.domSnapshot();
const relevant3 = snap3.split('\n').filter(l => /Open|Closed|Issues|issue|No results|open-codex-computer-use|Pull requests|Starred/.test(l));
nodeRepl.write(relevant3.slice(0, 160).join('\n'));

这样可以让使用方进入一种有状态的上下文中，可以不断操作，而不需要反复去获取和定位一些诸如tab和元素等

接下去分别看看两者

IAB(In-App Browser)

这个在Codex.app里表现为Browser Use插件

就是右侧边栏那个内置的网页

这个方案是因为Codex.app本身就是Electron写的，内置的就已经有浏览器的能力了，他的做法是在中间自己抽象了一层业务层，以单个codex.app的窗口（window）+会话（session）唯一对应到一个浏览器页面，这个页面对应到Electron的WebContents，细节对上层屏蔽了。

这里就对应到我们前面聊Chrome里提到的部分，这个对于本身已经有类似产品的，是有不错的参考意义的。不过我不打算展开聊，有需要的人自行深入，有需要或问题也可以email我，我可以分享一些DeepDive时候的一些见解。

iab的一个优点是相对简单，且对于用户来说丝滑一些，直接在APP里就可以预览正在操作的浏览器

但是弊端也很明显：

• 目前设计只能打开一个页面，打开其他页面会顶掉前面的页面
• 内置的无法安装一些浏览器插件，尤其是针对某些操作依赖某些浏览器插件时
• 无法无缝接入用户的浏览器

Chrome Extension

在Codex.app里放在了Computer Use里的Google Chrome（不知道为什么放在这里🤡）

搭配Chrome插件使用

浏览器插件的形态会更加通用，适应力更强。一些Chrome内核的浏览器也都可以用，而且可以做到在浏览器里模拟cursor的操作。

这里不得不提一下OpenAI的巧思，或者说产品力

任务会以分组Group来聚合，这点就非常妙，这个任务下的tab都集中在这个分组，这样任务结束的时候直接整个分组关了就不会污染用户的tab。

在此期间，这些tab都是非激活状态的，也就是这个浏览器插件是具备后台操作能力的，和Computer Use的Background能力一致，非常丝滑的产品体验！

操作过程如果去查看tab，也能看到和Computer Use类似的鼠标悬浮和移动，让人可以直观感受到在做什么

结束后除了收掉Group和内部的tab以外，还有可能出现移交tab到Codex这个通用分组下。这些都是写在skill里的指导。

CDP（Chrome DevTools Protocol）

这个是第三种方式，我不详细展开了，本质上是通过CDP协议去连到Chrome，是最技术的方案，需要Chrome以Remote Debugging / CDP监听的方式去启动的，对于普通用户几乎不可能，对于研发人员接触的比较多。

现在Chrome官方也提供了MCP，以及配套的chrome-devtool-cli。类似Playwright、Selenium、puppeteer本质上都是基于CDP做的。也是最根源的方式，包括很多云端Sandbox里包装了Chrome的也都是通过CDP去交互的

至此我们对于codex拥有的整个浏览器操作已经有了全局的认知了，很多技术细节没有再额外展开，有兴趣的可以按需找AI一点通一下。

Open Browser Use

为什么我们需要一个开源替代方案呢？

• 因为甚至连Codex CLI都无法用Codex.app的这两个Browser Use的能力，我们需要一个平台中立的方案，可以让所有的AI Agent轻易使用，可以让所有的AI应用轻易集成
• 技术实现不等于产品实现。我会尽量用产品的角度来推进这个开源项目，因为技术方案前面CDP一节里提到了好几个，但是他们对于AI开箱即用的能力太弱了，或者他们天然的定位就不是面向AI的。Chrome MCP好一点点，但是也有很多痛点在里面。

Open Browser Use的实现方案和Codex.app的extension路线是一致的，我希望的定位是打造成超集的存在，就是在满足原有的一切能力以外还能有一些额外的能力可以赋能上层业务的开箱即用

https://github.com/iFurySt/open-codex-browser-use

目前是以浏览器插件的形式存在（插件商店版本还在审核，目前直接通过zip/crx安装）

具体使用方式参见GitHub里，这边就不展开赘述了。

尾声

其实这篇文章我愿称之为半成品，因为很多原来我预想和规划的内容我没有完整的展现出来，最近的时间精力也不够完全支撑我写完这篇文章到我满意的程度，但是又不希望因为不完美而不完成，因此还是决定发出来，因为我相信哪怕它不完美，依然可以触达很多的人。做人和做事都是如此，追求完成应是第一要务，在此之上，能追求完美的人，才有机会成为传奇。

回到Codex和OAI本身，OpenAI虽然人才流失了很多，但是依然妨碍不了继续牛逼，或许是组织足够厉害，也可能是现在还在的人里充满了人才，不管怎样，最近这段时间持续给大家递送更好的产品，喜闻乐见。在这背后，也不断激发我对于产品力的思考。

Coding≠Engineering, Technology≠Product.

AI带给我们的很多，但是还有很多东西其（暂时）无法带给我们。我依然相信持续保持好奇心、敢于尝试的勇气，以及立刻行动的执行力，是支撑着我们探索无尽未知的原始动力

References

想了解现代浏览器的可以看Chrome这四篇Post文章，简单易懂：

1. Inside look at modern web browser (part 1)
2. Inside look at modern web browser (part 2)
3. Inside look at modern web browser (part 3)
4. Inside look at modern web browser (part 4)