BitFlow-MoE/quickstart.md

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

问候类

中文	命令	回复
你好	`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`
你是谁	`GEN:109,45	15`

喜好

中文	命令	回复
你喜欢什么	`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，可以使用对话工具：

# 安装依赖
pip install pyserial

# 运行对话工具（自动查找 micro:bit 串口）
python chat_moe.py

对话工具会自动：

1. 查找 micro:bit 的 USB 串口
2. 显示常用短语菜单
3. 你输入序号或文字
4. 自动发送并翻译回复

六、在电脑上训练自己的模型

# 安装依赖
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）

八、技术参考

• 架构设计文档 — 详细的架构分析
• 训练过程图 — 10,000 轮训练可视化
• 训练代码 — 完整的训练脚本
• 推理代码 — micro:bit 推理实现