210 lines
5.7 KiB
Markdown
210 lines
5.7 KiB
Markdown
# BitFlow MoE 用户快速上手指南
|
||
|
||
## 一、什么是 BitFlow MoE？
|
||
|
||
BitFlow MoE 是一个可以在 **BBC micro:bit** 上运行的微型中文语言模型。它可以：
|
||
|
||
- 回答基础问答（你好、谢谢、你的名字）
|
||
- 进行简单推理（什么会飞、什么吃草）
|
||
- 记住事实（猫吃什么、天是什么颜色）
|
||
|
||
## 二、硬件准备
|
||
|
||
### 必需
|
||
|
||
- **BBC micro:bit v2**（推荐 v2，nRF52833 芯片）
|
||
- **USB 数据线**（Micro-USB）
|
||
- **电脑**（Windows / macOS / Linux）
|
||
|
||
### 可选
|
||
|
||
- 串口工具（PuTTY、Tera Term、minicom）
|
||
- Python 3.8+（用于训练和对话工具）
|
||
|
||
## 三、快速部署（3 分钟）
|
||
|
||
### 步骤 1: 下载模型文件
|
||
|
||
从本仓库下载：
|
||
- `bitflow_moe_weights.bin`（58KB，int8 量化权重）
|
||
- `bitflow_moe.py`（micro:bit 推理代码）
|
||
|
||
### 步骤 2: 拷贝到 micro:bit
|
||
|
||
将两个文件拷贝到 micro:bit 的 USB 驱动器中：
|
||
|
||
```
|
||
MICROBIT/
|
||
├── weights.bin ← bitflow_moe_weights.bin 改名
|
||
├── main.py ← bitflow_moe.py 改名
|
||
└── ...
|
||
```
|
||
|
||
> **注意**：文件名必须是 `weights.bin` 和 `main.py`，不能改名！
|
||
|
||
### 步骤 3: 按下复位键
|
||
|
||
按下 micro:bit 背面的 **RST** 按钮（或拔插 USB），micro:bit 会自动运行 main.py。
|
||
|
||
### 步骤 4: 通过串口对话
|
||
|
||
打开串口工具（115200 波特率），发送：
|
||
|
||
```
|
||
GEN:109,110|15
|
||
```
|
||
|
||
回复：`你好`
|
||
|
||
更多命令见下方 [常用短语 ID 表](#四常用短语id)。
|
||
|
||
## 四、常用短语 ID
|
||
|
||
### 问候类
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 你好 | `GEN:109,110|15` | 你好 |
|
||
| 你好吗 | `GEN:109,110,111|15` | 我很好谢谢 |
|
||
| 早安 | `GEN:116,118|15` | 早安 |
|
||
| 晚安 | `GEN:117,118|15` | 晚安 |
|
||
| 再见 | `GEN:114,115|15` | 再见 |
|
||
|
||
### 礼貌类
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 谢谢 | `GEN:113,113|15` | 不客气 |
|
||
| 你好棒 | `GEN:110,110,120|15` | 谢谢你好 |
|
||
|
||
### 自我介绍
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 你叫什么名字 | `GEN:109,131,39,40,129,130|15` | 我叫bit |
|
||
| 你是谁 | `GEN:109,45|15` | 我是bit |
|
||
|
||
### 喜好
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 你喜欢什么 | `GEN:109,123,124,39,40|15` | 我喜欢花 |
|
||
| 你喜欢猫吗 | `GEN:109,123,124,43|15` | 我很喜欢猫 |
|
||
|
||
### 情感
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 你开心吗 | `GEN:109,70,71|15` | 我很开心你好 |
|
||
| 你伤心吗 | `GEN:109,126,127|15` | 我不伤心 |
|
||
|
||
### 能力
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 你会什么 | `GEN:109,78,59|15` | 我会说话 |
|
||
|
||
### 闲聊
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 你在做什么 | `GEN:109,60,61|15` | 我在看猫 |
|
||
| 今天好吗 | `GEN:140,60,36,37|15` | 今天很好 |
|
||
|
||
### 动物推理
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 什么会飞 | `GEN:39,40,78,15|15` | 鸟会飞 |
|
||
| 什么会跑 | `GEN:39,40,78,14|15` | 猫会跑 |
|
||
| 什么会游 | `GEN:39,40,78,16|15` | 鱼会游 |
|
||
| 什么吃草 | `GEN:39,40,78,18|15` | 牛吃草 |
|
||
|
||
### 事实
|
||
|
||
| 中文 | 命令 | 回复 |
|
||
|------|------|------|
|
||
| 天是什么颜色 | `GEN:54,35,38,39,40|15` | 天是蓝的 |
|
||
| 猫吃什么 | `GEN:43,35,18|15` | 猫吃鱼 |
|
||
| 猫是什么 | `GEN:43,35,38|15` | 猫是动物 |
|
||
|
||
## 五、使用 Python 对话工具
|
||
|
||
如果你不想手动输入 ID，可以使用对话工具：
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install pyserial
|
||
|
||
# 运行对话工具（自动查找 micro:bit 串口）
|
||
python chat_moe.py
|
||
```
|
||
|
||
对话工具会自动：
|
||
1. 查找 micro:bit 的 USB 串口
|
||
2. 显示常用短语菜单
|
||
3. 你输入序号或文字
|
||
4. 自动发送并翻译回复
|
||
|
||
## 六、在电脑上训练自己的模型
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install torch matplotlib
|
||
|
||
# 训练
|
||
python train_bitflow_moe.py
|
||
|
||
# 训练完成后会自动：
|
||
# 1. 保存 PyTorch 权重 (bitflow_moe.pt)
|
||
# 2. 导出 int8 量化权重 (bitflow_moe_weights.bin)
|
||
# 3. 测试推理效果
|
||
# 4. 绘制训练过程图 (training_analysis.png)
|
||
```
|
||
|
||
## 七、常见问题
|
||
|
||
### Q1: 为什么回复是一串数字？
|
||
|
||
BitFlow MoE 输出的是**字符 ID**（0-148），不是中文。这是为了在 micro:bit 上节省内存——字符 ID 只需要 1 字节，而中文字符需要多字节。
|
||
|
||
你可以通过 `chat_moe.py` 自动翻译，或参考上方 ID 表手动解码。
|
||
|
||
### Q2: 模型回答不总是对的？
|
||
|
||
是的。这个模型是**微型模型**，学习的数据量很小（290K tokens），词表只有 149 字符。它更像是一个"概念演示"，证明在 micro:bit 上可以做语言建模。
|
||
|
||
### Q3: 可以扩展词表吗？
|
||
|
||
可以。修改 `VOCAB_CHARS` 字符串即可扩展词表，但需要：
|
||
1. 增加 DIM 和 FFN_DIM（参数量会增大）
|
||
2. 可能需要更大的 micro:bit（如 ESP32）
|
||
3. 重新训练
|
||
|
||
### Q4: 可以用在其他单片机上吗？
|
||
|
||
可以！本项目的推理代码是纯 Python/MicroPython，理论上可以移植到任何支持 MicroPython 的 MCU。我们提供了内存分析：
|
||
|
||
| 平台 | RAM | 是否可用 |
|
||
|------|-----|----------|
|
||
| micro:bit v2 | 256KB (可用 ~108KB) | ✅ 刚好够用 |
|
||
| STM32F4 | 192KB | ✅ 完全够用 |
|
||
| ESP32 | 520KB | ✅ 绰绰有余 |
|
||
| Arduino Nano | 2KB | ❌ 远远不够 |
|
||
|
||
### Q5: 推理速度很慢？
|
||
|
||
micro:bit 的 CPU 是 64MHz，每个字符生成需要 200-500ms。这是硬件限制，无法通过软件优化大幅改善。
|
||
|
||
如果你需要更快的推理，可以考虑：
|
||
- 降低 DIM（32 → 24）
|
||
- 减少专家数量（3 → 1）
|
||
- 换用更强的 MCU（如 ESP32-S3）
|
||
|
||
## 八、技术参考
|
||
|
||
- [架构设计文档](architecture.md) — 详细的架构分析
|
||
- [训练过程图](training_analysis.png) — 10,000 轮训练可视化
|
||
- [训练代码](train_bitflow_moe.py) — 完整的训练脚本
|
||
- [推理代码](bitflow_moe.py) — micro:bit 推理实现
|