【AI大模型】RKNN Model Zoo 模型从入门到实战

目录一、ModelZoo 核心基础认知必学1.1 什么是 RKNN Model Zoo1.2 ModelZoo 核心特点与优势1.3 学习前提衔接RKNN基础二、环境准备ModelZoo 专属配置2.1 下载 ModelZoo 官方仓库2.2 补充 ModelZoo 专属依赖2.3 版本适配检查关键步骤2.4 数据集准备可选用于二次优化三、ModelZoo 仓库结构深度解析快速找模型、找代码3.1 根目录核心文件夹3.2 模型目录models详细解析3.3 示例代码目录examples详细解析四、ModelZoo 核心操作实操重点必练4.1 第一步查找并下载所需模型4.2 第二步使用预转换模型PC端仿真推理4.3 第三步使用预转换模型板端部署4.3.1 Python部署简单快捷适合调试4.3.2 C/C部署工业级高效稳定4.4 第四步模型二次优化进阶按需学习4.4.1 重新量化模型提升推理速度、降低功耗4.4.2 调整模型输入尺寸适配特定场景4.4.3 模型加密防止模型泄露五、实操案例3个典型场景新手必练案例1图像分类ResNet50—— 识别图片中的物体类别场景说明实操步骤案例2目标检测YOLO V10—— 检测图片中的多个目标场景说明实操步骤案例3语义分割U-Net—— 分割图片中的目标区域场景说明实操步骤六、进阶技巧与常见问题避坑指南6.1 进阶技巧提升开发效率6.2 常见问题与解决方案新手必看七、学习资源推荐进阶提升八、学习路线总结新手必看一、ModelZoo 核心基础认知必学1.1 什么是 RKNN Model ZooRKNN Model Zoo简称 ModelZoo是瑞芯微Rockchip官方维护的预适配模型仓库专为瑞芯微系列芯片RK3588、RK3576、RK3566等的NPU打造核心作用是为开发者提供“开箱即用”的AI模型及配套资源无需从零进行模型训练和转换大幅降低瑞芯微NPU平台的AI部署门槛。简单来说ModelZoo 就像一个“模型超市”里面包含了计算机视觉、自然语言处理、语音识别等多个领域的主流模型所有模型均已提前转换为瑞芯微NPU支持的.rknn格式并经过量化优化和性能调试开发者可直接下载使用快速完成AI应用的原型验证和产品落地。ModelZoo 与 RKNN 工具链RKNN-Toolkit2、RKNN Runtime深度协同是瑞芯微边缘AI生态的重要组成部分其核心价值在于“简化部署流程、提升开发效率、保证模型兼容性”尤其适合新手快速上手瑞芯微NPU的模型部署开发。1.2 ModelZoo 核心特点与优势模型丰富且主流覆盖分类、目标检测、语义分割、姿态估计、OCR、LLM大语言模型等多个AI场景包含ResNet、YOLO、U-Net、PPLCNetV2、Qwen等经典及最新模型满足不同行业的应用需求。预适配全优化所有模型均已适配瑞芯微主流芯片的NPU提前完成INT8量化、算子适配、性能调优可直接加载到开发板运行无需开发者自行处理模型转换和优化的复杂流程部分模型还支持零拷贝API进一步提升推理效率。配套资源完整每个模型均提供完整的配套资源包括预转换的.rknn模型文件、Python/C推理示例代码、模型说明文档、预处理/后处理脚本部分模型还提供性能基准数据推理延迟、精度便于开发者选型和调试。持续更新维护瑞芯微官方会持续更新模型库新增主流模型如YOLO V10、YOLO V11、InternVL3等优化现有模型的性能和兼容性同时同步适配RKNN工具链的新版本确保模型的可用性。支持二次开发开发者可基于ModelZoo中的预转换模型根据自身需求进行二次优化如重新量化、调整输入尺寸、模型剪枝也可参考示例代码将模型集成到自己的应用程序中灵活适配实际场景。1.3 学习前提衔接RKNN基础学习ModelZoo的核心是“会用预转换模型、能基于示例调试、可二次优化”需具备以下基础若未掌握建议先学习RKNN基础教程环境基础已完成PC端Ubuntu 20.04RKNN-Toolkit2和板端瑞芯微开发板RKNN Runtime环境搭建能正常使用RKNN API进行模型加载和推理。操作基础熟悉Ubuntu终端命令掌握Python基础语法了解AI模型的基本概念输入尺寸、预处理、推理流程。硬件准备推荐瑞芯微开发板如RK3576、RK3588便于实操模型部署和性能验证无硬件可先用PC端仿真推理功能调试。注意ModelZoo 模型的使用依赖 RKNN-Toolkit2 和 RKNN Runtime需确保两者版本匹配如RKNN-Toolkit2 1.6.0版本对应ModelZoo最新稳定分支避免出现兼容性问题。二、环境准备ModelZoo 专属配置ModelZoo 的环境准备需基于已搭建好的RKNN基础环境重点完成“仓库下载、依赖补充、版本适配”步骤如下全程在Ubuntu 20.04 PC端操作2.1 下载 ModelZoo 官方仓库ModelZoo 官方仓库托管在GitHub包含所有模型、示例代码和说明文档下载步骤如下# 1. 进入之前创建的RKNN项目目录若未创建先执行mkdir Projects cd Projects cd ~/Projects # 2. 克隆ModelZoo仓库--depth 1 表示只下载最新版本节省空间 git clone https://github.com/airockchip/rknn_model_zoo.git --depth 1 # 3. 进入仓库目录查看结构 cd rknn_model_zoo ls下载完成后仓库根目录会出现models、examples、datasets、tools等文件夹后续将详细解析各文件夹的作用。注意若克隆失败网络问题可通过瑞芯微开发者官网下载仓库压缩包解压后放入Projects目录效果一致同时建议定期执行git pull命令更新仓库至最新版本获取新增模型和优化内容。2.2 补充 ModelZoo 专属依赖ModelZoo 的示例代码依赖部分额外的Python库如torch、onnx、opencv-python等若之前安装RKNN-Toolkit2时未安装需补充安装# 激活之前创建的RKNN-Toolkit2 Conda环境 conda activate RKNN-Toolkit2 # 安装专属依赖 pip install torch1.12.0 onnx1.13.0 opencv-python4.6.0 numpy1.24.0 # 安装模型转换和评估工具 pip install onnx-simplifier # 用于简化ONNX模型二次开发时使用 pip install matplotlib # 用于推理结果可视化注意部分模型如LLM模型可能需要额外依赖可在对应模型的说明文档中查看按需安装避免冗余。2.3 版本适配检查关键步骤ModelZoo 仓库的模型与 RKNN-Toolkit2、RKNN Runtime 的版本强相关版本不匹配会导致模型加载失败、推理报错检查步骤如下查看 RKNN-Toolkit2 版本python -c from rknn.api import RKNN; print(RKNN().version)查看 ModelZoo 支持的版本打开ModelZoo仓库根目录的README.md文件查看“Compatible RKNN-Toolkit2 Version”确保两者版本一致如RKNN-Toolkit2 1.6.0 对应 ModelZoo 20241008版本。查看板端 RKNN Runtime 版本adb shellstrings /usr/lib/librknnrt.so | grep -i librknnrt version若版本不匹配需升级/降级RKNN-Toolkit2或切换ModelZoo的分支如git checkout 对应版本分支确保三者版本协同。2.4 数据集准备可选用于二次优化若后续需要对ModelZoo中的模型进行重新量化、精度分析需准备校准数据集与模型输入尺寸、预处理方式一致。ModelZoo 提供了部分数据集的下载脚本可通过以下命令下载# 进入ModelZoo的datasets目录 cd ~/Projects/rknn_model_zoo/datasets # 查看可用数据集脚本如coco、imagenet等 ls # 下载示例数据集以coco子集为例 bash download_coco_subset.sh注意数据集体积较大建议根据需要下载如分类模型用imagenet子集目标检测模型用coco子集无需全部下载节省存储空间。三、ModelZoo 仓库结构深度解析快速找模型、找代码ModelZoo 仓库结构清晰按“模型类型功能模块”划分掌握结构可快速找到所需模型和示例代码核心目录解析如下基于最新版本仓库3.1 根目录核心文件夹文件夹名称核心作用关键内容models核心模型目录按场景分类存放所有预转换模型包含classification分类、detection检测、segmentation分割、llm大语言模型等子目录每个子目录下是具体模型examples推理示例代码目录与models目录一一对应每个模型对应Python/C示例代码包含模型加载、预处理、推理、结果解析全流程datasets数据集目录存放校准数据、测试数据及下载脚本包含coco、imagenet等常用数据集的子集和下载脚本用于模型量化、精度分析tools辅助工具目录用于模型转换、量化、性能评估包含模型转换脚本、量化工具、性能分析工具可用于模型二次开发docs文档目录存放ModelZoo使用说明、模型详情每个模型的说明文档模型介绍、性能参数、使用方法新手必看3.2 模型目录models详细解析models目录是ModelZoo的核心按AI场景划分子目录每个子目录下的具体模型文件夹包含以下核心文件以classification/resnet50为例resnet50.onnx原始ONNX格式模型用于二次转换、重新量化。resnet50.rknn预转换好的.rknn格式模型可直接加载推理部分模型会提供INT8量化版如resnet50_int8.rknn和FP32版。model.yml模型配置文件包含模型输入尺寸、预处理参数均值、标准差、量化配置、支持的芯片型号等关键信息。README.md模型说明文档包含模型介绍、性能基准如RK3588上的推理延迟、使用方法、注意事项。注意不同类型的模型如YOLO检测模型会额外包含后处理配置文件如postprocess_config.yml用于解析推理输出结果如目标坐标、置信度。3.3 示例代码目录examples详细解析examples目录与models目录结构完全对应每个模型的示例代码分为Python版和C/C版适合不同开发需求Python版路径为examples/[模型类型]/[模型名称]/python代码简洁便于快速调试和验证适合新手入门核心包含模型加载、输入预处理、推理、结果可视化等步骤。C/C版路径为examples/[模型类型]/[模型名称]/cpp代码更高效、稳定适合工业级部署可直接编译为板端可执行文件核心包含RKNN Runtime API的调用、内存管理、推理流程封装。注意示例代码中已包含完整的预处理和后处理逻辑开发者可直接运行也可根据自身需求修改如调整输入图片路径、推理置信度阈值。四、ModelZoo 核心操作实操重点必练ModelZoo 的核心操作围绕“下载模型→使用预转换模型PC端仿真板端部署→二次优化模型”展开结合具体示例一步步实操重点掌握预转换模型的使用和调试方法。4.1 第一步查找并下载所需模型根据自身应用场景在ModelZoo中查找对应的模型步骤如下确定场景明确需求是分类、检测、分割还是LLM例如“目标检测”对应models/detection目录。选择模型进入对应场景目录查看模型列表如YOLO V8、YOLO V10、Faster R-CNN等参考每个模型的README.md根据性能需求延迟、精度和芯片型号选择合适的模型。确认模型文件进入模型文件夹确认存在.rknn格式模型预转换完成、model.yml配置文件和示例代码。可选下载模型若仓库中未包含预转换的.rknn模型部分模型需手动转换可运行tools目录下的转换脚本生成.rknn模型示例命令如下以YOLO V10为例# 进入ModelZoo根目录cd ~/Projects/rknn_model_zoo# 运行YOLO V10转换脚本需提前准备ONNX模型python tools/convert.py models/detection/yolov10/yolov10s.onnx rk3576 i8# 说明rk3576是目标芯片型号i8表示INT8量化fp表示FP32不量化注意转换模型时需准备校准数据默认路径为datasets/COCO/coco_subset_20.txt可修改为自己的校准数据数量建议至少20张确保量化精度。4.2 第二步使用预转换模型PC端仿真推理PC端仿真推理无需开发板可快速验证模型的正确性和推理效果以“ResNet50分类模型”为例步骤如下进入示例代码目录cd ~/Projects/rknn_model_zoo/examples/classification/resnet50/python查看示例代码resnet50_demo.py核心逻辑包括初始化RKNN对象、加载.rknn模型、预处理输入图片、执行推理、解析输出结果代码中已包含详细注释可重点查看模型加载和推理部分。修改输入图片路径打开resnet50_demo.py找到“img_path”变量修改为自己的测试图片路径如./test.jpg确保图片格式为JPG/PNG尺寸与模型输入尺寸一致ResNet50为224×224。运行仿真推理python resnet50_demo.py查看推理结果终端会输出推理得到的类别、概率同时会弹出可视化窗口显示测试图片和推理结果若能正常输出结果说明模型加载和推理正常。注意若仿真推理报错优先检查以下几点1. RKNN-Toolkit2版本与ModelZoo版本是否匹配2. 输入图片尺寸、预处理方式是否与模型要求一致3. .rknn模型文件路径是否正确。4.3 第三步使用预转换模型板端部署板端部署是ModelZoo模型的核心应用场景分为Python部署调试和C/C部署工业级以“YOLO V10目标检测模型”为例结合RK3576开发板实操4.3.1 Python部署简单快捷适合调试准备文件将预转换的yolov10s.rknn模型和Python示例代码传到开发板# PC端执行通过ADB传文件adb push ~/Projects/rknn_model_zoo/models/detection/yolov10/yolov10s.rknn /home/root/adb push ~/Projects/rknn_model_zoo/examples/detection/yolov10/python/yolov10_demo.py /home/root/# 传测试图片adb push ~/test.jpg /home/root/开发板终端执行推理# 进入开发板终端adb shellcd /home/root/# 确保板端已安装rknn-toolkit2若未安装执行pip install rknn-toolkit2python3 yolov10_demo.py --model yolov10s.rknn --img test.jpg查看结果推理完成后终端会输出检测到的目标类别、置信度、坐标同时会生成带检测框的图片如result.jpg可通过ADB将图片拉回PC查看adb pull /home/root/result.jpg ~/Projects/4.3.2 C/C部署工业级高效稳定PC端编译C/C示例代码# 进入YOLO V10的C/C示例目录cd ~/Projects/rknn_model_zoo/examples/detection/yolov10/cpp# 修改Makefile指定交叉编译器路径之前下载的aarch64编译器vim Makefile# 找到CROSS_COMPILE变量修改为交叉编译器路径示例# CROSS_COMPILE ~/Projects/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-# 编译代码make# 编译完成后生成可执行文件 yolov10_demo将可执行文件和模型传到开发板执行推理adb push ./yolov10_demo /home/root/adb push ~/Projects/rknn_model_zoo/models/detection/yolov10/yolov10s.rknn /home/root/adb shellcd /home/root/# 赋予执行权限chmod x yolov10_demo# 执行推理./yolov10_demo ./yolov10s.rknn ./test.jpg查看结果与Python部署一致终端输出检测结果生成带检测框的图片可拉回PC查看。注意C/C部署时需确保交叉编译器与开发板架构一致如RK3576为aarch64架构若编译报错检查Makefile中的编译器路径和依赖配置同时确保板端RKNN Runtime版本与模型版本匹配避免出现库文件缺失报错。4.4 第四步模型二次优化进阶按需学习ModelZoo 中的预转换模型可根据实际需求进行二次优化提升性能或适配特定场景核心优化操作包括重新量化、调整输入尺寸、模型加密以下是具体示例4.4.1 重新量化模型提升推理速度、降低功耗若预转换模型为FP32精度可重新量化为INT8精度在保证精度损失可控的前提下提升推理速度步骤如下from rknn.api import RKNN import yaml # 1. 读取模型配置文件获取输入尺寸、预处理参数 with open(../models/classification/resnet50/model.yml, r) as f: config yaml.safe_load(f) input_size config[input_size] mean config[mean] std config[std] # 2. 初始化RKNN对象 rknn RKNN() # 3. 加载原始ONNX模型 onnx_model_path ../models/classification/resnet50/resnet50.onnx ret rknn.load_onnx(modelonnx_model_path, input_size_list[input_size]) # 4. 重新量化使用ModelZoo的校准数据集 calib_dataset ../datasets/imagenet/imagenet_calib.txt ret rknn.build(do_quantizationTrue, datasetcalib_dataset, quantization_accuracy_level2) # 5. 保存重新量化后的模型 rknn.save_rknn(./resnet50_int8_optimized.rknn) # 6. 精度分析查看量化精度损失 rknn.accuracy_analysis(dataset../datasets/imagenet/imagenet_test.txt, output_dir./accuracy) rknn.release() print(重新量化完成优化后的模型已保存)4.4.2 调整模型输入尺寸适配特定场景若实际场景需要不同的输入尺寸如将ResNet50的224×224改为320×320可修改模型配置文件重新转换模型打开model.yml文件修改input_size为[3, 320, 320]。运行转换脚本生成新的.rknn模型参考4.1节的转换命令。修改示例代码中的预处理步骤将输入图片缩放至320×320重新运行推理。4.4.3 模型加密防止模型泄露工业场景中可对模型进行加密防止模型被篡改或泄露步骤如下# 在模型build时添加加密密钥 ret rknn.build(do_quantizationTrue, datasetcalib_dataset, encrypt_keyyour_custom_key) # 保存加密后的模型 rknn.save_rknn(./resnet50_encrypted.rknn) # 板端推理时需传入对应密钥 ret rknn.load_rknn(./resnet50_encrypted.rknn, encrypt_keyyour_custom_key)注意加密密钥需妥善保管丢失后无法加载模型加密后的模型仅能在指定的瑞芯微芯片上运行提升安全性。五、实操案例3个典型场景新手必练结合ModelZoo的核心模型选取“图像分类、目标检测、语义分割”3个典型场景完整演示从模型查找、下载到板端部署的全流程贴合实际应用新手可直接跟着实操。案例1图像分类ResNet50—— 识别图片中的物体类别场景说明识别图片中的物体如猫、狗、汽车适用于智能监控、物体识别等场景基于RK3576开发板部署使用ModelZoo预转换的ResNet50 INT8模型。实操步骤查找模型进入models/classification/resnet50确认存在resnet50_int8.rknn模型和model.yml配置文件。PC端仿真参考4.2节运行Python示例代码验证模型能正确识别物体类别如测试图片为猫输出“cat”及概率。板端部署参考4.3.1节将模型和示例代码传到RK3576开发板执行推理查看识别结果。优化调整若识别精度不足重新量化模型提升量化精度等级若推理速度不足开启零拷贝API修改示例代码中的初始化方式# 零拷贝API初始化替换原有的init_runtimeret rknn.init_runtime(targetrk3576, runtime_modezero_copy)案例2目标检测YOLO V10—— 检测图片中的多个目标场景说明检测图片中的多个目标如行人、车辆、物体并标注目标坐标和类别适用于智能交通、安防监控等场景基于RK3588开发板部署使用ModelZoo预转换的YOLO V10模型。实操步骤查找模型进入models/detection/yolov10下载yolov10s.rknn模型INT8量化版查看README.md了解模型性能如RK3588上推理延迟约30ms/帧。PC端仿真修改Python示例代码中的置信度阈值如0.5运行推理查看检测框是否准确调整阈值优化检测效果。板端部署参考4.3.2节编译C/C示例代码传到RK3588开发板执行推理通过HDMI连接显示器实时显示检测画面。性能测试运行推理10次统计平均推理延迟验证模型性能是否符合预期若延迟过高可降低模型输入尺寸如640×640改为480×480。注意YOLO V10模型的后处理逻辑较为复杂示例代码中已包含完整的坐标转换、非极大值抑制NMS逻辑无需手动修改若需调整检测框精度可修改后处理配置文件中的NMS阈值。案例3语义分割U-Net—— 分割图片中的目标区域场景说明分割图片中的特定区域如道路、建筑、植物适用于自动驾驶、医学影像分析等场景基于RK3576开发板部署使用ModelZoo预转换的U-Net模型。实操步骤查找模型进入models/segmentation/unet确认存在unet_int8.rknn模型和示例代码。PC端仿真运行Python示例代码查看分割结果生成掩码图不同区域用不同颜色标注验证分割精度。板端部署将模型和示例代码传到开发板执行推理生成分割后的图片拉回PC查看效果。二次优化若分割精度不足增加校准数据集数量重新量化模型若推理速度不足简化模型结构如使用U-Net Lite轻量级模型。补充该案例可结合多模型协同部署例如先使用YOLO V10检测目标再使用U-Net分割目标区域实现更复杂的AI场景如菜品识别区域分割参考ModelZoo中的多模型协同示例代码。六、进阶技巧与常见问题避坑指南6.1 进阶技巧提升开发效率模型快速选型参考ModelZoo中每个模型的README.md查看模型在不同瑞芯微芯片上的性能参数延迟、精度、内存占用根据自身场景如实时性要求高选择延迟低的轻量级模型快速选型。批量部署模型使用ModelZoo提供的批量部署脚本tools/batch_deploy.py同时部署多个模型到开发板提升开发效率适合多模型协同场景。模型性能调优通过RKNN-Toolkit2的performance_analysis()函数分析模型各层的推理耗时针对性优化模型结构如剪枝、量化或调整NPU频率提升推理速度。自定义模型贡献若自己训练的模型适配瑞芯微NPU可按照ModelZoo的规范将模型转换为.rknn格式编写示例代码和说明文档提交到官方仓库贡献自己的模型。Docker部署利用瑞芯微AI平台支持的Docker部署功能将ModelZoo模型和推理环境打包为Docker镜像实现跨设备快速部署且推理性能几乎无损失。6.2 常见问题与解决方案新手必看问题1加载预转换模型时报错“model format error”解决方案检查模型文件是否完整.rknn文件未损坏确认模型版本与RKNN Runtime版本匹配若模型是自己转换的检查转换脚本的参数是否正确如芯片型号、量化方式。问题2PC端仿真正常板端推理报错“rknn_server not running”解决方案在开发板终端执行restart_rknn.sh启动rknn_server服务若启动失败检查NPU驱动是否正常或重新烧录开发板固件。问题3推理结果异常如分类错误、检测框偏移解决方案检查输入图片的预处理方式是否与模型要求一致如通道顺序、归一化参数确认测试图片与模型训练数据的分布一致调整模型的置信度阈值、NMS阈值。问题4量化后模型精度严重下降解决方案增加校准数据集数量至少20张确保校准数据与训练数据分布一致提升量化精度等级quantization_accuracy_level避免对精度敏感的模型如医学影像分割模型使用INT8量化可选择INT16量化。问题5C/C示例代码编译失败提示“undefined reference to rknn_init”解决方案检查Makefile中的RKNN Runtime库路径是否正确确保链接了librknnrt.so库确认交叉编译器与开发板架构一致重新编译。问题6ModelZoo仓库中没有所需的模型解决方案参考ModelZoo中的转换脚本将自己训练的模型PyTorch/TensorFlow格式转换为ONNX格式再转换为.rknn格式或在瑞芯微开发者社区提问获取其他开发者分享的模型。七、学习资源推荐进阶提升官方仓库RKNN Model Zoo 官方GitHub仓库https://github.com/airockchip/rknn_model_zoo包含最新模型、示例代码和说明文档定期更新。官方文档瑞芯微RKNN官方文档包含ModelZoo的使用说明、模型转换规范、API详细解释可在瑞芯微开发者官网下载。实操视频触觉智能、米尔电子等开发板厂商提供免费的ModelZoo模型部署实操视频结合具体开发板一步步演示操作流程适合新手跟着学。社区交流瑞芯微开发者社区、CSDN、知乎可搜索ModelZoo相关问题获取其他开发者的避坑经验和二次开发技巧也可提问求助解决自己遇到的问题。官方示例ModelZoo中的examples目录每个模型的示例代码是最好的学习资料可逐行分析代码逻辑理解模型加载、推理、后处理的完整流程。八、学习路线总结新手必看1. 基础阶段掌握ModelZoo的核心概念、仓库结构完成环境准备和版本适配能独立找到所需模型运行PC端仿真推理验证模型正确性。2. 实操阶段完成3个典型案例分类、检测、分割的板端部署掌握Python和C/C两种部署方式能排查常见的部署报错调整模型参数优化效果。3. 进阶阶段学习模型二次优化重新量化、输入尺寸调整、模型加密掌握多模型协同部署技巧尝试将自己的模型转换后上传到ModelZoo提升实战能力。提示ModelZoo学习的核心是“多实操、多调试”无需死记硬背重点掌握“如何找模型、如何用模型、如何优化模型”结合开发板反复练习就能快速上手将ModelZoo的模型灵活应用到实际项目中。同时要注意关注ModelZoo的更新及时获取最新的模型和优化工具提升开发效率。