Merge branch 'main' of https://git.cancerai.top/qing/blackbird
This commit is contained in:
qing committed
commit
85eaa2114e
13 files changed
+1149
-312
No files matched your search
+28
-14
@@ -1,19 +1,26 @@
|
||||
# actpred — 动作预测模块
|
||||
|
||||
输入摄像头图像 + 历史动作序列，预测下一个连续动作（回归）。
|
||||
输入多帧摄像头图像 + 历史动作序列，预测下一时间步的连续动作（回归）。
|
||||
|
||||
纯神经网络实现（PyTorch），支持轻量 CNN 或 MobileNetV2 图像编码，MLP/GRU 动作历史编码。总参数量 ~140K（默认）至 ~2.3M。
|
||||
纯神经网络实现（PyTorch）：轻量 CNN 或 MobileNetV2 逐帧编码，图像/动作 token 进轻量
|
||||
Transformer（pre-LN）自注意力融合，取 [PRED] token 回归下一步动作。
|
||||
默认配置总参数量 ~450K。
|
||||
|
||||
## 架构
|
||||
|
||||
```
|
||||
图像 (3×64×64) ──► CNN 编码器 ──► img_feat (128)
|
||||
│
|
||||
├─ concat ──► 融合头 ──► 预测动作 (action_dim)
|
||||
│
|
||||
动作历史 (H×D) ──► MLP/GRU ──► act_feat (64)
|
||||
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_model=128)
|
||||
│
|
||||
取 PRED 位置输出 ─► MLP 头 ─► 预测动作 (action_dim)
|
||||
```
|
||||
|
||||
token 序列长度固定为 F+H+1（默认 3+5+1=9），除 batch 外无动态 shape，对 NPU（如树莓派
|
||||
AI 扩展板）部署友好。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
@@ -23,8 +30,10 @@ cd actpred && bash _set.sh
|
||||
# 训练
|
||||
bash _run.sh train --data-dir ./data --epochs 100 --action-dim 18
|
||||
|
||||
# 推理（--action-history 格式：冒号分隔各步，每步 action_dim 个值，共 history_len 步）
|
||||
bash _run.sh --model checkpoints/best_inference.pt --image frame.jpg \
|
||||
# 推理（--images 按时间顺序旧→新传入 frame_len 个图像路径，冷启动时可重复传同一帧；
|
||||
# --action-history 格式：冒号分隔各步，每步 action_dim 个值，共 history_len 步）
|
||||
bash _run.sh --model checkpoints/best_inference.pt \
|
||||
--images frame_t-2.jpg frame_t-1.jpg frame_t.jpg \
|
||||
--action-history "45,0,45,0,45,0,45,0,90,90,10,200,0,0,0,0,0,0:45,0,45,0,45,0,45,0,90,90,0,20,0,0,0,0,0,0:45,0,45,0,45,0,45,0,90,90,0,0,0,0,0,0,0,0:45,0,45,0,45,0,45,0,90,90,0,0,0,0,0,0,0,0:45,0,45,0,45,0,45,0,90,90,0,0,0,0,0,0,0,0"
|
||||
|
||||
# 导出 ONNX（如安装了 onnxruntime，导出后自动验证一致性）
|
||||
@@ -39,7 +48,7 @@ python test_actpred.py
|
||||
|
||||
## 预训练（从 .mt 脚本，无需图像）
|
||||
|
||||
从 bot4cj 的 `.mt` 动作脚本中提取 `@Action` 矩阵，用零图像占位预训练动作动力学（history → next action），
|
||||
从 bot4cj 的 `.mt` 动作脚本中提取 `@Action` 矩阵，用全零多帧图像占位预训练动作动力学（history → next action），
|
||||
保存的 checkpoint 与正常训练格式完全兼容，可直接用于推理或作为微调起点。
|
||||
|
||||
```bash
|
||||
@@ -74,7 +83,8 @@ data/
|
||||
...
|
||||
```
|
||||
|
||||
每个 timestep 的样本：当前图像 + 前 `history_len` 步动作 → 当前步动作。
|
||||
每个 timestep 的样本：帧 `[t-frame_len+1, t]`（旧→新）+ 前 `history_len` 步动作 → 当前步动作。
|
||||
采样起点为 `max(history_len, frame_len-1)`。
|
||||
|
||||
### 数据采集
|
||||
|
||||
@@ -96,8 +106,11 @@ recorder.flush()
|
||||
| `--image-size` | 64 | 图像缩放尺寸 |
|
||||
| `--action-dim` | 18 | 动作向量维度（对齐 bot4cj 18 列：10 舵机 + 2 云台 + 扬声器频率 + 延时 + 4 预留）|
|
||||
| `--history-len` | 5 | 历史动作窗口长度 |
|
||||
| `--frame-len` | 3 | 输入图像帧数（含当前帧，旧帧在前）|
|
||||
| `--backbone` | simple | CNN 类型 (simple/mobilenet) |
|
||||
| `--history-encoder` | mlp | 历史编码器 (mlp/gru) |
|
||||
| `--attn-dim` | 128 | 注意力 token 维度 d_model（须能被 attn-heads 整除）|
|
||||
| `--attn-heads` | 4 | 注意力头数 |
|
||||
| `--attn-layers` | 2 | TransformerEncoder 层数 |
|
||||
| `--epochs` | 100 | 训练轮数 |
|
||||
| `--lr` | 0.001 | 学习率 |
|
||||
| `--batch-size` | 32 | 批次大小 |
|
||||
@@ -124,7 +137,8 @@ recorder.flush()
|
||||
from predict import ActionPredictorInference
|
||||
|
||||
predictor = ActionPredictorInference("checkpoints/best_inference.pt")
|
||||
print(predictor.action_dim, predictor.history_len) # 公共属性
|
||||
action = predictor.predict(image_rgb, action_history) # np.ndarray (action_dim,)
|
||||
print(predictor.action_dim, predictor.history_len, predictor.frame_len) # 公共属性
|
||||
# images: 长度为 frame_len 的 RGB 图像列表（旧→新，末帧为当前帧；冷启动可重复同一帧）
|
||||
action = predictor.predict(images, action_history) # np.ndarray (action_dim,)
|
||||
# action_history 形状须为 (history_len, action_dim)
|
||||
```
|
||||
+21
-7
@@ -8,6 +8,7 @@ class DataConfig:
|
||||
image_size: int = 64
|
||||
action_dim: int = 18
|
||||
history_len: int = 5
|
||||
frame_len: int = 3
|
||||
data_dir: str = "./data"
|
||||
normalize_actions: bool = False
|
||||
action_stats_path: Optional[str] = None
|
||||
@@ -17,10 +18,11 @@ class DataConfig:
|
||||
class ModelConfig:
|
||||
cnn_backbone: str = "simple"
|
||||
cnn_feature_dim: int = 128
|
||||
action_hidden_dim: int = 64
|
||||
fused_hidden_dim: int = 128
|
||||
dropout: float = 0.1
|
||||
history_encoder: str = "mlp"
|
||||
attn_dim: int = 128
|
||||
attn_heads: int = 4
|
||||
attn_layers: int = 2
|
||||
|
||||
|
||||
@dataclass
|
||||
@@ -60,15 +62,17 @@ def build_argparser(description: str = "") -> argparse.ArgumentParser:
|
||||
parser.add_argument("--image-size", type=int, default=None)
|
||||
parser.add_argument("--action-dim", type=int, default=None)
|
||||
parser.add_argument("--history-len", type=int, default=None)
|
||||
parser.add_argument("--frame-len", type=int, default=None)
|
||||
parser.add_argument("--data-dir", type=str, default=None)
|
||||
parser.add_argument("--normalize-actions", action=argparse.BooleanOptionalAction, default=None)
|
||||
parser.add_argument("--action-stats-path", type=str, default=None)
|
||||
parser.add_argument("--backbone", type=str, default=None, choices=["simple", "mobilenet"])
|
||||
parser.add_argument("--cnn-feature-dim", type=int, default=None)
|
||||
parser.add_argument("--action-hidden-dim", type=int, default=None)
|
||||
parser.add_argument("--fused-hidden-dim", type=int, default=None)
|
||||
parser.add_argument("--dropout", type=float, default=None)
|
||||
parser.add_argument("--history-encoder", type=str, default=None, choices=["mlp", "gru"])
|
||||
parser.add_argument("--attn-dim", type=int, default=None)
|
||||
parser.add_argument("--attn-heads", type=int, default=None)
|
||||
parser.add_argument("--attn-layers", type=int, default=None)
|
||||
parser.add_argument("--batch-size", type=int, default=None)
|
||||
parser.add_argument("--epochs", type=int, default=None)
|
||||
parser.add_argument("--lr", type=float, default=None)
|
||||
@@ -95,11 +99,14 @@ def validate_config_values(data_cfg: DataConfig, model_cfg: ModelConfig,
|
||||
checks = [
|
||||
("image_size", data_cfg.image_size, 1, 1024, int),
|
||||
("history_len", data_cfg.history_len, 1, 1024, int),
|
||||
("frame_len", data_cfg.frame_len, 1, 1024, int),
|
||||
("action_dim", data_cfg.action_dim, 1, 1024, int),
|
||||
("cnn_feature_dim", model_cfg.cnn_feature_dim, 1, 4096, int),
|
||||
("action_hidden_dim", model_cfg.action_hidden_dim, 1, 4096, int),
|
||||
("fused_hidden_dim", model_cfg.fused_hidden_dim, 1, 4096, int),
|
||||
("dropout", model_cfg.dropout, 0.0, 1.0, float),
|
||||
("attn_dim", model_cfg.attn_dim, 1, 4096, int),
|
||||
("attn_heads", model_cfg.attn_heads, 1, 64, int),
|
||||
("attn_layers", model_cfg.attn_layers, 1, 64, int),
|
||||
]
|
||||
for name, val, lo, hi, typ in checks:
|
||||
if typ is int:
|
||||
@@ -110,6 +117,11 @@ def validate_config_values(data_cfg: DataConfig, model_cfg: ModelConfig,
|
||||
raise ValueError(
|
||||
f"checkpoint config {name}={val} 超出合理范围 [{lo}, {hi}]")
|
||||
|
||||
if model_cfg.attn_dim % model_cfg.attn_heads != 0:
|
||||
raise ValueError(
|
||||
f"attn_dim={model_cfg.attn_dim} 必须能被 attn_heads="
|
||||
f"{model_cfg.attn_heads} 整除")
|
||||
|
||||
if train_cfg is not None:
|
||||
t_checks = [
|
||||
("batch_size", train_cfg.batch_size, 1, 65536, int),
|
||||
@@ -162,15 +174,17 @@ def apply_overrides(cfg: Config, args: argparse.Namespace) -> Config:
|
||||
"image_size": ("data", "image_size"),
|
||||
"action_dim": ("data", "action_dim"),
|
||||
"history_len": ("data", "history_len"),
|
||||
"frame_len": ("data", "frame_len"),
|
||||
"data_dir": ("data", "data_dir"),
|
||||
"normalize_actions": ("data", "normalize_actions"),
|
||||
"action_stats_path": ("data", "action_stats_path"),
|
||||
"backbone": ("model", "cnn_backbone"),
|
||||
"cnn_feature_dim": ("model", "cnn_feature_dim"),
|
||||
"action_hidden_dim": ("model", "action_hidden_dim"),
|
||||
"fused_hidden_dim": ("model", "fused_hidden_dim"),
|
||||
"dropout": ("model", "dropout"),
|
||||
"history_encoder": ("model", "history_encoder"),
|
||||
"attn_dim": ("model", "attn_dim"),
|
||||
"attn_heads": ("model", "attn_heads"),
|
||||
"attn_layers": ("model", "attn_layers"),
|
||||
"batch_size": ("train", "batch_size"),
|
||||
"epochs": ("train", "epochs"),
|
||||
"lr": ("train", "lr"),
|
||||
|
||||
+15
-7
@@ -17,10 +17,12 @@ def _natural_key(p):
|
||||
class ActionDataset(Dataset):
|
||||
def __init__(self, data_dir: str, history_len: int, action_dim: int,
|
||||
image_size: int = 64, normalize_actions: bool = False,
|
||||
action_stats_path: str = None, episode_indices: list = None):
|
||||
action_stats_path: str = None, episode_indices: list = None,
|
||||
frame_len: int = 3):
|
||||
self.history_len = history_len
|
||||
self.action_dim = action_dim
|
||||
self.image_size = image_size
|
||||
self.frame_len = frame_len
|
||||
|
||||
self.transform = transforms.Compose([
|
||||
transforms.Resize((image_size, image_size)),
|
||||
@@ -51,8 +53,11 @@ class ActionDataset(Dataset):
|
||||
print(f"WARNING: {ep_dir} 动作帧数 {n_frames} 与图像数 {n_images} 不一致，"
|
||||
f"按较少者（{min(n_frames, n_images)}）使用，请检查录制完整性")
|
||||
n = min(n_frames, n_images)
|
||||
for t in range(history_len, n):
|
||||
self.samples.append((image_files[t], actions[t - history_len:t], actions[t]))
|
||||
# 每个样本：帧 [t-frame_len+1, t]（旧→新）+ 动作历史 [t-history_len, t) → 动作 t
|
||||
start = max(history_len, frame_len - 1)
|
||||
for t in range(start, n):
|
||||
self.samples.append((image_files[t - frame_len + 1: t + 1],
|
||||
actions[t - history_len:t], actions[t]))
|
||||
|
||||
self._action_mean = None
|
||||
self._action_std = None
|
||||
@@ -77,15 +82,18 @@ class ActionDataset(Dataset):
|
||||
return len(self.samples)
|
||||
|
||||
def __getitem__(self, idx):
|
||||
image_path, action_history, target = self.samples[idx]
|
||||
image = Image.open(image_path).convert("RGB")
|
||||
image = self.transform(image)
|
||||
image_paths, action_history, target = self.samples[idx]
|
||||
frames = []
|
||||
for p in image_paths:
|
||||
image = Image.open(p).convert("RGB")
|
||||
frames.append(self.transform(image))
|
||||
images = torch.stack(frames) # (F, 3, S, S)
|
||||
action_history = torch.tensor(action_history, dtype=torch.float32)
|
||||
target = torch.tensor(target, dtype=torch.float32)
|
||||
if self._action_mean is not None:
|
||||
action_history = (action_history - self._action_mean) / self._action_std
|
||||
target = (target - self._action_mean) / self._action_std
|
||||
return {"image": image, "action_history": action_history, "target": target}
|
||||
return {"images": images, "action_history": action_history, "target": target}
|
||||
|
||||
def get_action_stats(self):
|
||||
if self._action_mean is not None:
|
||||
|
||||
@@ -19,16 +19,17 @@ def main():
|
||||
model.load_state_dict(checkpoint["model_state_dict"])
|
||||
model.eval()
|
||||
|
||||
dummy_image = torch.randn(1, 3, data_cfg.image_size, data_cfg.image_size)
|
||||
dummy_images = torch.randn(
|
||||
1, data_cfg.frame_len, 3, data_cfg.image_size, data_cfg.image_size)
|
||||
dummy_history = torch.randn(1, data_cfg.history_len, data_cfg.action_dim)
|
||||
|
||||
torch.onnx.export(
|
||||
model, (dummy_image, dummy_history),
|
||||
model, (dummy_images, dummy_history),
|
||||
args.output,
|
||||
input_names=["image", "action_history"],
|
||||
input_names=["images", "action_history"],
|
||||
output_names=["predicted_action"],
|
||||
dynamic_axes={
|
||||
"image": {0: "batch"},
|
||||
"images": {0: "batch"},
|
||||
"action_history": {0: "batch"},
|
||||
"predicted_action": {0: "batch"},
|
||||
},
|
||||
@@ -41,11 +42,11 @@ def main():
|
||||
import onnxruntime as ort
|
||||
import numpy as np
|
||||
sess = ort.InferenceSession(args.output)
|
||||
img_np = dummy_image.numpy()
|
||||
img_np = dummy_images.numpy()
|
||||
hist_np = dummy_history.numpy()
|
||||
ort_out = sess.run(None, {"image": img_np, "action_history": hist_np})[0]
|
||||
ort_out = sess.run(None, {"images": img_np, "action_history": hist_np})[0]
|
||||
with torch.no_grad():
|
||||
torch_out = model(dummy_image, dummy_history).numpy()
|
||||
torch_out = model(dummy_images, dummy_history).numpy()
|
||||
max_diff = np.abs(ort_out - torch_out).max()
|
||||
print(f"ONNX 一致性验证通过（最大差异: {max_diff:.6e}）")
|
||||
except ImportError:
|
||||
|
||||
+44
-46
@@ -53,34 +53,7 @@ class MobileNetEncoder(nn.Module):
|
||||
return self.proj(x)
|
||||
|
||||
|
||||
class MLPHistoryEncoder(nn.Module):
|
||||
def __init__(self, input_dim: int, hidden_dim: int = 64, dropout: float = 0.1):
|
||||
super().__init__()
|
||||
self.net = nn.Sequential(
|
||||
nn.Linear(input_dim, hidden_dim),
|
||||
nn.ReLU(inplace=True),
|
||||
nn.Dropout(dropout),
|
||||
nn.Linear(hidden_dim, hidden_dim),
|
||||
nn.ReLU(inplace=True),
|
||||
)
|
||||
|
||||
def forward(self, x: torch.Tensor) -> torch.Tensor:
|
||||
return self.net(x)
|
||||
|
||||
|
||||
class GRUHistoryEncoder(nn.Module):
|
||||
def __init__(self, input_dim: int, hidden_dim: int = 64, dropout: float = 0.1):
|
||||
super().__init__()
|
||||
self.gru = nn.GRU(input_size=input_dim, hidden_size=hidden_dim,
|
||||
num_layers=1, batch_first=True)
|
||||
self.dropout = nn.Dropout(dropout)
|
||||
|
||||
def forward(self, x: torch.Tensor) -> torch.Tensor:
|
||||
_, h = self.gru(x)
|
||||
return self.dropout(h.squeeze(0))
|
||||
|
||||
|
||||
class FusionHead(nn.Module):
|
||||
class PredictionHead(nn.Module):
|
||||
def __init__(self, input_dim: int, hidden_dim: int, output_dim: int, dropout: float = 0.1):
|
||||
super().__init__()
|
||||
self.net = nn.Sequential(
|
||||
@@ -97,6 +70,13 @@ class FusionHead(nn.Module):
|
||||
|
||||
|
||||
class ActionPredictor(nn.Module):
|
||||
"""多帧图像 + 历史动作的 Transformer 注意力融合预测器
|
||||
|
||||
token 序列：[img×F, act×H, PRED]，长度固定为 F+H+1，
|
||||
取 PRED 位置输出进预测头回归下一时间步动作。
|
||||
除 batch 维外全部维度静态，保证 ONNX/NPU 部署友好。
|
||||
"""
|
||||
|
||||
def __init__(self, model_cfg: ModelConfig, data_cfg: DataConfig,
|
||||
pretrained: bool = True):
|
||||
super().__init__()
|
||||
@@ -106,26 +86,44 @@ class ActionPredictor(nn.Module):
|
||||
else:
|
||||
self.image_encoder = SimpleCNN(model_cfg.cnn_feature_dim)
|
||||
|
||||
history_input_dim = data_cfg.history_len * data_cfg.action_dim
|
||||
if model_cfg.history_encoder == "gru":
|
||||
self.action_encoder = GRUHistoryEncoder(
|
||||
data_cfg.action_dim, model_cfg.action_hidden_dim, model_cfg.dropout)
|
||||
else:
|
||||
self.action_encoder = MLPHistoryEncoder(
|
||||
history_input_dim, model_cfg.action_hidden_dim, model_cfg.dropout)
|
||||
d = model_cfg.attn_dim
|
||||
self.img_proj = nn.Linear(model_cfg.cnn_feature_dim, d)
|
||||
self.act_proj = nn.Linear(data_cfg.action_dim, d)
|
||||
|
||||
fused_input = model_cfg.cnn_feature_dim + model_cfg.action_hidden_dim
|
||||
self.head = FusionHead(
|
||||
fused_input, model_cfg.fused_hidden_dim, data_cfg.action_dim, model_cfg.dropout)
|
||||
seq_len = data_cfg.frame_len + data_cfg.history_len + 1
|
||||
self.pred_token = nn.Parameter(torch.zeros(1, 1, d))
|
||||
self.pos_embed = nn.Parameter(torch.zeros(1, seq_len, d))
|
||||
nn.init.trunc_normal_(self.pred_token, std=0.02)
|
||||
nn.init.trunc_normal_(self.pos_embed, std=0.02)
|
||||
|
||||
self._use_gru = model_cfg.history_encoder == "gru"
|
||||
encoder_layer = nn.TransformerEncoderLayer(
|
||||
d_model=d, nhead=model_cfg.attn_heads,
|
||||
dim_feedforward=d * 2, dropout=model_cfg.dropout,
|
||||
batch_first=True, norm_first=True)
|
||||
self.encoder = nn.TransformerEncoder(
|
||||
encoder_layer, num_layers=model_cfg.attn_layers,
|
||||
enable_nested_tensor=False)
|
||||
|
||||
self.head = PredictionHead(
|
||||
d, model_cfg.fused_hidden_dim, data_cfg.action_dim, model_cfg.dropout)
|
||||
|
||||
self._frame_len = data_cfg.frame_len
|
||||
self._history_len = data_cfg.history_len
|
||||
self._action_dim = data_cfg.action_dim
|
||||
self._image_size = data_cfg.image_size
|
||||
self._cnn_feature_dim = model_cfg.cnn_feature_dim
|
||||
|
||||
def forward(self, image: torch.Tensor, action_history: torch.Tensor) -> torch.Tensor:
|
||||
img_feat = self.image_encoder(image)
|
||||
if self._use_gru:
|
||||
act_feat = self.action_encoder(action_history)
|
||||
else:
|
||||
act_feat = self.action_encoder(action_history.flatten(1))
|
||||
return self.head(torch.cat([img_feat, act_feat], dim=-1))
|
||||
def forward(self, images: torch.Tensor, action_history: torch.Tensor) -> torch.Tensor:
|
||||
# images: (B, F, 3, S, S) action_history: (B, H, D)
|
||||
b = images.size(0)
|
||||
frames = images.reshape(
|
||||
b * self._frame_len, 3, self._image_size, self._image_size)
|
||||
img_feat = self.image_encoder(frames).reshape(
|
||||
b, self._frame_len, self._cnn_feature_dim)
|
||||
img_tokens = self.img_proj(img_feat)
|
||||
act_tokens = self.act_proj(action_history)
|
||||
pred_token = self.pred_token.expand(b, -1, -1)
|
||||
tokens = torch.cat([img_tokens, act_tokens, pred_token], dim=1)
|
||||
tokens = tokens + self.pos_embed
|
||||
out = self.encoder(tokens)
|
||||
return self.head(out[:, -1])
|
||||
+23
-6
@@ -28,6 +28,7 @@ class ActionPredictorInference:
|
||||
|
||||
self.action_dim = self._data_cfg.action_dim
|
||||
self.history_len = self._data_cfg.history_len
|
||||
self.frame_len = self._data_cfg.frame_len
|
||||
|
||||
self._transform = transforms.Compose([
|
||||
transforms.Resize((self._data_cfg.image_size, self._data_cfg.image_size)),
|
||||
@@ -61,13 +62,23 @@ class ActionPredictorInference:
|
||||
self._action_std = stats[1].astype(np.float32)
|
||||
|
||||
@torch.no_grad()
|
||||
def predict(self, image: np.ndarray, action_history: np.ndarray) -> np.ndarray:
|
||||
def predict(self, images, action_history: np.ndarray) -> np.ndarray:
|
||||
"""images: 长度为 frame_len 的 RGB 图像序列（旧→新，末帧为当前帧）"""
|
||||
if not isinstance(images, (list, tuple)):
|
||||
images = [images]
|
||||
if len(images) != self._data_cfg.frame_len:
|
||||
raise ValueError(
|
||||
f"images 应为 {self._data_cfg.frame_len} 帧，实际为 {len(images)} 帧。"
|
||||
f"冷启动时可重复传入同一帧。")
|
||||
expected_shape = (self._data_cfg.history_len, self._data_cfg.action_dim)
|
||||
if action_history.shape != expected_shape:
|
||||
raise ValueError(
|
||||
f"action_history 形状应为 {expected_shape}，实际为 {action_history.shape}")
|
||||
img = Image.fromarray(image) if isinstance(image, np.ndarray) else image
|
||||
img_tensor = self._transform(img).unsqueeze(0).to(self._device)
|
||||
frames = []
|
||||
for image in images:
|
||||
img = Image.fromarray(image) if isinstance(image, np.ndarray) else image
|
||||
frames.append(self._transform(img))
|
||||
img_tensor = torch.stack(frames).unsqueeze(0).to(self._device) # (1, F, 3, S, S)
|
||||
history = torch.tensor(action_history, dtype=torch.float32)
|
||||
if self._action_mean is not None:
|
||||
history = (history - self._action_mean) / self._action_std
|
||||
@@ -93,7 +104,9 @@ def parse_action_history(s: str, action_dim: int) -> np.ndarray:
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="actpred inference")
|
||||
parser.add_argument("--model", required=True, help="checkpoint path")
|
||||
parser.add_argument("--image", required=True, help="image file path")
|
||||
parser.add_argument("--images", required=True, nargs="+",
|
||||
help="按时间顺序（旧→新）传入 frame_len 个图像路径；"
|
||||
"冷启动时可重复传同一帧路径")
|
||||
parser.add_argument("--action-history", required=True,
|
||||
help="冒号分隔各步，每步 action_dim 个值，共 history_len 步。"
|
||||
"e.g. '0,0,0,0:1,0,0,0' (action_dim=4, history_len=2)")
|
||||
@@ -106,9 +119,13 @@ def main():
|
||||
predictor = ActionPredictorInference(args.model, args.device)
|
||||
action_dim = args.action_dim or predictor.action_dim
|
||||
|
||||
image = Image.open(args.image).convert("RGB")
|
||||
if len(args.images) != predictor.frame_len:
|
||||
raise SystemExit(
|
||||
f"--images 需传入 {predictor.frame_len} 个路径（旧→新），"
|
||||
f"实际为 {len(args.images)} 个。冷启动时可重复传同一帧路径。")
|
||||
images = [np.array(Image.open(p).convert("RGB")) for p in args.images]
|
||||
history = parse_action_history(args.action_history, action_dim)
|
||||
predicted = predictor.predict(np.array(image), history)
|
||||
predicted = predictor.predict(images, history)
|
||||
|
||||
if args.output_format == "json":
|
||||
print(json.dumps({"predicted_action": predicted.tolist()}, indent=2))
|
||||
|
||||
+21
-15
@@ -76,24 +76,25 @@ class MTActionDataset(Dataset):
|
||||
}
|
||||
|
||||
|
||||
def pretrain_one_epoch(model, loader, optimizer, device, image_size,
|
||||
def pretrain_one_epoch(model, loader, optimizer, device, image_size, frame_len,
|
||||
max_grad_norm=None, noise_std=0.0):
|
||||
model.train()
|
||||
total_loss = 0.0
|
||||
count = 0
|
||||
zero_image = None
|
||||
zero_images = None
|
||||
for batch in tqdm(loader, desc=" pretrain", leave=False):
|
||||
history = batch["action_history"].to(device)
|
||||
target = batch["target"].to(device)
|
||||
if noise_std > 0:
|
||||
history = history + torch.randn_like(history) * noise_std
|
||||
target = target + torch.randn_like(target) * noise_std
|
||||
if zero_image is None or zero_image.size(0) != history.size(0):
|
||||
zero_image = torch.zeros(
|
||||
history.size(0), 3, image_size, image_size, device=device
|
||||
if zero_images is None or zero_images.size(0) != history.size(0):
|
||||
zero_images = torch.zeros(
|
||||
history.size(0), frame_len, 3, image_size, image_size,
|
||||
device=device,
|
||||
)
|
||||
optimizer.zero_grad()
|
||||
pred = model(zero_image, history)
|
||||
pred = model(zero_images, history)
|
||||
loss = torch.nn.functional.mse_loss(pred, target)
|
||||
loss.backward()
|
||||
if max_grad_norm:
|
||||
@@ -105,19 +106,20 @@ def pretrain_one_epoch(model, loader, optimizer, device, image_size,
|
||||
|
||||
|
||||
@torch.no_grad()
|
||||
def validate(model, loader, device, image_size):
|
||||
def validate(model, loader, device, image_size, frame_len):
|
||||
model.eval()
|
||||
total_loss = 0.0
|
||||
count = 0
|
||||
zero_image = None
|
||||
zero_images = None
|
||||
for batch in tqdm(loader, desc=" val ", leave=False):
|
||||
history = batch["action_history"].to(device)
|
||||
target = batch["target"].to(device)
|
||||
if zero_image is None or zero_image.size(0) != history.size(0):
|
||||
zero_image = torch.zeros(
|
||||
history.size(0), 3, image_size, image_size, device=device
|
||||
if zero_images is None or zero_images.size(0) != history.size(0):
|
||||
zero_images = torch.zeros(
|
||||
history.size(0), frame_len, 3, image_size, image_size,
|
||||
device=device,
|
||||
)
|
||||
pred = model(zero_image, history)
|
||||
pred = model(zero_images, history)
|
||||
loss = torch.nn.functional.mse_loss(pred, target)
|
||||
total_loss += loss.item() * history.size(0)
|
||||
count += history.size(0)
|
||||
@@ -198,8 +200,10 @@ def main():
|
||||
print(f"Model params: {n_params:,}")
|
||||
print(f"Config: action_dim={cfg.data.action_dim}, "
|
||||
f"history_len={cfg.data.history_len}, "
|
||||
f"frame_len={cfg.data.frame_len}, "
|
||||
f"backbone={cfg.model.cnn_backbone}, "
|
||||
f"encoder={cfg.model.history_encoder}")
|
||||
f"attn={cfg.model.attn_layers}x{cfg.model.attn_heads}h"
|
||||
f"@{cfg.model.attn_dim}")
|
||||
print(f"Pre-training: noise_std={args.noise_std}")
|
||||
|
||||
optimizer = torch.optim.AdamW(
|
||||
@@ -222,9 +226,11 @@ def main():
|
||||
f"lr={optimizer.param_groups[0]['lr']:.6f}")
|
||||
train_loss = pretrain_one_epoch(
|
||||
model, train_loader, optimizer, device,
|
||||
cfg.data.image_size, cfg.train.max_grad_norm, args.noise_std,
|
||||
cfg.data.image_size, cfg.data.frame_len,
|
||||
cfg.train.max_grad_norm, args.noise_std,
|
||||
)
|
||||
val_loss = validate(model, val_loader, device, cfg.data.image_size)
|
||||
val_loss = validate(model, val_loader, device,
|
||||
cfg.data.image_size, cfg.data.frame_len)
|
||||
scheduler.step()
|
||||
print(f" train_loss={train_loss:.6f} val_loss={val_loss:.6f}")
|
||||
|
||||
|
||||
+102
-35
@@ -79,45 +79,57 @@ class TestParseActionHistory(unittest.TestCase):
|
||||
|
||||
|
||||
class TestActionPredictor(unittest.TestCase):
|
||||
"""测试模型前向传播"""
|
||||
"""测试多帧注意力模型前向传播"""
|
||||
|
||||
def test_forward_simple_mlp(self):
|
||||
data_cfg = DataConfig(image_size=64, action_dim=18, history_len=5)
|
||||
model_cfg = ModelConfig(cnn_backbone="simple", history_encoder="mlp")
|
||||
def test_forward_multi_frame(self):
|
||||
data_cfg = DataConfig(image_size=64, action_dim=18, history_len=5, frame_len=3)
|
||||
model_cfg = ModelConfig(cnn_backbone="simple")
|
||||
model = ActionPredictor(model_cfg, data_cfg)
|
||||
model.eval()
|
||||
|
||||
image = torch.randn(2, 3, 64, 64)
|
||||
images = torch.randn(2, 3, 3, 64, 64)
|
||||
history = torch.randn(2, 5, 18)
|
||||
with torch.no_grad():
|
||||
out = model(image, history)
|
||||
out = model(images, history)
|
||||
self.assertEqual(out.shape, (2, 18))
|
||||
|
||||
def test_forward_simple_gru(self):
|
||||
data_cfg = DataConfig(image_size=64, action_dim=18, history_len=5)
|
||||
model_cfg = ModelConfig(cnn_backbone="simple", history_encoder="gru")
|
||||
def test_forward_single_frame_degenerate(self):
|
||||
"""frame_len=1 退化为单帧输入也应正常前向"""
|
||||
data_cfg = DataConfig(image_size=32, action_dim=4, history_len=3, frame_len=1)
|
||||
model_cfg = ModelConfig(cnn_backbone="simple")
|
||||
model = ActionPredictor(model_cfg, data_cfg)
|
||||
model.eval()
|
||||
|
||||
image = torch.randn(2, 3, 64, 64)
|
||||
history = torch.randn(2, 5, 18)
|
||||
images = torch.randn(2, 1, 3, 32, 32)
|
||||
history = torch.randn(2, 3, 4)
|
||||
with torch.no_grad():
|
||||
out = model(image, history)
|
||||
self.assertEqual(out.shape, (2, 18))
|
||||
out = model(images, history)
|
||||
self.assertEqual(out.shape, (2, 4))
|
||||
|
||||
def test_forward_dynamic_batch(self):
|
||||
data_cfg = DataConfig(image_size=32, action_dim=4, history_len=3)
|
||||
model_cfg = ModelConfig(cnn_backbone="simple", history_encoder="mlp")
|
||||
data_cfg = DataConfig(image_size=32, action_dim=4, history_len=3, frame_len=2)
|
||||
model_cfg = ModelConfig(cnn_backbone="simple")
|
||||
model = ActionPredictor(model_cfg, data_cfg)
|
||||
model.eval()
|
||||
|
||||
for batch_size in [1, 4, 8]:
|
||||
image = torch.randn(batch_size, 3, 32, 32)
|
||||
images = torch.randn(batch_size, 2, 3, 32, 32)
|
||||
history = torch.randn(batch_size, 3, 4)
|
||||
with torch.no_grad():
|
||||
out = model(image, history)
|
||||
out = model(images, history)
|
||||
self.assertEqual(out.shape, (batch_size, 4))
|
||||
|
||||
def test_custom_attn_config(self):
|
||||
"""自定义 attn_dim/heads/layers 应可构建并前向"""
|
||||
data_cfg = DataConfig(image_size=32, action_dim=4, history_len=3, frame_len=2)
|
||||
model_cfg = ModelConfig(attn_dim=64, attn_heads=2, attn_layers=1)
|
||||
model = ActionPredictor(model_cfg, data_cfg)
|
||||
model.eval()
|
||||
|
||||
with torch.no_grad():
|
||||
out = model(torch.randn(1, 2, 3, 32, 32), torch.randn(1, 3, 4))
|
||||
self.assertEqual(out.shape, (1, 4))
|
||||
|
||||
|
||||
class TestDataRecorder(unittest.TestCase):
|
||||
"""测试数据录制器"""
|
||||
@@ -169,17 +181,30 @@ class TestActionDataset(unittest.TestCase):
|
||||
def test_dataset_loading(self):
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
self._create_dummy_episode(Path(tmpdir), n_frames=10, action_dim=4)
|
||||
ds = ActionDataset(tmpdir, history_len=3, action_dim=4, image_size=32)
|
||||
self.assertEqual(len(ds), 7) # 10 - 3 = 7 samples
|
||||
ds = ActionDataset(tmpdir, history_len=3, action_dim=4, image_size=32,
|
||||
frame_len=3)
|
||||
# 采样起点 max(history_len, frame_len-1) = 3 → 10 - 3 = 7 samples
|
||||
self.assertEqual(len(ds), 7)
|
||||
|
||||
sample = ds[0]
|
||||
self.assertIn("image", sample)
|
||||
self.assertIn("images", sample)
|
||||
self.assertIn("action_history", sample)
|
||||
self.assertIn("target", sample)
|
||||
self.assertEqual(sample["image"].shape, (3, 32, 32))
|
||||
self.assertEqual(sample["images"].shape, (3, 3, 32, 32))
|
||||
self.assertEqual(sample["action_history"].shape, (3, 4))
|
||||
self.assertEqual(sample["target"].shape, (4,))
|
||||
|
||||
def test_frame_len_gt_history_shifts_start(self):
|
||||
"""frame_len-1 > history_len 时采样起点由帧窗口决定"""
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
self._create_dummy_episode(Path(tmpdir), n_frames=10, action_dim=4)
|
||||
ds = ActionDataset(tmpdir, history_len=3, action_dim=4, image_size=32,
|
||||
frame_len=6)
|
||||
# 起点 max(3, 5) = 5 → 10 - 5 = 5 samples
|
||||
self.assertEqual(len(ds), 5)
|
||||
sample = ds[0]
|
||||
self.assertEqual(sample["images"].shape, (6, 3, 32, 32))
|
||||
|
||||
def test_episode_count(self):
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
self._create_dummy_episode(Path(tmpdir))
|
||||
@@ -241,17 +266,24 @@ class TestConfig(unittest.TestCase):
|
||||
self.assertEqual(cfg.data.image_size, 64)
|
||||
self.assertEqual(cfg.data.action_dim, 18)
|
||||
self.assertEqual(cfg.data.history_len, 5)
|
||||
self.assertEqual(cfg.data.frame_len, 3)
|
||||
self.assertEqual(cfg.model.cnn_backbone, "simple")
|
||||
self.assertEqual(cfg.model.history_encoder, "mlp")
|
||||
self.assertEqual(cfg.model.attn_dim, 128)
|
||||
self.assertEqual(cfg.model.attn_heads, 4)
|
||||
self.assertEqual(cfg.model.attn_layers, 2)
|
||||
self.assertEqual(cfg.train.epochs, 100)
|
||||
|
||||
def test_apply_overrides(self):
|
||||
parser = build_argparser("test")
|
||||
args = parser.parse_args(["--epochs", "50", "--lr", "0.01", "--backbone", "mobilenet"])
|
||||
args = parser.parse_args(["--epochs", "50", "--lr", "0.01",
|
||||
"--backbone", "mobilenet",
|
||||
"--frame-len", "4", "--attn-dim", "64"])
|
||||
cfg = apply_overrides(Config(), args)
|
||||
self.assertEqual(cfg.train.epochs, 50)
|
||||
self.assertEqual(cfg.train.lr, 0.01)
|
||||
self.assertEqual(cfg.model.cnn_backbone, "mobilenet")
|
||||
self.assertEqual(cfg.data.frame_len, 4)
|
||||
self.assertEqual(cfg.model.attn_dim, 64)
|
||||
|
||||
def test_normalize_actions_flag(self):
|
||||
"""--normalize-actions 和 --no-normalize-actions 都应可用"""
|
||||
@@ -421,18 +453,23 @@ class TestValidateConfigValues(unittest.TestCase):
|
||||
|
||||
def test_out_of_range_or_non_int_raises(self):
|
||||
for field, value in [("image_size", 99999), ("image_size", 0),
|
||||
("history_len", -1), ("action_dim", "18")]:
|
||||
("history_len", -1), ("frame_len", 0),
|
||||
("frame_len", 99999), ("action_dim", "18")]:
|
||||
cfg = Config()
|
||||
setattr(cfg.data, field, value)
|
||||
with self.assertRaises(ValueError, msg=f"{field}={value}"):
|
||||
validate_config_values(cfg.data, cfg.model)
|
||||
|
||||
def test_model_field_out_of_range_raises(self):
|
||||
"""model 字段越界（fused_hidden_dim 超限、dropout 越界）应抛 ValueError"""
|
||||
"""model 字段越界（fused_hidden_dim 超限、dropout 越界、attn_* 越界）应抛 ValueError"""
|
||||
for field, value in [("fused_hidden_dim", 10 ** 9),
|
||||
("fused_hidden_dim", 0),
|
||||
("cnn_feature_dim", 99999),
|
||||
("action_hidden_dim", -1),
|
||||
("attn_dim", 0),
|
||||
("attn_dim", 99999),
|
||||
("attn_heads", 0),
|
||||
("attn_heads", 128),
|
||||
("attn_layers", 0),
|
||||
("dropout", 1.5),
|
||||
("dropout", -0.1)]:
|
||||
cfg = Config()
|
||||
@@ -440,6 +477,14 @@ class TestValidateConfigValues(unittest.TestCase):
|
||||
with self.assertRaises(ValueError, msg=f"{field}={value}"):
|
||||
validate_config_values(cfg.data, cfg.model)
|
||||
|
||||
def test_attn_dim_not_divisible_by_heads_raises(self):
|
||||
"""attn_dim 不能被 attn_heads 整除应抛 ValueError"""
|
||||
cfg = Config()
|
||||
cfg.model.attn_dim = 130
|
||||
cfg.model.attn_heads = 4
|
||||
with self.assertRaisesRegex(ValueError, "整除"):
|
||||
validate_config_values(cfg.data, cfg.model)
|
||||
|
||||
def test_train_field_out_of_range_raises(self):
|
||||
"""train 字段越界（lr 为负、val_split>1 等）应抛 ValueError"""
|
||||
for field, value in [("lr", -1.0), ("lr", 0.0),
|
||||
@@ -474,6 +519,15 @@ class TestParseCheckpointConfig(unittest.TestCase):
|
||||
with self.assertRaisesRegex(ValueError, "evil_extra_key"):
|
||||
parse_checkpoint_config(d)
|
||||
|
||||
def test_legacy_checkpoint_config_rejected(self):
|
||||
"""旧架构 checkpoint（含 history_encoder/action_hidden_dim）应拒载"""
|
||||
cfg = Config()
|
||||
d = cfg.to_dict()
|
||||
d["model"]["history_encoder"] = "mlp"
|
||||
d["model"]["action_hidden_dim"] = 64
|
||||
with self.assertRaisesRegex(ValueError, "history_encoder"):
|
||||
parse_checkpoint_config(d)
|
||||
|
||||
def test_missing_section_raises(self):
|
||||
cfg = Config()
|
||||
d = cfg.to_dict()
|
||||
@@ -519,11 +573,13 @@ class TestActionPredictorInference(unittest.TestCase):
|
||||
"""测试推理封装端到端：checkpoint 保存 → 加载 → 推理"""
|
||||
|
||||
@staticmethod
|
||||
def _make_checkpoint(tmpdir, normalize_actions=False, image_size=32):
|
||||
def _make_checkpoint(tmpdir, normalize_actions=False, image_size=32,
|
||||
frame_len=3):
|
||||
cfg = Config()
|
||||
cfg.data.image_size = image_size
|
||||
cfg.data.action_dim = 4
|
||||
cfg.data.history_len = 3
|
||||
cfg.data.frame_len = frame_len
|
||||
cfg.data.normalize_actions = normalize_actions
|
||||
model = ActionPredictor(cfg.model, cfg.data)
|
||||
model.eval()
|
||||
@@ -533,17 +589,19 @@ class TestActionPredictorInference(unittest.TestCase):
|
||||
return path, model, cfg
|
||||
|
||||
def test_end_to_end_predict(self):
|
||||
"""加载 checkpoint 后推理输出形状正确、数值有限且可复现"""
|
||||
"""加载 checkpoint 后多帧推理输出形状正确、数值有限且可复现"""
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
path, _, _ = self._make_checkpoint(tmpdir)
|
||||
predictor = ActionPredictorInference(path, device="cpu")
|
||||
self.assertEqual(predictor.action_dim, 4)
|
||||
self.assertEqual(predictor.history_len, 3)
|
||||
self.assertEqual(predictor.frame_len, 3)
|
||||
|
||||
image = np.random.randint(0, 255, (32, 32, 3), dtype=np.uint8)
|
||||
images = [np.random.randint(0, 255, (32, 32, 3), dtype=np.uint8)
|
||||
for _ in range(3)]
|
||||
history = np.random.randn(3, 4).astype(np.float32)
|
||||
pred1 = predictor.predict(image, history)
|
||||
pred2 = predictor.predict(image, history)
|
||||
pred1 = predictor.predict(images, history)
|
||||
pred2 = predictor.predict(images, history)
|
||||
self.assertEqual(pred1.shape, (4,))
|
||||
self.assertTrue(np.all(np.isfinite(pred1)))
|
||||
np.testing.assert_array_equal(pred1, pred2) # eval 模式确定性
|
||||
@@ -563,9 +621,18 @@ class TestActionPredictorInference(unittest.TestCase):
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
path, _, _ = self._make_checkpoint(tmpdir)
|
||||
predictor = ActionPredictorInference(path, device="cpu")
|
||||
image = np.zeros((32, 32, 3), dtype=np.uint8)
|
||||
images = [np.zeros((32, 32, 3), dtype=np.uint8)] * 3
|
||||
with self.assertRaisesRegex(ValueError, "action_history"):
|
||||
predictor.predict(image, np.zeros((2, 4), dtype=np.float32))
|
||||
predictor.predict(images, np.zeros((2, 4), dtype=np.float32))
|
||||
|
||||
def test_wrong_frame_count_raises(self):
|
||||
"""传入帧数与 frame_len 不一致应抛 ValueError"""
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
path, _, _ = self._make_checkpoint(tmpdir)
|
||||
predictor = ActionPredictorInference(path, device="cpu")
|
||||
images = [np.zeros((32, 32, 3), dtype=np.uint8)] * 2
|
||||
with self.assertRaisesRegex(ValueError, "帧"):
|
||||
predictor.predict(images, np.zeros((3, 4), dtype=np.float32))
|
||||
|
||||
def test_missing_action_stats_raises(self):
|
||||
"""启用归一化但缺 action_stats.npy 应抛 FileNotFoundError"""
|
||||
@@ -594,9 +661,9 @@ class TestActionPredictorInference(unittest.TestCase):
|
||||
image = np.random.randint(0, 255, (32, 32, 3), dtype=np.uint8)
|
||||
history = np.random.randn(3, 4).astype(np.float32)
|
||||
pred_raw = ActionPredictorInference(
|
||||
raw_path, device="cpu").predict(image, history)
|
||||
raw_path, device="cpu").predict([image] * 3, history)
|
||||
pred_norm = ActionPredictorInference(
|
||||
norm_path, device="cpu").predict(image, history)
|
||||
norm_path, device="cpu").predict([image] * 3, history)
|
||||
np.testing.assert_allclose(pred_norm, pred_raw, rtol=1e-5, atol=1e-6)
|
||||
|
||||
def test_stats_shape_mismatch_raises(self):
|
||||
|
||||
+10
-10
@@ -25,18 +25,18 @@ def train_one_epoch(model, loader, optimizer, device, max_grad_norm: float = Non
|
||||
total_loss = 0.0
|
||||
count = 0
|
||||
for batch in tqdm(loader, desc=" train", leave=False):
|
||||
image = batch["image"].to(device)
|
||||
images = batch["images"].to(device)
|
||||
history = batch["action_history"].to(device)
|
||||
target = batch["target"].to(device)
|
||||
optimizer.zero_grad()
|
||||
pred = model(image, history)
|
||||
pred = model(images, history)
|
||||
loss = torch.nn.functional.mse_loss(pred, target)
|
||||
loss.backward()
|
||||
if max_grad_norm:
|
||||
torch.nn.utils.clip_grad_norm_(model.parameters(), max_grad_norm)
|
||||
optimizer.step()
|
||||
total_loss += loss.item() * image.size(0)
|
||||
count += image.size(0)
|
||||
total_loss += loss.item() * images.size(0)
|
||||
count += images.size(0)
|
||||
return total_loss / max(count, 1)
|
||||
|
||||
|
||||
@@ -46,13 +46,13 @@ def validate(model, loader, device):
|
||||
total_loss = 0.0
|
||||
count = 0
|
||||
for batch in tqdm(loader, desc=" val ", leave=False):
|
||||
image = batch["image"].to(device)
|
||||
images = batch["images"].to(device)
|
||||
history = batch["action_history"].to(device)
|
||||
target = batch["target"].to(device)
|
||||
pred = model(image, history)
|
||||
pred = model(images, history)
|
||||
loss = torch.nn.functional.mse_loss(pred, target)
|
||||
total_loss += loss.item() * image.size(0)
|
||||
count += image.size(0)
|
||||
total_loss += loss.item() * images.size(0)
|
||||
count += images.size(0)
|
||||
if count == 0:
|
||||
return float("inf") # 空验证集不参与比较，避免假 best
|
||||
return total_loss / count
|
||||
@@ -83,7 +83,7 @@ def main():
|
||||
train_ds = ActionDataset(
|
||||
cfg.data.data_dir, cfg.data.history_len, cfg.data.action_dim,
|
||||
cfg.data.image_size, cfg.data.normalize_actions,
|
||||
cfg.data.action_stats_path, train_indices)
|
||||
cfg.data.action_stats_path, train_indices, cfg.data.frame_len)
|
||||
if cfg.data.normalize_actions and not cfg.data.action_stats_path:
|
||||
# 归一化统计量必须只用训练集计算，再供验证集复用，否则 val loss 不可信
|
||||
stats_path = os.path.join(cfg.train.checkpoint_dir, "action_stats.npy")
|
||||
@@ -93,7 +93,7 @@ def main():
|
||||
val_ds = ActionDataset(
|
||||
cfg.data.data_dir, cfg.data.history_len, cfg.data.action_dim,
|
||||
cfg.data.image_size, cfg.data.normalize_actions,
|
||||
cfg.data.action_stats_path, val_indices)
|
||||
cfg.data.action_stats_path, val_indices, cfg.data.frame_len)
|
||||
|
||||
print(f"Samples: {len(train_ds)} train, {len(val_ds)} val")
|
||||
if len(train_ds) == 0:
|
||||
|
||||
-165
@@ -1,165 +0,0 @@
|
||||
# micro_servers 文档索引
|
||||
|
||||
所有项目文档的统一入口。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── INDEX.md # 本文件（文档总索引）
|
||||
├── security/ # 安全审计与加固（29 篇）
|
||||
├── reviews/ # 代码审查日志（4 篇）
|
||||
└── reports/ # 分析报告与开发规划（14 篇）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 一、项目总览
|
||||
|
||||
| 文档 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| 项目 README | [../README.md](../README.md) | 架构总览、服务说明、安装运行指南 |
|
||||
|
||||
---
|
||||
|
||||
## 二、安全文档 (`security/`)
|
||||
|
||||
### 全局审计与加固
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [DEPLOY_SECURITY_AUDIT_20260801.md](security/DEPLOY_SECURITY_AUDIT_20260801.md) | 部署配置安全审计（docker-compose、systemd、防火墙、TLS 等） |
|
||||
| [DEPS_SECURITY_AUDIT_20260801.md](security/DEPS_SECURITY_AUDIT_20260801.md) | 依赖安全审计（第三方库版本、已知漏洞、许可证） |
|
||||
| [SECURITY_HARDENING_PLAN_20260803.md](security/SECURITY_HARDENING_PLAN_20260803.md) | 安全加固计划（内网通信安全加固开发计划） |
|
||||
|
||||
### 各模块安全审计报告
|
||||
|
||||
| 模块 | 文档 | 审计范围 |
|
||||
|------|------|----------|
|
||||
| waf | [waf_SECURITY_AUDIT_20260801.md](security/waf_SECURITY_AUDIT_20260801.md) | Go WAF 网关（TLS、coraza、反向代理） |
|
||||
| gateway | [gateway_SECURITY_AUDIT.md](security/gateway_SECURITY_AUDIT.md) | C++20 应用网关安全审计合并文档（v0.8.0 三轮审计合并：初版/复审/增量复审；v0.9.0 纯转发，认证迁 ca） |
|
||||
| ca | [ca_SECURITY_AUDIT.md](security/ca_SECURITY_AUDIT.md) | C++20 中央认证服务（Central Auth，v1.0.0），承接原 gateway 认证职责；含迁移接收项与 ca 相关开放项 |
|
||||
| core | [core_SECURITY_AUDIT_20260801.md](security/core_SECURITY_AUDIT_20260801.md) | C++20 进程托管服务（PMC/Nidus） |
|
||||
| db | [db_SECURITY_AUDIT_20260801.md](security/db_SECURITY_AUDIT_20260801.md) | Python 数据库服务（pymsg、SQLAlchemy、日志收集） |
|
||||
| db2 | [db2_SECURITY_AUDIT_20260806.md](security/db2_SECURITY_AUDIT_20260806.md) | C++20 数据库 RPC 服务（db 的 C++ 重实现，SQLite C API） |
|
||||
| pymsg | [pymsg_SECURITY_AUDIT_20260801.md](security/pymsg_SECURITY_AUDIT_20260801.md) | Python RPC 基础库（长度前缀帧、MsgClient/Server） |
|
||||
| dnfs | [dnfs_SECURITY_AUDIT_20260801.md](security/dnfs_SECURITY_AUDIT_20260801.md) | Python 树状网络文件系统（**已废弃，生产用 dnfs2**；2026-08-10 复核为全量 16 项发现） |
|
||||
| dnfs2 | [dnfs2_SECURITY_AUDIT_20260808.md](security/dnfs2_SECURITY_AUDIT_20260808.md) | C++20 树状网络文件系统（dnfs 重实现，**生产在跑**，评级 A） |
|
||||
| static | [static_SECURITY_AUDIT_20260801.md](security/static_SECURITY_AUDIT_20260801.md) | Python 前端托管/文件服务 |
|
||||
| fsys | [fsys_SECURITY_AUDIT_20260808.md](security/fsys_SECURITY_AUDIT_20260808.md) | Python 文件系统服务 |
|
||||
| ai_review | [ai_review_SECURITY_AUDIT_20260801.md](security/ai_review_SECURITY_AUDIT_20260801.md) | Python AI 内容审核（DeepSeek + RAG） |
|
||||
| smtp | [smtp_SECURITY_AUDIT_20260801.md](security/smtp_SECURITY_AUDIT_20260801.md) | Python 邮件服务（验证码发送/校验）初版 + 0809 复审合并版 |
|
||||
| smtp3 | [smtp3_SECURITY_AUDIT_20260809.md](security/smtp3_SECURITY_AUDIT_20260809.md) | C++20 邮件服务（smtp 重写），2 项 P0 + P1-2 + 全部 P3 当日已修复，仅剩 P1-1（TLS 校验）待修 |
|
||||
| captcha | [captcha_SECURITY_AUDIT_20260801.md](security/captcha_SECURITY_AUDIT_20260801.md) | Python 验证码服务 |
|
||||
| captcha2 | [captcha2_SECURITY_AUDIT_20260809.md](security/captcha2_SECURITY_AUDIT_20260809.md) | C++20 验证码服务（captcha 重写，FreeType + stb，含 P0 大小写缺陷发现） |
|
||||
| confs | [confs_SECURITY_AUDIT_20260801.md](security/confs_SECURITY_AUDIT_20260801.md) | Python 统一配置服务 |
|
||||
| libmsg | [libmsg_SECURITY_AUDIT_20260806.md](security/libmsg_SECURITY_AUDIT_20260806.md) | C++ RPC 基础库（pymsg 协议帧、MsgClient/Server、RpcClient/Server） |
|
||||
| libhttp | [libhttp_SECURITY_AUDIT_20260803.md](security/libhttp_SECURITY_AUDIT_20260803.md) | C++ HTTP/WebSocket 库（请求/响应/WS/静态文件） |
|
||||
| libsqlite3 | [libsqlite3_SECURITY_AUDIT_20260806.md](security/libsqlite3_SECURITY_AUDIT_20260806.md) | C++ SQLite3 封装（Header-only） |
|
||||
| libth | [libth_SECURITY_AUDIT_20260804.md](security/libth_SECURITY_AUDIT_20260804.md) | C++ 线程库（Thread、Cv_wait、Fsm） |
|
||||
| aibox | [aibox_SECURITY_AUDIT_20260801.md](security/aibox_SECURITY_AUDIT_20260801.md) | Python AI 智能体系统（WebSocket） |
|
||||
| BotOps | [BotOps_SECURITY_AUDIT_20260801.md](security/BotOps_SECURITY_AUDIT_20260801.md) | BotOps 运维控制面板 |
|
||||
| actpred | [actpred_SECURITY_AUDIT_20260808.md](security/actpred_SECURITY_AUDIT_20260808.md) | Python 动作预测模块（PyTorch 训练/推理、.mt 解析、ONNX 导出） |
|
||||
|
||||
---
|
||||
|
||||
## 三、代码审查 (`reviews/`)
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [core_CODE_REVIEW_LOG_20260730.md](reviews/core_CODE_REVIEW_LOG_20260730.md) | Core 模块代码审查日志（2026-07-30，自动化审查） |
|
||||
| [DEPLOY_DEFECT_AUDIT_20260806.md](reviews/DEPLOY_DEFECT_AUDIT_20260806.md) | 部署缺陷审查（2026-08-06，首次原生部署实录，含修复记录） |
|
||||
| [actpred_CODE_AUDIT_20260808.md](reviews/actpred_CODE_AUDIT_20260808.md) | actpred 模块代码审计（2026-08-08，两轮合并：第 1 轮 16 项 + 第 2 轮复审 11 项，共 27 项全部修复） |
|
||||
| [bot4cj_CODE_AUDIT_20260808.md](reviews/bot4cj_CODE_AUDIT_20260808.md) | bot4cj 模块代码审计（2026-08-08，仓颉机器人硬件脚本解析器，15 项发现，待修复） |
|
||||
|
||||
---
|
||||
|
||||
## 四、分析报告与开发规划 (`reports/`)
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [blackbird_research_report.md](reports/blackbird_research_report.md) | blackbird 项目研究报告（安全架构分析、改进建议、里程碑规划） |
|
||||
| [core_service_registry_dev_doc.md](reports/core_service_registry_dev_doc.md) | Core 模块注册中心功能扩展开发文档（服务注册/发现/健康守护/自动重启） |
|
||||
| [auth_service_plan.md](reports/auth_service_plan.md) | 认证独立化（CA 模块）开发文档（waf→ca→gateway 前置拓扑；gateway 退 8445 纯转发不验签；下游/WAF/前端零改动） |
|
||||
| [aibox_open_dev_plan.md](reports/aibox_open_dev_plan.md) | aibox 开放版开发计划（命令注入漏洞修复、安全沙箱方案） |
|
||||
| [aibox_file_network_cli_refactor.md](reports/aibox_file_network_cli_refactor.md) | aibox 文件/网络操作命令行化重构计划 |
|
||||
| [blackbird_promo_full.md](reports/blackbird_promo_full.md) | blackbird 项目完整版宣传文案 |
|
||||
| [bot4cj_analysis_20260525_00.md](reports/bot4cj_analysis_20260525_00.md) | bot4cj 机器人模块分析报告（Markdown） |
|
||||
| [libcrypt_CBC_deprecation_dev_doc.md](reports/libcrypt_CBC_deprecation_dev_doc.md) | libcrypt CBC 模式缺陷分析与 AES-GCM 迁移开发文档 |
|
||||
| [bot4cj_analysis_20260525_00.html](reports/bot4cj_analysis_20260525_00.html) | bot4cj 机器人模块分析报告（HTML） |
|
||||
| [actpred_pretrain_test_20260808.md](reports/actpred_pretrain_test_20260808.md) | actpred 预训练与推理测试报告（action_dim=18 变更、.mt 解析器、预训练、推理基准、NPU 调研） |
|
||||
| [captcha_cpp_rewrite_dev_doc.md](reports/captcha_cpp_rewrite_dev_doc.md) | captcha 模块 C++20 重写开发方案（FreeType + stb_image_write 替代 Pillow，协议兼容零改动） |
|
||||
| [smtp_cpp_rewrite_dev_doc.md](reports/smtp_cpp_rewrite_dev_doc.md) | smtp 模块 C++20 重写开发方案（SMTP_SSL 客户端手写，审计 7 项遗留一并在重写中修复，零新增系统依赖） |
|
||||
| [libhttp_remote_addr_dev_doc.md](reports/libhttp_remote_addr_dev_doc.md) | libhttp 对端地址透传开发方案（X-Remote-Addr 可信头注入，非破坏；gateway trust_xff 配套，闭环审计 A4） |
|
||||
| [confs2_cpp_rewrite_dev_doc.md](reports/confs2_cpp_rewrite_dev_doc.md) | confs 模块 C++20 重写开发方案（libmsg RpcServer 替代 pymsg，协议兼容零改动，审计 7 项遗留一并修复，零新增系统依赖，未来可合入 core 注册中心） |
|
||||
| [fsys_public_frontend_research_20260810.md](reports/fsys_public_frontend_research_20260810.md) | fsys/public 前端研究报告（Vanilla 技术栈、HttpOnly Cookie 认证体系、dnfs/aibox/view/mgmt 页面分析、8 项问题与改进建议） |
|
||||
|
||||
---
|
||||
|
||||
## 五、各模块 README（保留在原目录）
|
||||
|
||||
各模块根目录的 `README.md` 保留在原位，方便 GitHub 直接浏览：
|
||||
|
||||
### 核心服务
|
||||
|
||||
| 模块 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| core | [../core/README.md](../core/README.md) | 进程托管服务（PMC/Nidus） |
|
||||
| waf | [../waf/README.md](../waf/README.md) | WAF 网关（Go, coraza） |
|
||||
| gateway | [../gateway/README.md](../gateway/README.md) | 应用层网关（C++20） |
|
||||
| db | [../db/README.md](../db/README.md) | 通用数据库服务（pymsg） |
|
||||
| db2 | [../db2/README.md](../db2/README.md) | C++20 数据库 RPC 服务（db 重实现） |
|
||||
| confs | [../confs/README.md](../confs/README.md) | 统一配置服务 |
|
||||
| static | [../static/README.md](../static/README.md) | 前端托管服务 |
|
||||
| dnfs | [../dnfs/README.md](../dnfs/README.md) | 树状网络文件系统 |
|
||||
| dnfs2 | [../dnfs2/README.md](../dnfs2/README.md) | C++20 树状菜单服务（dnfs 重实现） |
|
||||
| ai_review | [../ai_review/README.md](../ai_review/README.md) | AI 内容审核 |
|
||||
| captcha | [../captcha/README.md](../captcha/README.md) | 验证码服务 |
|
||||
| smtp | [../smtp/README.md](../smtp/README.md) | 邮件服务 |
|
||||
| redirect80 | [../redirect80/README.md](../redirect80/README.md) | HTTP 重定向服务 |
|
||||
|
||||
### 共享库
|
||||
|
||||
| 库 | 路径 | 说明 |
|
||||
|----|------|------|
|
||||
| pymsg | [../pymsg/README.md](../pymsg/README.md) | Python RPC 基础库 |
|
||||
| libhttp | [../libhttp/README.md](../libhttp/README.md) | C++ HTTP/WebSocket 库 |
|
||||
| libcrypt | [../libcrypt/README.md](../libcrypt/README.md) | C++ 加密库 |
|
||||
| libth | [../libth/README.md](../libth/README.md) | C++ 线程库 |
|
||||
| libsqlite3 | [../libsqlite3/README.md](../libsqlite3/README.md) | C++ SQLite3 封装 |
|
||||
| libmsg | [../libmsg/README.md](../libmsg/README.md) | C++ RPC 基础库（pymsg 协议 C++ 实现） |
|
||||
| libtry | [../libtry/](../libtry/) | 嵌入式脚本解释器 |
|
||||
|
||||
### 其他模块
|
||||
|
||||
| 模块 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| aibox | [../aibox/README.md](../aibox/README.md) | AI 智能体系统 |
|
||||
| bot4cj | [../bot4cj/README.md](../bot4cj/README.md) | 机器人硬件脚本解析器（仓颉） |
|
||||
| BotOps | [../BotOps/README.md](../BotOps/README.md) | aibox 智能体 TUI 前端（Textual） |
|
||||
| actpred | [../actpred/README.md](../actpred/README.md) | 动作预测神经网络（PyTorch） |
|
||||
| lci | [../lci/README.md](../lci/README.md) | 嵌入式帧缓冲图形界面 |
|
||||
| fsys | [../fsys/README.md](../fsys/README.md) | 文件系统服务 |
|
||||
| tests | [../tests/blackbox/README.md](../tests/blackbox/README.md) | 黑盒测试套件 |
|
||||
|
||||
### Robot 文档 (README.robot.md)
|
||||
|
||||
| 模块 | 路径 |
|
||||
|------|------|
|
||||
| pymsg | [../pymsg/README.robot.md](../pymsg/README.robot.md) |
|
||||
| libhttp | [../libhttp/README.robot.md](../libhttp/README.robot.md) |
|
||||
| libtry | [../libtry/README.robot.md](../libtry/README.robot.md) |
|
||||
| aibox | [../aibox/README.robot.md](../aibox/README.robot.md) |
|
||||
| bot4cj | [../bot4cj/README.robot.md](../bot4cj/README.robot.md) |
|
||||
|
||||
---
|
||||
|
||||
## 六、aibox 技能与任务文档
|
||||
|
||||
aibox 模块的技能提示词和任务模板属于运行时数据，保留在原目录：
|
||||
|
||||
| 类型 | 路径 |
|
||||
|------|------|
|
||||
| 技能格式说明 | [../aibox/SKILLS_FORMAT.md](../aibox/SKILLS_FORMAT.md) |
|
||||
| 技能目录 | [../aibox/skills/](../aibox/skills/) |
|
||||
| 任务目录 | [../aibox/tasks/](../aibox/tasks/) |
|
||||
@@ -0,0 +1,212 @@
|
||||
# actpred 多帧注意力架构改造测试报告
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 日期 | 2026-08-09 |
|
||||
| 模块 | actpred |
|
||||
| 测试人 | qing |
|
||||
| 环境 | Intel Xeon E3-1200 v2 (Ivy Bridge), 4 核, Linux 24.04, Python 3.x, PyTorch (CPU-only) |
|
||||
| 关联文件 | `config.py`, `model.py`, `dataset.py`, `train.py`, `pretrain_mt.py`, `predict.py`, `export_onnx.py`, `test_actpred.py` |
|
||||
| 前置报告 | [actpred_pretrain_test_20260808.md](actpred_pretrain_test_20260808.md) |
|
||||
|
||||
---
|
||||
|
||||
## 一、改造背景与目标
|
||||
|
||||
原架构为"单帧 CNN + 历史动作 MLP/GRU + concat 融合"，仅支持单帧图像输入。
|
||||
本次改造目标：
|
||||
|
||||
1. 引入注意力机制，支持**多帧图像 + 历史动作序列**联合建模，预测下一时间步动作
|
||||
2. 保持 checkpoint 格式（`model_state_dict` + `config`）、CLI 工作流与 ONNX 导出链路不变
|
||||
3. 保持除 batch 维外全静态 shape，面向树莓派 AI 扩展板（NPU）部署友好
|
||||
4. 直接替换旧架构（用户决策）：删除 MLP/GRU 编码器与 concat 路径，旧 checkpoint 作废
|
||||
|
||||
## 二、新架构
|
||||
|
||||
```
|
||||
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_model=128)
|
||||
│
|
||||
取 PRED 位置输出 ─► MLP 头 ─► 预测动作 (action_dim)
|
||||
```
|
||||
|
||||
| 设计点 | 取值/说明 |
|
||||
|--------|----------|
|
||||
| token 序列 | `[img×F, act×H, PRED]`，长度固定 F+H+1（默认 3+5+1=9） |
|
||||
| 帧序约定 | 旧→新，末帧为当前帧；冷启动可重复传同一帧 |
|
||||
| 注意力 | `nn.TransformerEncoder`，pre-LN（norm_first），dim_feedforward=2×d_model |
|
||||
| 位置编码 | 可学习 `pos_embed (1, F+H+1, d)`，trunc_normal 初始化 |
|
||||
| 输出 | 取末位 PRED token 过 MLP 头（d → 128 → 64 → action_dim） |
|
||||
| 静态性 | forward 中 reshape 仅 batch 维动态，其余编译期固定 |
|
||||
| 参数量 | 409,042（旧架构 142,034，约 2.9 倍） |
|
||||
|
||||
### 新增配置参数
|
||||
|
||||
| 参数 | 默认值 | 校验范围 |
|
||||
|------|--------|---------|
|
||||
| `--frame-len` | 3 | [1, 1024] |
|
||||
| `--attn-dim` | 128 | [1, 4096]，且须能被 attn-heads 整除 |
|
||||
| `--attn-heads` | 4 | [1, 64] |
|
||||
| `--attn-layers` | 2 | [1, 64] |
|
||||
|
||||
删除参数：`--history-encoder`、`--action-hidden-dim`。
|
||||
旧 checkpoint 因 config 含未知键（`history_encoder`/`action_hidden_dim`）在加载时被
|
||||
`parse_checkpoint_config` 以明确 ValueError 拒载，符合"作废"预期（有专项测试覆盖）。
|
||||
|
||||
## 三、单元测试
|
||||
|
||||
```
|
||||
$ python test_actpred.py
|
||||
Ran 56 tests in 5.959s
|
||||
OK
|
||||
```
|
||||
|
||||
**56 项测试全部通过**（安装 onnxscript/onnxruntime 后无跳过项）。本次新增/改写用例：
|
||||
|
||||
| 用例 | 验证点 |
|
||||
|------|--------|
|
||||
| `test_forward_multi_frame` | (2,3,3,64,64) + (2,5,18) → (2,18) |
|
||||
| `test_forward_single_frame_degenerate` | frame_len=1 退化单帧仍正常前向 |
|
||||
| `test_forward_dynamic_batch` | batch 1/4/8 动态（frame_len=2） |
|
||||
| `test_custom_attn_config` | attn_dim=64/heads=2/layers=1 可构建前向 |
|
||||
| `test_attn_dim_not_divisible_by_heads_raises` | 130 % 4 ≠ 0 → ValueError |
|
||||
| `test_dataset_loading` | 多帧样本 shape (3,3,32,32)，batch key 改为 `images` |
|
||||
| `test_frame_len_gt_history_shifts_start` | 采样起点 max(history_len, frame_len-1) 正确 |
|
||||
| `test_legacy_checkpoint_config_rejected` | 旧架构 checkpoint 拒载 |
|
||||
| `test_wrong_frame_count_raises` | 推理帧数不符 → ValueError |
|
||||
| `test_end_to_end_predict` 等推理用例 | 多帧输入端到端、归一化等价性、确定性 |
|
||||
|
||||
## 四、预训练测试
|
||||
|
||||
### 4.1 训练配置
|
||||
|
||||
| 参数 | 值 |
|
||||
|------|-----|
|
||||
| 数据来源 | `../bot4cj/scripts/*.mt`（13 文件） |
|
||||
| train/val 划分 | **文件级**（11 训练文件 / 2 验证文件，杜绝滑动窗口泄漏） |
|
||||
| 输入 | 全零多帧图像 (B, 3, 3, 64, 64) + action_history (B, 5, 18) |
|
||||
| 优化器/调度 | AdamW (lr=0.001, wd=1e-4) + CosineAnnealingLR |
|
||||
| 数据增强 | Gaussian noise (std=1.0) |
|
||||
| batch_size / epochs / patience | 8 / 200 / 30 |
|
||||
| 随机种子 | 42 |
|
||||
|
||||
### 4.2 训练结果
|
||||
|
||||
| 指标 | 值 |
|
||||
|------|-----|
|
||||
| 最终轮数 | 65（早停，patience=30） |
|
||||
| 最优 val_loss | **2476.75** |
|
||||
| 产出 | `checkpoints/pretrain_best.pt`（含 optimizer）、`checkpoints/pretrain_best_inference.pt` |
|
||||
|
||||
> **关于 val_loss 数值的说明**：本次 2476.75 与前次报告的 190.58 不可直接对比——
|
||||
> 前次数值系样本级滑动窗口划分导致的数据泄漏虚低值（已在 0808 审计中定性）；
|
||||
> 本次为文件级划分（验证集是训练中完全未见过的动作脚本），且模型更大（409K vs 142K）
|
||||
> 而数据仅 13 个脚本，属"诚实的困难任务"数值。注意力架构的真实收益需在真实图像数据
|
||||
> 微调后评估。
|
||||
|
||||
## 五、推理链路验证
|
||||
|
||||
### 5.1 CLI 全链路
|
||||
|
||||
```
|
||||
$ bash _run.sh --model checkpoints/pretrain_best_inference.pt \
|
||||
--images /tmp/f0.jpg /tmp/f1.jpg /tmp/f2.jpg \
|
||||
--action-history "45,0,...（5 步 × 18 值）"
|
||||
18.3430 10.1614 17.3654 ... （18 维输出，数值有限）
|
||||
```
|
||||
|
||||
✅ 3 帧 + 5 步历史全链路输出正常。
|
||||
|
||||
### 5.2 错误场景
|
||||
|
||||
```
|
||||
$ ... --images /tmp/f0.jpg ...
|
||||
--images 需传入 3 个路径（旧→新），实际为 1 个。冷启动时可重复传同一帧路径。
|
||||
```
|
||||
|
||||
✅ 帧数不符时报错信息明确，含冷启动指引。
|
||||
|
||||
## 六、ONNX 导出验证
|
||||
|
||||
```
|
||||
$ python export_onnx.py --model checkpoints/pretrain_best_inference.pt --output /tmp/actpred_attn.onnx
|
||||
ONNX model exported to: /tmp/actpred_attn.onnx
|
||||
ONNX 一致性验证通过（最大差异: 7.629395e-06）
|
||||
```
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 导出 | ✅ 成功（opset 17，输入 `images (batch,3,3,64,64)` + `action_history (batch,5,18)`） |
|
||||
| onnxruntime 一致性 | ✅ 最大差异 7.63e-06（< 1e-4 阈值） |
|
||||
| 动态维 | 仅 batch，NPU 编译友好 |
|
||||
|
||||
注：本次为环境补装了 `onnxscript` 与 `onnxruntime`（torch ≥ 2.12 ONNX 导出依赖）。
|
||||
|
||||
## 七、CPU 推理性能基准
|
||||
|
||||
测试方法：warmup 20 次后测 200 次取平均，输入随机 3 帧 (64,64,3) uint8 + (5,18) float32。
|
||||
|
||||
| 环节 | 本次（注意力，3 帧） | 前次（concat，单帧） |
|
||||
|------|---------------------|---------------------|
|
||||
| 参数量 | 409,042 | 142,034 |
|
||||
| 端到端推理（含预处理） | **4.25 ms (235 FPS)** | 1.61 ms (622 FPS) |
|
||||
| 纯前向 | 2.77 ms (360 FPS) | 1.09 ms (916 FPS) |
|
||||
| image_encoder 占比 | 1.30 ms（47%，3 帧） | 0.82 ms（75%，1 帧） |
|
||||
|
||||
评估：
|
||||
|
||||
- 235 FPS 对 bot4cj 30 FPS 控制循环仍有 **7.8 倍余量**，实时性满足
|
||||
- 延迟增长主因：CNN 由 1 帧变 3 帧（约 3×0.43ms）+ Transformer 编码器（约 1.5ms）
|
||||
- image_encoder 占比由 75% 降至 47%，注意力部分成为新的次要热点；
|
||||
部署到树莓派 AI 扩展板后两者均可被 NPU 加速（静态 shape 已保证）
|
||||
|
||||
## 八、结论与下一步
|
||||
|
||||
### 8.1 测试结论
|
||||
|
||||
| 测试项 | 结果 |
|
||||
|--------|------|
|
||||
| 多帧注意力模型前向 | ✅ 通过（多帧/单帧退化/动态 batch/自定义 attn 配置） |
|
||||
| 配置校验 | ✅ 通过（frame_len/attn_* 值域 + 整除校验 + 旧 checkpoint 拒载） |
|
||||
| 多帧数据集采样 | ✅ 通过（采样起点与样本数断言） |
|
||||
| 单元测试 | ✅ 56/56 通过 |
|
||||
| 预训练 | ✅ 通过（65 epoch 早停，文件级划分无泄漏） |
|
||||
| 推理 CLI | ✅ 通过（正常 + 错误场景） |
|
||||
| ONNX 导出 | ✅ 通过（一致性 7.63e-06） |
|
||||
| CPU 性能 | ✅ 通过（235 FPS，7.8 倍实时余量） |
|
||||
|
||||
### 8.2 已知局限
|
||||
|
||||
1. **预训练图像分支未习得**：全零多帧占位下 image_encoder 与图像 token 的注意力权重
|
||||
无有效梯度信号，真实收益依赖后续真实图像微调
|
||||
2. **数据量极少**：13 个 .mt 脚本对 409K 参数模型明显不足，val_loss 绝对值偏高属预期
|
||||
3. **旧 checkpoint 全部作废**：已删除并重训预训练 checkpoint；如有外部持有旧
|
||||
`best_inference.pt` 需同步告知重训
|
||||
|
||||
### 8.3 下一步建议
|
||||
|
||||
1. **采集真实多帧数据**：用 `DataRecorder` 录制 bot4cj 摄像头 episode，以本次预训练
|
||||
checkpoint 为起点微调（勿开 `--normalize-actions`）
|
||||
2. **树莓派 AI 扩展板部署验证**：将 ONNX 模型走扩展板厂商工具链编译，实测 NPU 延迟
|
||||
3. **帧数消融**：真实数据到位后对比 frame_len=1/3/5 的验证误差，确认多帧收益
|
||||
4. **扩充 .mt 脚本**：增加动作脚本数量，缓解预训练数据不足
|
||||
|
||||
---
|
||||
|
||||
## 附录：文件变更清单
|
||||
|
||||
| 文件 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `actpred/config.py` | 修改 | 新增 frame_len/attn_*；删除 history_encoder/action_hidden_dim；整除校验 |
|
||||
| `actpred/model.py` | 重写 | 多帧 Transformer 注意力架构；删除 MLP/GRU 编码器与 concat 融合 |
|
||||
| `actpred/dataset.py` | 修改 | 多帧窗口采样；batch key `image` → `images` |
|
||||
| `actpred/train.py` | 修改 | 多帧适配（frame_len 透传、batch key） |
|
||||
| `actpred/pretrain_mt.py` | 修改 | 全零多帧占位；打印信息更新 |
|
||||
| `actpred/predict.py` | 修改 | `predict(images, history)` 多帧 API；CLI `--image` → `--images` |
|
||||
| `actpred/export_onnx.py` | 修改 | 多帧 dummy 输入；input_names 更新 |
|
||||
| `actpred/test_actpred.py` | 修改 | 56 项用例（新增多帧/校验/拒载/帧数错误等） |
|
||||
| `actpred/README.md` | 修改 | 架构图、CLI 示例、配置表、API 文档同步 |
|
||||
| `actpred/checkpoints/pretrain_best*.pt` | 重新生成 | 旧架构 checkpoint 已删除并重训 |
|
||||
@@ -0,0 +1,265 @@
|
||||
# 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 部署测试**。
|
||||
@@ -0,0 +1,400 @@
|
||||
# bot4cj 模块 Python 迁移开发方案
|
||||
|
||||
> 文档类型：功能开发计划
|
||||
> 模块：bot4cj → pybot（Python 迁移）
|
||||
> 作者：自动生成
|
||||
> 日期：2026-08-09
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
### 1.1 背景与动机
|
||||
|
||||
`bot4cj` 是基于仓颉（Cangjie）编程语言和 Linux I2C 接口的机器人硬件脚本解析器，通过 `.mt` 矩阵脚本描述机器人硬件构成与动作序列，驱动 PCA9685 舵机控制板、MPU6050 传感器等真实硬件（宿主机为树莓派 aarch64）。
|
||||
|
||||
将其迁移到 Python 的动机：
|
||||
|
||||
| 收益 | 说明 |
|
||||
|------|------|
|
||||
| 工具链门槛消除 | 仓颉编译器（cjc 1.1.3）+ cjpm + 4 个仓颉扩展包（ctype4cj/pthread4cj/spi4cj/lua4cj）→ 树莓派系统自带 Python3，零编译 |
|
||||
| 与 actpred 生态打通 | actpred（动作预测，PyTorch）已有 Python 版 `.mt` 解析器（`mt_parser.py`），迁移后"大脑（actpred）↔ 身体（bot4cj）"共享同一语言与数据结构，DRL 闭环开发成本大幅降低 |
|
||||
| Lua 扩展层可消除 | 仓颉版引入 Lua 是为了运行时可扩展硬件驱动；Python 本身即脚本语言，硬件驱动直接写成 Python 插件模块，砍掉 lua4cj + liblua5.4 + C 函数注册整层 |
|
||||
| C/C++ 共享库大部分可消除 | libi2c4cj.so 的功能可用 `fcntl.ioctl` + `os.read/write` 纯 Python 实现；矩阵/FFT/CNN 由 numpy/PyTorch（actpred 已有）承担 |
|
||||
| 审计遗留一并修复 | [bot4cj 代码审计](../reviews/bot4cj_CODE_AUDIT_20260808.md) 15 项发现（3 P0 + 5 P1 + 7 P2）全部待修复，迁移时逐项闭环 |
|
||||
| 与项目主流技术栈对齐 | micro_servers 业务服务以 Python/C++20 为主，仓颉是唯一的孤立技术栈，维护人手受限 |
|
||||
|
||||
**性能评估**：bot4cj 的执行节奏由硬件决定（舵机 50Hz PWM、I2C 100kHz~400kHz、动作行间 20~500ms 延时），解析与调度不是瓶颈，Python 的性能完全够用；且 Python 插件替代 Lua 桥接后，单次硬件调用的框架开销反而下降约两个数量级（详见附录 A 的量化分析）。这与 db2/captcha2 等"Python→C++ 求性能"的方向相反，是"仓颉→Python 求生态与可维护性"。
|
||||
|
||||
### 1.2 设计目标
|
||||
|
||||
1. **`.mt` 脚本零改动**：现有 `scripts/*.mt` 全部原样可用，块语法（`@Alias`/`@I2C`/`@PCA9685`/`@MPU6050_BIND`/`@Speaker`/`@Servo`/`@Action`）、`-` 占位符语义、`#` 注释、`;` 行结束符完全兼容。
|
||||
2. **CLI 兼容**：保持 `cat scripts/std.mt | ./bot` 的 stdin 管道用法与 `--help`/`--test` 分支。
|
||||
3. **零第三方依赖的核心**：解析器 + 硬件层仅用标准库（`fcntl`/`os`/`struct`/`threading`/`json`/`argparse`），树莓派上无需 venv 即可运行；numpy 仅测试/工具链可选。
|
||||
4. **硬件插件化（Python 替代 Lua）**：未知 `@Block` 路由到 `modules/<Name>.py` 插件，保留 build/call/destroy 三段生命周期协议。
|
||||
5. **审计 15 项发现全部修复**：见 §5 修复映射表。
|
||||
6. **可测试**：pytest 单元测试覆盖解析器、占位符语义、Servo 校准、插件加载；硬件层可用 Mock I2C 在无硬件的 x86 上跑通全流程。
|
||||
|
||||
### 1.3 不做什么
|
||||
|
||||
- **不迁移 math/NN/CNN/FFT/CUDA 层**（`src/math/*.cj`、`src/cpp/cnn/`、`src/cpp/fft*`、`src/cuda/`）：这部分是为 DRL 预留的自研神经网络库，功能已被 actpred（PyTorch）完全覆盖且质量更高。DRL 闭环未来直接调 actpred，不重复造轮子。相应地 `--test nn/cnn/cnn1` 分支不迁移。
|
||||
- **不迁移 `.bot` 旧版脚本支持**：`scripts/*.bot` 是历史遗留，仓颉版本身也未解析它。
|
||||
- **不改 `.mt` 语法**：`@Action_Auto` 等语法演进（旧分析 D11）留待后续版本。
|
||||
- **不引入 smbus2/RPi.GPIO 等三方库**：I2C 用 `fcntl.ioctl(fd, I2C_SLAVE=0x0703, addr)` 直接实现，与仓颉版 `I2C.cj`/`I2C.c` 行为逐字节对齐。
|
||||
- **不删除 bot4cj 目录**：遵循项目"原版与重写版并存 → 验证通过后切换"的渐进策略（同 db→db2、captcha→captcha2、smtp→smtp3）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状分析
|
||||
|
||||
### 2.1 仓颉版架构分层
|
||||
|
||||
```
|
||||
.mt 矩阵脚本（硬件定义 + 动作序列）
|
||||
↓
|
||||
MatrixParser（P.cj，FSM 逐字符解析）→ MatrixObject 链表
|
||||
↓
|
||||
RobotStruct（r.cj）createHardVars()：按 @块名分发到硬件变量工厂
|
||||
MatrixVars_Hardware 基类 + 三闭包：rise/things/free
|
||||
↓
|
||||
硬件实现 hd/*.cj：I2C（20 槽锁数组）、Servo、PCA9685、MPU6050、Speaker
|
||||
+ Lua 扩展 modules/*.lua（未知 @Block 的通用驱动，经 C 函数注册调 I2C/SPI）
|
||||
↓
|
||||
系统库 .so：libi2c4cj（I2C glibc 封装）、libsnd4cj（音频）、libmt4cj/libfft4cj/libcnn4cj（数学）
|
||||
```
|
||||
|
||||
### 2.2 迁移范围源码清单
|
||||
|
||||
| 仓颉源文件 | 行数 | 职责 | 迁移去向 |
|
||||
|-----------|------|------|---------|
|
||||
| `src/main.cj` | 178 | CLI 入口、stdin 管道、--test 分支 | `pybot/main.py` |
|
||||
| `src/P.cj` | 264 | MatrixParser（FSM）+ MatrixObject + MatrixSaver + 解析异常 | `pybot/parser.py` |
|
||||
| `src/r.cj` | 1072 | RobotStruct + 硬件变量基类 + 6 个工厂 + Lua 状态机桥接 | `pybot/robot.py` + `pybot/hardvars.py` |
|
||||
| `src/hd/I2C.cj` + `src/cpp/I2C.c` | 340+ | I2C glibc 封装 + 每 fd 互斥锁 | `pybot/hd/i2c.py` |
|
||||
| `src/hd/Servo.cj` | 31 | max/min/offset 校准 + 负 max 角度翻转 | `pybot/hd/servo.py` |
|
||||
| `src/hd/MPU6050.cj` | 244 | 6 轴传感器 + 后台采样线程 + 卡尔曼 | `pybot/hd/mpu6050.py` |
|
||||
| `src/hd/snd.cj` + `src/cpp/snd.cpp` | 23+ | 扬声器（仓颉侧仅 sleep 占位） | `pybot/hd/speaker.py` |
|
||||
| `src/hd/PCA9685.cj` | — | 已标记"由 Lua 取代" | 不迁移（走插件） |
|
||||
| `modules/*.lua`（PCA9685/ADS1115/ADS1256/SPI/TEST） | — | Lua 硬件驱动 | `pybot/modules/*.py` 插件 |
|
||||
| `src/math/*.cj`、`src/cpp/cnn|fft|Matrix|kalman`、`src/cuda/` | ~2000 | 自研 NN/数学库 | **不迁移**（actpred 承担）；卡尔曼滤波例外，MPU6050 需要，~40 行纯 Python |
|
||||
|
||||
### 2.3 关键语义（必须逐项对齐）
|
||||
|
||||
1. **占位符 `-`**：递归沿用上一行同列值；首行为 `-` 时，`parseMt` 解析为 `0`（数值列），`getMt` 返回字面 `-`。
|
||||
⚠️ 注意与 actpred `mt_parser.py` 的差异：后者首行 `-` 用 `@Servo` 初始角度填充（这是 ML 数据管线的语义）。**pybot 运行时语义以仓颉版为准（填 0）**，因为运行时 Servo 有 max/min 钳位保护；数据管线语义留在 actpred 不变。
|
||||
2. **@Action 列名 `dev.param`**：点号拆分为硬件名 + 参数名；参数名经 `@Alias` 表转换（`A`→`angle`、`F`→`frequency`）后传入硬件。
|
||||
3. **每行执行**：同一行按硬件聚合参数字典，逐硬件调用一次 `play()`；行间时延由 `spk.delay` 参数承担。
|
||||
4. **硬件生命周期**：`active()` 按创建顺序 build，`deactive()` 倒序 destroy，且必须在 `try/finally` 中保证执行。
|
||||
5. **Servo 角度算法**：`a = angle + offset; a = clamp(a, |min|, |max|); if max < 0: a = 180 - a`。
|
||||
6. **PCA9685 脉宽映射**：50Hz、0°→0.5ms、180°→2.5ms、`offval = width * 4096 / 20`、寄存器 `0x06 + 4*channel` 写 4 字节。
|
||||
7. **MPU6050**：±500°/s、±8g、10ms 采样周期、卡尔曼滤波（Q=20, R=200）、roll/pitch 由加速度计反正切求得。
|
||||
8. **I2C 互斥**：同一 fd 上"设地址 + 读/写寄存器"必须是原子序列（多设备共享总线）。
|
||||
|
||||
### 2.4 审计遗留（迁移时修复的输入清单）
|
||||
|
||||
来自 [bot4cj_CODE_AUDIT_20260808.md](../reviews/bot4cj_CODE_AUDIT_20260808.md)：3 项 P0（S01 列数校验恒假 / S02 调试 print 污染 stdout / S03 扬声器无实声）、5 项 P1（S04 转义不一致 / S05 MPU6050 地址重复 / S06 有符号读寄存器 / S07 Lua 路径硬编码 / S08 文档滞后）、7 项 P2（无测试、注释代码、锁扫描 O(n)、无编译告警、消费端报错不可读、线程退出、GC 析构不确定）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标架构
|
||||
|
||||
### 3.1 目录结构
|
||||
|
||||
```
|
||||
pybot/
|
||||
├── pybot/
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # CLI 入口（argparse：--help / --test / -i / -o 预留）
|
||||
│ ├── parser.py # MatrixParser + MatrixObject + MatrixSaver + 解析异常
|
||||
│ ├── robot.py # RobotStruct（createHardVars / active / run / deactive / save）
|
||||
│ ├── hardvars.py # HardwareVar 基类 + Alias/I2C/Servo/Speaker/MPU6050_BIND 工厂
|
||||
│ ├── plugin.py # Python 插件加载器（替代 Lua 状态机桥接）
|
||||
│ └── hd/
|
||||
│ ├── __init__.py
|
||||
│ ├── i2c.py # fcntl.ioctl I2C + 每 fd 锁（dict + threading.Lock）
|
||||
│ ├── servo.py # 舵机校准与翻转
|
||||
│ ├── mpu6050.py # 传感器 + threading.Thread 采样 + kalman
|
||||
│ ├── kalman.py # 一维卡尔曼滤波（~40 行）
|
||||
│ └── speaker.py # 正弦波发声（可选 alsaaudio，默认 aplay 子进程 / 静默降级）
|
||||
├── modules/ # 硬件驱动插件（Python 替代 Lua）
|
||||
│ ├── PCA9685.py
|
||||
│ ├── ADS1115.py
|
||||
│ ├── ADS1256.py
|
||||
│ └── SPI.py
|
||||
├── scripts -> ../bot4cj/scripts # 软链或复制，.mt 脚本共享
|
||||
├── tests/
|
||||
│ ├── test_parser.py
|
||||
│ ├── test_hardvars.py
|
||||
│ ├── test_servo.py
|
||||
│ └── mock_i2c.py # Mock I2C 总线（记录寄存器写序列，供断言）
|
||||
├── _run.sh # cat x.mt | bash _run.sh（exec python3 -m pybot）
|
||||
├── _set.sh # 无编译；可选建 venv 装 pytest
|
||||
├── requirements.txt # 核心为空；[dev] pytest
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### 3.2 数据流（与仓颉版一致）
|
||||
|
||||
```
|
||||
stdin → MatrixParser.parse()（逐块产出 MatrixObject）
|
||||
→ RobotStruct.create_hardvars()（按块名分发工厂；未知块 → plugin.load("modules/<Name>.py")）
|
||||
→ robot.active()（按序 build）
|
||||
→ robot.run()（逐行 @Action：聚合参数 → 逐硬件 play(dict)）
|
||||
→ robot.deactive()（倒序 destroy，try/finally 保证）
|
||||
```
|
||||
|
||||
### 3.3 关键映射决策
|
||||
|
||||
| 仓颉版机制 | Python 版方案 | 理由 |
|
||||
|-----------|--------------|------|
|
||||
| `JsonValue` 统一通信协议 | 原生 `dict`（进程内直接传递） | 无跨语言边界后无需序列化；插件协议文档化 dict 键约定 |
|
||||
| 三闭包 rise/things/free | `HardwareVar` 基类三方法 `build()/play(params)/destroy()`，子类覆写 | Python 惯用法；闭包捕获改为实例属性 |
|
||||
| Lua 状态机 + C 函数注册（i2c_open 等 11 个） | `importlib` 动态加载 `modules/<Name>.py`，插件直接 `from pybot.hd import i2c` | 消除整个 FFI 层；插件与核心同语言 |
|
||||
| 20 槽 I2C 锁数组（O(n) 线性扫描） | `dict[fd → threading.Lock]` + 全局注册锁 | 修复审计 Q03；容量不再受限 |
|
||||
| pthread_create/pthread_cancel（MPU6050 采样） | `threading.Thread(daemon=True)` + `threading.Event` 停止标志 | 修复审计 Q06/D3，安全退出 |
|
||||
| 仓颉 GC 终结器不确定 | 上下文管理器 `with RobotStruct(...) as robot:` + `atexit` 兜底 | 修复审计 Q07/D1，确定性释放 fd |
|
||||
| cjpm build + Makefile .so | 无构建步骤 | 树莓派上 `git pull` 即部署 |
|
||||
|
||||
### 3.4 插件协议（modules/*.py，替代 Lua build/call/destroy）
|
||||
|
||||
```python
|
||||
# modules/PCA9685.py —— 与 PCA9685.lua 逐语义对齐
|
||||
def build(ctx: dict) -> dict:
|
||||
"""ctx: 元数据（fd/address/... 来自 @PCA9685 块行 + 引用硬件的 play() 展开）
|
||||
初始化：重启 → SLEEP → 设 prescale(50Hz) → 唤醒"""
|
||||
def call(ctx: dict) -> dict:
|
||||
"""ctx 额外含实时参数（channel/angle）；写 4 个 PWM 寄存器"""
|
||||
def destroy(ctx: dict) -> dict:
|
||||
"""复位 PCA9685"""
|
||||
```
|
||||
|
||||
- 插件查找顺序（修复审计 S07）：`$PYBOT_MODULES_PATH`（冒号分隔多路径）→ 包内置 `modules/` → 当前工作目录 `./modules/`。
|
||||
- 加载失败抛出含插件名与搜索路径的 `PluginNotFound` 异常。
|
||||
|
||||
---
|
||||
|
||||
## 4. 详细设计
|
||||
|
||||
### 4.1 parser.py
|
||||
|
||||
- **MatrixObject**：`name: str` + `rows: list[list[str]]`；提供 `__getitem__((row, col))`、`index_of_col(row, key)`、`save(writer)`。越界访问抛 `MatrixIndexError(块名, 行, 列)`（修复审计 Q05 的报错可读性）。
|
||||
- **MatrixParser**：保持 FSM 逐字符解析（非正则），状态与仓颉版一致（nl/cm/nm 三标志），原因：`@` 块嵌套注释、行内注释、任意空白分隔的兼容性已被现有脚本验证。
|
||||
- 修复 S01：`submit_line` 用 `len(grp) != len(rows[-1])` 校验列数，不一致抛 `DoesNotSync(行号, 期望列数, 实际列数)`。
|
||||
- 修复 S02：删除逐字符 debug 打印；提供 `--verbose` 时输出到 **stderr**（stdout 保留给未来管道通信）。
|
||||
- 修复 S04：Python 无 Rune/String 混淆问题，换行统一 `"\n"` 字符比较；补充单测覆盖"漏写分号跨行"场景。
|
||||
- **占位符语义**（§2.3-1）：`get_mt(obj, row, col)` 递归向上；`parse_mt(obj, row, col, type)` 首行 `-` 返回 `type("0")`。
|
||||
- **MatrixSaver**：保持与仓颉版相同的输出格式（`@Name` / 空格分隔 / `;` 结尾 / `@` 收尾），保证 `--test matrix_o/matrix_2` 的解析↔序列化往返可用。
|
||||
|
||||
### 4.2 hd/i2c.py
|
||||
|
||||
```python
|
||||
I2C_SLAVE = 0x0703
|
||||
class I2CBus:
|
||||
def __init__(self, path): self.fd = os.open(path, os.O_RDWR); _register_lock(self.fd)
|
||||
def set_addr(self, addr): fcntl.ioctl(self.fd, I2C_SLAVE, addr)
|
||||
def write_reg(self, reg, val): os.write(self.fd, bytes([reg, val]))
|
||||
def read_reg(self, reg) -> int: # 返回 0..255 无符号（修复 S06）
|
||||
os.write(self.fd, bytes([reg])); return os.read(self.fd, 1)[0]
|
||||
def transaction(self): # with bus.transaction(): 原子序列（设地址+读写）
|
||||
```
|
||||
|
||||
- 锁注册表：`_LOCKS: dict[int, threading.Lock]` + `_MAIN_LOCK`；`transaction()` 上下文管理器持锁，替代仓颉版 `I2cLock_lock/unlock` 手动配对。
|
||||
- `read_reg` 天然返回无符号 int（`bytes[0]` ∈ 0..255），16 位拼接 `(hh << 8) | ll` 后用 `struct.unpack('>h')` 转有符号——修复 S06 的符号扩展错误且保留传感器数据的正确符号。
|
||||
|
||||
### 4.3 hd/servo.py
|
||||
|
||||
与 `Servo.cj` 逐行对齐（§2.3-5），构造参数 `max/min/offset/set_angle_callback`。补单测：正装（max=90）、反装（max=-180 翻转）、offset 漂移、越界钳位。
|
||||
|
||||
### 4.4 hd/mpu6050.py
|
||||
|
||||
- 寄存器常量与 `MPU6050.cj` 一致；**修复 S05**：`ADDR_0 = 0x68`、`ADDR_1 = 0x69`。
|
||||
- 采样线程：`threading.Thread` + `self._stop = threading.Event()`，循环 `while not self._stop.wait(0.01)`（10ms 周期且可即时打断）——修复 Q06。
|
||||
- 读传感器整体包在 `bus.transaction()` 中（设地址 + 14 字节连读），比仓颉版逐寄存器 12 次 I2C 往返更高效且原子。
|
||||
- 卡尔曼滤波参数保持 Q=20、R=200；roll/pitch 公式不变。
|
||||
- 数据出口：`latest()` 返回带 `threading.Lock` 保护的最近一帧滤波值（仓颉版 mutex 字段从未真正使用，此处补全）。
|
||||
|
||||
### 4.5 hd/speaker.py（决策 S03）
|
||||
|
||||
仓颉版 `play()` 仅 sleep（实声 C++ 函数被注释）。Python 版决策：**实现真实发声，带静默降级**。
|
||||
|
||||
- 首选：标准库 `wave` + `subprocess.run(["aplay", "-q", tmp.wav])`——树莓派自带 alsa-utils，零 pip 依赖；正弦波生成用 `math.sin`（每次 ≤ 数秒 @48kHz，纯 Python 可接受），保留 5ms 淡入淡出。
|
||||
- `aplay` 不存在或播放失败：log 一次警告后仅 sleep(delay)，行为与仓颉版一致（延时职责不丢失）。
|
||||
- `delay` 语义不变：`play()` 阻塞 `delay` 毫秒（发声与延时并行时取延时为准）。
|
||||
|
||||
### 4.6 robot.py / hardvars.py
|
||||
|
||||
- `RobotStruct` 保持仓颉版结构：`C: list[MatrixObject]` + `M: dict[str, HardwareVar]`（Python dict 有序，天然满足"倒序 destroy"需求）。
|
||||
- `create_hardvars()` 分发表：`{"I2C": I2CVar, "Alias": AliasVar, "Servo": ServoVar, "Speaker": SpeakerVar, "MPU6050_BIND": MPU6050Var}`；`Action` 跳过；未知块 → `plugin.PluginVar`。
|
||||
- 重名键检查（仓颉版 FIXME r.cj:911）：同名硬件变量重复定义时，先 `destroy()` 旧值再覆盖，并输出 stderr 警告。
|
||||
- `run()` 逐行执行 `@Action`；列名合法性（必须含一个 `.`）在**执行前**整表校验一次，报错含列号与列名（配合 Q05 修复）。
|
||||
- 上下文管理器：`__enter__`→`active()`，`__exit__`→`deactive()`；`main.py` 用 `with` 替代仓颉版 try/finally。
|
||||
|
||||
### 4.7 main.py
|
||||
|
||||
| 仓颉版 CLI | Python 版 | 说明 |
|
||||
|-----------|-----------|------|
|
||||
| （无参）stdin 管道 | 同 | `cat std.mt | ./bot` 不变；另支持 `pybot path/to/x.mt` 位置参数（增强，非破坏） |
|
||||
| `--help` | argparse 自动生成 | 文案更新 |
|
||||
| `--test nn/cnn/cnn1` | **移除**（见 §1.3） | NN 由 actpred 承担 |
|
||||
| `--test matrix_o/matrix_2` | `--test roundtrip <in.mt> <out.mt>` | 解析↔序列化往返测试，路径改为参数（仓颉版硬编码 `ss/test.mt`） |
|
||||
| `-i` / `-o`（DRL 预留） | 保留参数位，标注 reserved | 未来对接 actpred |
|
||||
| （新增）`--dry-run` | 解析 + 构建硬件变量但不开 I2C，Mock 总线打印动作序列 | 无硬件调试 .mt 脚本 |
|
||||
| （新增）`--verbose` | FSM 与硬件调用日志到 stderr | 替代 S02 删掉的调试打印 |
|
||||
|
||||
### 4.8 日志规范
|
||||
|
||||
- 所有诊断输出走 `logging`（stderr），stdout 保留纯净——为未来 actpred 管道集成预留（审计 §六 的阻塞项 S02 根治）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 审计发现修复映射表
|
||||
|
||||
| 审计 ID | 级别 | 仓颉版问题 | Python 版修复方式 | 落点 |
|
||||
|---------|------|-----------|------------------|------|
|
||||
| S01 | P0 | submitLine 列数校验恒假 | `len(grp) != len(rows[-1])` 显式校验 + DoesNotSync 带期望/实际列数 | parser.py |
|
||||
| S02 | P0 | parse() 逐字符 print 污染 stdout | 移除；--verbose 走 stderr logging | parser.py / main.py |
|
||||
| S03 | P0 | 扬声器仅 sleep 无实声 | wave + aplay 实现发声，缺 aplay 静默降级为 sleep | hd/speaker.py |
|
||||
| S04 | P1 | r"\n" 与 r'\n' 转义不一致 | Python 无此坑；补"漏分号跨行"单测防回归 | tests/test_parser.py |
|
||||
| S05 | P1 | MPU6050 ADDR_1 应为 0x69 | `ADDR_1 = 0x69` | hd/mpu6050.py |
|
||||
| S06 | P1 | readI2cReg 返回有符号 Int8 | read_reg 返回 0..255；16 位拼接后 struct 显式转有符号 | hd/i2c.py |
|
||||
| S07 | P1 | Lua 路径硬编码 ./modules/ | `$PYBOT_MODULES_PATH` → 包内置 → cwd 三级查找 | plugin.py |
|
||||
| S08 | P1 | README 已知问题表滞后 | pybot README 重写；bot4cj README 标注维护状态 | README.md |
|
||||
| Q01 | P2 | 无单元测试 | pytest：解析器/占位符/Servo/插件/Mock I2C 全流程 | tests/ |
|
||||
| Q02 | P2 | 大量注释旧代码 | 新代码库不携带 | — |
|
||||
| Q03 | P2 | I2C 锁 O(n) 线性扫描 | dict[fd → Lock] | hd/i2c.py |
|
||||
| Q04 | P2 | Makefile 告警关闭 | 无 C 编译；CI 跑 `python -m pyflakes`（可选） | _set.sh |
|
||||
| Q05 | P2 | 列数不匹配报错不可读 | MatrixIndexError 带块名/行/列 + run() 前整表校验 | parser.py / robot.py |
|
||||
| Q06 | P2 | pthread_cancel 非安全点退出 | threading.Event 优雅停止 | hd/mpu6050.py |
|
||||
| Q07 | P2 | GC 析构不确定，fd 泄漏 | with 上下文管理器 + atexit 兜底 | robot.py / main.py |
|
||||
|
||||
---
|
||||
|
||||
## 6. 测试计划
|
||||
|
||||
### 6.1 单元测试（无硬件，x86 可跑）
|
||||
|
||||
| 用例组 | 覆盖 |
|
||||
|--------|------|
|
||||
| test_parser | 全部 `scripts/*.mt` 解析成功；列数不一致抛 DoesNotSync；漏分号跨行；注释/空行/CRLF；roundtrip（解析→save→再解析等价） |
|
||||
| test_placeholder | `-` 递归沿用；首行 `-` 数值列=0；与 actpred mt_parser 语义差异的显式断言（防止两边被误"统一"） |
|
||||
| test_servo | 正装/反装翻转/offset/钳位边界 |
|
||||
| test_hardvars | @Alias 转换；@Action 列名拆分；同行参数聚合；重名覆盖警告 |
|
||||
| test_plugin | 插件三级路径查找；PluginNotFound 报错内容；PCA9685.py 用 Mock I2C 断言寄存器写序列（prescale=121、reg=0x06+4*ch、offval 字节序） |
|
||||
| test_mpu6050 | Mock 总线注入 14 字节样本 → 有符号拼接正确（高字节 ≥ 0x80 场景，回归 S06）；Event 停止 1s 内退出 |
|
||||
|
||||
### 6.2 实机验证（树莓派 + Dashun 蜘蛛机器人）
|
||||
|
||||
1. `cat scripts/std.mt | bash _run.sh`：站立姿态与仓颉版目测一致（10 舵机角度逐一对照 --verbose 日志）。
|
||||
2. `jump.mt` / `lie-down.mt` / `tilt-*.mt` 逐个回放，动作时序无可感知差异。
|
||||
3. 双 MPU6050（0x68 + 0x69）同总线并行采样（回归 S05），roll/pitch 数值与仓颉版单设备输出同量级。
|
||||
4. 扬声器 `spk.F` 发声可闻（回归 S03），无爆音（淡入淡出生效）。
|
||||
5. Ctrl-C 中断：舵机停止、I2C fd 全部释放（`ls /proc/<pid>/fd` 验证）、MPU6050 线程退出。
|
||||
|
||||
### 6.3 交叉验证
|
||||
|
||||
- `--dry-run` 模式下用 Mock 总线记录全部 I2C 写序列，与仓颉版（打补丁记录）同脚本输出逐字节 diff——作为迁移等价性的最强证据（可参考 captcha2 迁移的像素级验证经验）。
|
||||
|
||||
---
|
||||
|
||||
## 7. 里程碑
|
||||
|
||||
| 阶段 | 内容 | 产出 |
|
||||
|------|------|------|
|
||||
| M1 解析器 | parser.py + 全量单测 + roundtrip | 全部 scripts/*.mt 解析通过 |
|
||||
| M2 硬件抽象 | hardvars.py + robot.py + plugin.py + Mock I2C | --dry-run 全流程可跑（x86） |
|
||||
| M3 硬件落地 | i2c.py / servo.py / mpu6050.py / speaker.py + modules/*.py | 树莓派实机 std.mt 站立 |
|
||||
| M4 等价性验证 | §6.2 实机回放 + §6.3 写序列 diff | 验证报告 |
|
||||
| M5 切换 | README/INDEX 更新、bot4cj 标注 legacy、aibox/BotOps 若有引用改指 pybot | 并存期结束评估 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险与对策
|
||||
|
||||
| 风险 | 影响 | 对策 |
|
||||
|------|------|------|
|
||||
| Python GIL + 解释器抖动影响动作时序 | 舵机动作节奏轻微不均 | 动作行间延时 ≥ 20ms，抖动 <1ms 不可感知；MPU6050 采样用 Event.wait 定时，不忙等；量化依据见附录 A |
|
||||
| aplay 子进程首次启动延迟 | 首个音符滞后 | build() 时预热（播放 0 长度静音）；或后续可选接 alsaaudio |
|
||||
| 仓颉版行为的未记录细节 | 等价性缺口 | §6.3 写序列逐字节 diff 兜底 |
|
||||
| .mt 脚本方言分裂（pybot vs actpred 解析器） | 语义漂移 | test_placeholder 显式断言两者差异；长期可评估 actpred 复用 pybot parser 的只读模式 |
|
||||
| 树莓派 Python 版本参差 | 语法兼容 | 目标 Python ≥ 3.9（树莓派 OS Bullseye 起自带 3.9） |
|
||||
|
||||
---
|
||||
|
||||
## 9. 与 actpred 的集成展望（非本期范围）
|
||||
|
||||
迁移完成后，"大脑-身体"闭环的最短路径：
|
||||
|
||||
```
|
||||
actpred predict.py（图像+历史 → 动作向量 action_dim=18）
|
||||
→ 向量转 @Action 单行（pybot 提供 action_row_from_vector() 工具函数）
|
||||
→ pybot RobotStruct 增量执行（对应仓颉版 TODO：@Action 位置指示器）
|
||||
→ MPU6050 姿态反馈回流 actpred（DRL 奖励信号）
|
||||
```
|
||||
|
||||
同语言后，上述管线可在单进程内完成，无需序列化协议——这正是本次迁移最大的战略收益。
|
||||
|
||||
---
|
||||
|
||||
## 附录 A：性能评估依据
|
||||
|
||||
迁移评审中最常见的两个疑虑是"Python 做驱动会不会慢"与"Python 替代 Lua 会不会引入开销"。本附录给出量化分析，结论：**两者均不构成风险，后者反而是性能收益**。
|
||||
|
||||
### A.1 Python 做硬件驱动的时间尺度分析
|
||||
|
||||
bot4cj 架构中所有微秒级时序都已下沉到专用硬件芯片（PCA9685 自主生成 PWM 波形），主机侧只发送设定值，该路径的瓶颈是 I2C 总线物理速率，与宿主语言无关：
|
||||
|
||||
| 环节 | 耗时量级 | 由谁承担 |
|
||||
|------|---------|---------|
|
||||
| 舵机 PWM 波形（50Hz、0.5~2.5ms 脉宽） | µs 级精度 | PCA9685 硬件芯片，主机不参与 |
|
||||
| I2C 写一个寄存器（100kHz 标准模式） | ~200–300 µs/次 | 总线物理速率，语言无关 |
|
||||
| Python 一次 `os.write`/`ioctl` 调用开销 | ~2–5 µs | 解释器 + 系统调用 |
|
||||
| 设一个舵机角度（4 次寄存器写） | ~1 ms | 总线 ≈ 99%，Python ≈ 1% |
|
||||
| 舵机机械转动 60° | ~100–200 ms | 物理惯性 |
|
||||
| `.mt` 动作行间延时 | 20–500 ms | 脚本显式指定 |
|
||||
|
||||
Python 解释开销比总线时间低约两个数量级，比机械动作低四五个数量级。逐项检查潜在慢点：
|
||||
|
||||
- **MPU6050 10ms 采样循环**：14 字节连读 ≈ 1.5–2ms 总线时间 + 卡尔曼滤波 6 次浮点（纯 Python 数 µs），周期内富余充足；且连读比仓颉版逐寄存器 12 次往返（每次重发从机地址）更快。
|
||||
- **正弦波生成**：48kHz 下每秒音频约 4.8 万次 `math.sin`，纯 Python 10–30ms 算完，发声前一次性生成，可接受。
|
||||
- **GIL/GC**：仅主线程 + 1 个采样线程，GIL 无竞争；GC 停顿亚毫秒级，低于 `sleep()` 本身的 ms 级精度。
|
||||
|
||||
Python 不适用的边界（bot4cj 均不涉及）：主机 GPIO bit-bang 生成 PWM/WS2812 单线协议、>1kHz 闭环控制、硬实时保证（Linux 非 RTOS，仓颉版同样做不到）。若未来 DRL 需要高频控制环，正确做法是下沉到协处理器（如 RP2040），属架构问题而非语言问题。
|
||||
|
||||
### A.2 Python 插件替代 Lua 桥接的开销对比
|
||||
|
||||
单论解释器速度 Lua 5.4 快于 CPython，但现有 Lua 路径的开销主要在跨语言桥接而非驱动代码本身。仓颉版每次硬件调用（[r.cj MtVars_Lua.things](../../bot4cj/src/r.cj#L311-L331)）的实际成本：
|
||||
|
||||
| 步骤 | 实现 | 开销量级 |
|
||||
|------|------|---------|
|
||||
| 元数据深拷贝 | `JsonValue.fromStr(metadata.toJsonString())`——JSON 序列化+反序列化一整轮 | ~10–50 µs |
|
||||
| 参数推入 Lua 表 | 每键 `mallocCString` + `Lua_pushstring/setfield` + `free`，跨仓颉→C→Lua 三层 FFI | ~几 µs/键 |
|
||||
| `Lua_pcallk` + 返回表遍历 | `Lua_next` 循环 + 每键值 `Lua_tostring` 转仓颉 String | ~几 µs |
|
||||
| 强制调试打印 | 仓颉侧 2 次 `println` + Lua 侧 `print_table` 全表打印 | ~几十 µs 至 ms 级（终端 I/O） |
|
||||
| Lua 内 4 次 `i2c_write_reg` | 每次跨 Lua→C→仓颉 @C 三层 | 桥接 ~1 µs + 总线 ~250 µs |
|
||||
|
||||
合计框架开销 ~0.1–1 ms/次，与 I2C 总线时间同量级。Python 插件路径的对应成本：
|
||||
|
||||
| 步骤 | 实现 | 开销量级 |
|
||||
|------|------|---------|
|
||||
| 上下文构造 | `{**metadata, **params}` dict 合并（同进程传引用，无序列化） | ~0.5 µs |
|
||||
| 插件调用 | 同解释器直接函数调用 | ~0.1 µs |
|
||||
| I2C 写 | 插件直接 `i2c.write_reg()`，一层 `os.write` 到底 | 系统调用 ~2 µs + 总线 ~250 µs |
|
||||
| 诊断输出 | 默认关闭，`--verbose` 时走 stderr logging（即审计 S02 修复） | 0 |
|
||||
|
||||
框架开销 ~1–2 µs/次，比 Lua 桥接低约两个数量级。插件内部计算（脉宽换算、移位掩码）在两种解释器上的差距为百纳秒级，相对 1ms 总线时间可忽略。
|
||||
|
||||
**结论**：Lua 层在仓颉版存在的唯一理由是"编译型宿主做不了运行时扩展"，为此付出 JSON 往返 + 五层 FFI（仓颉→C→Lua→C→仓颉→glibc）的税；宿主换成 Python 后调用链缩短为 Python→glibc 一层，此项迁移是删除一整层间接性，而非语言互换。
|
||||
|
||||
---
|
||||
|
||||
## 参考文档
|
||||
|
||||
- [bot4cj 代码审计报告](../reviews/bot4cj_CODE_AUDIT_20260808.md)（15 项发现）
|
||||
- [bot4cj 深度分析报告](bot4cj_analysis_20260525_00.md)（D1-D29）
|
||||
- [actpred 与 bot4cj 研究报告](actpred_bot4cj_research_20260809.md)
|
||||
- [bot4cj README.robot.md](../../bot4cj/README.robot.md)
|
||||
- [actpred mt_parser.py](../../actpred/mt_parser.py)（Python 解析器先例）
|
||||
|
||||
---
|
||||
|
||||
*本文档为开发计划，实施前需结合实际硬件环境评估。*
|
||||
Reference in new issue
Block a user