# 第 27 课：模型转换、OpenAI API 与 WebUI

这一课讲 MiniMind 的部署侧链路：训练脚本产出的原生 PyTorch 权重如何变成 transformers 生态可加载的模型目录，CLI/API/WebUI 又如何复用同一套 tokenizer、chat template 和 `generate` 约定。

本节不讲生产级服务治理。这里的目标是看懂 MiniMind 项目中已有的三个部署入口：模型格式转换、OpenAI 兼容 API、Streamlit WebUI。

## 目录

- [0. 本节主线](#l27-mainline)
- [1. 本节要懂的 6 个原理](#l27-principles)
- [2. 完整原理：部署侧把训练产物包装成可调用接口](#l27-complete-principle)
- [3. 源码阅读顺序图](#l27-reading-order)
- [4. MiniMind 源码走读](#l27-source-walkthrough)
- [5. 本节必须会写 / 暂时不要求](#l27-must-write)
- [6. 实验验证](#l27-experiment)
- [7. 阶段组装](#l27-stage-assembly)
- [8. 本节检查](#l27-check)
- [9. 下一课](#l27-next)

<a id="l27-mainline"></a>
## 0. 本节主线

MiniMind 的部署链路是：

```text
训练得到 out/full_sft_768.pth
-> convert_model.py 把原生 torch state_dict 转成 transformers 模型目录
-> transformers 目录保存 config、tokenizer、chat template、model weights
-> CLI / API / WebUI 用 AutoTokenizer + AutoModelForCausalLM 加载
-> messages 通过 apply_chat_template 变成 prompt 文本
-> tokenizer(prompt) 得到 input_ids / attention_mask
-> model.generate 生成新 token
-> tokenizer.decode 得到 assistant 文本
-> API/WebUI 再把 <think>、<tool_call> 文本协议转成 reasoning_content / tool_calls / 可视化结果
```

一句话：

```text
训练代码负责学会生成协议；
部署代码负责加载权重、套模板、调用 generate、再把文本协议包装成用户能调用的接口。
```

这一课最容易混的三个边界：

```text
模型格式：
  原生 torch 权重是 state_dict；transformers 目录是 config + tokenizer + 权重文件。

聊天协议：
  messages/tools/open_thinking 不是直接喂给模型，而是先由 chat template 渲染成文本 prompt。

接口协议：
  MiniMind 内部生成的是 <think> / <tool_call> 文本；OpenAI API 返回的是 reasoning_content / tool_calls 字段。
```

<a id="l27-principles"></a>
## 1. 本节要懂的 6 个原理

| 原理 | 要理解什么 | 源码位置 |
|---|---|---|
| 转换的本质是保存结构合同和权重 | transformers 目录必须同时有 config、tokenizer、chat template 和模型权重 | `scripts/convert_model.py:16-36`, `scripts/convert_model.py:40-96`, `minimind-3/config.json:1-38` |
| MiniMind 有两种加载路径 | `load_from` 指向 `model` 时走原生 torch 权重；指向模型目录时走 transformers 加载 | `eval_llm.py:12-30`, `scripts/serve_openai_api.py:28-47` |
| API 服务只是把 OpenAI 请求转成本地 generate | request 的 `messages/tools/open_thinking` 先进入 chat template，再生成 token | `scripts/serve_openai_api.py:50-68`, `scripts/serve_openai_api.py:171-225` |
| 部署侧要解析文本协议 | `<think>` 和 `<tool_call>` 是模型生成文本，服务端要转换成 API 字段 | `scripts/serve_openai_api.py:83-102`, `minimind-3/chat_template.jinja:1-11`, `minimind-3/chat_template.jinja:78-84` |
| WebUI 是本地多轮循环 | WebUI 维护 session messages、加载模型、流式生成，并可执行工具后继续生成 | `scripts/web_demo.py:198-209`, `scripts/web_demo.py:239-248`, `scripts/web_demo.py:350-413` |
| 客户端只认 OpenAI 兼容接口 | `chat_api.py` 不关心模型内部结构，只向 base_url 发 chat completions 请求 | `scripts/chat_api.py:3-22`, `scripts/chat_api.py:27-39` |

学完本节，你应该能解释这些对象：

```text
torch state_dict:
  trainer 保存的原生 PyTorch 参数字典，通常位于 out/*.pth。

transformers model directory:
  包含 config.json、tokenizer.json、tokenizer_config.json、model.safetensors 等文件的目录。

chat template:
  把 OpenAI 风格 messages/tools 渲染成 MiniMind 实际训练过的文本协议。

OpenAI-compatible API:
  对外暴露 /v1/chat/completions，但内部仍然调用本地 tokenizer 和 model.generate。

reasoning_content:
  从模型生成的 <think>...</think> 中解析出来的思考字段。

tool_calls:
  从模型生成的 <tool_call>...</tool_call> JSON 中解析出来的 OpenAI 风格工具调用字段。
```

<a id="l27-complete-principle"></a>
## 2. 完整原理：部署侧把训练产物包装成可调用接口

### 2.1 训练产物不能直接等同于可部署模型目录

训练脚本通常保存的是：

```text
out/full_sft_768.pth
```

这个文件主要是 PyTorch `state_dict`。它知道每个参数张量的名字和值，但它本身不完整表达：

```text
模型结构配置
tokenizer 文件
chat template
special tokens
第三方推理框架需要的 config 字段
```

transformers 目录则是一个更完整的部署包。当前本地 `minimind-3/` 里至少包含：

```text
config.json
tokenizer.json
tokenizer_config.json
chat_template.jinja
model.safetensors
```

所以 `convert_model.py` 做的不是“训练”，而是把训练后的参数放进一个生态更容易识别的目录结构。

### 2.2 部署入口复用训练时的文本协议

从第 4、5、26 课已经看到，MiniMind 不是直接训练裸文本问答，而是训练了带角色、思考、工具的模板协议：

```text
<|im_start|>user
...
<|im_end|>
<|im_start|>assistant
<think>
...
</think>

<tool_call>
{"name": "...", "arguments": {...}}
</tool_call>
```

部署时不能绕过这个协议。CLI、API、WebUI 都会做同一件事：

```text
messages -> tokenizer.apply_chat_template(...) -> prompt -> tokenizer(prompt) -> generate
```

区别只是外壳不同：

```text
CLI:
  从终端读 input，终端打印 response。

API:
  从 HTTP request 读 messages，返回 OpenAI 兼容 JSON / SSE。

WebUI:
  从浏览器输入框读 prompt，用 Streamlit session 保存历史并渲染结果。
```

### 2.3 OpenAI 兼容不等于模型变成 OpenAI 模型

`serve_openai_api.py` 暴露的是 OpenAI 风格接口：

```text
POST /v1/chat/completions
```

请求格式像这样：

```json
{
  "model": "minimind",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": true,
  "tools": [],
  "chat_template_kwargs": {"open_thinking": true}
}
```

但内部仍然是本地 MiniMind：

```text
AutoTokenizer.from_pretrained(...)
AutoModelForCausalLM.from_pretrained(...)
tokenizer.apply_chat_template(...)
model.generate(...)
```

也就是说，OpenAI 兼容只是接口层协议兼容，不是训练目标或模型结构发生了变化。

<a id="l27-reading-order"></a>
## 3. 源码阅读顺序图

按这个顺序读源码：

```text
1. minimind-3/config.json:1-38
   先看 transformers 目录里的结构合同。

2. scripts/convert_model.py:16-36, 40-96
   看原生 torch 权重如何保存成 transformers 目录。

3. eval_llm.py:12-30, 71-88
   用最简单的 CLI 入口理解 load -> template -> generate -> decode。

4. scripts/serve_openai_api.py:50-68
   看 API request 支持哪些字段。

5. scripts/serve_openai_api.py:83-102
   看服务端如何解析 <think> 和 <tool_call>。

6. scripts/serve_openai_api.py:171-225
   看非流式 API 的完整调用链。

7. scripts/serve_openai_api.py:105-165
   再看流式响应如何拆 reasoning/content/tool_calls。

8. scripts/web_demo.py:239-248, 350-413
   最后看 WebUI 如何选模型、维护历史、处理工具循环。

9. scripts/chat_api.py:3-39
   用客户端视角确认 OpenAI 兼容接口的意义。
```

<a id="l27-source-walkthrough"></a>
## 4. MiniMind 源码走读

### 4.1 transformers 目录保存结构合同

File: `minimind-3/config.json:1-38`

Read this to understand: transformers 模型目录必须告诉加载器使用什么模型结构、多少层、多少 head、词表多大。

Code/config/template excerpt:

```json
{
  "architectures": [
    "Qwen3ForCausalLM"
  ],
  "hidden_size": 768,
  "model_type": "qwen3",
  "num_attention_heads": 8,
  "num_hidden_layers": 8,
  "num_key_value_heads": 4,
  "vocab_size": 6400
}
```

This code shows:

- 当前下载好的 `minimind-3` 对齐的是 `Qwen3ForCausalLM` 生态接口。
- 模型结构参数和第 8-12 课学过的 hidden size、layer、head、vocab 是同一类合同。
- 部署加载时不只需要权重，还需要这些配置字段。

### 4.2 转换脚本有两条路线

File: `scripts/convert_model.py:16-36`

Read this to understand: MiniMind 自定义结构也可以注册成 transformers 可加载模型。

Code/config/template excerpt:

```python
def convert_torch2transformers_minimind(torch_path, transformers_path, dtype=torch.float16):
    MiniMindConfig.register_for_auto_class()
    MiniMindForCausalLM.register_for_auto_class("AutoModelForCausalLM")
    lm_model = MiniMindForCausalLM(lm_config)
    state_dict = torch.load(torch_path, map_location=device)
    lm_model.load_state_dict(state_dict, strict=False)
    lm_model = lm_model.to(dtype)
    lm_model.save_pretrained(transformers_path, safe_serialization=False)
    tokenizer = AutoTokenizer.from_pretrained('../model/')
    tokenizer.save_pretrained(transformers_path)
```

This code shows:

- `torch_path` 是训练保存的原生权重。
- `save_pretrained` 写出 transformers 目录。
- tokenizer 会一起保存，否则部署端无法复原 chat template 和 token id。

File: `scripts/convert_model.py:40-96`

Read this to understand: 项目主线也支持转换成 Qwen3 兼容结构，方便 vLLM、Ollama 等生态加载。

Code/config/template excerpt:

```python
common_config = {
    "vocab_size": lm_config.vocab_size,
    "hidden_size": lm_config.hidden_size,
    "intermediate_size": lm_config.intermediate_size,
    "num_hidden_layers": lm_config.num_hidden_layers,
    "num_attention_heads": lm_config.num_attention_heads,
    "num_key_value_heads": lm_config.num_key_value_heads,
    "rope_theta": lm_config.rope_theta,
}
qwen_config = Qwen3Config(**common_config, use_sliding_window=False, sliding_window=None)
qwen_model = Qwen3ForCausalLM(qwen_config)
qwen_model.load_state_dict(state_dict, strict=True)
qwen_model.save_pretrained(transformers_path)
tokenizer.save_pretrained(transformers_path)
```

This code shows:

- 转换时把 MiniMind config 映射到 Qwen3 config。
- `strict=True` 要求 state_dict 名称和目标结构完全对齐。
- 转换后的目录能被更多 transformers 生态工具识别。

### 4.3 CLI 与 API 共享两种加载路径

File: `eval_llm.py:12-30`

Read this to understand: MiniMind 推理入口如何区分原生 torch 权重和 transformers 目录。

Code/config/template excerpt:

```python
tokenizer = AutoTokenizer.from_pretrained(args.load_from)
if 'model' in args.load_from:
    model = MiniMindForCausalLM(MiniMindConfig(...))
    ckp = f'./{args.save_dir}/{args.weight}_{args.hidden_size}{moe_suffix}.pth'
    model.load_state_dict(torch.load(ckp, map_location=args.device), strict=True)
else:
    model = AutoModelForCausalLM.from_pretrained(args.load_from, trust_remote_code=True)
return model.half().eval().to(args.device), tokenizer
```

This code shows:

- `--load_from model` 走项目自定义 `MiniMindForCausalLM`。
- `--load_from ./minimind-3` 走 transformers `AutoModelForCausalLM`。
- 两条路径最后都返回 `model, tokenizer`，后面的推理流程相同。

注意：这里用的是字符串判断 `if 'model' in args.load_from`。学习时够用；做更稳的工程时应改成显式参数或检查目录结构，避免路径名误判。

File: `scripts/serve_openai_api.py:28-47`

Read this to understand: API 服务端复用了同一套加载边界。

Code/config/template excerpt:

```python
tokenizer = AutoTokenizer.from_pretrained(args.load_from)
if 'model' in args.load_from:
    model = MiniMindForCausalLM(MiniMindConfig(...))
    model.load_state_dict(torch.load(ckp, map_location=device), strict=True)
else:
    model = AutoModelForCausalLM.from_pretrained(args.load_from, trust_remote_code=True)
return model.half().eval().to(device), tokenizer
```

This code shows:

- API 服务不是另一套模型，它仍然先加载本地模型和 tokenizer。
- `load_from` 决定加载原生权重还是 transformers 目录。
- `model.eval()` 表示部署侧不训练，只推理。

### 4.4 CLI 推理是最小部署闭环

File: `eval_llm.py:71-88`

Read this to understand: 最小推理闭环就是 messages、chat template、tokenizer、generate、decode。

Code/config/template excerpt:

```python
conversation.append({"role": "user", "content": prompt})
inputs = tokenizer.apply_chat_template(
    conversation,
    tokenize=False,
    add_generation_prompt=True,
    open_thinking=bool(args.open_thinking)
)
inputs = tokenizer(inputs, return_tensors="pt", truncation=True).to(args.device)
generated_ids = model.generate(
    inputs=inputs["input_ids"],
    attention_mask=inputs["attention_mask"],
    max_new_tokens=args.max_new_tokens,
    do_sample=True,
)
response = tokenizer.decode(generated_ids[0][len(inputs["input_ids"][0]):], skip_special_tokens=True)
```

This code shows:

- `conversation` 是 OpenAI 风格消息列表。
- `apply_chat_template` 把消息列表变成模型实际看到的 prompt。
- decode 时只取 prompt 后面新生成的 token。

### 4.5 chat template 固化工具和思考协议

File: `minimind-3/chat_template.jinja:1-11`

Read this to understand: 有 tools 时，模板会把工具 schema 写进 system prompt，并要求模型输出 `<tool_call>` JSON。

Code/config/template excerpt:

```jinja
{%- if tools %}
    {{- '<|im_start|>system\n' }}
    {{- "# Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>" }}
    {%- for tool in tools %}
        {{- "\n" }}
        {{- tool | tojson }}
    {%- endfor %}
    {{- "\n</tools>\n\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:" }}
```

This code shows:

- 工具不是 Python 函数直接进模型，而是 schema 文本进入 prompt。
- 模型学到的是输出 `<tool_call>` 这类文本动作。
- 这和第 26 课的 Agent rollout 使用的是同一套协议。

File: `minimind-3/chat_template.jinja:78-84`

Read this to understand: `open_thinking` 控制 assistant 起始处的 `<think>` 形态。

Code/config/template excerpt:

```jinja
{%- if add_generation_prompt %}
    {{- '<|im_start|>assistant\n' }}
    {%- if open_thinking is defined and open_thinking is true %}
        {{- '<think>\n' }}
    {%- else %}
        {{- '<think>\n\n</think>\n\n' }}
    {%- endif %}
{%- endif %}
```

This code shows:

- 开启 thinking 时，模型从未闭合的 `<think>` 后继续生成。
- 不开启 thinking 时，模板给一个空 thinking 块，让模型直接回答。
- 部署侧的 `open_thinking` 本质是 chat template 参数，不是模型结构开关。

### 4.6 API 请求模型定义

File: `scripts/serve_openai_api.py:50-68`

Read this to understand: OpenAI 兼容接口接收哪些字段，以及 thinking 如何兼容不同客户端传法。

Code/config/template excerpt:

```python
class ChatRequest(BaseModel):
    model: str
    messages: list
    temperature: float = 0.7
    top_p: float = 0.92
    max_tokens: int = 8192
    stream: bool = True
    tools: list = []
    open_thinking: bool = False
    chat_template_kwargs: dict = None

    def get_open_thinking(self) -> bool:
        if self.open_thinking:
            return True
        if self.chat_template_kwargs:
            return self.chat_template_kwargs.get('open_thinking', False) or \
                   self.chat_template_kwargs.get('enable_thinking', False)
        return False
```

This code shows:

- API 请求保留 OpenAI 风格的 `messages` 和 `tools`。
- `open_thinking` 可以直接传，也可以通过 `chat_template_kwargs` 传。
- 服务端最终只需要知道是否把 `open_thinking=True` 传给 template。

### 4.7 服务端解析模型输出协议

File: `scripts/serve_openai_api.py:83-102`

Read this to understand: 模型输出是文本，服务端要把文本协议转换成 OpenAI 风格字段。

Code/config/template excerpt:

```python
def parse_response(text):
    reasoning_content = None
    think_match = re.search(r'<think>(.*?)</think>', text, re.DOTALL)
    if think_match:
        reasoning_content = think_match.group(1).strip()
        text = re.sub(r'<think>.*?</think>\s*', '', text, flags=re.DOTALL)
    tool_calls = []
    for i, m in enumerate(re.findall(r'<tool_call>(.*?)</tool_call>', text, re.DOTALL)):
        call = json.loads(m.strip())
        tool_calls.append({
            "id": f"call_{int(time.time())}_{i}",
            "type": "function",
            "function": {"name": call.get("name", ""), "arguments": json.dumps(call.get("arguments", {}), ensure_ascii=False)}
        })
    return text.strip(), reasoning_content, tool_calls or None
```

This code shows:

- `reasoning_content` 来自 `<think>...</think>`。
- `tool_calls` 来自 `<tool_call>...</tool_call>` 中的 JSON。
- `content` 会移除 thinking 和 tool_call，只留下普通回答文本。

### 4.8 非流式 API 完整路径

File: `scripts/serve_openai_api.py:187-225`

Read this to understand: 非流式接口如何从 request 到 response。

Code/config/template excerpt:

```python
new_prompt = tokenizer.apply_chat_template(
    request.messages,
    tokenize=False,
    add_generation_prompt=True,
    tools=request.tools or None,
    open_thinking=request.get_open_thinking()
)
inputs = tokenizer(new_prompt, return_tensors="pt", truncation=True).to(device)
generated_ids = model.generate(
    inputs["input_ids"],
    max_length=inputs["input_ids"].shape[1] + request.max_tokens,
    attention_mask=inputs["attention_mask"],
    top_p=request.top_p,
    temperature=request.temperature
)
answer = tokenizer.decode(generated_ids[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
content, reasoning_content, tool_calls = parse_response(answer)
message = {"role": "assistant", "content": content}
```

This code shows:

- API 和 CLI 一样先套 chat template。
- `answer` 只 decode 新生成部分。
- 返回前调用 `parse_response`，把 MiniMind 文本协议转成 API 字段。

### 4.9 流式 API 额外处理 reasoning/content/tool_calls

File: `scripts/serve_openai_api.py:105-165`

Read this to understand: 流式响应为什么要在生成过程中区分 reasoning 和 content。

Code/config/template excerpt:

```python
queue = Queue()
streamer = CustomStreamer(tokenizer, queue)
Thread(target=_generate).start()

full_text = ""
thinking_ended = not bool(open_thinking)
while True:
    text = queue.get()
    if text is None:
        break
    full_text += text
    if not thinking_ended:
        pos = full_text.find('</think>')
        ...
        yield json.dumps({"choices": [{"delta": {"reasoning_content": new_r}}]}, ensure_ascii=False)
    else:
        yield json.dumps({"choices": [{"delta": {"content": new_c}}]}, ensure_ascii=False)

_, _, tool_calls = parse_response(full_text)
if tool_calls:
    yield json.dumps({"choices": [{"delta": {"tool_calls": tool_calls}}]}, ensure_ascii=False)
```

This code shows:

- `TextStreamer` 把生成结果持续放进 queue。
- `</think>` 出现前的增量作为 `reasoning_content`。
- 工具调用要等完整文本生成后再解析，因为 JSON 需要闭合标签。

### 4.10 WebUI 加载模型并维护多轮上下文

File: `scripts/web_demo.py:198-209`

Read this to understand: WebUI 加载的是 transformers 模型目录，而不是训练脚本对象。

Code/config/template excerpt:

```python
@st.cache_resource
def load_model_tokenizer(model_path):
    model = AutoModelForCausalLM.from_pretrained(
        model_path,
        trust_remote_code=True
    )
    tokenizer = AutoTokenizer.from_pretrained(
        model_path,
        trust_remote_code=True
    )
    model = model.half().eval().to(device)
    return model, tokenizer
```

This code shows:

- WebUI 默认服务的是 transformers 格式模型目录。
- `st.cache_resource` 避免每次交互都重新加载权重。
- WebUI 和 API 一样只做推理。

File: `scripts/web_demo.py:239-248`

Read this to understand: WebUI 为什么要求把模型目录放到 `scripts/` 下面。

Code/config/template excerpt:

```python
script_dir = os.path.dirname(os.path.abspath(__file__))
MODEL_PATHS = {}
for d in sorted(os.listdir(script_dir), reverse=True):
    full_path = os.path.join(script_dir, d)
    if os.path.isdir(full_path) and not d.startswith('.') and not d.startswith('_'):
        if any(f.endswith(('.bin', '.safetensors', '.pt')) or os.path.exists(os.path.join(full_path, 'model.safetensors.index.json')) for f in os.listdir(full_path) if os.path.isfile(os.path.join(full_path, f))):
            MODEL_PATHS[d] = [d, d]
if not MODEL_PATHS:
    MODEL_PATHS = {"No models found": ["", "No models"]}
```

This code shows:

- WebUI 扫描的是 `scripts/` 目录下的子目录。
- 子目录里要有 `.safetensors`、`.bin` 或 `.pt` 这类权重文件。
- 所以 README 才要求把 `minimind-3` 复制到 `scripts/minimind-3`。

File: `scripts/web_demo.py:350-413`

Read this to understand: WebUI 如何把一次用户输入变成多轮工具循环。

Code/config/template excerpt:

```python
tools = [t for t in TOOLS if t['function']['name'] in st.session_state.get('selected_tools', [])] or None
st.session_state.chat_messages = sys_prompt + st.session_state.chat_messages[-(st.session_state.history_chat_num + 1):]
template_kwargs = {"tokenize": False, "add_generation_prompt": True}
if st.session_state.get('enable_thinking', False):
    template_kwargs["open_thinking"] = True
if tools:
    template_kwargs["tools"] = tools
new_prompt = tokenizer.apply_chat_template(st.session_state.chat_messages, **template_kwargs)
inputs = tokenizer(new_prompt, return_tensors="pt", truncation=True).to(device)
Thread(target=model.generate, kwargs=generation_kwargs).start()
...
for _ in range(16):
    tool_calls = re.findall(r'<tool_call>(.*?)</tool_call>', answer, re.DOTALL)
    if not tool_calls:
        break
    st.session_state.chat_messages.append({"role": "assistant", "content": answer})
    ...
    st.session_state.chat_messages.append({"role": "tool", "content": json.dumps(result, ensure_ascii=False)})
    new_prompt = tokenizer.apply_chat_template(st.session_state.chat_messages, **template_kwargs)
```

This code shows:

- WebUI 里的工具执行和第 26 课 `rollout_single` 很像：生成 tool_call，执行工具，把 tool message 拼回上下文，再生成。
- `history_chat_num` 控制携带多少历史消息。
- WebUI 使用 streamer，让页面逐步显示生成结果。

### 4.11 客户端只需要 OpenAI 兼容协议

File: `scripts/chat_api.py:3-22`

Read this to understand: 对客户端来说，本地 MiniMind 服务就是一个 OpenAI-compatible endpoint。

Code/config/template excerpt:

```python
client = OpenAI(
    api_key="sk-123",
    base_url="http://localhost:11434/v1"
)
response = client.chat.completions.create(
    model="minimind-local:latest",
    messages=conversation_history[-(history_messages_num or 1):],
    stream=stream,
    temperature=0.8,
    max_tokens=2048,
    top_p=0.8,
    extra_body={"chat_template_kwargs": {"open_thinking": True}, "reasoning_effort": "medium"}
)
```

This code shows:

- 客户端通过 `base_url` 连接本地或第三方 OpenAI 兼容服务。
- `messages` 仍然是标准聊天消息。
- `open_thinking` 被放进 `extra_body.chat_template_kwargs`。

File: `scripts/chat_api.py:27-39`

Read this to understand: 流式客户端如何接收 `reasoning_content` 和普通 `content`。

Code/config/template excerpt:

```python
for chunk in response:
    delta = chunk.choices[0].delta
    r = getattr(delta, 'reasoning_content', None) or ""
    c = delta.content or ""
    if r:
        print(f'\033[90m{r}\033[0m', end="", flush=True)
    if c:
        print(c, end="", flush=True)
    assistant_res += c
```

This code shows:

- 客户端把 `reasoning_content` 和 `content` 分开显示。
- 对话历史只保存普通回答 `assistant_res`。
- 客户端不需要知道模型内部 logits、mask 或 loss。

<a id="l27-must-write"></a>
## 5. 本节必须会写 / 暂时不要求

本节必须会写：

```text
1. 说明 torch state_dict 和 transformers 模型目录的区别。
2. 画出 CLI/API/WebUI 共同的推理链路：
   messages -> chat_template -> tokenizer -> generate -> decode。
3. 解释 open_thinking 为什么是 template 参数。
4. 解释 <think> 和 <tool_call> 如何变成 reasoning_content 和 tool_calls。
5. 用 OpenAI SDK 写一个最小 chat.completions 请求。
```

本节暂时不要求：

```text
1. 手写生产级 HTTP 服务。
2. 实现并发调度、批量推理、KV cache 复用服务。
3. 实现鉴权、限流、日志、监控。
4. 重新实现 Streamlit WebUI。
5. 调通 vLLM / Ollama / llama.cpp 的所有参数。
```

部署侧属于工程外围。课程里优先复用原项目脚本，把学习重点放在接口边界和数据流上。

<a id="l27-experiment"></a>
## 6. 实验验证

### 实验 A：检查部署侧三个协议面

这个实验不启动服务，也不加载完整模型权重。它检查三件事：

```text
transformers 模型目录是否齐全；
chat template 如何把 tools/open_thinking 渲染进 prompt；
serve_openai_api.parse_response 如何把模型文本拆成 API 字段。
```

命令：

```bash
cd /home/sun/minimind
python course/labs/trace_deploy_surfaces.py
```

记录：

```text
model_type =
architectures =
contains_tools_tag =
contains_tool_call_instruction =
has_open_think_prompt =
reasoning_content =
tool_calls =
```

输出怎么看：

```text
contains_tools_tag=True:
  说明工具 schema 已经进入 prompt。

contains_tool_call_instruction=True:
  说明模板明确要求模型用 <tool_call>...</tool_call> 输出动作。

has_open_think_prompt=True:
  说明 open_thinking=True 时，assistant 起始处留下未闭合的 <think>。

tool_calls 非空:
  说明服务端能把 MiniMind 文本协议转成 OpenAI 风格 tool_calls 字段。
```

### 实验 B：用本地 transformers 模型跑一次真实推理

这个实验验证 `minimind-3/` 目录能被当前环境加载，并能完成一次真实生成。

命令：

```bash
cd /home/sun/minimind
python course/labs/run_minimind3_once.py --device cpu --max_new_tokens 32 --prompt "MiniMind 是什么？"
```

记录：

```text
input_ids.shape =
generated_ids.shape =
new_tokens =
response =
```

输出怎么看：

```text
input_ids.shape:
  prompt 被 chat template 和 tokenizer 转成了模型输入。

generated_ids.shape:
  模型完成了自回归生成。

new_tokens:
  新生成 token 数量，不包含 prompt。
```

### 实验 C：可选启动 OpenAI 兼容服务

当前课程默认不要求启动长驻服务。准备好 transformers 模型目录后，可以手动试：

命令：

```bash
cd /home/sun/minimind/scripts
python serve_openai_api.py --load_from ../minimind-3 --device cpu
```

另开一个终端调用：

```bash
cd /home/sun/minimind/scripts
python chat_api.py
```

注意：

```text
chat_api.py 默认 base_url 是 http://localhost:11434/v1；
serve_openai_api.py 默认端口是 8998。
如果要直接连这个服务，需要把 chat_api.py 里的 base_url 改成 http://localhost:8998/v1，
或者用兼容 OpenAI 的客户端自己指定 base_url。
```

### 实验 D：可选启动 WebUI

WebUI 会扫描 `scripts/` 目录下的模型子目录。当前本地模型在项目根目录 `minimind-3/`，所以需要先复制或软链接到 `scripts/` 下。

命令：

```bash
cd /home/sun/minimind
ln -s ../minimind-3 scripts/minimind-3
cd scripts
streamlit run web_demo.py
```

如果 `streamlit` 未安装，这个实验会失败。当前课程的必须验收仍然是实验 A 和实验 B。

<a id="l27-stage-assembly"></a>
## 7. 阶段组装

到第 27 课为止，完整 MiniMind 链路可以这样收束：

```text
第 1-7 课：
  数据、tokenizer、pretrain/SFT 训练入口。

第 8-13 课：
  MiniMind 模型结构、Attention、RoPE、KV cache、FFN/MoE。

第 14-19 课：
  训练机制、checkpoint、full SFT、LoRA。

第 20-26 课：
  distillation、DPO、PPO、GRPO/CISPO、reward/logprob/KL、Agentic RL。

第 27 课：
  把训练出的模型接到 CLI、OpenAI-compatible API、WebUI。
```

部署阶段不新增手写核心模型模块。它主要复用：

```text
model/model_minimind.py:
  原生 torch 权重加载时使用。

minimind-3/:
  transformers 生态加载时使用。

scripts/convert_model.py:
  在原生权重和 transformers 目录之间转换。

scripts/serve_openai_api.py:
  暴露 OpenAI 兼容 HTTP 接口。

scripts/web_demo.py:
  提供本地浏览器交互界面。

course/labs/trace_deploy_surfaces.py:
  验证部署协议面，不依赖长驻服务。
```

阶段验收命令：

```bash
cd /home/sun/minimind
python course/labs/check_project_readiness.py
python course/labs/trace_deploy_surfaces.py
python course/labs/run_minimind3_once.py --device cpu --max_new_tokens 16 --prompt "你好"
```

Portfolio 记录可以写：

```text
读懂并验证了 MiniMind 从训练权重到部署接口的链路：
torch state_dict -> transformers model directory -> AutoTokenizer/AutoModelForCausalLM -> chat template -> generate -> OpenAI-compatible response。
能够解释 <think> / <tool_call> 文本协议如何在 API/WebUI 侧转换为 reasoning_content / tool_calls。
```

<a id="l27-check"></a>
## 8. 本节检查

1. 原生 `out/full_sft_768.pth` 和 `minimind-3/` transformers 目录有什么区别？
2. `convert_model.py` 为什么要保存 tokenizer，而不只是保存模型权重？
3. `eval_llm.py --load_from model` 和 `eval_llm.py --load_from ./minimind-3` 分别走哪条加载路径？
4. `open_thinking=True` 最终影响的是模型结构、采样参数，还是 chat template？
5. API 服务端为什么要把 `<tool_call>` 文本解析成 `tool_calls` 字段？
6. WebUI 为什么要重新 `apply_chat_template` after tool result？
7. OpenAI-compatible API 里的“compatible”具体兼容的是哪一层？

<a id="l27-next"></a>
## 9. 下一课

第 28 课进入总复盘与小项目。

下一课要把全课程收束成一个可展示的成果：

```text
从 tiny 数据跑通关键实验；
整理 tokenizer / model / train / RL / deploy 的完整调用链；
列出教学版实现和原项目实现的差异；
把 portfolio 中的实验记录、实现说明和简历描述整理成最终版本。
```