模型训好了

你花了几天时间完成了预训练、SFT、DPO，终于得到了一个对话还不错的模型。现在你想让其他人也能用它。

你不能让每个人都 clone 你的代码、装 PyTorch、手动加载权重。你需要一个服务。

本章地图

Part 1：推理

从加载权重到生成文本的完整流程。

推理流水线

四步走：加载 → 编码 → 生成 → 解码

# eval_llm.py 核心流程
model, tokenizer = init_model(args)  # 加载模型

while True:
    user_input = input("用户: ")
    messages = [{"role": "user", "content": user_input}]
    # 编码
    inputs = tokenizer.apply_chat_template(messages, return_tensors="pt")
    # 生成
    outputs = model.generate(inputs.to(device), max_new_tokens=8192,
                              temperature=0.85, top_p=0.95)
    # 解码
    response = tokenizer.decode(outputs[0][inputs.shape[-1]:])
    print(f"助手: {response}")

模型加载

支持两种权重格式：原生 torch 和 HuggingFace transformers

def init_model(args):
    tokenizer = AutoTokenizer.from_pretrained(args.load_from)
    if 'model' in args.load_from:
        # 路径1：原生 MiniMind 格式（.pth 权重）
        model = MiniMindForCausalLM(MiniMindConfig(...))
        model.load_state_dict(torch.load(ckp, map_location=args.device))
        if args.lora_weight != 'None':
            apply_lora(model)  # 可选：加载 LoRA 旁路
            load_lora(model, lora_path)
    else:
        # 路径2：HuggingFace transformers 格式
        model = AutoModelForCausalLM.from_pretrained(args.load_from)
    return model.half().eval().to(args.device), tokenizer

采样参数详解

控制模型"怎么说"的三个旋钮

这是上一章 MiniMindForCausalLM.generate() 中讲过的 Temperature、Top-P 采样的实际应用。temperature=0 表示贪心解码（每次选概率最高的词）。

命令行对话

eval_llm.py —— 最快的验证方式

# 基础用法
$ python eval_llm.py --weight full_sft

# 使用 LoRA 权重
$ python eval_llm.py --weight full_sft --lora_weight lora_medical

# 调整采样参数
$ python eval_llm.py --weight full_sft \
    --temperature 0.5 --top_p 0.9 --max_new_tokens 2048

# 使用 MoE 模型
$ python eval_llm.py --weight full_sft --use_moe 1

# 开启思考模式
$ python eval_llm.py --weight full_sft --open_thinking 1

Part 2：API

把模型包装成 OpenAI 兼容的 API，任何客户端都能调用。

API 服务架构

# serve_openai_api.py 核心端点
@app.post("/v1/chat/completions")
async def chat_completions(request: ChatRequest):
    messages = request.messages
    # 应用聊天模板
    inputs = tokenizer.apply_chat_template(messages, return_tensors="pt")
    if request.stream:
        # 流式输出
        return StreamingResponse(generate_stream(inputs, request),
                                 media_type="text/event-stream")
    else:
        # 同步输出
        outputs = model.generate(inputs, max_new_tokens=request.max_tokens)
        return format_response(outputs, request)

流式输出

逐 Token 推送，不用等完整回答生成

定义：Server-Sent Events（SSE）是一种服务器向客户端单向推送的技术。每生成一个 Token 就立即推送，用户看到"打字机"效果。

说白了，就像微信语音转文字——不用等整段话说完，一边说一边出字。

这个比喻只是为了帮你建立直观感受。在计算机内部，SSE 是一种 HTTP 长连接协议，服务器通过 data: 前缀逐行发送文本块，浏览器用 EventSource API 接收。

class CustomStreamer(TextStreamer):
    def __init__(self, tokenizer, queue):
        super().__init__(tokenizer)
        self.queue = queue

    def on_finalized_text(self, text, stream_end=False):
        # 每生成一个 token，推入队列
        self.queue.put(text)
        if stream_end:
            self.queue.put(None)  # 发送结束信号

SSE 数据格式

兼容 OpenAI 的 data: {...} 格式

data: {"id":"chatcmpl-1","object":"chat.completion.chunk",
       "choices":[{"delta":{"content":"你"},"index":0}]}

data: {"id":"chatcmpl-1","object":"chat.completion.chunk",
       "choices":[{"delta":{"content":"好"},"index":0}]}

data: [DONE]

客户端用 OpenAI SDK 可以直接消费：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")

response = client.chat.completions.create(
    model="minimind",
    messages=[{"role": "user", "content": "你好"}],
    stream=True
)
for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")

启动 API 服务

# 启动服务（默认端口 8000）
$ python scripts/serve_openai_api.py --weight full_sft

# 指定端口和模型参数
$ python scripts/serve_openai_api.py \
    --weight full_sft --port 8080 \
    --hidden_size 768 --num_hidden_layers 8

# 使用 HuggingFace 格式模型
$ python scripts/serve_openai_api.py \
    --load_from ../transformers_minimind/

Part 3：Web

用 Streamlit 快速搭建一个网页聊天界面。

Web 界面

web_demo.py —— 几十行代码的 Web 聊天

# 启动 Web 界面
$ streamlit run scripts/web_demo.py -- --weight full_sft

Part 4：转换

让 MiniMind 模型兼容更广泛的生态系统。

为什么需要转换

原生 .pth 权重只能用 MiniMind 代码加载

两种转换方式

convert_model.py 提供两个函数

# 转换为 Qwen3 兼容格式（推荐，可用于 vLLM）
$ python scripts/convert_model.py \
    --convert_type torch2transformers \
    --torch_path ../out/full_sft_768.pth \
    --transformers_path ../transformers_minimind/

# 转换为 MiniMind transformers 格式
$ python scripts/convert_model.py \
    --convert_type torch2transformers_minimind \
    --torch_path ../out/full_sft_768.pth \
    --transformers_path ../transformers_minimind_custom/

兼容原理

MiniMind 的架构与 Qwen3 高度相似

LoRA 合并转换

先合并 LoRA，再转格式

# 步骤 1：合并 LoRA 到基础模型
$ python -c "
from model.model_lora import merge_lora
from model.model_minimind import MiniMindConfig, MiniMindForCausalLM
config = MiniMindConfig()
model = MiniMindForCausalLM(config)
merge_lora(model, '../out/lora_medical_768.pth', '../out/merged_768.pth')
"

# 步骤 2：转换合并后的模型
$ python scripts/convert_model.py \
    --convert_type torch2transformers \
    --torch_path ../out/merged_768.pth \
    --transformers_path ../transformers_medical/

Part 5：高性能

转换成 Qwen3 格式后，用 vLLM / SGLang 把吞吐量拉满。

vLLM 启动实战

转换成 Qwen3 格式后，一条命令起高吞吐服务

vLLM 不认识 MiniMind 的私有架构，但它认识 Qwen3。上一节 convert_torch2transformers 把权重转成 Qwen3Config 结构后，vLLM 就能直接加载。

# 1. 安装 vLLM（需要 CUDA 环境）
$ pip install vllm

# 2. 一条命令启动 OpenAI 兼容服务
$ python -m vllm.entrypoints.openai.api_server \
    --model ./transformers_minimind_768/ \
    --served-model-name minimind \
    --dtype bfloat16 \
    --max-model-len 2048 \
    --port 8000

# 3. 用同样的 chat_api.py 调用（接口完全兼容）
$ python scripts/chat_api.py

吞吐量对比

原生 PyTorch vs vLLM，差在哪

深度边界：SGLang 是另一个高性能引擎，优势在复杂提示词结构（多轮、分支）的编译优化。MiniMind 的 rollout_engine.py（阶段 8 RL 训练用）已经集成了 SGLang 客户端，这里不再展开。

FastAPI 并发

不用 vLLM 时，怎么让自带服务扛住多请求

MiniMind 自带的 serve_openai_api.py 默认单进程运行，同一时刻只处理一个请求。要扛并发，用 uvicorn 的多 worker 模式：

# 单 worker（默认，适合调试）
$ python scripts/serve_openai_api.py

# 多 worker 并发（生产部署）
$ uvicorn scripts.serve_openai_api:app \
    --host 0.0.0.0 --port 8000 \
    --workers 4

# 配合 gunicorn 更稳定（Linux）
$ gunicorn scripts.serve_openai_api:app \
    -w 4 -k uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000

Part 6：排错

部署中常见的问题。

常见错误诊断

动手练习

知识全景图