Blame for docs/NETWORK_STRUCTURE.md

# Direct Tactile Action Decoder：完整网络结构与实验协议

本文档描述 VB3 当前 `DirectTactileActionDecoder` 实验的**实际代码结构**，用于模型复现、论文讨论和跨团队交接。

## 1. 一句话概述

该系统先用冻结的 SmolVLA 离线生成一个归一化粗动作块，用冻结的触觉 ResNet18 离线生成四个当前帧触觉 token，再训练一个 471,828 参数的两层 Transformer Decoder，直接重新生成完整动作块：

\[
f_\theta:
\left(
A_{\text{SmolVLA}}\in\mathbb{R}^{20\times20},
T\in\mathbb{R}^{4\times512}
\right)
\rightarrow
\hat A\in\mathbb{R}^{20\times20}.
\]

输出是完整新动作，不是 `coarse_action + residual`。

## 2. 关键实验边界

| 模块 | 资产 | 状态 | Decoder 训练时是否运行 |
|---|---|---:|---:|
| SmolVLA base | `lerobot/smolvla_base`，revision `c83c3163...` | 冻结 | 否 |
| SmolVLA PEFT adapter | `KaiyueChen/pick_tube_01`，revision `c2bb4296...` | 冻结 | 否 |
| 触觉 encoder | `KaiyueChen/encoder_ckpt_0809` 转换后的 ResNet18 | 冻结、永久 eval | 否 |
| DirectTactileActionDecoder | 本文第 8 节 | 可训练 | 是 |

该实验不是端到端联合训练，而是两个阶段：

1. 离线运行冻结 producer，生成不可变数值 cache。
2. 只读取 cache，训练小型动作 decoder。

训练程序接收冻结资产路径是为了验证 SHA256 provenance；它不会在训练 loop 中再次加载或运行 SmolVLA/触觉 encoder。

## 3. 整体数据流

```mermaid
flowchart TB
    subgraph A[阶段 A：离线冻结特征生成]
        RGB[两路 RGB + 20D state + task] --> PRE[SmolVLA saved preprocessor]
        PRE --> SVLA[冻结 SmolVLA base + pick_tube_01 PEFT]
        NOISE[固定 seed=0 flow noise] --> SVLA
        SVLA --> COARSE[coarse_action\nB x 20 x 20\n归一化空间]

        TOUCH[当前帧四路触觉 RGB] --> TPRE[uint8预处理\n224x224 / 255]
        TPRE --> R18[共享冻结 ResNet18]
        R18 --> TRMS[per-sensor RMS normalize]
        TRMS --> TEMB[tactile_embedding\nB x 4 x 512]

        EXPERT[Pick_tube_05 专家动作] --> NORM[adapter action mean/std]
        NORM --> TARGET[expert_action B x 20 x 20\naction_pad_mask B x 20]
    end

    subgraph B[阶段 B：只训练 Decoder]
        COARSE --> APATH[action_in 20->128\n+ action position]
        TEMB --> TPATH[RMS normalize\ntactile_in 512->128\n+ sensor identity]
        APATH --> TD[2-layer Transformer Decoder]
        TPATH -->|cross-attention memory| TD
        TD --> OUT[LayerNorm + Linear 128->20]
        OUT --> PRED[prediction B x 20 x 20]
        PRED --> LOSS[Masked Smooth L1]
        TARGET --> LOSS
    end
```

## 4. 离线 cache 的每行内容

| 字段 | dtype | shape | 含义 |
|---|---|---:|---|
| `episode_index` | int64 | `[]` | 原始 episode ID |
| `frame_index` | int64 | `[]` | episode 内 anchor 帧 |
| `split_id` | int64 | `[]` | train=0，val=1，test=2 |
| `coarse_action` | float32 | `[20,20]` | 冻结 SmolVLA 的归一化动作块 |
| `tactile_embedding` | float32 | `[4,512]` | 四路当前帧触觉特征 |
| `expert_action` | float32 | `[20,20]` | 归一化专家动作块 |
| `action_pad_mask` | bool | `[20]` | 哪些未来时间步有效 |

Cache 不包含原始 RGB、原始触觉图像、state、task token、SmolVLA hidden state 或 ResNet feature map。

## 5. 冻结 SmolVLA 粗动作 producer

### 5.1 有效输入

每个 anchor 使用一个当前观测步：

| 输入 | shape |
|---|---:|
| 两路 RGB | 每路 `[3,224,224]`，processor 后进入有效 camera1/camera2 |
| `observation.state` | `[20]` |
| task | 字符串，token 长度固定为 48 |

原始 `camera0/camera1` 由 adapter processor 映射为 SmolVLA 的有效 `camera1/camera2`。触觉图像绝不进入 SmolVLA preprocessor。

运行时强制使用实际 20D state、20D action、两路相机和 `empty_cameras=0`；不能直接把 adapter `config.json` 中陈旧的 6D/额外相机 metadata 当成有效输入契约。

### 5.2 模型与 PEFT

- VLM：`HuggingFaceTB/SmolVLM2-500M-Video-Instruct`
- VLM layers：16
- Action expert layers：16（来自 `pick_tube_01` adapter 有效配置）
- PEFT：LoRA，`r=16`，`alpha=16`，dropout=0
- LoRA target：VLM text layers self-attention 的 `q_proj` 和 `v_proj`
- 额外保存/训练过的 adapter 模块：language expert、state/action projection 和 action-time MLP
- 当前 decoder 实验中以上所有模块均冻结

加载后执行：

```python
PeftModel.from_pretrained(..., is_trainable=False)
for parameter in policy.parameters():
    parameter.requires_grad_(False)
policy.eval()
```

SmolVLA 前向还在 `torch.inference_mode()` 下运行。

### 5.3 粗动作生成

每个 anchor 使用固定噪声：

```text
seed             = 0
external noise   = [B,20,20]
internal padding = [B,20,32]
flow steps       = 10
```

内部动作最大维度为 32，最终只保留前 20 个有效动作维度：

```text
frozen SmolVLA output [B,20,32]
              unpad ↓
coarse_action        [B,20,20]
```

`coarse_action` 没有经过 postprocessor，仍处于 adapter 保存的 mean/std 归一化空间。

## 6. 冻结触觉 encoder

当前 direct-decoder 实验使用的是 `encoder_ckpt_0809` 中的 Flax ResNet18 转换结果，不是 AnyTouch2，也不是两帧触觉 VideoMAE。

### 6.1 四路输入顺序

```text
0. observation.images.tactile_left_0
1. observation.images.tactile_right_0
2. observation.images.tactile_left_1
3. observation.images.tactile_right_1
```

四路都是当前帧；该实现不使用首帧背景差分和触觉历史。

### 6.2 图像预处理

输入必须是 uint8 RGB，支持 NHWC 或 NCHW：

1. 转为 NCHW float32。
2. 保持宽高比缩放到不超过 `224x224`。
3. 缩小时使用 area，放大时使用 bilinear。
4. 中心补零到 `224x224`。
5. 除以 255，得到 `[0,1]`。
6. 不使用 ImageNet mean/std。

原始 Pick_tube_05 触觉图像已经是 `224x224`，因此实际主要执行通道转换和 `/255`。

### 6.3 ResNet18 逐层结构

所有卷积使用与 Flax/TensorFlow 一致的动态 SAME padding。

| 阶段 | 结构 | 输出 shape |
|---|---|---:|
| 输入 | RGB float32 | `[N,3,224,224]` |
| Stem | Conv `7x7`, 3→64, stride 2；BN；ReLU | `[N,64,112,112]` |
| Pool | MaxPool `3x3`, stride 2 | `[N,64,56,56]` |
| Layer 1 | 2×BasicBlock，64→64 | `[N,64,56,56]` |
| Layer 2 | 2×BasicBlock，首块 stride 2，64→128 | `[N,128,28,28]` |
| Layer 3 | 2×BasicBlock，首块 stride 2，128→256 | `[N,256,14,14]` |
| Layer 4 | 2×BasicBlock，首块 stride 2，256→512 | `[N,512,7,7]` |
| 输出 | 空间维度 global average | `[N,512]` |

BasicBlock：

```text
input ───────────────────────────────┐
  │                                  │ identity / 1x1 Conv+BN
  └→ Conv3x3 → BN → ReLU → Conv3x3 → BN
                                      +
                                      ↓
                                    ReLU
```

Layer 2–4 的首个 block 使用 stride-2 的 `1x1 Conv + BN` residual projection。模型没有分类 FC 层。

### 6.4 四路 batch 编码

```text
[B,4,3,224,224]
       flatten sensor dimension
[B*4,3,224,224]
       shared frozen ResNet18
[B*4,512]
       RMS normalize
[B*4,512]
       reshape
[B,4,512]
```

RMS normalization：

\[
z=\frac{f}{\sqrt{\operatorname{mean}(f^2)+10^{-6}}}.
\]

四路在 encoder 内互不交互；它们只在后续 Transformer cross-attention 中融合。

### 6.5 冻结与参数量

| 模块 | 参数量 |
|---|---:|
| conv1 | 9,408 |
| bn1 | 128 |
| layer1 | 147,968 |
| layer2 | 525,568 |
| layer3 | 2,099,712 |
| layer4 | 8,393,728 |
| **总参数** | **11,176,512** |
| **可训练参数** | **0** |

Encoder 构造时就执行 `eval()` 和 `requires_grad_(False)`，并重写 `train()`，所以外部调用 `train(True)` 也不会更新 BatchNorm 统计量。

## 7. Decoder 输入 token 构造

固定配置：

| 字段 | 数值 |
|---|---:|
| chunk/action horizon | 20 |
| action dimension | 20 |
| tactile token count | 4 |
| tactile embedding dimension | 512 |
| `d_model` | 128 |
| attention heads | 4 |
| head dimension | 32 |
| decoder layers | 2 |
| FFN hidden dimension | 256 |
| dropout | 0.1 |

### 7.1 动作 query token

输入：

```text
coarse_action [B,20,20]
```

共享线性投影并加入可学习时间位置：

\[
q_t=W_a a_t+b_a+p_t,
\]

```text
Linear(20→128)          [B,20,128]
action_position         [20,128]
动作 query token         [B,20,128]
```

`action_position` 用 `Normal(std=0.02)` 初始化。

### 7.2 触觉 memory token

输入：

```text
tactile_embedding [B,4,512]
```

Decoder 会对 cache embedding 再做一次防御性 per-token RMS normalization，然后使用一个共享 Linear：

\[
m_i=W_t\operatorname{RMSNorm}(t_i)+b_t+s_i,
\]

```text
RMS normalize            [B,4,512]
Linear(512→128)          [B,4,128]
sensor_identity          [4,128]
触觉 memory token         [B,4,128]
```

这里没有额外两层 MLP、激活函数或 tactile positional encoding。`sensor_identity` 表示四个物理传感器身份，用 `Normal(std=0.02)` 初始化。

触觉 token 不与动作 token 直接拼接，而是作为 Transformer Decoder 的 `memory`。

## 8. 两层 Transformer Decoder

PyTorch 配置：

```python
nn.TransformerDecoderLayer(
    d_model=128,
    nhead=4,
    dim_feedforward=256,
    dropout=0.1,
    activation="relu",
    batch_first=True,
    norm_first=True,
)
```

未传入 causal mask、target padding mask 或 memory mask。因此：

- 20 个动作 token 之间是非因果全连接 self-attention。
- 每个动作 token 都能 cross-attend 全部四个触觉 token。

每层：

```text
动作 token [B,20,128]
   ↓ Pre-Norm self-attention：20个动作时间步相互建模
   ↓ residual
   ↓ Pre-Norm cross-attention：Q来自动作，K/V来自4个触觉memory
   ↓ residual
   ↓ Pre-Norm FFN：Linear 128→256 → ReLU → Dropout → Linear 256→128
   ↓ residual
输出 [B,20,128]
```

两层后：

```text
[B,20,128]
    ↓ LayerNorm(128)
    ↓ Linear(128→20)
[B,20,20]
```

输出层没有激活函数。输出本身就是最终归一化动作块。

## 9. Decoder 精确参数量

| 模块 | 参数 shape / 映射 | 参数量 |
|---|---|---:|
| `action_in` | Linear 20→128 | 2,688 |
| `action_position` | `[20,128]` | 2,560 |
| `tactile_in` | Linear 512→128 | 65,664 |
| `sensor_identity` | `[4,128]` | 512 |
| Transformer layer 0 | self-attn + cross-attn + FFN + 3 norms | 198,784 |
| Transformer layer 1 | self-attn + cross-attn + FFN + 3 norms | 198,784 |
| `action_out` | LayerNorm + Linear 128→20 | 2,836 |
| **总计** |  | **471,828** |

每个 Transformer layer：

| 子模块 | 参数量 |
|---|---:|
| action self-attention | 66,048 |
| tactile cross-attention | 66,048 |
| FFN | 65,920 |
| 3×LayerNorm | 768 |
| **每层总计** | **198,784** |

两层 Transformer 合计 397,568 参数。

## 10. Action+tactile 与 Action-only

两个模式使用相同类、相同名义参数量，但分别训练独立 checkpoint。

| 项目 | Action+tactile | Action-only |
|---|---|---|
| coarse action | 使用 | 使用 |
| 真实 tactile embedding | 使用 | 忽略 |
| memory 输入 | 当前样本 `[B,4,512]` | 内部全零 `[B,4,512]` |
| projection 后 memory | `Linear(RMS(tactile))+sensor_id` | `Linear(0)+sensor_id` |
| memory 含义 | 样本相关触觉 token | 四个可学习常量 token |
| 参数量 | 471,828 | 471,828 |

Action-only 中：

\[
m_i=b_t+s_i.
\]

`tactile_in.weight` 的输入恒为零，因此对 forward 没有数据相关贡献；`tactile_in.bias` 和 `sensor_identity` 仍会通过 cross-attention 学习。所有名义参数都被放入 AdamW，但不应声称 action-only 中每个参数都收到非零数据梯度。

## 11. 训练目标

### 11.1 Episode-level split

| split | episodes | anchors | 用途 |
|---|---:|---:|---|
| train | 280 | 106,802 | 更新 decoder |
| validation | 35 | 13,294 | 选择 `best.pt` |
| test | 35 | 13,264 | 最终一次报告 |

同一 episode 不跨 split。

### 11.2 Expert chunk 与 mask

每个 anchor 的目标：

```text
expert_action   [B,20,20]
valid mask      [B,20]
```

规则：

- chunk 不跨 episode。
- episode 尾部越界位置填零并 mask 掉。
- 每个 episode 最后一帧全零 terminal action 被 mask 掉。
- terminal 行自身没有有效第一步，因此不作为 cache anchor。
- target 使用与冻结 adapter 相同的 action mean/std 归一化。

### 11.3 Loss

预测：

\[
\hat A=f_\theta(A_{\text{coarse}},T).
\]

损失是归一化空间的 masked Smooth L1（PyTorch 默认 `beta=1`）：

\[
L=\frac{\sum_{b,t,d}M_{b,t}\,\rho(\hat A_{b,t,d}-A^{expert}_{b,t,d})}{20\sum_{b,t}M_{b,t}},
\]

\[
\rho(x)=
\begin{cases}
\frac{1}{2}x^2,&|x|<1\\
|x|-\frac{1}{2},&|x|\ge1.
\end{cases}
\]

该 loss 监督完整动作，不监督 residual。

### 11.4 优化配置

```text
seed                  = 0
global batch size     = 256
epochs                = 50
optimizer             = AdamW
learning rate         = 3e-4
weight decay          = 1e-4
AdamW betas           = (0.9, 0.999), PyTorch default
AdamW epsilon         = 1e-8, PyTorch default
scheduler             = none
gradient clipping     = none
explicit AMP          = none
```

Train loader shuffle；validation loader 不 shuffle。训练时 dropout 开启，验证时 decoder `eval()`、dropout 关闭。

每个 epoch 计算 validation masked Smooth L1；严格更低时复制参数。最后保存 validation loss 最低的 `best.pt`，并在 CPU 上严格 reload 检查 `[1,20,20]` finite 输出。

实际 checkpoint：

| 模式 | best epoch | best validation loss |
|---|---:|---:|
| Action-only | 30 | 0.0735953188 |
| Action+tactile | 3 | 0.0762285802 |

## 12. 四条件最终测试

所有条件使用同一 held-out test split、相同有序 key、coarse action、expert target 和 mask：

```text
Frozen SmolVLA:
    prediction = coarse_action

Action-only:
    action_only_checkpoint(coarse_action, constant memory)

Action+tactile:
    action_tactile_checkpoint(coarse_action, synchronized tactile)

Shuffled-tactile:
    同一个 action_tactile checkpoint
    coarse/target/mask 保持不变
    tactile 替换成其他 episode 的 embedding
```

Shuffled-tactile 不是第四个训练模型，而是 action+tactile checkpoint 的错误输入条件。固定 seed=0，并保证 donor episode 与目标 episode 不同。

离线评估对完整有效 20-step chunk 计分，不截断到配置中的 `execute_steps=10`。

当前正式 test 结果：

| Condition | Normalized Smooth L1 | Physical MAE | Physical RMSE | MAE - baseline | Improved chunks |
|---|---:|---:|---:|---:|---:|
| Frozen SmolVLA | 0.11852655 | 0.000834609 | 0.001771636 | 0 | 0% |
| Action-only | **0.07258066** | **0.000636407** | **0.001334380** | **-0.000198201** | **91.2922%** |
| Action+tactile | 0.07536559 | 0.000685921 | 0.001395565 | -0.000148688 | 83.0066% |
| Shuffled-tactile | 0.09412303 | 0.000893633 | 0.001818145 | +0.000059024 | 42.4608% |

这些是离线动作误差，不等于真实机器人成功率。

## 13. 前向伪代码

```python
class DirectTactileActionDecoder(nn.Module):
    def __init__(self):
        self.action_in = nn.Linear(20, 128)
        self.action_position = nn.Parameter(torch.randn(20, 128) * 0.02)

        self.tactile_in = nn.Linear(512, 128)
        self.sensor_identity = nn.Parameter(torch.randn(4, 128) * 0.02)

        layer = nn.TransformerDecoderLayer(
            d_model=128,
            nhead=4,
            dim_feedforward=256,
            dropout=0.1,
            activation="relu",
            batch_first=True,
            norm_first=True,
        )
        self.decoder = nn.TransformerDecoder(layer, num_layers=2)
        self.action_out = nn.Sequential(
            nn.LayerNorm(128),
            nn.Linear(128, 20),
        )

    def forward(self, coarse_action, tactile_embedding, mode):
        # coarse_action: [B,20,20]
        action_tokens = self.action_in(coarse_action) + self.action_position

        if mode == "action_tactile":
            # tactile_embedding: [B,4,512]
            tactile = tactile_embedding.float()
            rms = tactile.square().mean(-1, keepdim=True).sqrt()
            tactile = tactile / rms.clamp_min(torch.finfo(torch.float32).eps)
        elif mode == "action_only":
            tactile = torch.zeros(
                coarse_action.shape[0], 4, 512,
                device=coarse_action.device,
                dtype=torch.float32,
            )
        else:
            raise ValueError(mode)

        tactile_tokens = self.tactile_in(tactile) + self.sensor_identity
        decoded = self.decoder(
            tgt=action_tokens,       # [B,20,128]
            memory=tactile_tokens,  # [B,4,128]
        )
        prediction = self.action_out(decoded)  # [B,20,20]
        return prediction
```

## 14. 部署/在线推理边界

部署时需要重新组合三个模块：

```text
当前 RGB/state/task
    → frozen SmolVLA
    → normalized coarse action [B,20,20]

当前四路触觉
    → frozen ResNet18
    → tactile embedding [B,4,512]

coarse + tactile
    → trained decoder best.pt
    → fine normalized action [B,20,20]

fine normalized action
    → adapter postprocessor
    → physical action [B,20,20]
```

配置计划执行前 10 步：预测 horizon 为 20，`execute_steps=10`。当前离线结果只证明数值误差，不证明真实机器人在线链路或成功率。