---
tags: [nanochat, inference, cli, serving]
阶段: 09-推理Engine与工具
难度: ★★☆
created: 2026-10-22
related: "[[自回归解码与prefill-decode]], [[工具调用与Python沙箱]], [[部署与成本]], [[模型推理优化]]"
---

# CLI与WebUI

## 定义

**命令行界面**（command-line interface，CLI）是以标准输入输出为通道、由进程直接持有模型与会话状态的交互形态。nanochat 的实现是 `scripts/chat_cli.py`：它加载一个检查点，把用户输入拼成对话 token，调用 `Engine.generate` 流式解码，把 token 逐个打印，再把本轮回复并入历史。**Web 界面**（Web UI）是以 HTTP 为通道、由服务进程同时服务多个客户端、以流式响应逐段推送 token 的交互形态。当前 master 没有内置 Web 服务，`scripts/` 下只有 `chat_cli.py`、`chat_eval.py` 等 9 个脚本，没有 `chat_web.py`。

术语定义如下。

| 术语 | 含义 |
|---|---|
| 会话（session） | 一段持续的多轮对话，包含历史 token、生成参数与（可选的）KV 缓存 |
| 流式解码（streaming decoding） | 每生成一个 token 就立即发送，而不是等整段回复完成 |
| SSE | Server-Sent Events，HTTP 响应体按空行分帧的单向流 |
| TTFT | 从请求到达服务端到客户端收到第一个 token 的时间 |
| 限流（rate limiting） | 对并发请求数、token 预算或请求频率设上限，防止单个客户端占满 GPU 与显存 |

## 为什么重要

CLI 是 nanochat 交付链的最后一米：`runs/speedrun.sh` 训练完模型后，README 给出的验证方式就是 `python -m scripts.chat_cli`。它把前面八个阶段的产物变成一个可以对话的进程，也暴露了推理路径的全部工程约束：对话历史如何拼接、特殊 token 如何插入、生成何时停止、结束时如何补齐 `<|assistant_end|>`。这些约束在 CLI 里由几十行代码固定下来，任何 Web 封装都必须复现同一套 token 协议，否则模型看到的输入分布与训练时不一致，回复质量会无声地下降。

Web 封装解决的是另一组问题。CLI 假定一个进程只有一个用户、一次只有一轮生成、标准输出是唯一的消费者；Web 服务要同时处理多个会话、在客户端断开时释放显存、在 GPU 过载时拒绝请求、在公网上认证与限流。这些不是模型问题，而是状态归属与资源配额问题：会话历史属于谁、KV 缓存在什么时候分配与释放、并发上限由什么决定。若不做这层工程，直接把 `engine.generate` 挂到一个 HTTP 端点上，会得到三个后果：并发请求各自分配缓存导致显存峰值叠加；客户端取消后生成器未关闭导致缓存滞留；单请求无长度上限导致 GPU 被一个长提示占满。

在「懂原理、能复现、懂工程」三项中，本篇属于第三项：它不引入新的模型公式，只把 [[自回归解码与prefill-decode]] 的生成器协议接到进程边界与网络边界上。成本侧的换算见 [[部署与成本]]，工具调用的安全边界见 [[工具调用与Python沙箱]]。

## 原理与推导

### 1 `chat_cli.py` 的参数与加载链路

`scripts/chat_cli.py` 用 `argparse` 定义 7 个参数。

| 参数 | 默认值 | 作用 |
|---|---|---|
| `-i` / `--source` | `sft` | 选择检查点来源；`load_model` 把它映射到 `base_checkpoints`、`chatsft_checkpoints`、`chatrl_checkpoints` |
| `-g` / `--model-tag` | `None` | 指定模型目录；为空时 `find_largest_model` 按 `d<数字>` 取最大深度，若都不匹配则取最近修改的一个 |
| `-s` / `--step` | `None` | 指定检查点步数；为空时 `find_last_step` 取最后一个 |
| `-p` / `--prompt` | 空串 | 非空时只回答一次并退出，不再读标准输入 |
| `-t` / `--temperature` | `0.6` | 采样温度 |
| `-k` / `--top-k` | `50` | top-k 截断 |
| `--device-type` | 空串 | `cuda`、`cpu`、`mps`；为空时自动检测 |

加载链路是：`compute_init(device_type)` 初始化设备与分布式上下文，`load_model(source, device, phase="eval", model_tag=None, step=None)` 读取检查点并构建模型，`Engine(model, tokenizer)` 包装成推理入口。`load_model` 的目录映射写在 `nanochat/checkpoint_manager.py` 中，`source` 只接受 `base`、`sft`、`rl` 三个键；传入其它值会在字典查找处抛 `KeyError`。CLI 的帮助文本写的是 `sft|rl`，但底层支持 `base`，用它可以直接和预训练模型对话，观察 base 与 chat 模型的行为差异。

生成参数里没有暴露 `max_tokens`：CLI 把它硬编码为 256。这个值小于训练上下文 2048，意味着单轮回复被截断的概率不低；截断后代码会补上 `<|assistant_end|>`，保证历史格式合法。`num_samples` 固定为 1。

### 2 对话 token 的拼接

对话状态是一个 `list[int]`，初始为 `[bos]`。每轮用户输入到达时，追加三个片段：

```python
conversation_tokens.append(user_start)
conversation_tokens.extend(tokenizer.encode(user_input))
conversation_tokens.append(user_end)
conversation_tokens.append(assistant_start)
```

然后调用 `engine.generate(conversation_tokens, **generate_kwargs)`，其中 `generate_kwargs` 含 `num_samples=1`、`max_tokens=256`、`temperature` 与 `top_k`。生成结束后，把本轮回复的 token 追加到历史；若最后一个 token 不是 `<|assistant_end|>`，先补一个再追加。最终历史形如

```text
[bos]
  <|user_start|> Hello <|user_end|> <|assistant_start|> Hi! How can I help? <|assistant_end|>
  <|user_start|> How are you? <|user_end|> <|assistant_start|>
```

这个格式与 `nanochat/tokenizer.py` 的 `render_conversation` 一致：BOS 在开头，user 段被两个定界符包住，assistant 段以 `<|assistant_start|>` 开始、以 `<|assistant_end|>` 结束。CLI 没有 system message 的处理，也没有工具输出段的构造；它只覆盖纯文本多轮对话。

每一轮都重新调用 `engine.generate`，而 `Engine.generate` 每次都新建 `KVCache` 并对完整历史做 prefill。因此第 $k$ 轮的计算量与前 $k-1$ 轮的历史长度成正比，总成本随轮数超线性增长。CLI 没有做历史截断：当历史长度超过训练上下文 2048 时不会报错，模型仍会继续生成，但位置编码与注意力窗口都超出了训练分布，回复质量下降；当单次 prefill 的长度超过旋转缓存 `rotary_seq_len = sequence_len * 10 = 20480` 时，`GPT.forward` 的 `T <= self.cos.size(1)` 断言才会失败。若历史是在解码过程中逐步超过 20480，则每步只送入一个 token，断言不会触发，但 RoPE 切片会越界并产生未定义行为。生产封装必须在拼接前做窗口截断，且应按完整轮次截断而不是从中间切断。

### 3 流式解码与输出

`Engine.generate` 每次 `yield` 一列 token 与一列 mask；CLI 取第 0 行、把单个 token 解码成文本并立即打印：

```python
for token_column, token_masks in engine.generate(conversation_tokens, **generate_kwargs):
    token = token_column[0]
    response_tokens.append(token)
    token_text = tokenizer.decode([token])
    print(token_text, end="", flush=True)
```

`tokenizer.decode` 直接调用 tiktoken 编码器的 `decode`。BPE 的 token 是字节片段，一个多字节 UTF-8 字符可能被拆到两个 token 中；逐 token 解码时，第一个 token 的字节序列不完整，tiktoken 会用替换字符 U+FFFD 代替，第二个 token 再补上剩余字节，输出中就会出现一个无法还原的替换符。英文 ASCII 输出不受影响，中文、表情与部分符号会受影响。正确的流式解码应累积字节、只在字节序列构成完整 UTF-8 字符时输出；CLI 没有做这一层缓冲，因此它的流式输出只保证「近似正确」。

逐 token 打印还意味着输出速度就是 TPOT：用户看到的文本增长速度等于解码速度，而不是等整段生成完成。这是流式的价值，也是它的代价：任何一步的停顿都会直接可见。

### 4 交互循环与退出条件

主循环的行为由四个分支决定。

第一，`args.prompt` 非空时，每轮都使用同一个提示，生成一次后 `break`，进程退出。这适合脚本化调用与快速验证。

第二，标准输入读到 `quit` 或 `exit`（大小写不敏感）时打印 `Goodbye!` 并退出；读到 `EOFError` 或 `KeyboardInterrupt` 时也打印 `Goodbye!` 并退出。

第三，读到 `clear` 时把 `conversation_tokens` 重置为 `[bos]`，打印 `Conversation cleared.`，继续下一轮。

第四，空输入被忽略，循环继续。

启动时打印的横幅是固定的五行：`NanoChat Interactive Mode`、50 个连字符、`Type 'quit' or 'exit' to end the conversation`、`Type 'clear' to start a new conversation`、50 个连字符。这些字符串是 CLI 的可见契约，包装脚本若解析输出，应按它们定位。

### 5 当前 master 没有内置 WebUI

这一点必须显式说明，因为网上关于 nanochat 的材料跨越多个版本，容易把历史文件当成现状。当前快照的证据有三条。

第一，`scripts/` 目录只有 9 个文件：`base_eval.py`、`base_train.py`、`chat_cli.py`、`chat_eval.py`、`chat_rl.py`、`chat_sft.py`、`infer_bench.py`、`tok_eval.py`、`tok_train.py`，没有 `chat_web.py`。

第二，README 的 File structure 一节逐个列出 `scripts/` 下的文件与用途，同样没有 Web 入口；它给出的对话方式是 `python -m scripts.chat_cli`。

第三，`dev/LOG.md` 的 2026-03-04 条目在列举「移除 autocast 时被修改的文件」时仍提到 `chat_web.py`。这说明该文件在更早的版本中存在过，但在当前快照里已经被删除。不能据此认为 master 仍带 WebUI，也不能凭记忆补出一个 `chat_web.py` 的命令行参数。

因此，任何 Web 能力都需要自己封装。下面给出一个最小方案，它的目标不是生产可用，而是把「HTTP → Engine → SSE」的边界走通，并把并发、缓存生命周期与安全边界标出来。

### 6 最小 WebUI：FastAPI + SSE

整体结构是三层：加载一次模型与 `Engine` 的进程内单例；按 `session_id` 维护历史与锁的会话表；把 `Engine.generate` 的同步生成器包成异步 SSE 响应。

```python
import asyncio, json, os
from contextlib import asynccontextmanager

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import StreamingResponse

from nanochat.common import compute_init
from nanochat.checkpoint_manager import load_model
from nanochat.engine import Engine

MAX_CTX, MAX_NEW = 2048, 256
API_KEY = os.environ.get("NANOCHAT_API_KEY")

@asynccontextmanager
async def lifespan(app):
    _, _, _, _, device = compute_init("cuda")
    model, tokenizer, _ = load_model("sft", device, phase="eval")
    app.state.engine = Engine(model, tokenizer)
    app.state.tokenizer = tokenizer
    app.state.bos = tokenizer.get_bos_token_id()
    app.state.assistant_end = tokenizer.encode_special("<|assistant_end|>")
    app.state.sessions = {}
    app.state.gpu = asyncio.Semaphore(2)   # 同时最多两条流
    yield

app = FastAPI(lifespan=lifespan)

def get_session(state, sid):
    if sid not in state.sessions:
        state.sessions[sid] = {"tokens": [state.bos], "lock": asyncio.Lock()}
    return state.sessions[sid]

@app.post("/chat")
async def chat(request: Request):
    if API_KEY and request.headers.get("authorization") != f"Bearer {API_KEY}":
        raise HTTPException(401, "unauthorized")
    body = await request.json()
    try:
        sid, message = body["session_id"], body["message"]
    except (KeyError, TypeError):
        raise HTTPException(422, "session_id and message are required")
    if not isinstance(sid, str) or not isinstance(message, str):
        raise HTTPException(422, "session_id and message must be strings")
    state, tok = request.app.state, request.app.state.tokenizer
    message_ids = tok.encode(message)
    if len(message_ids) > 512:
        raise HTTPException(413, "message too long")
    sess, engine = get_session(state, sid), state.engine
    if sess["lock"].locked():
        raise HTTPException(429, "session busy")
    await sess["lock"].acquire()
    try:
        await asyncio.wait_for(state.gpu.acquire(), timeout=5.0)
    except asyncio.TimeoutError:
        sess["lock"].release()
        raise HTTPException(503, "gpu busy")
    history = sess["tokens"]
    if len(history) + len(message_ids) + 2 > MAX_CTX - MAX_NEW:
        state.gpu.release(); sess["lock"].release()
        raise HTTPException(409, "context full")
    mark = len(history)
    history += [tok.encode_special("<|user_start|>"), *message_ids,
                tok.encode_special("<|user_end|>"), tok.encode_special("<|assistant_start|>")]

    async def sse():
        produced, done = [], False
        gen = engine.generate(history, num_samples=1, max_tokens=MAX_NEW, temperature=0.6, top_k=50)
        def step():
            try:
                return next(gen)
            except StopIteration:
                return None
        try:
            while True:
                if await request.is_disconnected():
                    break
                item = await asyncio.to_thread(step)
                if item is None:
                    break
                column, _ = item
                produced.append(column[0])
                chunk = tok.decode([column[0]])
                yield f"data: {json.dumps({'token': chunk}, ensure_ascii=False)}\n\n"
            if not produced or produced[-1] != state.assistant_end:
                produced.append(state.assistant_end)
            history.extend(produced)
            done = True
            yield f"data: {json.dumps({'done': True, 'tokens': len(produced)})}\n\n"
        finally:
            if not done:
                del history[mark:]
            gen.close()
            state.gpu.release()
            sess["lock"].release()

    return StreamingResponse(sse(), media_type="text/event-stream",
                             headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
```

这段代码有五个工程要点。

第一，模型只加载一次。`lifespan` 里的 `load_model` 与 `Engine` 在所有请求之间共享；`Engine` 本身不保存对话状态，状态在 `sessions` 里。

第二，`asyncio.to_thread(step)` 把同步的 `next(gen)` 放到工作线程，避免阻塞事件循环。工作线程每次只推进一步，不会长时间占住线程池。代价是 `use_calculator` 的 `signal.signal` 只能在主线程注册，工作线程中的工具调用会静默返回 `None`；若要在 Web 场景保留计算器，应把生成放进独立进程，或在主线程串行执行。

第三，`gen.close()` 必须放在 `finally`。客户端断开时 `is_disconnected()` 返回真，循环 `break`，但生成器仍持有解码缓存；不关闭就要等垃圾回收，显存峰值按并发流数量叠加。关闭后 `KVCache` 才可回收。

第四，会话锁与全局信号量分工不同。会话锁保证同一会话的请求串行，避免两轮回复交错写入同一历史；全局信号量限制同时占用 GPU 的流数量，把显存峰值控制在可预算范围内。超过 5 秒拿不到信号量返回 503，而不是无限排队。

第五，`done` 标志与 `mark` 处理异常与取消：发生异常时历史回滚到本轮之前，不会留下半个 user 段加 `<|assistant_start|>` 的残缺结构；客户端正常断开时保留已生成的部分并补齐 `<|assistant_end|>`，若希望丢弃半截回复，应在 `break` 分支把 `done` 保持为 `False` 并主动回滚。另外，若响应从未开始迭代，框架不保证执行异步生成器的 `finally`，生产实现应在端点层注册 `BackgroundTask` 或在中间件里兜底释放信号量与锁。

对应的客户端调用是：

```bash
curl -N -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NANOCHAT_API_KEY" \
  -d '{"session_id":"demo","message":"Why is the sky blue?"}'
```

预期响应是逐帧的 `data: {"token": "The"}` 形式，每一帧一个 SSE 事件，最后一帧为 `data: {"done": true, "tokens": 42}`。`-N` 关闭 curl 的缓冲，否则 SSE 会被攒成一次性输出。

### 7 并发与 KV Cache 生命周期

`Engine` 的构造函数只保存 `model` 与 `tokenizer`，不保存对话或缓存；`RowState` 与 `KVCache` 都在 `generate` 调用内部创建。因此当前实现中每个请求的缓存是独立的，一个 `Engine` 实例可以被多个请求共享；「每会话一个 `Engine` 实例」并不会复制权重（它们指向同一模型），也不会带来额外的缓存隔离，因为缓存本来就不在 `Engine` 上。

真正需要按会话隔离的是三样东西：历史 token、会话锁、以及如果要做跨轮缓存复用时的 `KVCache`。`KVCache` 的 `cache_seqlens` 与 `prev_embedding` 是单会话状态：两个会话共用一个缓存，第二个会话的 `prefill` 会覆盖第一个的位置与 smear 状态，注意力会读到别人的键值。因此一旦把「每轮重新 prefill」改成「复用上一轮的缓存」，就必须每会话一个缓存句柄，并且会话结束时显式释放。

Web 场景所说的「每会话独立引擎实例」应理解为「每会话独立的会话对象」：历史、锁、生成参数与可选的 `KVCache` 都归属该会话，而模型权重通过引用共享，不复制。当前代码里 `Engine` 只保存 `model` 与 `tokenizer`，多个会话共用一个实例也能正确工作；但生产部署若要避免每轮重新 prefill，就需要把 `KVCache` 从 `generate` 内部移到会话对象上，此时一个会话一个缓存（通常也意味着一个绑定该缓存的引擎包装）是硬性要求。限流则限制同时存活的会话缓存数量与总 token 预算，防止 N 个会话把显存与带宽吃满；没有限流时，单用户的并发请求就足以让显存峰值失控。

按当前实现，一个 2048 上下文的流在解码阶段占用约 288 MiB 的 KV 缓存（d24、bf16），预填充阶段另有一份长度为提示的临时缓存。两条并发流约 0.6 GiB，八条约 2.3 GiB；加上 d24 权重约 3.94 GiB 与激活、CUDA 上下文，24 GB 卡在八条流以内是可行的，但这只是容量账。吞吐账更差：每条流各自做 batch=1 的前向，权重被重复读取，GPU 带宽利用率低。nanochat 没有连续批处理（continuous batching）与跨请求调度器，`Engine.generate` 的 `num_samples` 只支持同一提示的多行采样，不支持把不同会话的 decode 步合并成一批。因此 Web 封装能做的只有限流与排队；要提升吞吐，需要改 `Engine` 的接口，把多个会话的当前位置与缓存交给一个批调度器。

### 8 安全边界

最小方案只解决了「能跑」，安全边界需要另外补。

| 风险 | 措施 |
|---|---|
| 未认证访问 | Bearer token 或反向代理的认证；默认只监听 `127.0.0.1` |
| 请求体过大 | 限制 `Content-Length`，限制消息 token 数（示例为 512） |
| 上下文耗尽 | 服务端按轮次截断历史，或在超限时返回 409；不能依赖客户端自觉 |
| GPU 显存耗尽 | 并发信号量、每请求 `max_tokens` 上限、队列超时 |
| 会话串扰 | 每会话锁与独立历史；不要把 `session_id` 交给客户端任意指定而不校验归属 |
| 会话表无限增长 | 为会话设置 TTL 与最大数量，定期清理空闲历史；否则内存随会话数增长 |
| 输出注入 | 前端用 `textContent` 渲染，禁止把模型输出当 HTML；SSE 帧用 JSON 编码 |
| 工具执行 | 计算器白名单风险较低；若要接入 `execution.py`，先读 [[工具调用与Python沙箱]] 的边界表 |
| 错误泄露 | 不要把 traceback、检查点路径、GPU 型号返回给客户端 |
| 滥用 | 按 IP 或用户做请求频率与 token 预算限流；记录审计日志 |

认证与限流不是模型能力的一部分，但它们决定了服务能否暴露到公网。一个只做演示的服务可以只监听本机；一个对外开放的服务至少需要认证、TLS、请求大小限制与并发上限四项。

### 在 nanochat 中的落地

| 位置 | 作用 | 关键细节 |
|---|---|---|
| `scripts/chat_cli.py` 的 argparse | 七个参数 | `source`、`model-tag`、`step`、`prompt`、`temperature`、`top-k`、`device-type` |
| 同一文件的对话循环 | 拼接与流式 | 每轮重新拼接完整历史，`max_tokens=256`，结束时补 `<\|assistant_end\|>` |
| `nanochat/checkpoint_manager.py` 的 `load_model` | 检查点映射 | `base`/`sft`/`rl` 三个目录，`model_tag` 与 `step` 为空时猜测 |
| `nanochat/engine.py` 的 `Engine.generate` | 生成器 | CLI 只消费第 0 行，`token_masks` 未使用 |
| `scripts/chat_web.py` | 不存在 | 当前 master 没有 WebUI，需要按本篇方案自建 |

这张表也说明了封装的边界：CLI 只覆盖纯文本多轮对话，不处理工具输出段、不做上下文截断、不做认证与限流；这些缺口在 Web 封装中必须补齐。

## 关键直觉

> [!tip] 机制性直觉
> CLI 与 Web 的差异不在模型，而在状态归属与资源配额：CLI 把「一个进程、一个会话、一次生成」当作默认前提，Web 必须把这三件事拆开，分别交给会话表、锁与信号量。`Engine` 是无状态的执行器，`KVCache` 是有状态的数据，二者混在同一个对象上时，并发才会出错；把缓存从 `Engine` 里移到会话对象上，问题就变成「谁分配、谁释放、上限多少」的资源管理问题。

这一直觉与严格定义的关系：会话是历史与参数的容器，不是模型的副本；限流是对并发缓存与带宽的预算，不是对模型能力的限制。把「每会话一个引擎」理解为「每会话一份缓存与历史」，才是当前代码下可实现的隔离。

## 例子与代码

### 例 1：一次真实交互的命令与输出结构

```bash
python -m scripts.chat_cli -i sft -p "Why is the sky blue?" -t 0.6 -k 50
```

预期输出结构（回复文本随模型与检查点变化，结构固定）：

```text

NanoChat Interactive Mode
--------------------------------------------------
Type 'quit' or 'exit' to end the conversation
Type 'clear' to start a new conversation
--------------------------------------------------

Assistant: The sky appears blue because air molecules scatter shorter wavelengths of sunlight more strongly than longer ones.
```

注意三点：第一，`-p` 模式下不会打印 `User:`，因为用户输入来自命令行而不是 `input()`；第二，`Assistant: ` 前有一个空行，来自 `print("\nAssistant: ", end="", flush=True)`；第三，输出结束后进程直接退出，不进入交互循环。若去掉 `-p`，则会进入 `User:` 提示符，`quit` 与 `clear` 生效。

### 例 2：多轮历史的 token 形态

```python
def append_turn(history, tok, user_text, reply_tokens):
    history.append(tok.encode_special("<|user_start|>"))
    history.extend(tok.encode(user_text))
    history.append(tok.encode_special("<|user_end|>"))
    history.append(tok.encode_special("<|assistant_start|>"))
    history.extend(reply_tokens)
    if not reply_tokens or reply_tokens[-1] != tok.encode_special("<|assistant_end|>"):
        history.append(tok.encode_special("<|assistant_end|>"))
    return history
```

这个函数是 `chat_cli` 拼接逻辑的最小复现。`reply_tokens` 为空时也要补 `<|assistant_end|>`，否则下一轮的 assistant 段没有闭合，`render_conversation` 的奇偶校验会在训练侧失败；CLI 里因为 `Engine` 至少产出一个 token，`response_tokens[-1]` 不会越界，但封装层不应依赖这一点。

### 例 3：用 `curl` 验证 SSE 分帧

```bash
curl -N -s -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"session_id":"demo","message":"hello"}' | head -5
```

预期前几行形如

```text
data: {"token": "Hello"}
data: {"token": "!"}
data: {"token": " How"}
data: {"token": " can"}
data: {"token": " I"}
```

若输出被攒成一行，检查反向代理是否开启了缓冲；Nginx 需要 `proxy_buffering off;`，代码里已用 `X-Accel-Buffering: no` 提示。若第一帧迟迟不到，TTFT 由 prefill 与排队决定，而不是由 `curl` 决定。

## 易错点

> [!warning] 常见错误
> 1. 以为 master 带 WebUI。当前 `scripts/` 没有 `chat_web.py`，README 的文件结构也没有 Web 入口；`dev/LOG.md` 里的历史提及只说明它曾经存在。不要凭旧版本材料写命令或参数。
> 2. 每轮重新拼接却忘了补 `<|assistant_end|>`。生成长度达到 256 时最后一个 token 通常不是终止符，不补会让历史结构在下一轮失效；CLI 的 `if response_tokens[-1] != assistant_end` 就是为此。
> 3. 逐 token `tokenizer.decode` 处理中文。多字节 UTF-8 被拆开时会产生 U+FFFD；流式输出需要字节缓冲或增量解码器，CLI 没有做。
> 4. 把 `Engine` 当会话对象，或在 `StreamingResponse` 里直接 `break` 而不 `close` 生成器。前者会误以为缓存跨请求复用，后者会让缓存与生成器栈帧滞留到垃圾回收；高并发下显存峰值按未关闭的流数量增长。
> 5. 在线程池里调用工具链。`signal.signal` 只能注册在主线程，`use_calculator` 在工作线程中会返回 `None`；需要工具能力时应使用独立进程或主线程串行生成。
> 6. 只做会话锁不做全局并发上限。会话锁只保证同一会话不交错，多个会话仍可同时分配缓存；没有全局信号量时，N 个并发请求就是 N 份 KV 缓存。

## 关联笔记

- 前置：[[自回归解码与prefill-decode]] —— CLI 的流式循环直接消费 `Engine.generate` 的 `(token_column, token_masks)`，生成器协议在该篇。
- 前置：[[工具调用与Python沙箱]] —— CLI 会触发计算器路径；Web 场景下线程与信号限制、沙箱边界的讨论在该篇。
- 后续：[[部署与成本]] —— 并发数、上下文长度与 batch 决定显存与每百万 token 成本；Web 服务的限流参数应从这些量反推。
- 跨库：[[模型推理优化]] —— 连续批处理、KV 分页与请求调度的通用方案见该篇，本篇只讲当前 `Engine` 的能力边界。
- 跨库：[[Harness与Loop工程]] —— 会话状态、工具循环与流式接口的通用工程模式见该篇，本篇只保留 nanochat 的最小实现。

## 达标检测

- [ ] 能列出 `chat_cli.py` 的 7 个参数与默认值，并说明 `-p`、`-i`、`-g`、`-s` 的作用。
- [ ] 能写出多轮对话的 token 形态，说明为什么每轮都要以 `<|assistant_start|>` 开始、以 `<|assistant_end|>` 结束。
- [ ] 能解释为什么生成长度达到上限时必须手动补 `<|assistant_end|>`，以及不补的后果。
- [ ] 能指出当前 master 没有 WebUI 的三条证据，并说明历史版本提及不能作为现状依据。
- [ ] 能画出 FastAPI 方案的三层结构（模型单例、会话表、SSE 流），并说明每层保存什么状态。
- [ ] 能解释 `gen.close()` 与 `finally` 在客户端断开时的作用，以及不关闭的显存后果。
- [ ] 能说明会话锁与全局信号量的分工，以及为什么当前 `Engine` 不适合直接做多会话共享缓存。
- [ ] 能给出至少五条 Web 安全措施，并指出哪一条与工具执行直接相关。

## 参考来源

- Karpathy, *nanochat*（commit 92d63d4），`scripts/chat_cli.py`、`nanochat/engine.py`、`nanochat/checkpoint_manager.py`、README 的 File structure —— 本篇参数、拼接逻辑、输出字符串与「无 WebUI」结论的事实来源。
- Karpathy, *nanochat* `dev/LOG.md`（2026-03-04 Remove autocast 条目）—— `chat_web.py` 历史存在的唯一间接证据。
- FastAPI 文档, *StreamingResponse* 与 *Lifespan Events* —— 对应 SSE 响应与模型单例加载的实现方式。
- Python 文档, *asyncio — Asynchronous I/O*（`to_thread`、`Semaphore`、`wait_for`）—— 对应同步生成器与事件循环的桥接、并发上限与超时。
- PyTorch 文档, *torch.inference_mode* —— `Engine.generate` 的推理模式语义，对应缓存与自动求导的关闭。
