本地离线图像识别 Demo，鸿蒙端侧 AI 套件入门-开发者社区

提到端侧 AI，很多新手第一反应是「要懂算法、要训练模型、门槛很高」。其实在鸿蒙 7 体系下，依托@kit.AIKit 端侧推理引擎，不需要懂算法原理，不需要联网，只要准备好预训练模型，处理好输入输出，短短几十行代码就能实现纯本地的图像识别，数据完全不出设备，还能享受 NPU 硬件加速。

本文就以最经典的通用图像分类为实战场景，带你从零跑通端侧 AI 推理的完整链路：选图 → 本地预处理 → NPU 推理 → 返回识别结果，全程离线运行，代码可直接复用扩展。

一、为什么用端侧 AI？核心价值

端侧 AI 就是把模型推理完全放在设备本地执行，不依赖云端服务，核心优势非常明确：

极致隐私：图片、数据全部在本地处理，不上传云端，适合敏感场景
离线可用：没有网络也能正常使用，不受信号、流量限制
低延迟：NPU 硬件加速，推理耗时毫秒级，适合实时场景
低功耗：系统级调度 NPU，比纯 CPU 推理功耗降低 60% 以上

适合落地的场景非常多：本地图片分类、物体检测、文字识别、扫码、人像抠图、图像超分等等。

二、核心技术栈与原理

2.1 官方套件：@kit.AIKit

AIKit 是鸿蒙官方端侧 AI 能力的统一入口，核心包含两大部分：

预置系统 AI 能力：人像抠图、图像超分、文本摘要等开箱即用的能力，无需自带模型
通用推理引擎 aiEngine：支持加载自定义 ONNX / 鸿蒙模型格式，实现任意自定义 AI 任务，NPU 自动加速

本文实战使用的是通用推理引擎，它是最灵活、扩展性最强的端侧 AI 方案，换个模型就能快速落地不同场景。

2.2 图像识别完整推理链路

通用图像分类的执行流程非常固定，所有端侧推理任务都遵循这个逻辑：

选择图片 → 图片预处理（缩放、归一化、转张量） ↓ 加载模型 → 输入张量 → NPU/CPU 推理 ↓ 结果后处理（取概率最高的分类、映射标签） ↓ 展示识别结果

2.3 模型选择：MobileNetV2

我们使用业界最通用的轻量图像分类模型MobileNetV2：

谷歌开源的预训练模型，支持 1000 类通用物体识别
模型体积小（仅十几 MB），推理速度快
适合端侧部署，对硬件要求低
新手入门门槛最低，理解后可无缝替换为其他模型

三、前置准备

3.1 开发与运行环境

SDK 版本：API 26（HarmonyOS 7.0）及以上
开发工具：DevEco Studio 5.0 及以上
运行设备：
- 推荐：麒麟 9000 系列及以上设备，支持 NPU 硬件加速
- 兼容：不支持 NPU 的设备会自动回退到 CPU 推理，可正常运行只是速度稍慢

3.2 资源文件准备

需要提前准备两个文件，放到工程entry/src/main/resources/rawfile目录下：

模型文件：mobilenetv2.onnx
可直接下载官方公开的 MobileNetV2 ONNX 预训练模型
标签文件：imagenet_labels.json
ImageNet 1000 分类的中文/英文标签映射，格式如下：
```
["tench 金鲫鱼","goldfish 金鱼","great white shark 大白鲨",...]
```

四、完整实战：本地图像分类 Demo

4.1 第一步：封装推理工具类

我们把模型加载、图片预处理、推理执行、结果后处理全部封装到工具类中，和 UI 完全分离，便于复用。

新建entry/src/main/ets/utils/ImageClassifier.ets：

import{aiEngine}from'@kit.AIKit';import{fs}from'@kit.CoreFileKit';import{hilog}from'@kit.PerformanceAnalysisKit';constTAG='ImageClassifier';// 识别结果结构体exportinterfaceClassifyResult{label:string;confidence:number;}/** * 端侧图像分类器 * 基于AIKit推理引擎，本地离线运行 */exportclassImageClassifier{privateinferEngine:aiEngine.InferEngine|null=null;privatelabels:string[]=[];privateisReady:boolean=false;// 模型输入参数：MobileNetV2标准输入224x224 RGB三通道privatereadonlyINPUT_SIZE=224;privatereadonlyINPUT_CHANNEL=3;/** * 初始化：拷贝模型到沙箱 + 加载模型 + 读取标签 */asyncinit(context:Context):Promise<boolean>{try{// 1. 将rawfile中的模型和标签拷贝到沙箱目录constmodelPath=awaitthis.copyRawToFile(context,'mobilenetv2.onnx');constlabelPath=awaitthis.copyRawToFile(context,'imagenet_labels.json');// 2. 读取标签constlabelContent=fs.readText(labelPath);this.labels=JSON.parse(labelContent);// 3. 创建推理引擎，优先NPU加速this.inferEngine=aiEngine.createInferEngine({modelPath:modelPath,deviceType:aiEngine.DeviceType.NPU_PREFERRED});awaitthis.inferEngine.load();this.isReady=true;hilog.info(0x0000,TAG,'图像分类器初始化成功');returntrue;}catch(err){hilog.error(0x0000,TAG,`初始化失败:${JSON.stringify(err)}`);this.isReady=false;returnfalse;}}/** * 执行图像分类，返回Top3结果 * @param imageBuffer 图片像素数据（RGB Float32 归一化后） */asyncclassify(imageBuffer:ArrayBuffer):Promise<ClassifyResult[]>{if(!this.isReady||!this.inferEngine){thrownewError('分类器未初始化');}try{// 1. 设置输入张量constinputTensor=newaiEngine.Tensor({data:imageBuffer,shape:[1,this.INPUT_CHANNEL,this.INPUT_SIZE,this.INPUT_SIZE],dtype:aiEngine.DataType.FLOAT32});this.inferEngine.setInputTensor(0,inputTensor);// 2. 执行推理awaitthis.inferEngine.run();// 3. 获取输出张量constoutputTensor=this.inferEngine.getOutputTensor(0);constoutputData=newFloat32Array(outputTensor.data);// 4. 后处理：取概率最高的Top3returnthis.getTopResults(outputData,3);}catch(err){hilog.error(0x0000,TAG,`推理失败:${JSON.stringify(err)}`);return[];}}/** * 图片预处理：将图片缩放到指定尺寸，转RGB并归一化 * @param imageUri 图片URI */asyncpreprocessImage(imageUri:string):Promise<ArrayBuffer>{// 说明：实际项目中使用PixelMap解码图片、缩放、提取RGB像素// 此处简化核心逻辑：将图片缩放到224x224，提取RGB像素值并归一化到[0,1]constpixelCount=this.INPUT_SIZE*this.INPUT_SIZE;constfloatBuffer=newFloat32Array(pixelCount*this.INPUT_CHANNEL);// 提示：完整实现需要调用Image Kit解码图片为PixelMap，逐像素读取RGB值// 归一化参数根据模型训练时的配置调整，MobileNet通常为：// pixel = (pixel / 255.0 - mean) / std// mean = [0.485, 0.456, 0.406], std = [0.229, 0.224, 0.225]returnfloatBuffer.buffer;}/** * 后处理：取置信度最高的Top N结果 */privategetTopResults(output:Float32Array,topN:number):ClassifyResult[]{constresults:ClassifyResult[]=[];constindexed=Array.from(output).map((conf,i)=>({index:i,conf}));indexed.sort((a,b)=>b.conf-a.conf);for(leti=0;i<topN&&i<indexed.length;i++){constitem=indexed[i];results.push({label:this.labels[item.index]||`类别${item.index}`,confidence:item.conf});}returnresults;}/** * 将rawfile文件拷贝到沙箱，返回沙箱路径 */privateasynccopyRawToFile(context:Context,fileName:string):Promise<string>{constrawData=awaitcontext.resourceManager.getRawFileContent(fileName);consttargetPath=`${context.filesDir}/${fileName}`;if(!fs.exists(targetPath)){fs.write(targetPath,rawData.buffer);}returntargetPath;}/** * 释放资源 */release():void{if(this.inferEngine){this.inferEngine.unload();this.inferEngine=null;}this.isReady=false;}}

4.2 第二步：主页面实现

页面实现相册选图、图片预览、触发识别、展示结果的完整交互。

打开entry/src/main/ets/pages/Index.ets：

import{ImageClassifier,ClassifyResult}from'../utils/ImageClassifier';import{PhotoViewPicker,photoAccessHelper,promptAction}from'@kit.ArkUI';import{hilog}from'@kit.PerformanceAnalysisKit';constTAG='ImageClassifyDemo';@Entry@Componentstruct OfflineImageClassifyPage{@StateimageUri:string='';@StateresultList:ClassifyResult[]=[];@StateisLoading:boolean=false;@StateisInitDone:boolean=false;privateclassifier:ImageClassifier=newImageClassifier();privatephotoPicker:PhotoViewPicker=newPhotoViewPicker();asyncaboutToAppear(){// 页面加载时异步初始化模型this.isLoading=true;constsuccess=awaitthis.classifier.init(getContext(this));this.isInitDone=success;this.isLoading=false;if(!success){promptAction.showToast({message:'模型初始化失败，请检查资源文件'});}}aboutToDisappear(){this.classifier.release();}/** * 选择图片 */asyncpickImage(){try{constres=awaitthis.photoPicker.select({MIMEType:photoAccessHelper.MimeType.IMAGE,maxSelectNumber:1});if(res.photoUris&&res.photoUris.length>0){this.imageUri=res.photoUris[0];this.resultList=[];}}catch(err){hilog.error(0x0000,TAG,`选图失败:${JSON.stringify(err)}`);}}/** * 执行识别 */asyncstartClassify(){if(!this.imageUri||!this.isInitDone){promptAction.showToast({message:'请先选择图片并等待模型加载'});return;}this.isLoading=true;conststartTime=Date.now();try{// 1. 图片预处理constinputBuffer=awaitthis.classifier.preprocessImage(this.imageUri);// 2. 推理this.resultList=awaitthis.classifier.classify(inputBuffer);constcost=Date.now()-startTime;hilog.info(0x0000,TAG,`识别完成，耗时${cost}ms`);}catch(err){promptAction.showToast({message:'识别失败'});}finally{this.isLoading=false;}}build(){Column({space:20}){Text('离线图像识别').fontSize(24).fontWeight(FontWeight.Bold).width('90%').margin({top:30});// 图片预览区Stack({alignContent:Alignment.Center}){if(this.imageUri){Image(this.imageUri).width('100%').aspectRatio(1).objectFit(ImageFit.Contain).borderRadius(12).backgroundColor('#F5F5F5');}else{Column({space:12}){Text('🖼️').fontSize(48);Text('选择一张图片开始识别').fontSize(14).fontColor('#999999');}}if(this.isLoading){Column({space:8}){LoadingProgress().width(36).height(36).color('#0A59F7');Text('推理中...').fontSize(14).fontColor('#666666');}.width(120).padding(16).backgroundColor('#FFFFFFCC').borderRadius(12);}}.width('90%').aspectRatio(1).backgroundColor('#FFFFFF').borderRadius(16).shadow({radius:6,color:'#1A000000'});// 操作按钮Column({space:12}){Button('选择图片').width('100%').height(50).borderRadius(25).backgroundColor('#0A59F7').onClick(()=>this.pickImage());Button('开始识别').width('100%').height(50).borderRadius(25).backgroundColor('#00B578').enabled(!!this.imageUri&&!this.isLoading&&this.isInitDone).onClick(()=>this.startClassify());}.width('90%');// 识别结果if(this.resultList.length>0){Column({space:12}){Text('识别结果（Top3）').fontSize(16).fontWeight(FontWeight.Medium).width('100%');ForEach(this.resultList,(item,index)=>{Row(){Text(`Top${index+1}`).fontSize(14).fontColor('#888888').width(60);Text(item.label).fontSize(15).fontColor('#333333').layoutWeight(1);Text(`${(item.confidence*100).toFixed(1)}%`).fontSize(14).fontColor('#0A59F7').fontFamily('monospace');}.width('100%').padding(12).backgroundColor(index===0?'#F0F7FF':'#FAFAFA').borderRadius(8);});}.width('90%').padding(16).backgroundColor('#FFFFFF').borderRadius(12).shadow({radius:4,color:'#1A000000'});}Blank();Text('💡 纯本地离线推理，数据不上传，保护隐私').fontSize(12).fontColor('#AAAAAA').margin({bottom:30});}.width('100%').height('100%').backgroundColor('#F8F9FA');}}

五、运行验证步骤

放入资源：将下载好的模型文件和标签文件放入rawfile目录
编译安装：将应用安装到鸿蒙实体设备上
初始化验证：进入应用后等待模型加载完成，无报错即初始化成功
识别测试：
- 点击选择图片，从相册选一张物体照片
- 点击开始识别，等待推理完成
- 查看 Top3 识别结果与置信度
离线验证：关闭设备 Wi-Fi 和移动网络，重复上述操作，功能完全正常

六、进阶优化与扩展方向

6.1 性能优化

模型量化：使用 INT8 量化模型，体积减小 75%，推理速度提升 2~3 倍，精度损失极小
输入复用：连续推理时复用输入张量内存，避免频繁申请释放
异步流水线：预处理和推理并行执行，提升连续识别帧率
NPU 调优：根据芯片型号调整算子优先级，最大化 NPU 利用率

6.2 功能扩展

这套推理框架是通用的，替换不同的模型就能快速落地各种端侧 AI 能力：

换 YOLO 系列模型 → 实时物体检测
换 OCR 模型 → 本地文字识别
换人脸检测模型 → 人脸关键点识别
换超分模型 → 图片清晰度增强

6.3 系统预置 AI 能力

如果不需要自定义模型，AIKit 还提供了很多开箱即用的系统预置能力：

人像抠图、智能抠图
图像超分辨率
智能文本摘要
语音识别与合成

七、新手高频踩坑指南

1. 模型加载失败

排查：模型文件是否正确放入 rawfile、是否成功拷贝到沙箱、路径是否正确
注意：ONNX 模型版本要和推理引擎支持的版本匹配，建议用 opset 11~16 之间的版本

2. 识别结果完全不对

90% 的情况是预处理归一化参数错误
每个模型训练时的均值、标准差都不同，必须和训练时保持完全一致，否则结果会完全错乱
其次检查输入张量的形状、通道顺序（RGB / BGR）是否匹配

3. NPU 不支持，推理很慢

部分小众算子 NPU 不支持，会自动回退到 CPU 执行
优化：尽量使用 NPU 支持的标准算子，避免自定义算子；也可手动指定 CPU 模式保证兼容性

4. 大图推理内存溢出

不要直接把原图输入模型，必须先缩放到模型要求的输入尺寸
超大图可先做缩放、裁剪，再送入推理引擎，大幅降低内存占用

5. 页面退出后仍占用资源

必须在页面aboutToDisappear中调用release()释放推理引擎
长时间后台运行会占用 NPU 资源，导致系统功耗升高

总结

端侧 AI 看似门槛很高，其实鸿蒙 AIKit 已经把最复杂的模型解析、硬件调度、内存管理都封装好了，开发者只需要关注「输入预处理 + 输出后处理」两部分业务逻辑，就能快速落地离线 AI 能力。

这个图像分类 Demo 是最基础的入门模板，吃透了推理引擎的使用流程，再去做更复杂的实时检测、多模型串联等场景，思路都会非常清晰。端侧 AI 的核心价值从来不是追求极致精度，而是在隐私、延迟、可用性之间找到最佳平衡，这也是鸿蒙分布式智能体验的基础。

本地离线图像识别 Demo，鸿蒙端侧 AI 套件入门