docs: expand bpu quantization guide

四足机器狗训练到实机部署全流程指南.md

@@ -558,9 +558,47 @@ BPU 量化不是把 ONNX 改一个后缀。至少需要：
 
 当前量化脚本会保留 actions 输出、降级 opset、包装为 BPU 需要的 4D 输入，并把 MoE grouped Conv 等价替换为 Gemm，以减少 CPU fallback。中间 norm 节点位于 actor 之前，不能随意删除或移到后处理。
 
+量化脚本内部流程如下：
+
+```text
+真实日志 steps.jsonl
+  -> make_calibration_data.py 生成 float32 featuremap 校准样本
+  -> keep_actions_output.py 只保留 actions 输出
+  -> downgrade_policy_to_opset11.py 降级到工具链可接受的 opset
+  -> make_bpu_4d_onnx.py 把 [1, D] 输入包装成 [1, 1, 1, D]
+  -> replace_group_conv_with_gemm.py 把 MoE grouped Conv 替换为等价 Gemm
+  -> compare_4d_onnx.py 检查浮点图变换等价
+  -> hb_mapper / hb_compile 生成板端模型
+```
+
+脚本中的主要可调变量含义：
+
+| 参数 | 含义 | 常用设置 |
+| --- | --- | --- |
+| `--policy` | 原始 ONNX 路径，必须在部署仓库内 | `../policy_robotlab_26000.onnx` |
+| `--round` | 输出目录和校准目录里的轮次标签，不参与计算 | `26000`、`35k` |
+| `--name` | 输出模型 basename；不填时取 ONNX 文件名 | `policy_robotlab_26000` |
+| `--history-len` | 历史帧数，用于重建输入维度 | RobotLab 为 `10`，Gym 为 `5` |
+| `--flat-dim` | 平铺输入维度；不填时为 `45 * history-len` | RobotLab 为 `450`，Gym 为 `225` |
+| `--samples` | 校准样本数量，越大越慢但覆盖更稳 | 默认 `64`，必要时 `128` |
+| `--min-samples` | 最少有效样本数，不足则中止 | 默认 `32` |
+| `--log-prefix` | 从 `logs/` 下筛选部署日志的目录前缀 | `robotlab_go1_deploy` |
+| `--cal-tag` | 校准目录标签，区分 RobotLab/Gym | `robotlab`、`gym` |
+| `--compare-limit` | 浮点 ONNX 等价对比样本数 | 默认 `64` |
+| `--quant` | 量化策略 | 默认 `int16`，`int8` 仅作对照 |
+| `--docker-image` | D-Robotics CPU 工具链镜像 | X5/S100 各自不同 |
+
+量化建议在 Mac 或训练机的 Docker 中完成，不在 X5/S100 板端跑 Docker。板端只负责加载产物做离线测速、数值对齐和实机部署。
+
 ### 11.2 RDK X5
 
-量化机执行：
+X5 使用 D-Robotics X5 CPU 工具链镜像：
+
+```bash
+docker pull openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8
+```
+
+脚本默认会用 `docker run --rm --platform linux/amd64` 启动这个镜像，并把当前仓库挂载到 `/workspace/deploy_go1_pro`。量化机执行：
 
 ```bash
 cd /path/to/go1_pro_deploy
@@ -574,9 +612,17 @@ bash deploy_45dim_rl_gym/bpu_quantization/quantize_policy_x5.sh \
   --min-samples 32 \
   --log-prefix robotlab_go1_deploy \
   --cal-tag robotlab \
+  --docker-image openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8 \
   --quant int16
 ```
 
+X5 关键配置：
+
+- `march` 固定为 `bayes-e`。
+- 输入类型为 `featuremap`，运行时输入 shape 是 `obs_4d [1, 1, 1, 450]`。
+- int16 时脚本在 YAML 中写入 `optimization: "set_all_nodes_int16"`。
+- `hb_mapper checker` 默认会先运行；明确知道模型已检查过时才使用 `--skip-checker`。
+
 预期产物：
 
 ```text
@@ -584,6 +630,18 @@ deploy_45dim_rl_gym/bpu_quantization/mapper_output_26000_gemm/
   policy_robotlab_26000_int16_gemm.bin
 ```
 
+如果要量化旧 Gym 5 帧模型，必须同步修改历史长度、日志前缀和标签：
+
+```bash
+bash deploy_45dim_rl_gym/bpu_quantization/quantize_policy_x5.sh \
+  --policy ../policy_35k.onnx \
+  --round 35k \
+  --history-len 5 \
+  --log-prefix rlgym_go1_deploy \
+  --cal-tag gym \
+  --quant int16
+```
+
 板端先做完全离线自检，不连接电机控制：
 
 ```bash
@@ -599,6 +657,14 @@ X5 的 featuremap 模型不要直接改用 `hobot_dnn.pyeasy_dnn.forward()`。
 
 ### 11.3 S100
 
+S100 使用新版 S100/S600 CPU 工具链镜像：
+
+```bash
+docker pull registry.d-robotics.cc/deliver/ai_toolchain_ubuntu_22_s100_s600_cpu:v3.7.0
+```
+
+脚本同样在量化机 Docker 中运行，不在 S100 板端运行 Docker：
+
 ```bash
 cd /path/to/go1_pro_deploy
 
@@ -611,10 +677,18 @@ bash deploy_45dim_rl_gym/bpu_quantization/quantize_policy_s100.sh \
   --min-samples 32 \
   --log-prefix robotlab_go1_deploy \
   --cal-tag robotlab \
+  --docker-image registry.d-robotics.cc/deliver/ai_toolchain_ubuntu_22_s100_s600_cpu:v3.7.0 \
   --march nash-e \
   --quant int16
 ```
 
+S100 关键配置：
+
+- `--march nash-e` 对应当前 S100 平台；不要沿用 X5 的 `bayes-e`。
+- 输出是 `.hbm`，不是 X5 的 `.bin`。
+- int16 时脚本在 YAML 中写入 `quant_config.model_config.all_node_type: int16`。
+- `compiler_parameters.core_num` 当前为 `1`，优先保证单次策略推理低延迟；需要多核吞吐测试时应另做离线 benchmark，不要直接改实机脚本。
+
 预期产物：
 
 ```text
@@ -622,6 +696,13 @@ deploy_45dim_rl_gym/bpu_quantization/mapper_output_26000_s100_gemm/
   policy_robotlab_26000_s100_int16_gemm.hbm
 ```
 
+产物同步到 S100 后，先看模型信息再测速：
+
+```bash
+/usr/hobot/bin/hrt_model_exec model_info \
+  --model_file deploy_45dim_rl_gym/bpu_quantization/mapper_output_26000_s100_gemm/policy_robotlab_26000_s100_int16_gemm.hbm
+```
+
 板端测速：
 
 ```bash