266 lines
10 KiB
Markdown
266 lines
10 KiB
Markdown
# 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
|
||
```
|
||
|
||
预测值集中在 8~18 附近，而实际动作在 0~45 之间跳变，模型未能跟踪动作变化趋势。
|
||
|
||
---
|
||
|
||
## 五、分场景效果预测
|
||
|
||
### 场景 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 部署测试**。
|