blackbird/docs/reports/actpred_effectiveness_evaluation_20260809.md

actpred 模块效果评估报告

日期：2026-08-09 评估范围：actpred 模块架构、代码质量、预训练模型实际预测能力、部署就绪度 评估方法：源码审阅 + 单元测试 + 预训练 checkpoint 全量滑动窗口定量评估

---

一、模块定位

actpred 是 micro_servers 的独立/边缘模块，纯离线 CLI 工具，不参与微服务调用链。 核心功能：输入多帧摄像头图像 + 历史动作序列 → 预测下一时间步的连续动作（回归）。 面向树莓派 Dashun 蜘蛛机器人（配合 bot4cj 模块），目标部署场景为嵌入式机器人实时控制。

---

二、架构评估

2.1 模型架构

多帧 Transformer 注意力融合（2026-08 重写）：

F 帧图像 (F×3×64×64) → 共享 CNN 编码器 → F 个 token → proj → d_model ┐
                                                                  ├→ [img×F, act×H, PRED] + 位置编码
动作历史 (H×D)          → Linear proj → d_model → H 个 token ─┤        │
可学习 [PRED] token ─────────────────────────────────────────┘        ▼
                                   TransformerEncoder (pre-LN, 2层, 4头, d=128)
                                                                         │
                                       取 PRED 位置输出 → MLP 头 → 预测动作

2.2 关键指标

指标	数值
参数量	~450K
CPU 端到端推理	4.25 ms（235 FPS）
CPU 纯 forward	2.77 ms
image_encoder 占比	47%（pure forward）
ONNX 导出	opset 17，仅 batch 维动态
ONNX 一致性	max diff ~1.5e-8
单元测试	56 个，全部通过

2.3 架构评价

维度	评级	说明
模型设计	A	多帧注意力融合合理，token 序列固定长度 F+H+1，NPU 友好
推理速度	A	4.25ms 端到端，满足实时控制需求（>100 FPS）
ONNX 部署	A-	静态 shape 导出正确，版本转换有轻微告警不影响功能
安全性	A	零网络攻击面 + weights_only + 完整配置校验链

---

三、代码质量评估

3.1 代码规模

文件	行数	职责
config.py	205	三层 dataclass 配置 + CLI + 校验
model.py	130	SimpleCNN / MobileNetV2 / Transformer 模型
dataset.py	151	数据集加载 + DataRecorder
train.py	187	训练入口（episode 级划分）
pretrain_mt.py	289	.mt 预训练入口（文件级划分）
predict.py	138	推理封装 + CLI
export_onnx.py	58	ONNX 导出 + 一致性验证
mt_parser.py	133	.mt @Action 矩阵解析器
test_actpred.py	722	单元测试（56 cases）
合计	2013

3.2 优点

1. 安全性设计扎实

   • torch.load(..., weights_only=True) 全局使用
   • parse_checkpoint_config 实现键集合 + 值域 + 整除性三重校验
   • 旧架构 checkpoint 被未知键检查拒载

2. 数据泄漏已修复

   • pretrain_mt.py 采用文件级 train/val 划分（非样本级滑动窗口）
   • train.py 采用 episode 级划分，归一化统计量仅用训练集计算

3. 工程化成熟

   • Config dataclass 三层结构 + CLI override + checkpoint roundtrip
   • DataRecorder 原子 mkdir 防并发竞态
   • mt_parser - 前向填充取 @Servo 初始角度

4. 测试覆盖全面

   • 56 单元测试，覆盖前向传播、数据加载、配置校验、mt 解析、推理端到端、ONNX 导出
   • 边界条件充分（空数据集、维度不匹配、帧数不一致、未知键、旧 checkpoint 拒载等）

3.3 可改进项

1. image_encoder 仍为推理瓶颈（占 pure forward 的 47%），后续可 INT8 量化
2. 训练仅用 CosineAnnealingLR，未配置 warmup
3. ONNX 导出 opset 17 版本转换有告警（axes_input_to_attribute 断言失败后 fallback），不影响正确性但值得跟进
4. requirements.txt 版本范围宽松（torch>=2.0,<3.0），生产环境建议锁定

---

四、预训练模型定量评估

4.1 训练数据概况

.mt 脚本文件数:  13
总动作行数:      77
训练数据列数:    12（补零到 18）
文件级划分后:    ~10 文件训练 / ~3 文件验证
训练样本数:      ~50（滑动窗口）
模型参数量:      450K
样本/参数比:     1:9000（严重欠定）

各 .mt 文件数据量：

文件	行数	动作范围
jump.mt	5	[-180, 200]
left-hand.mt	4	[-180, 1000]
left-turn.mt	11	[-180, 200]
lie-down.mt	6	[-180, 200]
rght-hand.mt	4	[-180, 1000]
std.mt	1	[-180, 200]
stdd.mt	7	[-180, 200]
t0.mt	10	[-180, 500]
t1.mt	1	[10, 20]
tilt-b/f/l/r.mt	各 7	[-180, 200]

4.2 全量滑动窗口评估

使用预训练 checkpoint pretrain_best_inference.pt，对所有 .mt 文件做 history_len=5 滑动窗口预测：

脚本	预测数	平均 L2 误差
left-turn.mt	6	117.9
lie-down.mt	1	107.8
stdd.mt	2	138.7
t0.mt	5	239.1
tilt-b.mt	2	193.9
tilt-f.mt	2	201.4
tilt-l.mt	2	210.9
tilt-r.mt	2	183.4

4.3 与 Baseline 对比

方法	Mean L2 Error	相对比率
模型预测	175.8	0.76x
Naive（复制上一步）	230.0	1.0x（基准）
全局均值预测器	251.2	1.09x

模型比 "复制上一步" 好 24%，比 "全局均值" 好 30%。但评估集仅 22 个预测点，统计意义有限。

4.4 预测分布分析

指标	预测	实际
数值范围	[-164.5, 176.3]	[-180.0, 500.0]
各维 std（舵机 0-9）	12~57	0~95
各维 std（扬声器/延时 10-11）	4~58	4~139
各维 std（预留 12-17）	1~6	0

核心问题：预测严重趋于均值（regression to the mean），预测 std 仅为实际 std 的 ~50%。极端值（如扬声器频率 1000Hz、延时 200ms）完全无法捕获。

4.5 典型预测案例

left-turn.mt 滑动窗口预测（前 6 维）：

t=5: pred=[18.0, 10.3, 17.1, -1.3, 16.5, 11.2]  actual=[45, 0, 45, 45, 45, 0]   L2=129.4
t=6: pred=[16.2,  8.5, 15.5, -0.4, 15.1,  8.9]  actual=[45, 0,  0, 45, 45, 0]   L2=127.3
t=7: pred=[15.7,  8.0, 15.0, -0.3, 14.7,  8.3]  actual=[45, 0,  0,  0, 45, 0]   L2=109.1

预测值集中在 818 附近，而实际动作在 045 之间跳变，模型未能跟踪动作变化趋势。

---

五、分场景效果预测

场景 A：当前预训练模型直接部署

评级：不可用

• image_encoder 在零图像上训练，真实摄像头输入产生随机特征
• 预测值被压缩到均值附近 ±15°，无法执行跳变动作
• 扬声器频率预测几乎为 0
• 预期表现：蜘蛛机器人缓慢无规律蠕动，无法完成有意义动作

场景 B：初步采集真实数据微调（~1K 帧，1-2 episodes）

评级：有限可用

• 450K 参数在 1K 帧上可学到基本运动模式
• 平滑动作（站立→缓走）MAE ~15-25°/关节
• 急变动作（跳跃、急转）MAE ~40-60°/关节
• image_encoder 开始学习真实视觉特征

场景 C：充分数据采集（~10K 帧，10+ episodes，多场景）

评级：基本可用

• 平滑动作 MAE ~5-15°/关节
• 急变动作 MAE ~20-40°/关节
• 配合 noise_std 数据增强和早停，泛化可接受
• SimpleCNN 表达力上限开始制约视觉理解

场景 D：场景 C + MobileNetV2 + 归一化动作

评级：较好

• MobileNetV2 ImageNet 预训练权重提供强视觉先验
• 归一化动作空间让 MSE loss 对各维度公平
• 平滑动作 MAE ~3-8°/关节

场景 E：理想状态（~100K 帧，充分多样性）

评级：生产可用

• MAE ~1-5°/关节
• 可完成绝大部分预设动作

---

六、核心瓶颈排序

优先级	瓶颈	严重度	说明
1	数据量	致命	77 行 / 13 文件，450K 参数 vs ~50 样本，样本/参数比 1:9000
2	零图像预训练的 image_encoder	严重	47% 推理算力浪费在未训练的随机 CNN 上
3	动作空间异质性	中等	dim 0-9 角度 [0-200°]、dim 10-11 频率/延时 [0-1000]、dim 12-17 全零，未归一化导致 MSE 被大数值维度主导
4	编舞脚本 vs 反应式行为	中等	.mt 是预设动作编排，不含视觉反馈逻辑，模型学到的是 "动作惯性" 而非 "视觉→动作" 映射
5	SimpleCNN 表达力	轻微	4 层 Conv 对细粒度空间信息编码不足

---

七、量化预测总结

阶段	数据量	可用度	舵机 MAE	能否完成预设动作
当前预训练	77 行 / 零图像	不可用	>50°	不能
初步采集	~1K 帧	有限	15-40°	部分（简单动作）
充分采集	~10K 帧	基本可用	5-20°	大部分
充分 + MobileNet	~10K 帧	较好	3-10°	大部分
理想状态	~100K 帧	生产可用	1-5°	绝大部分

---

八、建议优先级

1. 最高优先：实现遥操作/示教采集，尽快积累真实 (图像, 动作) 配对数据
2. 高优先：采集前开启 --normalize-actions，平衡各维度 loss 权重
3. 中优先：用真实数据微调后再评估，决定是否换 backbone
4. 低优先：考虑预训练时冻结 image_encoder（减少无效梯度），或换恒等映射替代零图像

---

九、结论

actpred 模块架构设计合理，代码质量高，安全防护到位，推理速度满足实时需求。 当前最大短板是 数据量严重不足（77 行零图像预训练），导致模型预测趋于均值、直接部署不可用。 采集 10K 帧以上真实数据微调后，预计可达实用水平。 模块已具备从 "实验原型" 向 "生产部署" 过渡的架构基础，下一步关键路径是 数据采集 → 微调验证 → NPU 部署测试。