在 HarmonyOS NEXT 应用开发中，AI 能力的集成越来越常见——从端侧模型推理到智能对话，都需要依赖模型加载、推理管线和资源管理。但不少开发者会遇到一个问题：官方提供的 AI 相关 API 虽然看起来简单，实际项目里却因为依赖配置、编译链路、代码补全支持不足，导致开发效率低下。

DevEco Code 和 DevEco CLI 正是为了解决这些问题推出的提效工具。前者是内嵌在 DevEco Studio 中的 AI 辅助编程插件（类似 IntelliCode for HarmonyOS），提供智能代码补全、模板生成、实时错误检测；后者是命令行工具集，负责工程创建、构建和部署。两者配合 ArkCompiler，可以显著降低 AI 开发的门槛。

这篇文章不讲基础概念，只讲真正会用到的安装、配置和核心场景用法，以及容易忽略的限制。

它解决什么问题

在 AI 开发场景中，开发者通常需要：

1. 快速搭建工程骨架：包含神经网络模型绑定、@ohos.mindSpore 或 @ohos.ai 等依赖声明。
2. 高效编写推理代码：AI 推理涉及复杂的异步回调、生命周期管理，手动编写容易出错。
3. 一键构建与部署：不同设备（手机、平板、开发板）的 SDK 版本差异，构建参数需灵活调整。

DevEco Code 负责解决第 2 点，DevEco CLI 负责解决第 1 点和第 3 点。两者不冲突，但建议搭配使用。

与手动配置的对比

维度	手动方式	使用 DevEco Code + CLI
工程初始化	手动创建 oh-package.json5，写 index.ets 等	deveco init 一步生成
依赖添加	手动编辑 oh-package.json5，查版本号	DevEco Code 智能提示 + CLI 自动同步
构建命令	hvigorw build，需要记住参数	内置常用模板，如 hvigorw assembleHap --mode release
代码补全	基础 ArkTS 补全	支持 AI 模型相关 API 的上下文补全，含参数类型提示

环境说明

DevEco Studio 版本：DevEco Studio 5.0.0 及以上
HarmonyOS SDK 版本：HarmonyOS 5.0.0(23) 及以上
目标设备：手机（API 23+）或开发板（Hi3516DV300 等）

注意：DevEco CLI 随 DevEco Studio 安装自动附带，但需要手动配置环境变量（macOS/Linux 下将 $DEVECO_HOME/tools 加入 PATH）。

安装与配置

DevEco Code 插件

DevEco Studio 中搜索并安装 DevEco Code 插件。安装后重启 IDE，在 Settings → Tools → DevEco Code 中可以看到 AI 补全开关，默认启用。

关键配置：

• 模型路径：如果需要使用本地模型作补全来源，需要指定模型文件路径（私有部署场景）。
• 补全触发字符：建议保留默认，包括 . ( = 等。

DevEco CLI 初始化

打开终端（Windows 用 cmd，macOS/Linux 用 bash），运行：

deveco --version

如果提示命令不存在，需检查环境变量。通常 deveco 位于 $DEVECO_HOME/tools/command-line-tools/。

核心实现：创建一个 AI 推理工程

我们以 MindSpore Lite 推理为例，演示从初始化到构建的全流程。

1. 使用 DevEco CLI 创建工程

deveco init -n AIModelDemo -t app -s default

参数说明：

• -n：项目名称。
• -t app：应用工程类型。
• -s default：使用默认 SDK 版本。如果需要指定目标设备类型，可以使用 -s phone。

执行后会在当前目录下生成 AIModelDemo 文件夹，包含 oh-package.json5、build-profile.json5、src/main/ets 等。

2. 添加 AI 依赖

编辑 oh-package.json5，在 dependencies 中添加：

{
  "dependencies": {
    "@ohos/mindspore": "1.8.0",
    "@ohos/hiviewdfx": "1.2.0"
  }
}

然后运行命令同步依赖：

cd AIModelDemo
deveco ohpm install

deveco ohpm install 等同于 ohpm install，但会自动处理 SDK 版本兼容性。

3. 编写核心 ArkTS 代码

在 src/main/ets/entryability/EntryAbility.ts 中编写模型加载和推理逻辑。这里直接贴出完整的可运行代码：

// EntryAbility.ts
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import mindSporeLite from '@ohos.mindspore';

const MSLITE_CONTEXT = mindSporeLite.createContext({ device: 'CPU', numThread: 2 });

export default class EntryAbility extends UIAbility {
  private model: mindSporeLite.Model | null = null;

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // 在页面创建时加载模型
    this.loadModel();
    windowStage.loadContent('pages/Index', (err) => {
      if (err) {
        console.error('Failed to load content');
      }
    });
  }

  async loadModel(): Promise<void> {
    try {
      // 模型文件位于 resources/rawfile/models/ai_model.ms，编译时会打包
      const modelBuffer = await this.context.resourceManager.getRawFile('models/ai_model.ms');
      this.model = await mindSporeLite.Model.createFromBuffer(modelBuffer, MSLITE_CONTEXT);
      console.info('Model loaded successfully');
    } catch (err) {
      console.error('Model load failed:', err);
    }
  }

  async runInference(input: ArrayBuffer): Promise<ArrayBuffer> {
    if (!this.model) {
      throw new Error('Model not loaded');
    }
    const output = await this.model.predict(input);
    return output;
  }
}

这段代码完成了：

• 在 onWindowStageCreate 中预加载模型，避免首次推理卡顿。
• 使用 Model.createFromBuffer 从打包资源中加载模型数据。
• 提供 runInference 方法供页面调用。

注意事项：

• mindSporeLite.createContext 需要在主线程中调用，否则可能抛出 ERR_AI_DEVICE 错误。
• 模型文件必须放在 resources/rawfile/ 下，编译时会自动被打包到 HAP 中。
• Model.createFromBuffer 返回 Promise，但实际上内部涉及跨线程操作，官方文档没有提到底层是用了 TaskPool，所以不要在回调里直接操作 UI 组件状态。

4. 使用 DevEco CLI 构建

deveco build --mode module --module-name entry

命令解释：

• --mode module：仅构建指定模块，比全量构建快。
• --module-name entry：指定 entry 模块。默认工程包含 entry 模块。

如果需要生成 Release 包：

deveco build --mode release --sign-config ./sign/autoSign.json

签名配置可参考官方文档生成。

常见问题（真实踩坑）

问题1：DevEco Code 不触发 AI 补全

现象：输入 . 或 ( 后，没有补全候选列表。

原因：DevEco Code 的补全引擎依赖项目索引，首次打开大项目时索引尚未完成，或者模型路径配置错误。

解决方案：

• 等待索引完成（状态栏右下角有进度）。
• 在 Settings → Tools → DevEco Code 中检查“Enable Code Completion”是否勾选。
• 如果使用了本地模型，确保模型文件可读且路径正确。

问题2：构建时提示“hvigorw 找不到”

现象：运行 deveco build 报错 hvigorw: command not found。

原因：DevEco CLI 内部调用 hvigorw，但环境变量中缺少 hvigorw 路径。

解决方案：

• 确认 DevEco Studio 安装目录的 tools/hvigor/bin 已加入 PATH。
• 或者直接使用绝对路径：$DEVECO_HOME/tools/hvigor/bin/hvigorw build。
• 也可以在 DevEco Studio 的 Terminal 中运行，因为 IDE 已经自动配置了环境。

问题3：页面返回后 AI 模型状态丢失

现象：应用切换到后台再返回，推理调用报错 Model is destroyed。

原因：默认情况下，UIAbility 的重构（new instance）会销毁之前的模型对象。模型资源未做保存恢复处理。

解决方案：

• 使用全局单例管理模型实例，例如定义在 AppStorage 或通过 globalThis 存储模型引用。
• 在 onWindowStageWillDelete 回调中释放模型资源，但不要重复释放。

// 在 EntryAbility.ts 中
private static modelInstance: mindSporeLite.Model | null = null;

async loadModel(): Promise<void> {
  if (EntryAbility.modelInstance) {
    this.model = EntryAbility.modelInstance;
    return;
  }
  // 原始加载逻辑...
  EntryAbility.modelInstance = this.model;
}

最佳实践

1. 不要在 @Component 的 build() 中直接调用 runInference
   原因：build() 会频繁触发 UI 刷新，可能导致多次不必要推理。应通过 @State 控制触发时机，例如在 Button 的点击事件中调用。

2. 使用 TaskPool 处理耗时推理任务
   虽然 MindSpore Lite 内部已用了工作线程，但如果推理时间超过 50ms，建议自行用 @ohos.taskpool 封装，避免阻塞 UI 线程。ArkUI 的异步挂载（async）并不能真正迁移到子线程。

3. 预加载模型时机选在 onWindowStageCreate 之后
   不要在 onCreate 中加载，此时资源管理尚未完全初始化，getRawFile 可能返回空。实际项目中发现，在 onForeground 中加载更稳定。

Demo 入口

完整工程的 EntryAbility 见上，页面 pages/Index.ets 简单示例：

@Entry
@Component
struct Index {
  @State result: string = '';
  private ability: EntryAbility;

  aboutToAppear() {
    // 获取 Ability 引用，注意类型转换
    this.ability = getContext(this) as EntryAbility;
  }

  build() {
    Column() {
      Button('Run Inference')
        .onClick(async () => {
          const input = new ArrayBuffer(1024);
          try {
            const output = await this.ability.runInference(input);
            this.result = `Output size: ${output.byteLength}`;
          } catch (err) {
            this.result = `Error: ${err.message}`;
          }
        })
      Text(this.result)
        .fontSize(16)
    }
    .padding(20)
  }
}

FAQ

Q：DevEco CLI 与 hvigorw 什么关系？
A：DevEco CLI 是对 hvigorw 的封装，提供了更简洁的命令（如 deveco init、deveco build），内部自动传递参数。直接使用 hvigorw 也可，但 DevEco CLI 会自动检测 SDK 版本，减少配置错误。

Q：为什么模拟器上 AI 推理比真机慢很多？
A：模拟器没有硬件加速（如 NPU、GPU），MindSpore Lite 默认退回到 CPU 执行，且模拟器的 CPU 指令集可能与主流真机不同。建议 AI 推理始终在真机或开发板上验证。

Q：DevEco Code 的补全结果能否自定义？
A：目前只支持官方提供的 AI 补全（基于 HUAWEI 内部模型训练），无法自定义本地代码库的补全权重。但可以通过 .deveco-code.json 配置文件调整部分触发规则。

---

以上是 DevEco Code 和 DevEco CLI 在 AI 开发中的快速上手指南，重点在于避免那些官方文档没写清楚的陷阱。如果你在配置过程中遇到其他问题，欢迎在评论区交流。