1. 项目概述：一个为鸿蒙应用注入AI能力的技能库

最近在折腾鸿蒙应用开发，发现一个挺有意思的开源项目—— DengShiyingA/harmonyos-ai-skill 。这名字直译过来就是“鸿蒙AI技能”，听起来有点抽象，但它的核心价值非常明确： 为HarmonyOS（鸿蒙）应用开发者提供一套开箱即用的、模块化的AI功能组件 。

简单来说，它不是一个完整的AI应用，而是一个“工具箱”或者说“技能包”。想象一下，你正在开发一个鸿蒙版的智能相册、一个语音助手，或者一个能识别商品信息的购物应用。这些应用的核心亮点往往离不开AI能力，比如图像识别、语音转文字、自然语言处理。但自己从零开始集成AI模型、处理前后端逻辑，不仅门槛高，而且重复造轮子，效率低下。这个项目就是为了解决这个问题而生的。它把一些常见的AI能力（我称之为“技能”）封装成HarmonyOS的 Ability 或 Service ，你只需要像搭积木一样，在你的应用中调用这些封装好的服务，就能快速实现复杂的AI功能。

这个项目特别适合两类开发者：一是对AI感兴趣但不想深究底层模型训练的鸿蒙应用开发者；二是希望快速验证AI功能与鸿蒙生态结合可能性的创新者。它降低了AI应用的门槛，让开发者能更专注于业务逻辑和用户体验，而不是陷在模型部署和推理优化的泥潭里。

2. 核心架构与设计思路拆解

2.1 为什么是“技能”而非“SDK”？

项目命名为“AI-Skill”而非“AI-SDK”，这个用词很精准，体现了其设计哲学。传统的SDK（软件开发工具包）往往提供一个庞大的、统一的库，你需要学习其整体API设计。而“技能”的隐喻，更强调 独立、解耦、即插即用 。

在 harmonyos-ai-skill 的设计中，每一个独立的AI能力，例如“图像分类”、“语音识别”、“文本情感分析”，都被视为一个独立的“技能”。每个技能都是一个完整的、可独立部署和更新的鸿蒙组件（通常是 Service Ability 或 Particle Ability ）。这意味着：

  1. 按需引入 ：你的应用只需要引入你真正需要的那个技能包，不会引入不必要的依赖和体积膨胀。
  2. 独立进化 ：图像识别技能的优化和更新，不会影响到语音识别技能，维护和升级路径更清晰。
  3. 标准化接口 ：尽管技能内部实现各异，但对外（即对你的应用）提供标准化的调用接口，通常是基于鸿蒙的 Want 机制进行通信，降低了学习成本。

这种微服务化的架构思想，非常契合鸿蒙分布式和原子化服务的理念。你的应用可以作为一个“调度中心”，根据场景动态调用部署在本设备或其他设备上的AI技能服务。

2.2 技术栈选型与鸿蒙生态适配

要理解这个项目，必须把它放在鸿蒙应用开发的技术背景下看。鸿蒙应用主要使用ArkTS（基于TypeScript）或Java进行开发，其UI框架是ArkUI。 harmonyos-ai-skill 项目需要深度融入这个体系。

首先，AI模型的运行载体 。纯前端（ArkTS）直接运行大型AI模型（如TensorFlow.js或ONNX Runtime for Web）在移动设备上性能压力大，且模型文件体积会直接打包进HAP（HarmonyOS Ability Package），影响应用安装包大小。因此，更合理的架构是：

  • 本地推理 ：对于轻量级模型（如MobileNet、YOLO-Tiny），项目可能会选择集成 MindSpore Lite 或 Paddle Lite 等鸿蒙支持的端侧推理框架，将模型推理放在设备端，保障隐私和离线可用性。
  • 云端协同 ：对于复杂的模型（如大型语言模型、高精度语音识别），技能本身可能作为一个“代理”，负责处理输入数据的预处理、加密，然后调用云端AI服务（如项目可能预集成了或允许配置第三方API），再将结果返回给应用。这种模式下，技能封装了网络请求、鉴权、结果解析等脏活累活。

其次，与鸿蒙系统的集成方式 。项目很可能将每个技能实现为 Service Ability 。 Service Ability 在后台运行，没有UI，专门用于处理耗时任务和提供能力。应用通过 Feature Ability 发起一个 Want ，指定要调用的技能（通过 abilityName 和 parameters 传递输入数据），然后通过 Callback 或 Promise 异步获取结果。这种方式完美匹配了AI推理可能耗时的特性，避免了阻塞主线程导致UI卡顿。

最后，技能的管理与发现 。一个更高级的设想是，项目可能提供一套技能注册与发现机制。例如，一个“图像超分辨率”技能发布后，其他应用可以通过查询系统服务，发现并调用它，甚至可以实现跨应用的AI能力共享，这真正体现了鸿蒙的分布式能力。

3. 核心技能模块解析与实操要点

虽然我无法看到该项目所有技能的具体实现代码，但我们可以基于常见的AI应用场景，推断并构建出其核心技能模块的可能形态和实操要点。这对于理解和使用此类项目至关重要。

3.1 图像识别技能 ( ImageRecognitionSkill )

这可能是最常用的技能之一。它接收一张图片（URI或Base64数据），返回识别出的物体、场景或文字标签。

内部实现推测：

  1. 输入处理 ：技能接收到图片数据后，首先进行预处理，包括调整尺寸至模型要求（如224x224）、归一化像素值（如从0-255归一化到0-1或-1到1）、转换为模型所需的张量格式（NCHW或NHWC）。
  2. 模型推理 ：加载预置的轻量级图像分类模型（如经过转换的MobileNetV2或EfficientNet-Lite）。推理引擎很可能使用 MindSpore Lite ，因为它与鸿蒙生态结合最紧密。项目需要将模型文件（ .ms 格式）放置在技能的 resources/rawfile 目录下。
  3. 后处理与输出 ：获取模型输出的概率向量，通过 argmax 或 topk 操作得到最可能的几个类别及其置信度。映射回人类可读的标签（如“狗：95%”，“猫：3%”），最后将结构化的JSON数据返回给调用方。

实操要点与避坑指南：

  • 模型格式转换 ：开发者若想自定义模型，必须将训练好的模型（如PyTorch的 .pt 或TensorFlow的 .pb ）通过官方工具转换为MindSpore Lite支持的 .ms 格式。这个过程需要注意算子支持列表，某些复杂算子可能无法转换。
  • 图片输入路径 ：鸿蒙中访问本地图片需要使用 ohos.file.picker 选择器获取URI，或者使用 @ohos.multimedia.image 组件解码。直接将路径字符串传给技能是行不通的。技能接口设计时应明确接受 Want 中携带的 uri 参数。
  • 性能与功耗 ：连续调用图像识别技能（如用于实时摄像头预览帧分析）会显著增加CPU/NPU负载和耗电。在不需要实时性的场景，应合理设置调用频率或提供低功耗模式（如使用更小的模型）。
  • 内存管理 ：大尺寸图片在预处理时可能产生巨大的中间张量，需要注意及时释放内存，避免OOM（内存溢出）。技能实现中，应将大对象的创建和销毁放在一个明确的周期内。

注意 ：在真机上测试图像识别技能时，务必申请相应的权限（如 ohos.permission.READ_IMAGEVIDEO ），并在 module.json5 中正确声明技能 Ability 所需的能力和权限。

3.2 语音转文本技能 ( SpeechToTextSkill )

这个技能将用户的语音输入转换为文字，是语音助手、会议记录等应用的核心。

内部实现推测：

  1. 音频采集与预处理 ：技能可能提供两种接口：一是接收一个音频文件路径（如 .wav , .pcm ），二是直接对接系统的音频录制服务。预处理步骤包括重采样至模型要求的采样率（如16kHz）、分帧、加窗、计算梅尔频谱图（MFCCs或FBank），并将其转换为模型输入张量。
  2. 推理引擎选择 ：端侧语音识别模型相对复杂，完全端到端的模型（如基于RNN-T的模型）体积和算力要求高。更可行的方案是：
    • 端侧轻量模型 ：用于简单的命令词识别（如“打开灯光”、“下一首歌”），使用小的 Keyword Spotting 模型。
    • 云端API代理 ：对于大词汇量连续语音识别（LVCSR），技能作为客户端，将音频数据发送至云端语音识别服务（如可配置的百度、阿里云ASR API），处理鉴权和结果返回。这是平衡精度和成本的常见做法。
  3. 结果流式返回 ：对于长语音，技能应支持流式或分段处理，并通过回调接口逐步返回中间识别结果，提升用户体验。

实操要点与避坑指南：

  • 音频格式与质量 ：明确技能支持的音频格式（PCM、WAV）、编码、采样率、声道数。不匹配的格式会导致识别失败或准确率骤降。建议在调用前，使用鸿蒙的 AudioCapturer 或 AudioRecorder 组件按规范录制音频。
  • 噪音环境处理 ：端侧模型在嘈杂环境下效果会大打折扣。如果项目技能未集成降噪模块，应用层需要在调用前进行简单的音频增益或使用第三方降噪库预处理，或者引导用户在安静环境下使用。
  • 网络依赖与离线回退 ：如果技能依赖云端，必须优雅地处理网络不可用的情况。设计上，技能应能返回明确的错误码（如 ERROR_NETWORK_UNAVAILABLE ），应用端据此给出友好提示，或切换至备用的端侧命令词识别模式。
  • 隐私安全 ：语音数据是敏感信息。如果使用云端服务，必须在技能配置中明确告知用户数据将上传至云端，并提供隐私政策链接。端侧处理是更安全的选择，但能力有限。

3.3 自然语言处理技能 ( NaturalLanguageSkill )

这是一个更泛化的技能，可能包含文本分类、情感分析、关键词提取、文本摘要甚至简单的对话功能。

内部实现推测：

  1. 模块化设计 ：该技能内部可能由多个子模块构成，通过 Want 的参数来指定具体任务（ task: “sentiment” 或 task: “summarize” ）。
  2. 模型部署策略 ：
    • 轻量任务端侧化 ：如情感分析（正面/负面/中性）、垃圾文本分类，可以使用轻量级的BERT变体（如MobileBERT）或简单的TextCNN模型，转换为端侧格式运行。
    • 复杂任务云端化 ：如文本摘要、开放域问答，则调用云端大语言模型（LLM）的API。技能负责构造符合API要求的Prompt，并解析返回的JSON或Streaming响应。
  3. 文本预处理 ：包括分词（对于中文尤为重要）、去除停用词、构建词表索引等。如果使用预训练模型，必须使用与模型训练时一致的分词器（Tokenizer）。

实操要点与避坑指南：

  • 中文分词一致性 ：中文NLP的第一步就是分词。不同的分词工具（jieba, HanLP, PKU）结果不同，会导致后续特征不一致。 必须确保技能内部使用的分词器与模型训练时使用的完全一致 ，否则效果无法保证。项目文档应明确注明。
  • 输入长度限制 ：无论是端侧还是云端模型，都有最大输入长度（Token数）限制。例如，BERT-base通常是512个token。技能应对超长文本进行智能截断或分段处理，并在文档中说明处理策略和可能的信息损失。
  • Prompt工程（对于LLM调用） ：如果技能集成了大模型调用，那么 Want 中传递的 parameters 就包含了构造Prompt的指令。技能应提供一些最佳实践的Prompt模板，并允许开发者微调。例如，情感分析可以构造为：“请判断以下文本的情感倾向是正面、负面还是中性。文本：{用户输入}”。
  • 结果的可解释性 ：对于分类任务，技能不应只返回一个标签，而应返回所有候选类别的置信度分数，让应用开发者能根据阈值进行灵活判断或展示。

4. 集成与调用：从零开始在你的鸿蒙应用中接入AI技能

假设我们现在要开发一个“智能旅行日记”应用，需要集成图像识别（自动给照片打标签）和情感分析（分析日记文本情绪）两个技能。以下是详细的集成步骤。

4.1 环境准备与项目配置

首先，确保你的开发环境是最新的DevEco Studio，并创建了一个HarmonyOS应用项目。

  1. 引入技能依赖 ：如果 harmonyos-ai-skill 项目以HAR（HarmonyOS Archive）的形式发布，你需要在你的应用模块的 oh-package.json5 文件中添加依赖。 

    {
  "dependencies": {
    "@ohos/image-recognition-skill": "file:../harmonyos-ai-skill/ImageRecognitionSkill.har",
    "@ohos/nlp-skill": "file:../harmonyos-ai-skill/NaturalLanguageSkill.har"
  }
}

    然后执行 ohpm install 安装依赖。如果技能是以源码形式提供，你可能需要将其作为模块（Module）添加到你的工程中。

  2. 声明技能所需权限 ：在 entry/src/main/module.json5 文件中，声明应用和技能需要的权限。例如，图像识别需要读存储权限，网络技能需要网络权限。 

    {
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_IMAGEVIDEO"
      },
      {
        "name": "ohos.permission.INTERNET" // 如果技能需要联网
      }
    ]
  }
}

  3. 配置技能Ability ：如果技能是独立的 Service Ability ，你需要在 module.json5 的 abilities 标签内（或在技能自己的配置文件中）正确声明它，确保系统能正确识别和启动它。

4.2 编写调用代码：以图像识别为例

在你的日记编辑页面，当用户添加照片后，触发识别逻辑。 

// 导入技能相关的API，这里假设技能提供了统一的调用入口类
import { AISkillClient } from '@ohos/ai-skill-kit';
import { BusinessError } from '@ohos.base';
import common from '@ohos.app.ability.common';

@Entry
@Component
struct DiaryEditorPage {
  // 假设这是用户选择的图片URI
  private selectedImageUri: string = 'file://media/images/photo1.jpg';

  // 获取UIAbility的Context
  private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;

  build() {
    // ... UI布局代码
    Button('识别图片内容')
      .onClick(() => {
        this.recognizeImage();
      })
  }

  async recognizeImage() {
    // 1. 构造Want对象，指定要调用的技能和能力
    let want = {
      bundleName: 'com.example.aiskills', // 技能所在的包名
      abilityName: 'ImageRecognitionService', // 技能Service Ability的名称
      parameters: { // 传递参数
        'imageUri': this.selectedImageUri,
        'maxResults': 5 // 要求返回前5个可能的结果
      }
    };

    // 2. 使用AISkillClient或直接使用featureAbility.startAbility
    try {
      // 方式A：如果项目提供了客户端封装
      let result = await AISkillClient.callSkill(want);
      // 方式B：使用鸿蒙原生API
      // let result = await featureAbility.startAbility(want);

      // 3. 处理返回结果
      if (result && result.code === 0) {
        let tags = result.data.tags; // 假设返回数据结构为 {tags: [{label: 'dog', confidence: 0.95}, ...]}
        console.info('识别成功，标签：', JSON.stringify(tags));
        // 更新UI，将标签展示在图片下方
        // this.imageTags = tags;
        promptAction.showToast({ message: `识别出：${tags[0].label}` });
      } else {
        console.error('识别失败，错误码：', result.code, '信息：', result.message);
        promptAction.showToast({ message: '识别失败，请重试' });
      }
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('调用技能发生异常：', err.code, err.message);
      // 处理异常，如网络错误、权限错误等
    }
  }
}

4.3 异步处理与状态管理

AI技能调用是典型的异步I/O操作，必须妥善处理，避免阻塞UI。

  1. 使用Async/Await或Promise ：如上例所示，使用 async/await 语法能让异步代码更清晰。务必用 try...catch 包裹，处理所有可能的异常（网络超时、技能未安装、参数错误等）。
  2. UI状态反馈 ：在调用技能前，显示一个加载中的提示（如 Loading 组件）；调用结束后，无论成功失败，都要更新UI状态并隐藏加载提示。这是良好的用户体验基础。
  3. 结果缓存 ：对于相同输入的识别请求（例如同一张图片），可以考虑在应用内存或轻量存储中进行短期缓存，避免不必要的重复计算和网络请求，提升响应速度。

5. 开发、调试与性能优化实战

5.1 技能开发的“第一性原理”

如果你想为 harmonyos-ai-skill 项目贡献一个新的技能，或者借鉴其思路为自己项目创建私有技能，需要遵循几个核心原则：

  1. 定义清晰的接口契约 ：首先明确你的技能输入是什么（格式、范围），输出是什么（数据结构）。这个契约一旦确定，后续就要尽力保持向后兼容。例如，图像识别技能的输入必须明确是 uri 还是 base64 ，输出是 Array<Label> 对象。
  2. 错误处理标准化 ：定义一套技能内部使用的错误码和错误信息枚举。例如：
    • 1001: INVALID_PARAMETER - 输入参数缺失或格式错误。
    • 1002: MODEL_LOAD_FAILED - 模型文件加载失败。
    • 2001: NETWORK_ERROR - 网络请求失败。
    • 2002: API_AUTH_FAILED - 云端API鉴权失败。 在技能内部捕获异常，转化为标准的错误对象，通过 Want 的返回机制传递出去。
  3. 资源管理 ：模型文件、配置文件等资源应放在 resources/rawfile 目录。在技能的 onStart 生命周期中加载模型（注意这可能增加启动时间），在 onBackground 或 onStop 中考虑是否要释放以减少内存占用。对于大模型，懒加载可能是更好的策略。

5.2 真机调试与问题排查

在模拟器上运行良好的技能，在真机上可能遇到各种问题。

  • 问题一：技能调用超时或无响应

    • 排查 ：首先检查 Want 中的 bundleName 和 abilityName 是否正确。使用 hilog 命令查看技能服务的日志，确认技能是否成功启动。 hilog | grep <你的技能Ability名称> 。
    • 可能原因 ：技能 Service Ability 的 onStart 方法中进行了同步的耗时操作（如加载大模型），阻塞了主线程。 必须将耗时初始化放在异步任务或工作线程中 。
    • 解决 ：在技能的 onStart 中仅做轻量级初始化，然后启动一个 TaskDispatcher 来异步加载模型，加载完成后通过事件通知技能进入就绪状态。

  • 问题二：模型推理结果精度极低或完全错误

    • 排查 ：对比端侧推理结果与原始框架（如PyTorch）的推理结果。构建一个简单的测试用例，输入固定数据，对比输出。
    • 可能原因 ：
      1. 预处理不一致 ：这是最常见的原因。确保图片的缩放算法（双线性 vs. 最近邻）、归一化方式（除以255 vs. 减去均值除以标准差）与模型训练时完全一致。
      2. 模型转换错误 ：在转换为 .ms 格式时，某些不支持的算子被替换或忽略，导致模型结构改变。使用转换工具提供的可视化或校验功能检查转换后的模型。
      3. 输入输出格式错误 ：模型期望的输入张量格式是 NCHW ，但你提供了 NHWC 。
    • 解决 ：在技能内部实现一个“调试模式”，可以输出预处理后的张量值，与标准流程对比。严格遵循模型原项目的预处理代码。

  • 问题三：应用安装包体积暴增

    • 排查 ：分析HAP包的构成，看是否是模型文件过大。
    • 可能原因 ：将数十MB甚至上百MB的模型直接打包进了HAP。
    • 解决 ：
      1. 模型压缩 ：使用模型剪枝、量化技术（如INT8量化）大幅减小模型体积，这对精度影响通常可控。
      2. 动态下载 ：首次启动应用时，从服务器下载模型文件到应用的沙箱目录。技能运行时从该目录加载。这需要处理下载、校验、版本更新等逻辑。
      3. 按需分发 ：在应用市场上传多个HAP包，根据设备架构（arm64-v8a, armeabi-v7a）分发包含对应优化后模型的包。

5.3 性能优化关键点

  1. 推理引擎线程池 ：不要为每一次推理请求都创建新线程。在技能初始化时，创建一个固定的线程池（如 Worker 或 TaskDispatcher ），所有推理任务提交到该池中排队执行，避免线程创建销毁的开销和资源竞争。
  2. 模型预热 ：在技能启动后或收到第一个请求前，用一张小的虚拟输入数据（dummy input）进行一次推理。这可以触发推理引擎的初始化、模型加载和缓存机制，使第一次真实请求的延迟显著降低。
  3. 输入数据流水线 ：对于从摄像头获取的连续帧进行识别，不要等上一帧识别完成再处理下一帧。可以采用生产者-消费者模式，一个线程负责采集和预处理图像，另一个线程负责推理，中间用队列连接，实现流水线并行，提升吞吐量。
  4. 功耗感知 ：长时间连续调用高负载AI技能（如实时视频分析）会快速消耗电量。技能可以提供“省电模式”参数，在此模式下使用更小、更快的模型，或者降低推理频率。应用层应根据设备电量、温度状态智能切换模式。

6. 扩展思考：从技能到生态

harmonyos-ai-skill 项目的价值远不止于提供几个现成的AI功能。它更重要的是一种范式，启发我们如何构建鸿蒙生态下的AI能力共享体系。

技能市场与动态部署 ：未来是否可以设想一个“鸿蒙AI技能市场”？开发者可以将自己训练的优质模型封装成技能，发布到市场。其他应用可以动态发现、按需下载和调用这些技能，甚至为调用付费。技能本身可以独立更新，无需依赖调用它的应用升级。

跨设备技能调度 ：鸿蒙的分布式能力是王牌。一个技能可以部署在家中的智慧中控（性能强），手机上的应用通过软总线发现并调用这个技能，完成复杂的AI处理（如全家照片的智能分类），然后将结果返回手机。技能本身对调用者透明，实现了算力的最优分配。

技能组合与编排 ：单个技能能力有限，但多个技能组合能产生强大效果。例如，一个“视频理解”工作流，可以串联调用“视频抽帧技能”、“图像识别技能”、“文本摘要技能”，最终生成视频的图文摘要。需要一套工作流编排引擎来管理这些技能的调用顺序和数据流转。

隐私计算与联邦学习 ：当技能涉及用户敏感数据时，隐私保护至关重要。技能的设计应支持在端侧完成数据处理和特征提取，只有脱敏的、非隐私的特征数据（或加密后的数据）才被发送出去进行进一步分析。甚至，技能可以支持联邦学习模式，在本地利用用户数据更新模型参数，只上传参数更新，保护原始数据不出设备。

回到我们开头的“智能旅行日记”应用，通过集成 harmonyos-ai-skill ，我们快速拥有了图像理解和文本情感分析的能力。但这只是起点。你可以进一步思考：能否利用设备的GPS信息，调用一个“地理位置语义化技能”，将坐标转换为“埃菲尔铁塔脚下”、“京都清水寺”这样的诗意描述？能否在用户撰写日记时，实时调用一个“文本补全技能”提供写作建议？这些都需要更多、更细分的AI技能被创造和集成。

这个项目的意义，在于它搭建了一座桥，一边是强大但复杂的AI技术，另一边是蓬勃发展的鸿蒙应用生态。作为开发者，我们的任务就是走过这座桥，利用这些“技能积木”，去构建那些真正智能、贴心、充满想象力的下一代鸿蒙应用。

# 鸿蒙应用开发
Logo
码道开发者社区

码道开发者社区，聚焦华为云码道 CodeArts 代码智能体，沉淀 Agent、Skill、鸿蒙开发实战内容，供开发者查阅资料、交流技术、分享工程实践

更多推荐

cover

状态丢失排障：Claude 持久记忆的跨会话局限与知芽 Notebook Skill 单元记忆如何沉淀可复用知识资产

avatar 码道开发者社区
cover

vs code 下载安装 以及 如何配置 claude code 和codex

avatar 码道开发者社区
cover

GitHub不再让一个模型写到底：HydraFusion多模型编排，官方评测成本降低67%

avatar 码道开发者社区