# 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 推理实现