# RK-NPU开发学习

**Repository Path**: chen-hang911/rk-npu-development-learning

## Basic Information

- **Project Name**: RK-NPU开发学习
- **Description**: 学习国产AI芯片，为国产AI芯片做贡献，祝国产芯片越来越好
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RK3588 RKNPU2 端侧 AI 开发学习

基于瑞芯微 **RK3588** 平台的 NPU 端侧 AI 推理学习仓库。覆盖从 PC 端模型量化编译，到 Linux 板端 C/C++ 高性能部署、Python 快速验证，以及实时视觉检测等完整链路。

[English README](./README.en.md)

---

## 你将学到什么

- 使用 **RKNN-Toolkit2** 在 x86 PC 上将 PyTorch / ONNX 模型转换为 `.rknn`
- 在 RK3588 开发板上用 **RKNN-Toolkit-lite2** 快速验证、用 **RKNPU2 SDK** 正式部署
- 理解量化、精度分析、混合量化、性能评估与零拷贝优化
- 完成 YOLO 实时检测、目标追踪、车牌识别等视觉业务实例

---

## 硬件清单

| 设备 | 用途 |
|------|------|
| RK3588 开发板 | NPU 推理、板端部署 |
| V4L2 兼容 USB 摄像头 | 视觉实例采集 |
| x86 架构上位机 | 模型转换、Toolkit2 环境 |

---

## 版本约束

以下三者 **大版本号必须保持一致**：

```text
RKNN-Toolkit2  ===  RKNPU2 Runtime  ===  RKNN-Toolkit-lite2
```

版本不匹配会导致模型加载失败、算子异常或推理崩溃。建议从官方 GitHub 同一 Release 页面下载成套版本。

- [RKNN-Toolkit2](https://github.com/rockchip-linux/rknn-toolkit2)
- [RKNPU2 SDK](https://github.com/rockchip-linux/rknpu2)

---

## 仓库结构

```text
rk-npu-development-learning/
├── README.md
├── 01_export_rknn/                    # Phase 04 示例：ResNet18 -> .rknn
│   ├── export_rknn.py
│   ├── resnet18.pt
│   ├── dataset.txt
│   └── resnet18.rknn
├── 02_Inference/                      # Phase 05 示例：连板推理 TOP5
│   ├── Inference_rknn.py
│   ├── Inference_pytorch.py
│   ├── resnet18.pt
│   └── space_shuttle_224.jpg
├── 03_accuracy_analysis/              # Phase 06 示例：量化逐层精度分析
│   ├── accuracuy_analysis.py
│   ├── resnet18.pt
│   ├── dataset.txt
│   └── space_shuttle_224.jpg
├── 04_hybrid_quantization/            # Phase 07 示例：混合量化
│   ├── step1.py
│   ├── step2.py
│   ├── resnet18.pt
│   ├── dataset.txt
│   ├── resnet18.quantization.cfg
│   └── space_shuttle_224.jpg
├── 05_eval/                           # Phase 08 示例：性能与内存评估
│   ├── eval.py
│   ├── print.log
│   └── resnet18.rknn
├── Learning-path/                     # 分阶段学习路线
│   ├── phase-00-rk3588-npu-roadmap.md
│   ├── phase-01-rknpu-foundation.md
│   ├── phase-02-rknpu-inference-framework.md
│   ├── phase-03-rknn-toolkit2-setup.md
│   ├── phase-04-rknn-model-build.md
│   ├── phase-05-rknn-inference-test.md
│   ├── phase-06-rknn-quantization-accuracy.md
│   ├── phase-07-rknn-hybrid-quantization.md
│   └── phase-08-rknn-performance-memory-eval.md
└── Learning-README/                   # 章节笔记与概念梳理
    ├── 推理软件框架.md
    ├── RKNN 端侧 AI 全栈概念梳理笔记.md
    ├── RKNN Toolkit2 环境搭建笔记.md
    ├── RKNN 模型构建笔记.md
    ├── RKNN 推理测试笔记.md
    ├── RKNN 量化精度分析笔记.md
    ├── RKNN 性能与内存评估笔记.md
    └── AI模型量化与硬件推理误差分析.md
```

---

## 学习路线

建议按 **Phase 顺序** 推进，每完成一阶段再进入下一阶段。

| 阶段 | 文档 | 内容 | 状态 |
|------|------|------|------|
| Phase 00 | [总览路线图](./Learning-path/phase-00-rk3588-npu-roadmap.md) | 全链路概览、工具链、量化、优化手段 | ✅ |
| Phase 01 | [初识 RKNPU](./Learning-path/phase-01-rknpu-foundation.md) | NPU 硬件、CPU/GPU/NPU 分工、概念自检 | ✅ |
| Phase 02 | [推理软件框架与工具链](./Learning-path/phase-02-rknpu-inference-framework.md) | 三层架构、`.rknn` 格式、三工具包解剖 | ✅ |
| Phase 03 | [Toolkit2 环境搭建](./Learning-path/phase-03-rknn-toolkit2-setup.md) | PC 端 Miniconda / whl / PyCharm | ✅ |
| Phase 04 | [RKNN 模型构建](./Learning-path/phase-04-rknn-model-build.md) | ResNet18、`load_pytorch`、导出 `.rknn` | ✅ |
| Phase 05 | [RKNN 推理测试](./Learning-path/phase-05-rknn-inference-test.md) | 连板 `inference`、TOP5 分类、前后处理 | ✅ |
| Phase 06 | [RKNN 量化精度分析](./Learning-path/phase-06-rknn-quantization-accuracy.md) | `accuracy_analysis`、`golden/simulator`、逐层误差 | ✅ |
| Phase 07 | [RKNN 混合量化](./Learning-path/phase-07-rknn-hybrid-quantization.md) | `hybrid_quantization_step1/2`、`float16/INT8` 混合 | ✅ |
| Phase 08 | [RKNN 性能与内存评估](./Learning-path/phase-08-rknn-performance-memory-eval.md) | `perf_debug`、`eval_memory`、`print.log` 解读 | ✅ |
| Phase 09+ | 板端部署、RKNPU2 SDK、视觉实例 | 见 phase-00 课程目录 | 待编写 |

**新手起步顺序：** [Phase 00](./Learning-path/phase-00-rk3588-npu-roadmap.md) -> [Phase 01](./Learning-path/phase-01-rknpu-foundation.md) -> [Phase 02](./Learning-path/phase-02-rknpu-inference-framework.md) -> [Phase 03](./Learning-path/phase-03-rknn-toolkit2-setup.md) -> [Phase 04](./Learning-path/phase-04-rknn-model-build.md) -> [Phase 05](./Learning-path/phase-05-rknn-inference-test.md) -> [Phase 06](./Learning-path/phase-06-rknn-quantization-accuracy.md) -> [Phase 07](./Learning-path/phase-07-rknn-hybrid-quantization.md) -> [Phase 08](./Learning-path/phase-08-rknn-performance-memory-eval.md)

---

## 完整开发流程

```text
阶段一：x86 PC
PyTorch/ONNX -> RKNN-Toolkit2 量化编译 -> .rknn
           -> PC 仿真 / 连板评测（精度、耗时、内存）

阶段二：RK3588 板端
方案 A：RKNN-Toolkit-lite2（Python 快速验证）
方案 B：RKNPU2 SDK（C/C++ 正式部署）

阶段三：视觉业务流水线
V4L2 采集 -> RGA 预处理 -> NPU 推理 -> 后处理 -> 渲染输出
```

固定开发顺序：**Toolkit2 转模型 -> lite2 板端验证 -> RKNPU2 SDK 正式部署**

---

## 核心组件

| 组件 | 运行位置 | 职责 |
|------|----------|------|
| RKNN-Toolkit2 | x86 PC | 模型转换、量化、仿真与连板评测 |
| RKNPU2 Runtime | RK3588 板端 | 驱动调度 NPU，提供 C API |
| RKNN-Toolkit-lite2 | RK3588 板端 | Python 轻量推理，快速调试验证 |

### 推理软件三层架构

```text
应用层 -> AI 程序 + RKNN API + 运行时库
驱动层 -> 初始化 / 数据传输 / 任务调度
硬件层 -> RKNPU 芯片（RK3588 内置 RKNPU2，3 核 NPU）
```

---

## 对应课程目录

本仓库学习路径对齐以下课程章节：

```text
00_前言
01_初识RKNPU
02_RKNPU软件推理框架
03_RKNN Toolkit2环境搭建
04_RKNN模型构建
05_RKNN模型评估-推理测试
06_RKNN模型评估-量化精度分析
07_RKNN模型评估-性能和内存评估
08_RKNN Toolkit lite2部署RKNN模型
09_RKNPU2通用API讲解
10_RKNPU2零拷贝API讲解
11_实例：yolov5摄像头实时目标识别
12_实例：使用sort实现目标追踪
13_实例：车牌识别
```

---

## 常用命令

### PC 端模型转换（Phase 04）

```bash
conda activate rknn
cd 01_export_rknn
python export_rknn.py
```

### PC 连板推理（Phase 05）

```bash
conda activate rknn
adb devices
cd 02_Inference
cp ../01_export_rknn/resnet18.rknn ./
python Inference_rknn.py
```

### PC 端量化精度分析（Phase 06）

```bash
conda activate rknn
cd 03_accuracy_analysis
python accuracuy_analysis.py
```

### PC 端混合量化（Phase 07）

```bash
conda activate rknn
cd 04_hybrid_quantization
python step1.py
python step2.py
```

### PC 连板性能 / 内存评估（Phase 08）

```bash
conda activate rknn
adb devices
cd 05_eval
python eval.py
```

---

## 补充笔记

| 笔记 | 说明 |
|------|------|
| [推理软件框架](./Learning-README/推理软件框架.md) | 三层架构、工具包对比、学习路径 |
| [RKNN 端侧 AI 全栈概念梳理](./Learning-README/RKNN%20端侧%20AI%20全栈概念梳理笔记.md) | 名词体系、模型格式、量化原理、硬件功耗对比 |
| [RKNN Toolkit2 环境搭建](./Learning-README/RKNN%20Toolkit2%20环境搭建笔记.md) | Miniconda、pip 安装顺序、PyCharm 配置 |
| [RKNN 模型构建](./Learning-README/RKNN%20模型构建笔记.md) | Toolkit2 API、`config/load/build/export`、量化校准 |
| [RKNN 推理测试](./Learning-README/RKNN%20推理测试笔记.md) | `load_rknn/init_runtime/inference`、预处理、连板原理 |
| [RKNN 量化精度分析](./Learning-README/RKNN%20量化精度分析笔记.md) | `accuracy_analysis`、`golden/simulator`、逐层调优 |
| [RKNN 性能与内存评估](./Learning-README/RKNN%20性能与内存评估笔记.md) | `perf_debug`、`eval_memory`、热点定位、日志解读 |
| [AI 量化误差深度分析](./Learning-README/AI模型量化与硬件推理误差分析.md) | `quant_error/runtime_error` 深度解读 |

---

## 重要提醒

- 本仓库针对 **RKNPU2**（RK3588 / RK3568 / RK3576），不要混用 RKNPU1 旧教程
- Toolkit2 只能装在 **x86 PC**，不能在开发板上安装运行
- 实时视觉项目最终通常需要 **C SDK + 零拷贝 API**

---

## 参考链接

- [Rockchip GitHub](https://github.com/rockchip-linux)
- [RKNN-Toolkit2](https://github.com/rockchip-linux/rknn-toolkit2)
- [RKNPU2 SDK](https://github.com/rockchip-linux/rknpu2)