从零训练一个迷你 LLM 并部署成 Web 聊天应用（干中学）

现实提醒：从零训练“真正的大语言模型”（数十亿参数）需要海量数据与算力。
但训练闭环（数据→训练→评估→推理→部署）在小模型上完全一样。本项目用“迷你 GPT”跑通全链路，帮你用第一性原理掌握核心。

你会得到什么

• 一个可训练的迷你 GPT（字节级 tokenizer，next-token prediction）
• 一个推理服务（FastAPI，支持 SSE 流式输出）
• 一个 Web 聊天前端（React + TypeScript）
• 一套可复制的“升级路线”：后续可替换为开源大模型 + LoRA 微调 + 更强的推理引擎

目录结构

• python/：数据、训练、推理服务
• web/：聊天 UI
• docker/：Docker 化（可选）

Quick Start（本地跑通）

0) 准备环境（重点：PyTorch）

建议使用 Python 3.11/3.12 创建环境；如果你用 3.13 安装 torch 失败，再回到 3.12（这是 PyTorch wheel 兼容性导致的，与你代码无关）。

cd python
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt

1) 生成一份最小可训练数据

cd python
source .venv/bin/activate
python -m minillm.data --out data/sample.jsonl

2) 训练迷你 GPT（CPU 也能跑，但会慢）

cd python
source .venv/bin/activate
python -m minillm.train --data data/sample.jsonl --run demo

训练产物会写到：python/checkpoints/demo/

3) 启动推理服务（支持流式）

cd python
source .venv/bin/activate
python -m minillm.serve --checkpoint checkpoints/demo

3.1) （可选）启用 MCP 工具调用（含内置“当前时间”工具）

本项目支持通过 MCP (Model Context Protocol) 让模型在对话中调用外部工具（由服务端注入工具列表提示词，并解析模型输出的 <tool_call>...</tool_call> 来执行）。

启用方式：

cd python
source .venv/bin/activate

# 启用内置时间工具：builtin_time.time_now（返回到秒）
python -m minillm.serve --checkpoint checkpoints/demo --mcp-builtin-time

# 或：加载你的 mcp.json 来接入外部 MCP server
python -m minillm.serve --checkpoint checkpoints/demo --mcp-config /path/to/mcp.json

调用 /v1/chat/completions 时保持 use_tools=true（默认即为 true）即可。

默认地址：

• http://127.0.0.1:8000/health
• http://127.0.0.1:8000/v1/chat/completions

4) 启动 Web 聊天前端

cd web
pnpm install
pnpm dev

打开 Vite 提示的地址（通常是 http://127.0.0.1:5173），开始对话。

备注：本仓库默认用 pnpm 管理前端依赖；某些环境下 npm install 可能会因为依赖树里存在 workspace:* 形式的元数据而报错，用 pnpm 最省心。

进阶：方案 3（从零迷你 GPT + LoRA 微调开源基座）

你已经把“从零训练”跑通后，就可以用同一份 JSONL（messages 格式）去做 LoRA 微调，让输出质量立刻上一个台阶。

5) LoRA 微调（默认基座：Qwen/Qwen2.5-0.5B-Instruct）

第一次运行会下载基座模型（体积较大），请确保网络通畅与磁盘空间充足。

cd python
source .venv/bin/activate

# 用样例数据跑通（只训练很少步数，验证流程正确）
python -m minillm_lora.train \
  --base-model Qwen/Qwen2.5-0.5B-Instruct \
  --data data/sample.jsonl \
  --out checkpoints_lora/qwen-demo \
  --max-steps 20 \
  --batch-size 1 \
  --grad-accum 8 \
  --max-length 512

产物目录：python/checkpoints_lora/qwen-demo/（LoRA adapter + tokenizer + meta.json）

6) 启动 LoRA 推理服务（接口与 Web UI 兼容）

cd python
source .venv/bin/activate

python -m minillm_lora.serve \
  --base-model Qwen/Qwen2.5-0.5B-Instruct \
  --adapter checkpoints_lora/qwen-demo \
  --port 8000

然后保持 web/ 的 pnpm dev 不变，直接在网页里对话即可（它请求的还是 /v1/chat/completions）。

下一步：如何“变大 / 变强”

当你把这个闭环跑通后，你已经具备训练大模型所需的核心心智模型。接下来要升级为“实用路线”通常是：

1. 选一个开源基座（例如 0.5B~7B 的 Instruct 模型）
2. 用 LoRA 做指令微调（SFT）
3. 用更强的推理引擎（vLLM / llama.cpp / TensorRT 等）
4. 部署到云（容器 + 监控 + 限流 + 缓存）

如果你愿意，我可以在这个仓库里继续把“LoRA 微调开源基座”的脚本与部署也补齐。

Docker（可选：把“使用/部署”也跑通）

前提：你已经在本机训练好了一个 checkpoint（例如 --run demo 会产出 python/checkpoints/demo/）。

docker compose up --build

然后打开：

• Web：http://localhost:5173
• API：http://localhost:8000/health

如果你要在容器里跑 LoRA 服务（需要你先在宿主机训练出 adapter，例如 python/checkpoints_lora/qwen-demo）：

docker compose run --rm --service-ports api \\
  python -m minillm_lora.serve \\
  --base-model Qwen/Qwen2.5-0.5B-Instruct \\
  --adapter /app/checkpoints_lora/qwen-demo \\
  --host 0.0.0.0 --port 8000