RA8P1 模型轉換與部署教程（手勢識別）

適用范圍 ：RA8P1 (Ethos?U55)
工具鏈 ：e2 studio 集成 RUHMI
說明 ：本工程是基于官方示例人臉識別工程基礎上進行教學，本教程僅新增 手勢識別 模型的獲取、轉換與部署。

0. 基礎知識與技術棧簡介

為了更好地理解本教程，建議先了解以下核心技術概念，這將有助于你理解為什么需要進行“模型轉換”和“量化”操作。

核心硬件：RA8P1 與 Ethos-U55

• Renesas RA8P1 : 業界首款基于 Arm Cortex-M85 內核的微控制器。M85 搭載了 Helium? 矢量處理單元，DSP/ML 性能及其強悍。
• Arm Ethos-U55 : RA8P1 內部集成的微型神經網絡處理器 (microNPU)。它的作用是專門處理繁重的卷積和矩陣運算。
  • 優勢 ：相比僅用 CPU，使用 NPU 推理速度通常提升數倍甚至數十倍，且功耗極大降低。
  • 工作原理 ：NPU 并不運行普通 C 代碼，而是執行專門的“命令流”。我們在轉換步驟生成的 sub_xxxx_command_stream.c 就是 NPU 的指令集。

核心算法：YOLO-Fastest

• YOLO-Fastest : YOLO (You Only Look Once) 系列中最輕量級的版本之一。
• 為什么選它 ：標準 YOLOv5/v8 對于 MCU 來說過于龐大。YOLO-Fastest 優化了網絡結構（如使用深度可分離卷積），在保持檢測速度（FPS）的同時，模型體積通常能控制在 1MB 以內，非常適合部署在 MCU 的片內 Flash 中。

核心流程：RUHMI 與 量化 (Quantization)

• RUHMI / AI Navigator : Renesas 的 AI 部署工具鏈。它的核心任務是將通用的 AI 模型（如 .pt/.onnx）“翻譯”成嵌入式工程可用的 C 代碼。
• INT8 量化 (關鍵) ：Ethos-U55 是一個 定點加速器 ，它只能通過整數（INT8）進行計算，不支持浮點數（Float32）。
  • 轉換 ：工具會將模型中的權重（如 0.1234）映射為整數（如 12）。
  • 校準 (Calibration) ：為了讓整數運算的結果盡可能接近原始浮點結果，我們需要提供“校準集”圖片，讓工具統計數據的分布范圍（動態范圍）。如果校準沒做好（如 Mean/Std 設置錯誤），模型在板子上跑出來的結果就會完全不可用。

1. 環境搭建與 RUHMI 安裝

RUHMI (Renesas AI) 有兩種安裝方式：一種是圖形化界面，一種是命令行。本教程講解通過圖形化界面進行安裝與配置。

1.1 安裝 e2 studio

首先下載并安裝 Pyron e2 studio。安裝完成后打開模型轉換工具（RUHMI Dashboard）。

(圖示路徑)

1.2 安裝配置 Python 3.10 (關鍵步驟)

如果在選擇路徑后提示環境缺失（如提示找不到 Python），請按照以下步驟安裝。

第一步：下載 Python 3.10
e2 studio 通過 Windows 的 py 啟動器檢測版本，必須安裝官方純凈版。
下載地址 或前往 Python 官網下載 Python 3.10.x（建議 3.10.11 或更新版本）。

第二步：安裝設置（非常重要）
運行安裝包時，在第一個界面：

1. 不要勾選Add Python 3.10 to PATH —— 保護現有環境，避免沖突。
2. 務必勾選Install launcher for all users (Recommended) —— 讓 e2 studio 能通過 py -3.10 命令找到它。
3. 點擊 Install Now 完成安裝。

安裝完成后，重啟 e2 studio，按照之前的步驟再次點擊 Setup Environment 。
當出現如下圖示時，代表環境配置成功：

2. 模型訓練：手勢檢測 (YOLO-Fastest)

本節介紹從數據集準備到訓練出 .pt 文件的全流程。

• 任務 ：2 類目標檢測：ok、palm（張開手掌）
• 模型 ：YOLO-Fastest (2路輸出 head)
• 輸入 ：192x192，RGB 3通道
• 預處理 ：x/255 (0..1)，無 mean/std 減法

2.1 準備數據集 (HaGRID 子集)

我們使用 HaGRID 的 YOLO 格式數據，僅保留兩類（0=ok, 1=palm）。

下載與解壓

在 Windows PowerShell 執行以下命令：

mkdir D:gesture_ai
cd D:gesture_ai

# 下載示例數據集 (約10GB)
curl.exe -L -o yolo_format.zip "https://huggingface.co/datasets/testdummyvt/hagRIDv2_512px_10GB/resolve/main/yolo_format.zip?download=true"

# 解壓
mkdir hagrid_yolo_sample
tar -xf .yolo_format.zip -C .hagrid_yolo_sample

目錄結構示例 ：

• D:gesture_aihagrid_ok_palm_1imagestrain|val|test
• D:gesture_aihagrid_ok_palm_1labelstrain|val|test
• D:gesture_aihagrid_ok_palm_1data_ok_palm.yaml

2.2 訓練環境配置

1. 拉取代碼庫

cd D:gesture_ai
git clone https://github.com/Nota-NetsPresso/ModelZoo-YOLOFastest-for-ARM-U55-M85.git
cd .ModelZoo-YOLOFastest-for-ARM-U55-M85
pip install -r requirements.txt

2. 解決版本兼容性問題

• 該倉庫建議 torch >= 1.11, < 2.0。
• 如果使用 torch 1.x，需降級 NumPy 防止報錯：pip install "numpy<2"
• RTX 4060 顯卡建議安裝 CUDA 11.7 對應的 torch 版本：

  pip uninstall -y torch torchvision
  pip install torch==1.13.1+cu117 torchvision==0.14.1+cu117 --index-url https://download.pytorch.org/whl/cu117
  

2.3 執行訓練

D:gesture_ai.venvScriptspython.exe train.py 
  --data D:gesture_aihagrid_ok_palm_1data_ok_palm.yaml 
  --cfg .modelsyolo-fastest.yaml 
  --weights "" 
  --imgsz 192 
  --batch-size 64 
  --epochs 200 
  --device 0 
  --workers 4 
  --project D:gesture_airuns 
  --name ok_palm_192 
  --exist-ok 
  --noplots

訓練完成后得到 best.pt。

常見問題：DataLoader worker exited unexpectedly

解決方法：將 --workers 設為 0 并續訓。

D:gesture_ai.venvScriptspython.exe train.py 
  --resume D:gesture_airunsok_palm_192weightslast.pt 
  --epochs 200 
  --workers 0 
  ...

3. 模型導出 (ONNX)

RUHMI 支持導入 ONNX，因此我們需要將 PyTorch 模型導出為 ONNX 格式。需要保留兩路 head 輸出給板端處理。

注意 ：必須在倉庫根目錄下運行導出腳本，否則會報 ModuleNotFoundError: No module named 'models'。

3.1 創建導出腳本 export_onnx_heads.py

在倉庫根目錄新建文件 export_onnx_heads.py，代碼如下：

import torch
import torch.nn as nn

CKPT = r"D:gesture_ai
unsok_palm_192weightsest.pt"
OUT  = r"D:gesture_aiok_palm_192_heads.onnx"

ck = torch.load(CKPT, map_location="cpu")
model = ck["model"].float().eval()

class HeadWrapper(nn.Module):
    def __init__(self, m):
        super().__init__()
        self.m = m

    def forward(self, x):
        y, feats = self.m(x)
        # feats[0] - > (1,3,12,12,7)
        # feats[1] - > (1,3,6,6,7)
        return feats[0], feats[1]

w = HeadWrapper(model)
dummy = torch.zeros(1, 3, 192, 192)

torch.onnx.export(
    w,
    dummy,
    OUT,
    input_names=["images"],
    output_names=["p4_12x12", "p5_6x6"],
    opset_version=13,
    do_constant_folding=False,
)

print("saved:", OUT)

3.2 運行導出

D:gesture_ai.venvScriptspython.exe .export_onnx_heads.py

正常導出的 ONNX 文件大小約為 1MB 左右。

4. RUHMI 模型轉換 (AI Navigator)

參考關于RA生態工作室的視頻號回放：

啟動 RUHMI AI Navigator 進行轉換。

4.1 準備校準數據集 (Calibration Dataset)

用于 INT8 量化校準。建議從訓練集中隨機抽取 200 張圖片。

PowerShell 隨機抽取腳本：

$src = "D:gesture_aihagrid_ok_palm_1images	rain"
$dst = "D:gesture_aicalib_ok_palm_200"
mkdir $dst -Force | Out-Null
Get-ChildItem $src -File | Get-Random -Count 200 | Copy-Item -Destination $dst

在 AI Navigator 中選擇該目錄作為 Calibration dataset。

4.2 設置 Mean / Std (重要)

由于訓練時只做了 x/255 歸一化，板端輸入必須匹配。

推薦設置（板端輸入 0..1 float） ：

• Mean : 0, 0, 0
• Std : 1, 1, 1 (如果在板端沒做 /255，這里要設為 255)

注意 ：不要使用 mean=127.5, std=127.5，那是 -1..1 的歸一化方式。

4.3 檢查轉換輸出

轉換成功后，關鍵生成的源文件位于 buildMCUcompilationsrc：

• model.c/.h
• sub_xxxx_model_data.c/.h
• sub_xxxx_invoke.c/.h
• ...

5. 部署到工程：CPU 版本

目標：將 CPU-only 產物集成到 RT-Thread 工程，驗證前處理與解碼邏輯。

5.1 文件集成

將 RUHMI 生成的 compilationsrc 下的文件復制到工程目錄 src/models/：

• compute_sub_0000.c
• model.c
• kernel_library_int.c
• kernel_library_utils.c

5.2 編譯配置 (SConscript)

修改 src/models/SConscript，加入剛復制的源文件：

src = [
    os.path.join(cwd, 'model.c'),
    os.path.join(cwd, 'compute_sub_0000.c'),
    os.path.join(cwd, 'kernel_library_int.c'),
    os.path.join(cwd, 'kernel_library_utils.c'),
]

5.3 關鍵代碼修改

1. 輸入前處理對齊

修改 src/hal_entry.c，確保輸入轉為 0..1 (float)：

const float inv255 = 1.0f / 255.0f;
dst[0 * plane_size + pixel_idx] = (float)r * inv255;
dst[1 * plane_size + pixel_idx] = (float)g * inv255;
dst[2 * plane_size + pixel_idx] = (float)b * inv255;

2. 后處理解碼 (YOLOv5公式)

修改 src/yolo/yolo_rtthread.c，使用 YOLOv5 的解碼公式替代傳統 Darknet 公式：

float stride_pix = (float)INPUT_W / (float)grid;
float cx = (sigmoid(tx) * 2.0f - 0.5f + j) * stride_pix;
float cy = (sigmoid(ty) * 2.0f - 0.5f + i) * stride_pix;
float ww = (sigmoid(tw) * 2.0f); ww = ww * ww * anchor_w;
float hh = (sigmoid(th) * 2.0f); hh = hh * hh * anchor_h;

3. 調試顯示優化

建議在 LCD 顯示分類文本、置信度，并用不同顏***分 OK/PALM。

6. 部署到工程：NPU (Ethos-U55) 版本

目標：啟用 NPU 加速。RUHMI 針對 NPU 通常生成“三段式”代碼：前處理(CPU) -> NPU推理 -> 后處理(CPU)。

6.1 文件集成

RUHMI NPU 版輸出包含 sub_0001 (NPU) 等部分。需復制以下文件到 src/models/：

• compute_sub_0000.c (CPU 前處理)
• compute_sub_0002.c (CPU 后處理)
• sub_0001_*.c (NPU 相關：command strteam, weights, invoke)
• model.c, ethosu_common.h 等

6.2 編譯配置

修改 SConscript，加入所有新文件：

src = [
    os.path.join(cwd, 'model.c'),
    os.path.join(cwd, 'compute_sub_0000.c'),
    os.path.join(cwd, 'compute_sub_0002.c'),
    os.path.join(cwd, 'sub_0001_command_stream.c'),
    os.path.join(cwd, 'sub_0001_invoke.c'),
    os.path.join(cwd, 'sub_0001_model_data.c'), 
    os.path.join(cwd, 'sub_0001_tensors.c'),
    # ... 其他依賴庫
]

6.3 關鍵點：NPU 內存配置 (Arena)

1. Arena 放入 OSPI RAM
修改 sub_0001_invoke.c，將 arena 數組放到 OSPI 段，避免占用寶貴的內部 SRAM：

__attribute__((aligned(16), section(".ospi1_cs0_noinit"))) uint8_t sub_0001_arena[...];

2. 輸入數據寫入 Arena
NPU 的輸入通常直接映射到 Arena 的起始位置（offset 0）。
修改 model.c， 直接將量化后的數據寫入 Arena ，而不是臨時 buffer：

// 獲取 NPU 輸入在 Arena 中的地址
int8_t* npu_in = (int8_t*)(sub_0001_arena + sub_0001_address_images_...);
// 執行前處理，直接輸出到 npu_in
compute_sub_0000(compute_arena_sub_0000, buf_images, npu_in);

3. Cache 維護 (非常重要)
在調用 NPU 前后必須維護 D-Cache，否則 NPU 讀不到最新數據或 CPU 讀不到 NPU 的輸出。

// Invoke 前：Clean (將 CPU 寫的數據刷入 RAM)
SCB_CleanDCache_by_Addr(sub_0001_arena, sizeof(sub_0001_arena));

// Invoke
sub_0001_invoke(...);

// Invoke 后：Invalidate (讓 CPU 重新從 RAM 讀取)
SCB_InvalidateDCache_by_Addr(sub_0001_arena, sizeof(sub_0001_arena));

6.4 調試建議

1. 驗證 NPU 是否工作 ：打印輸入和輸出的 hash 值或 min/max 值。如果輸入變了但輸出 hash 不變，說明 NPU 沒運行或 invoke 失敗。
2. 調整閾值 ：初期將 CONF_THRESH 設低（如 0.2），觀察 max_sig，確認有檢測結果后再調高。

審核編輯 黃宇