08-应用部署 - 技术栈

阶段 8：应用部署

教学目标

掌握 MiniMind 模型的多种部署方式
能够部署 OpenAI 兼容的 API 服务
了解 vLLM、ollama、llama.cpp 等推理框架的接入方式
掌握模型格式转换（torch → transformers → GGUF）
了解端侧量化部署（MNN）
能够将模型接入 RAG 应用（FastGPT、Dify）

课时安排

理论讲解：0.5 课时（部署方案概述）
部署实践：1.5 课时（API 服务 + 多框架推理 + 模型转换）

8.1 部署方案概览

8.1.1 部署方式对比

方式	适用场景	性能	难度	代表工具
原生 PyTorch	本地测试、教学	低	低	`eval_llm.py`
OpenAI API	集成到应用	中	中	`serve_openai_api.py`
vLLM	高并发生产环境	高	中	vLLM
ollama	本地方便使用	中-高	低	ollama
llama.cpp	CPU/边缘设备推理	中	中	llama.cpp
MNN	移动端/嵌入式	中	高	MNN

8.1.2 推理性能参考

模型	参数量	显存占用	推理速度（tokens/s）
minimind-3 Dense	64M	~0.5GB	50-100（PyTorch GPU）
minimind-3 MoE	198M-A64M	~1.0GB	30-60（PyTorch GPU）
minimind-3 4bit	64M→16M	~0.2GB	80-150（量化推理）

8.2 OpenAI 兼容 API 服务

8.2.1 启动服务

MiniMind 提供了 OpenAI 兼容的 API 服务，可以直接替换 OpenAI API 使用：

bash 复制代码

cd minimind/scripts

# 启动 API 服务（默认端口 8998）
python serve_openai_api.py

# 指定模型权重和端口
python serve_openai_api.py --model_path ../out/full_sft_768.pth --port 8000

8.2.2 API 接口说明

MiniMind 的 API 服务兼容 OpenAI Chat Completions API：

接口地址 ：POST /v1/chat/completions

请求格式：

json 复制代码

{
  "model": "minimind-3",
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "max_tokens": 512,
  "temperature": 0.7,
  "top_p": 0.9,
  "open_thinking": false
}

特殊参数：

参数	类型	说明
`open_thinking`	bool	是否开启思考模式（输出 reasoning_content）
`stream`	bool	是否流式输出

响应格式（含思考）：

json 复制代码

{
  "id": "chatcmpl-xxx",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "正式回答内容",
        "reasoning_content": "思考过程内容"
      }
    }
  ]
}

8.2.3 API 调用示例

bash 复制代码

# 基本对话
curl http://localhost:8998/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimind-3",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 512
  }'

# 流式输出
curl http://localhost:8998/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimind-3",
    "messages": [{"role": "user", "content": "写一首诗"}],
    "stream": true
  }'

# 开启思考模式
curl http://localhost:8998/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimind-3",
    "messages": [{"role": "user", "content": "123*456等于多少？"}],
    "open_thinking": true
  }'

8.2.4 Python SDK 调用

python 复制代码

from openai import OpenAI

# 创建客户端（指向 MiniMind API）
client = OpenAI(
    api_key="dummy",  # MiniMind 不需要真实 key
    base_url="http://localhost:8998/v1"
)

# 基本对话
response = client.chat.completions.create(
    model="minimind-3",
    messages=[
        {"role": "user", "content": "请用 Python 写一个快速排序"}
    ],
    max_tokens=512
)
print(response.choices[0].message.content)

# 流式对话
stream = client.chat.completions.create(
    model="minimind-3",
    messages=[{"role": "user", "content": "介绍 Transformer"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

8.3 Web Demo 部署

8.3.1 Streamlit Web Demo

bash 复制代码

cd minimind/scripts
streamlit run web_demo.py

Web Demo 支持的功能：

多轮对话
思考过程展示（可开关）
工具调用测试
参数调节（temperature、top_p、max_tokens）

8.3.2 自定义 Web Demo

python 复制代码

import streamlit as st
from openai import OpenAI

st.title("MiniMind 对话助手")

# 初始化客户端
client = OpenAI(api_key="dummy", base_url="http://localhost:8998/v1")

# 会话历史
if "messages" not in st.session_state:
    st.session_state.messages = []

# 显示历史消息
for msg in st.session_state.messages:
    with st.chat_message(msg["role"]):
        st.markdown(msg["content"])

# 用户输入
if prompt := st.chat_input("请输入问题..."):
    st.session_state.messages.append({"role": "user", "content": prompt})
    with st.chat_message("user"):
        st.markdown(prompt)

    # 调用模型
    with st.chat_message("assistant"):
        response = client.chat.completions.create(
            model="minimind-3",
            messages=st.session_state.messages,
            max_tokens=512,
            stream=True
        )
        full_response = st.write_stream(response)

    st.session_state.messages.append(
        {"role": "assistant", "content": full_response}
    )

8.4 多推理框架集成

8.4.1 ollama

ollama 是最便捷的本地 LLM 推理工具：

bash 复制代码

# 安装 ollama（https://ollama.ai）
curl -fsSL https://ollama.ai/install.sh | sh

# 直接运行 MiniMind（自动下载模型）
ollama run jingyaogong/minimind-3

# 运行 MoE 版本
ollama run jingyaogong/minimind-3-moe

ollama 自动提供 OpenAI 兼容 API（端口 11434）：

bash 复制代码

curl http://localhost:11434/v1/chat/completions \
  -d '{
    "model": "jingyaogong/minimind-3",
    "messages": [{"role": "user", "content": "你好"}]
  }'

8.4.2 vLLM

vLLM 是高性能 LLM 推理引擎，适合高并发生产环境：

bash 复制代码

# 安装 vLLM
pip install vllm

# 启动推理服务
vllm serve ./minimind-3 --served-model-name "minimind" --port 8000

# 调用（与 ollama 类似，使用 OpenAI 兼容 API）
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimind",
    "messages": [{"role": "user", "content": "你好"}]
  }'

vLLM 的性能优势：

PagedAttention 技术，显存利用率更高
连续批处理（Continuous Batching），高并发更高效
支持多 GPU 推理

8.4.3 llama.cpp

llama.cpp 适合 CPU 推理和边缘设备部署：

bash 复制代码

# 安装 llama.cpp（https://github.com/ggerganov/llama.cpp）
# 需要先将模型转换为 GGUF 格式

# 转换为 GGUF（先转 transformers 格式，再用 llama.cpp 转换）
cd minimind/scripts
python convert_model.py --format transformers --input_dir ../minimind-3

# 使用 llama.cpp 的 convert 脚本转换为 GGUF
python convert_hf_to_gguf.py ./minimind-3 --outtype f16

# 运行推理
./llama-cli -m minimind-3.gguf -p "你好，请介绍一下你自己" -n 512

8.4.4 SGLang

SGLang 是高性能推理框架，同时支持作为 Agentic RL 的 rollout 引擎：

bash 复制代码

# 安装 SGLang
pip install sglang

# 启动推理服务
python -m sglang.launch_server --model-path ./minimind-3 --port 8998

# 作为 Agentic RL 的 rollout 引擎
python train_agent.py --rollout_engine sglang --sglang_base_url http://localhost:8998

8.4.5 MNN 端侧部署

MNN（Mobile Neural Network）是阿里开源的端侧推理框架，支持移动设备部署：

bash 复制代码

# MiniMind 支持 4-bit HQQ 量化
# 量化后的模型可以部署到手机、嵌入式设备

# 量化后模型大小：
# minimind-3: 64M × 4 bytes = 256MB → 4-bit: ~64MB

8.5 模型格式转换

8.5.1 支持的格式

MiniMind 支持以下格式之间的转换：

plain 复制代码

┌──────────────────────────────────────────────────────┐
│                   格式转换矩阵                          │
│                                                        │
│  torch (.pth)  ←→  transformers (config.json + safetensors)  │
│                                                        │
│  transformers  →  GGUF (llama.cpp)                     │
│                                                        │
│  transformers  →  ONNX / MNN (端侧)                   │
└──────────────────────────────────────────────────────┘

8.5.2 转换命令

bash 复制代码

cd minimind/scripts

# torch → transformers（导出为标准 HuggingFace 格式）
python convert_model.py --format transformers \
  --input_dir ../minimind-3 \
  --output_dir ../minimind-3-hf

# transformers → GGUF
# 需要使用 llama.cpp 的 convert_hf_to_gguf.py 脚本
python convert_hf_to_gguf.py ../minimind-3-hf --outtype f16

# LoRA 权重合并后导出
python convert_model.py --format transformers \
  --input_dir ../out \
  --output_dir ../merged-hf

8.5.3 transformers 格式的文件结构

plain 复制代码

minimind-3-hf/
├── config.json          # 模型配置
├── tokenizer.json       # Tokenizer 配置
├── tokenizer.model      # SentencePiece 模型
├── special_tokens_map.json
├── model.safetensors    # 模型权重
└── generation_config.json  # 生成参数配置

8.6 接入 RAG 应用

8.6.1 FastGPT 接入

FastGPT 是一个开源的 RAG 平台，可以直接使用 MiniMind 作为 LLM 后端：

plain 复制代码

FastGPT 设置步骤:
1. 部署 MiniMind OpenAI API 服务
2. 在 FastGPT 后台添加自定义 LLM 渠道
3. API 地址: http://your-server:8998/v1
4. API Key: 任意（MiniMind 不验证）
5. 模型名称: minimind-3

8.6.2 Dify 接入

Dify 是另一个流行的 LLM 应用开发平台：

plain 复制代码

Dify 设置步骤:
1. 进入 Dify → 设置 → 模型供应商
2. 添加 OpenAI API 兼容供应商
3. API Base URL: http://your-server:8998/v1
4. API Key: dummy
5. 选择模型: minimind-3

8.6.3 OpenAI 兼容性的意义

MiniMind 的 OpenAI API 兼容设计意味着几乎所有主流 LLM 应用平台都可以无缝接入：

平台	兼容性	用途
FastGPT	✅	知识库问答
Dify	✅	工作流编排
Open-WebUI	✅	ChatGPT 风格前端
LangChain	✅	Agent 开发框架
LobeChat	✅	聊天界面
AnythingLLM	✅	文档问答

8.7 性能优化技巧

8.7.1 推理参数调优

参数	建议值	说明
temperature	0.3-0.7	低值更确定性，高值更多样性
top_p	0.9	核采样，过滤低概率 token
top_k	50	Top-K 采样
max_tokens	512-2048	最大生成长度
repetition_penalty	1.1-1.2	防止重复生成

8.7.2 批量推理

python 复制代码

# 批量处理多个请求
import concurrent.futures
from openai import OpenAI

client = OpenAI(api_key="dummy", base_url="http://localhost:8998/v1")

questions = ["问题1", "问题2", ..., "问题N"]

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
    futures = [
        executor.submit(
            client.chat.completions.create,
            model="minimind-3",
            messages=[{"role": "user", "content": q}],
            max_tokens=256
        ) for q in questions
    ]

    for future in concurrent.futures.as_completed(futures):
        response = future.result()
        print(response.choices[0].message.content)

实践任务

任务 8.1：部署 OpenAI API 服务（必做）

启动 MiniMind API 服务
使用 curl 测试基本对话
使用 Python SDK 调用 API
测试流式输出
测试思考模式

bash 复制代码

# 启动服务
cd scripts && python serve_openai_api.py

# 在另一个终端测试
curl http://localhost:8998/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"minimind-3","messages":[{"role":"user","content":"你好"}]}'

任务 8.2：多框架推理体验（必做）

选择至少 2 种推理框架进行体验：

框架	是否成功	推理速度	使用体验
ollama
vLLM
llama.cpp

任务 8.3：模型格式转换（必做）

bash 复制代码

# 将 MiniMind 模型转换为 transformers 格式
cd scripts
python convert_model.py --format transformers --input_dir ../minimind-3

# 检查输出目录结构
ls -la ../minimind-3-hf/

任务 8.4：自定义 Web Demo（选做）

基于 Streamlit 实现一个增强版的 Web Demo：

支持多轮对话
支持参数调节（temperature、top_p）
支持思考模式切换
对话历史保存/清除
回答质量评分

任务 8.5：接入 RAG 平台（选做）

部署 FastGPT 或 Dify
将 MiniMind API 作为 LLM 后端接入
创建一个简单的知识库问答应用
测试端到端的问答效果

挑战任务（选做）

将 MiniMind 部署到 Docker 容器中
实现一个简单的负载均衡多实例部署
使用 MNN 将 MiniMind 部署到移动端

综合项目选题建议

以下为本课程的综合项目选题，学生可根据兴趣选择：

编号	选题	涉及阶段	难度
P1	从零训练一个领域专用 MiniMind（如网络工程）	4-6	★★★
P2	对比不同 RL 算法在特定任务上的表现	5-7	★★★★
P3	构建基于 MiniMind 的 RAG 问答系统	5, 8	★★★
P4	MiniMind 模型的量化与端侧部署	6, 8	★★★★
P5	改进 MiniMind 架构（如增加层数、调整注意力头数）	3-4	★★★★
P6	多模态 MiniMind（接入视觉模型）	3, 8	★★★★★

课程总结

通过本课程的 8 个阶段，你已经：

✅ 搭建了完整的 LLM 训练环境
✅ 理解了 Tokenizer（BPE）的工作原理
✅ 深入理解了 Transformer 架构的每个组件
✅ 完成了预训练，让模型学会语言规律
✅ 完成了 SFT，让模型学会对话
✅ 掌握了 LoRA 参数高效微调
✅ 了解了 RLHF/RLAIF 对齐技术
✅ 学会了模型部署和 API 服务搭建

MiniMind 虽然是一个小型模型，但它覆盖了大语言模型训练的完整技术栈。理解了 MiniMind 的每个组件，你就具备了阅读和理解主流大模型（如 LLaMA、Qwen、DeepSeek）代码的基础能力。

继续探索的方向：

阅读 LLaMA 3 / Qwen 3 的源码，对比架构差异
尝试在更大规模的数据集上训练
探索最新的对齐技术（如 Online RLHF、Constitutional AI）
构建 Agent 应用（工具调用、多步推理）