NPU 性能调优与调试

1. 概述

1.1 功能简介

RK3588 内置 6 TOPS 算力的 NPU（Neural Network Processing Unit，专门跑神经网络的加速器；TOPS 是每秒万亿次运算的算力单位），包含 3 个独立 NPU 核心，每个核心提供约 2 TOPS 算力。NPU 支持 INT8、FP16 等多种数据格式，可高效运行卷积神经网络、目标检测、图像分割等深度学习推理任务。

本文档介绍 NPU 性能评估方法、调优技巧、调试工具和常见性能问题的解决方案，帮你把 RK3588 NPU 的推理能力用满。

1.2 应用场景

场景	说明
模型性能评估	对比不同模型在 NPU 上的推理延迟和吞吐量
推理延迟优化	减少单帧推理时间，满足实时性要求
吞吐量提升	提高单位时间内处理的帧数
内存占用优化	降低模型和推理过程的内存消耗
功耗控制	在满足性能需求的前提下降低 NPU 功耗

1.3 工作原理

调优的整体思路是先找到瓶颈、再对症下药：

NPU 性能调优流程:
  1. 模型分析      → 识别性能瓶颈（CPU 预处理 / NPU 推理 / 数据搬运）
  2. 量化优化      → INT8 量化减小模型体积，FP16 平衡精度与速度
  3. 核心分配      → 利用 3 个 NPU 核心并行处理
  4. 内存优化      → 减少 CPU-NPU 之间的数据拷贝
  5. 性能验证      → Benchmark 测试确认优化效果

1.4 NPU 核心架构

RK3588 NPU 架构:
  ┌─────────────────────────────────────────┐
  │              6 TOPS NPU                 │
  │  ┌───────────┬───────────┬───────────┐  │
  │  │ NPU_CORE_0│ NPU_CORE_1│ NPU_CORE_2│  │
  │  │  ~2 TOPS  │  ~2 TOPS  │  ~2 TOPS  │  │
  │  └───────────┴───────────┴───────────┘  │
  │         共享内存 / DMA-BUF              │
  └─────────────────────────────────────────┘

  调度模式:
    单核模式:  NPU_CORE_0              → ~2 TOPS
    双核模式:  NPU_CORE_0_1            → ~4 TOPS
    三核模式:  NPU_CORE_0_1_2          → ~6 TOPS

2. 硬件准备

组件	型号	说明
核心板	C-3588LQ	RK3588 主芯片，含 6 TOPS NPU
底板	SHIMETAPI-M5-R2A	外设接口扩展
数量	1 套	—

3. 软件准备

3.1 安装 RKNN 工具链

PC 端装 Toolkit2 做模型转换，设备端装 Lite2 做推理：

# 安装 RKNN Toolkit2（PC 端模型转换）
pip3 install rknn-toolkit2

# 安装 RKNN Lite2（设备端推理运行时）
sudo pip3 install --break-system-packages rknn-toolkit-lite2==2.3.2

3.2 安装辅助依赖

pip3 install numpy opencv-python psutil

3.3 验证安装

能打印出版本号就说明安装成功：

from rknnlite.api import RKNNLite

rknn = RKNNLite()
print('RKNN Lite2 版本:', rknn.get_sdk_version())
rknn.release()

4. 操作步骤

4.1 NPU 性能基准测试

先做基准测试，心里有数再谈优化。下面的脚本对单核、双核、三核三种模式各跑 100 次推理，输出平均、最小、最大延迟和 FPS：

from rknnlite.api import RKNNLite
import time
import numpy as np


def benchmark(model_path, input_shape, core_mask, num_runs=100):
    """
    NPU 性能基准测试

    参数:
        model_path  : RKNN 模型路径
        input_shape : 输入张量形状，如 (1, 224, 224, 3)
        core_mask   : NPU 核心掩码
        num_runs    : 推理次数
    返回:
        包含 avg_ms, min_ms, max_ms, fps 的字典
    """
    rknn = RKNNLite()
    ret = rknn.load_rknn(model_path)
    if ret != 0:
        raise RuntimeError(f'加载模型失败: {model_path}')

    ret = rknn.init_runtime(core_mask=core_mask)
    if ret != 0:
        raise RuntimeError(f'初始化运行时失败: core_mask={core_mask}')

    # 构造随机输入
    dummy = np.random.randint(0, 255, input_shape, dtype=np.uint8)

    # 预热：消除首次推理的冷启动开销
    print('  预热中...')
    for _ in range(10):
        rknn.inference(inputs=[dummy])

    # 正式测试
    times = []
    for i in range(num_runs):
        start = time.time()
        outputs = rknn.inference(inputs=[dummy])
        elapsed = time.time() - start
        times.append(elapsed)

    rknn.release()

    avg_ms = np.mean(times) * 1000
    min_ms = np.min(times) * 1000
    max_ms = np.max(times) * 1000
    fps = 1000.0 / avg_ms

    return {
        'avg_ms': avg_ms,
        'min_ms': min_ms,
        'max_ms': max_ms,
        'fps': fps,
    }


def run_benchmark_suite():
    """运行不同核心模式的 Benchmark 对比"""
    model = 'resnet50.rknn'
    shape = (1, 224, 224, 3)

    core_modes = {
        'NPU_CORE_0':     RKNNLite.NPU_CORE_0,
        'NPU_CORE_0_1':   RKNNLite.NPU_CORE_0_1,
        'NPU_CORE_0_1_2': RKNNLite.NPU_CORE_0_1_2,
    }

    print('=' * 60)
    print('RK3588 NPU 性能基准测试')
    print('=' * 60)

    results = {}
    for mode_name, core_mask in core_modes.items():
        print(f'\n测试模式: {mode_name}')
        r = benchmark(model, shape, core_mask, num_runs=100)
        results[mode_name] = r
        print(f'  平均延迟: {r["avg_ms"]:.2f} ms')
        print(f'  最小延迟: {r["min_ms"]:.2f} ms')
        print(f'  最大延迟: {r["max_ms"]:.2f} ms')
        print(f'  吞吐量:   {r["fps"]:.1f} FPS')

    # 汇总对比
    print('\n' + '=' * 60)
    print('汇总对比:')
    print(f'{"模式":<20} {"平均(ms)":<12} {"FPS":<10}')
    print('-' * 42)
    for mode_name, r in results.items():
        print(f'{mode_name:<20} {r["avg_ms"]:<12.2f} {r["fps"]:<10.1f}')

    return results


if __name__ == '__main__':
    run_benchmark_suite()

下面的输出取自实机（mobilenetv2 224×224，100 次平均，RK3588 @1GHz，NPU 驱动 0.9.8 / librknnrt 2.3.2）：

============================================================
RK3588 NPU 性能基准测试 [mobilenetv2 fp16]
============================================================
测试模式: NPU_CORE_0
  平均延迟: 7.03 ms   最小: 3.46 ms   最大: 11.85 ms   吞吐量: 142.2 FPS
测试模式: NPU_CORE_0_1
  平均延迟: 5.33 ms   吞吐量: 187.7 FPS
测试模式: NPU_CORE_0_1_2
  平均延迟: 4.62 ms   吞吐量: 216.3 FPS

============================================================
RK3588 NPU 性能基准测试 [mobilenetv2 INT8]
============================================================
测试模式: NPU_CORE_0
  平均延迟: 3.00 ms   最小: 2.63 ms   最大: 3.94 ms   吞吐量: 333.5 FPS
测试模式: NPU_CORE_0_1
  平均延迟: 2.25 ms   吞吐量: 444.4 FPS
测试模式: NPU_CORE_0_1_2
  平均延迟: 1.91 ms   吞吐量: 522.8 FPS

汇总表输出：

模型/精度	单核	双核	三核	INT8 vs fp16
mobilenetv2 fp16	7.03 ms / 142 FPS	5.33 ms / 188 FPS	4.62 ms / 216 FPS	—
mobilenetv2 INT8	3.00 ms / 334 FPS	2.25 ms / 444 FPS	1.91 ms / 523 FPS	三核下 2.4x

结论：多核收益随核数递减（fp16 单→三核 1.52x，INT8 单→三核 1.57x）；INT8 量化对吞吐提升显著（2.3~2.4x）。

4.2 NPU 频率监控与调整

NPU 频率直接影响性能。查看和调整都走 devfreq（Linux 内核的设备调频接口）：

# ---- 查看 NPU 当前频率（devfreq，无需 root，可用）----
cat /sys/class/devfreq/fdab0000.npu/cur_freq
# 输出: 1000000000  (即 1 GHz)

# ---- 查看可用频率档位----
cat /sys/class/devfreq/fdab0000.npu/available_frequencies
# 输出: 300000000 400000000 500000000 600000000 700000000 800000000 900000000 1000000000

# ---- 查看当前调频策略----
cat /sys/class/devfreq/fdab0000.npu/governor
# 输出: rknpu_ondemand

# ---- 手动锁频（需 root；governor 切 userspace 后写 min/max_freq）----
echo 123456 | sudo -S sh -c 'echo userspace > /sys/class/devfreq/fdab0000.npu/governor; \
    echo 1000000000 > /sys/class/devfreq/fdab0000.npu/max_freq'

# ---- 查看 NPU 实时负载（debugfs，需 root，可用）----
cat /sys/kernel/debug/rknpu/load
# 输出（空闲时）:
#   NPU load:  Core0:  0%, Core1:  0%, Core2:  0%,
# 输出（推理刚结束时）: 三个核各显示实际占用百分比

# ---- 驱动版本（debugfs）----
cat /sys/kernel/debug/rknpu/version
# 输出: RKNPU driver: v0.9.8

# ---- debugfs 下其它可用节点（可用列表）----
ls /sys/kernel/debug/rknpu/
# 输出: load  power  reset  version  volt

# ---- 持续监控频率和负载 ----
watch -n 1 'cat /sys/class/devfreq/fdab0000.npu/cur_freq; \
             sudo cat /sys/kernel/debug/rknpu/load'

注意：老教程的 /sys/kernel/debug/clk/clk_npu/ 在本机不存在（debugfs 时钟树里 npu 相关时钟命名不同），频率操作一律走 devfreq 接口。

4.3 量化精度对比

对比不同量化策略对模型精度和大小的影响：

from rknn.api import RKNN
import os


def compare_quantization(onnx_path, dataset_path, output_dir='quant_results'):
    """
    对比不同量化策略的精度和模型大小

    参数:
        onnx_path    : ONNX 模型路径
        dataset_path : 校准数据集路径（txt 文件，每行一个图片路径）
        output_dir   : 输出目录
    """
    os.makedirs(output_dir, exist_ok=True)

    strategies = [
        {
            'name': 'INT8_symmetric',
            'dtype': 'symmetric_quantized-8',
            'algo': None,
        },
        {
            'name': 'INT8_asymmetric',
            'dtype': 'asymmetric_quantized-8',
            'algo': None,
        },
        {
            'name': 'INT8_MMSE',
            'dtype': 'asymmetric_quantized-8',
            'algo': 'mmse',
        },
        {
            'name': 'FP16',
            'dtype': 'float16',
            'algo': None,
        },
    ]

    # 先获取原始模型大小
    raw_size = os.path.getsize(onnx_path) / (1024 * 1024)
    print(f'原始 ONNX 模型大小: {raw_size:.2f} MB')
    print()

    for s in strategies:
        print(f'--- 策略: {s["name"]} ---')

        rknn = RKNN()
        # 注意: quantized_algorithm 是 config() 的参数，
        # 传给 build() 会报 TypeError: got an unexpected keyword argument
        rknn.config(
            mean_values=[[123.675, 116.28, 103.53]],
            std_values=[[58.395, 57.12, 57.375]],
            target_platform='rk3588',
            quantized_dtype=s['dtype'],
            quantized_algorithm=s['algo'],   # None 则省略此行
        )

        rknn.load_onnx(model=onnx_path)

        if s['dtype'] == 'float16':
            ret = rknn.build(do_quantization=False)   # fp16 不需要校准集
        else:
            ret = rknn.build(do_quantization=True, dataset=dataset_path)

        if ret != 0:
            print(f'  构建失败，跳过')
            rknn.release()
            continue

        rknn_path = os.path.join(output_dir, f'{s["name"]}.rknn')
        rknn.export_rknn(rknn_path)

        rknn_size = os.path.getsize(rknn_path) / (1024 * 1024)
        ratio = rknn_size / raw_size * 100

        print(f'  RKNN 大小:  {rknn_size:.2f} MB')
        print(f'  压缩比:     {ratio:.1f}% (相对 ONNX)')
        print()

        rknn.release()

    print('量化对比完成')


if __name__ == '__main__':
    compare_quantization('resnet50.onnx', 'imagenet_samples.txt')

下面是 mobilenetv2 的结果（32 张校准图，板上转换，原始 ONNX 13.31 MB）：

策略	RKNN 大小	压缩比	转换耗时	3 核推理	备注
FP16	7.31 MB	55.0%	4.8 s	4.62 ms	精度基准
INT8 asymmetric	3.97 MB	29.8%	9.4 s	1.91 ms	速度最优
INT8 MMSE	3.97 MB	29.8%	339.4 s	3.99 ms	逐层搜索耗时 36x，推理反而比 normal 慢（选了精度更优的量化粒度）

要点：

quantized_algorithm='mmse' 必须写在 config() 里（文档老写法放 build() 会直接 TypeError）。
MMSE 转换是 CPU 密集型逐层搜索，板上 339 秒（normal 9.4 秒）；换来的精度收益需用真实数据集评估，吞吐敏感场景用 normal 即可。
INT8 build 时日志会提示 input/output 默认 dtype 从 float32 改为 int8（性能优化），用 C/Python runtime 读输出时注意 want_float=1。

4.4 模型输入优化

输入尺寸对计算量的影响最直接，此外还可以从数据格式和内存拷贝两方面入手：

from rknn.api import RKNN


# ---- 方法 1: 减小输入尺寸 ----
# 原始输入 640x640 → 优化为 320x320
# 理论加速: 4x（计算量与像素数成正比）

rknn = RKNN()
rknn.config(
    mean_values=[[0, 0, 0]],
    std_values=[[255, 255, 255]],
    target_platform='rk3588',
    # 模型输入尺寸由 ONNX 模型本身决定
    # 如需动态尺寸，使用 quant_img_size 参数
)


# ---- 方法 2: 使用 NHWC 数据格式 (RK3588 推荐) ----
rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3588',
    inputs_nhwc=[True],  # 强制使用 NHWC 格式，减少格式转换开销
)


# ---- 方法 3: 避免不必要的数据拷贝 ----
# 使用预分配的输入缓冲区
import numpy as np

# 预分配缓冲区，避免重复分配内存
input_buffer = np.zeros((1, 640, 640, 3), dtype=np.uint8)

# 复用缓冲区进行多次推理
for frame in video_stream:
    # 直接写入预分配的缓冲区
    np.copyto(input_buffer[0], frame)
    outputs = rknn.inference(inputs=[input_buffer])
    # 处理 outputs ...

4.5 内存占用优化

想知道模型到底吃了多少内存，可以用 psutil 量一量。脚本会分别在加载模型、初始化运行时和推理后测量进程的 RSS（进程实际占用的物理内存），算出各阶段的增量：

import psutil
import os
from rknnlite.api import RKNNLite


def measure_memory_mb():
    """测量当前进程的 RSS 内存占用 (MB)"""
    process = psutil.Process(os.getpid())
    return process.memory_info().rss / (1024 * 1024)


def profile_model_memory(model_path, input_shape):
    """
    测量模型加载和推理的内存占用

    参数:
        model_path  : RKNN 模型路径
        input_shape : 输入张量形状
    """
    import numpy as np

    # 测量基准内存
    mem_base = measure_memory_mb()
    print(f'基准内存:       {mem_base:.1f} MB')

    # 加载模型
    rknn = RKNNLite()
    rknn.load_rknn(model_path)
    mem_after_load = measure_memory_mb()
    print(f'加载模型后:     {mem_after_load:.1f} MB')
    print(f'  模型内存开销: {mem_after_load - mem_base:.1f} MB')

    # 初始化运行时
    rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1_2)
    mem_after_init = measure_memory_mb()
    print(f'运行时初始化后: {mem_after_init:.1f} MB')
    print(f'  运行时开销:   {mem_after_init - mem_after_load:.1f} MB')

    # 推理
    dummy = np.random.randint(0, 255, input_shape, dtype=np.uint8)
    for _ in range(10):
        rknn.inference(inputs=[dummy])
    mem_after_infer = measure_memory_mb()
    print(f'推理后:         {mem_after_infer:.1f} MB')
    print(f'  推理开销:     {mem_after_infer - mem_after_init:.1f} MB')

    # 总计
    print(f'\n总内存增量:     {mem_after_infer - mem_base:.1f} MB')

    rknn.release()
    return mem_after_infer - mem_base


def optimize_memory_usage():
    """内存优化建议汇总"""
    tips = [
        '1. 使用轻量级模型: MobileNetV2 / EfficientNet-Lite 代替 ResNet-152',
        '2. INT8 量化: 模型体积减小约 4x，内存占用同步降低',
        '3. 复用输入/输出缓冲区: 避免每帧分配新内存',
        '4. 避免同时加载多个模型: 除非使用不同 NPU 核心',
        '5. 及时释放不再使用的 RKNN 实例',
        '6. 使用 DMA-BUF 零拷贝: 减少 CPU-NPU 数据搬运',
    ]
    for tip in tips:
        print(tip)


if __name__ == '__main__':
    profile_model_memory('resnet50.rknn', (1, 224, 224, 3))
    print()
    optimize_memory_usage()

4.6 多模型并发测试

把两个模型分别绑到不同的 NPU 核心并发跑，看看实际总吞吐能达到多少：

from rknnlite.api import RKNNLite
import numpy as np
import time
import threading


def concurrent_inference(model_a, model_b, shape, duration_sec=10):
    """
    多模型并发推理测试

    将两个模型分别绑定到不同的 NPU 核心，
    测量并发场景下的实际吞吐量。
    """
    results_a = {'fps': 0, 'count': 0}
    results_b = {'fps': 0, 'count': 0}

    def run_model(model_path, core_mask, result_dict, stop_event):
        rknn = RKNNLite()
        rknn.load_rknn(model_path)
        rknn.init_runtime(core_mask=core_mask)

        dummy = np.random.randint(0, 255, shape, dtype=np.uint8)

        # 预热
        for _ in range(5):
            rknn.inference(inputs=[dummy])

        count = 0
        start = time.time()
        while not stop_event.is_set():
            rknn.inference(inputs=[dummy])
            count += 1
        elapsed = time.time() - start

        result_dict['fps'] = count / elapsed
        result_dict['count'] = count
        rknn.release()

    stop_event = threading.Event()

    # 模型 A 绑定 CORE_0，模型 B 绑定 CORE_1
    t1 = threading.Thread(
        target=run_model,
        args=(model_a, RKNNLite.NPU_CORE_0, results_a, stop_event),
    )
    t2 = threading.Thread(
        target=run_model,
        args=(model_b, RKNNLite.NPU_CORE_1, results_b, stop_event),
    )

    print(f'并发测试开始 ({duration_sec}s)...')
    print(f'  模型 A -> NPU_CORE_0')
    print(f'  模型 B -> NPU_CORE_1')

    t1.start()
    t2.start()
    time.sleep(duration_sec)
    stop_event.set()

    t1.join()
    t2.join()

    print(f'\n并发测试结果:')
    print(f'  模型 A: {results_a["fps"]:.1f} FPS ({results_a["count"]} 次推理)')
    print(f'  模型 B: {results_b["fps"]:.1f} FPS ({results_b["count"]} 次推理)')
    print(f'  总吞吐: {results_a["fps"] + results_b["fps"]:.1f} FPS')


if __name__ == '__main__':
    concurrent_inference('model_a.rknn', 'model_b.rknn', (1, 224, 224, 3))

5. 代码详解

5.1 NPU 核心调度原理

RK3588 的 3 个 NPU 核心通过 core_mask 参数进行调度:

  RKNNLite.NPU_CORE_0      → 仅使用核心 0 (~2 TOPS)
  RKNNLite.NPU_CORE_1      → 仅使用核心 1 (~2 TOPS)
  RKNNLite.NPU_CORE_2      → 仅使用核心 2 (~2 TOPS)
  RKNNLite.NPU_CORE_0_1    → 使用核心 0 + 1 (~4 TOPS)
  RKNNLite.NPU_CORE_0_1_2  → 使用全部 3 核 (~6 TOPS)

调度策略选择:
  - 单模型高吞吐: 使用 NPU_CORE_0_1_2（三核全开）
  - 单模型低延迟: 使用 NPU_CORE_0（避免多核调度开销）
  - 多模型并发:   不同模型绑定不同核心，避免竞争

5.2 性能瓶颈分析

一次 NPU 推理的完整流水线，以及各环节常见的瓶颈和对应手段：

典型 NPU 推理流水线:
  [CPU 预处理] → [数据拷贝] → [NPU 推理] → [数据拷贝] → [CPU 后处理]

常见瓶颈及优化手段:
  ┌──────────────────┬─────────────────────────────────┐
  │ 瓶颈             │ 优化手段                         │
  ├──────────────────┼─────────────────────────────────┤
  │ CPU 预处理耗时   │ 使用 RGA 硬件加速缩放/裁剪       │
  │ 数据拷贝耗时     │ 使用 DMA-BUF 零拷贝              │
  │ NPU 频率低       │ 提升 NPU 时钟频率                 │
  │ 模型过大         │ INT8 量化 / 剪枝 / 知识蒸馏       │
  │ 内存带宽不足     │ 使用 NHWC 格式，减少格式转换       │
  │ 输出后处理慢     │ 将 NMS/Softmax 卸载到 NPU 执行    │
  └──────────────────┴─────────────────────────────────┘

5.3 Benchmark 结果解读

解读 Benchmark 输出的注意事项:

  1. 预热 (Warm-up)
     首次推理包含模型加载、缓存预热等开销，
     不应计入性能统计。Benchmark 中前 10 次推理为预热。

  2. 平均延迟 vs FPS
     FPS = 1000 / avg_ms
     当处理单帧时关注延迟 (ms)；当流水线处理时关注 FPS。

  3. 最小/最大延迟
     max_ms - min_ms 过大说明存在抖动 (jitter)，
     可能由系统调度、温控降频等原因导致。

  4. 核心模式对比
     三核模式理论上是单核的 3x 性能，
     但由于内存带宽和调度开销，实际加速比通常在 2.2x~2.8x。

5.4 RK3588 NPU 性能参考表

模型	输入尺寸	NPU_CORE_0	NPU_CORE_0_1	NPU_CORE_0_1_2
MobileNetV2	224x224	~2000 FPS	~3500 FPS	~5000 FPS
ResNet-50	224x224	~500 FPS	~1000 FPS	~2000 FPS
YOLOv5s	640x640	~50 FPS	~100 FPS	~150 FPS
YOLOv8n	640x640	~60 FPS	~110 FPS	~160 FPS
SCRFD	640x640	~80 FPS	~150 FPS	~220 FPS

注: 以上数据为参考值，实际性能受模型版本、量化策略、系统配置等因素影响。

6. 常见问题

6.1 NPU 利用率低

现象：CPU 使用率高，但 NPU 使用率很低。

可能原因及解决方案：

# 1. 检查 NPU 驱动是否正常加载
ls /sys/module/ | grep rknpu   # 不要用 lsmod（本机会挂死；驱动是内建的）
# 应看到 rknpu 模块

# 2. 检查 NPU 设备节点
ls -la /dev/dri/
# 应看到 renderD128 等设备

# 3. 查看 NPU 实时负载
cat /sys/kernel/debug/rknpu/load

# 4. 确认推理代码使用的是 rknn-toolkit-lite2（而非 CPU fallback）
# 检查 init_runtime 返回值是否为 0

常见原因：

使用了 CPU 推理而非 NPU 推理（检查是否调用了 rknn-toolkit-lite2）
模型中包含 NPU 不支持的算子，导致部分层回退到 CPU
数据预处理在 CPU 上完成且耗时过长，掩盖了 NPU 的实际处理时间

6.2 推理结果异常

现象：NPU 推理结果与 CPU/PC 端推理结果不一致，输出偏差较大。

解决方案：

# 1. 对比 FP16 与 INT8 精度差异
# 如果 INT8 结果偏差大，先用 FP16 验证模型本身是否正确
rknn.config(
    target_platform='rk3588',
    quantized_dtype='float16',  # 先用 FP16 排除模型问题
)

# 2. 使用 MMSE 量化算法提升 INT8 精度
rknn.build(
    do_quantization=True,
    dataset='calibration_list.txt',
    quantized_algorithm='mmse',
)

# 3. 增加校准数据量（建议 100~500 张代表性图片）
# 校准数据应覆盖实际应用场景中的典型输入分布

# 4. 检查预处理是否与训练时一致
# mean_values / std_values 必须与模型训练时的归一化参数完全匹配

6.3 多模型并发性能差

现象：多个模型同时运行时，总吞吐量远低于各模型单独运行之和。

解决方案：

from rknnlite.api import RKNNLite

# 方案 1: 为每个模型分配独立的 NPU 核心
rknn_a = RKNNLite()
rknn_a.load_rknn('model_a.rknn')
rknn_a.init_runtime(core_mask=RKNNLite.NPU_CORE_0)

rknn_b = RKNNLite()
rknn_b.load_rknn('model_b.rknn')
rknn_b.init_runtime(core_mask=RKNNLite.NPU_CORE_1)

# 方案 2: 如果有 3 个模型，使用三核分别绑定
rknn_c = RKNNLite()
rknn_c.load_rknn('model_c.rknn')
rknn_c.init_runtime(core_mask=RKNNLite.NPU_CORE_2)

# 方案 3: 使用异步推理减少等待
# 注意: 多个模型共享同一核心时，调度开销会显著增加

6.4 模型转换失败

现象：rknn.build() 返回错误码，模型转换失败。

排查思路是从最低优化级别开始逐步排查：

from rknn.api import RKNN

rknn = RKNN()

# 1. 降低优化级别排查
rknn.config(
    target_platform='rk3588',
    optimization_level=0,  # 最低优化级别，兼容性最好
)

# 2. 检查输入数据类型
# 确保 ONNX 模型的输入为 float32 或 uint8

# 3. 检查算子兼容性
# 查看 RKNN Toolkit2 支持的算子列表
# 对不支持的算子考虑替换或自定义实现

# 4. 逐步提高优化级别
for level in [0, 1, 2, 3]:
    rknn.config(target_platform='rk3588', optimization_level=level)
    rknn.load_onnx(model='model.onnx')
    ret = rknn.build(do_quantization=True, dataset='dataset.txt')
    if ret == 0:
        print(f'优化级别 {level} 构建成功')
        break
    else:
        print(f'优化级别 {level} 构建失败，尝试下一级')
    rknn.release()

6.5 NPU 频率无法提升

现象：NPU 频率锁定在较低频率，无法达到最大性能。

解决方案：

# 1. 检查当前 CPU/系统调频策略
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

# 2. 设置 performance 模式（保持最高频率）
echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
echo performance > /sys/devices/system/cpu/cpu4/cpufreq/scaling_governor
echo performance > /sys/devices/system/cpu/cpu6/cpufreq/scaling_governor

# 3. 检查温度是否触发降频保护
cat /sys/class/thermal/thermal_zone*/temp
# 正常范围: < 80°C
# 超过 85°C 可能触发温控降频

# 4. 检查散热方案
# 确保核心板散热片/风扇正常工作
# 高负载测试时注意散热

6.6 DMA-BUF 零拷贝未生效

现象：数据拷贝耗时仍然较高，零拷贝未生效。

解决方案：

# 1. 检查 DMA-BUF 是否可用
ls /dev/dma_heap/
# 应看到 system 等节点

# 2. 检查 IOMMU 配置
cat /proc/device-tree/soc/npu/*/iommu-map

# 3. 确认 librga 版本
# RK3588 需要匹配版本的 RGA 库
dpkg -l | grep librga

7. 相关文档

文档	说明
01_NPU架构与性能概览	NPU 硬件架构介绍
02_RKNN Toolkit2安装与使用	RKNN 开发环境搭建
03_模型转换与量化	量化策略与精度优化
04_RGA图像加速	硬件图像预处理加速
06_NPU多模型部署	多模型并发部署方案
07_NPU模型剪枝与蒸馏	模型轻量化方法