HarmonyOS开发：HMS Core AI能力集成全指南

核心要点：HMS Core为HarmonyOS开发者提供了一套完整的AI能力开放接口，涵盖语音、视觉、自然语言处理、推荐等多个领域。本文将系统讲解HMS Core AI能力的架构设计、集成流程与实战代码，帮助开发者快速将AI能力融入HarmonyOS应用。

一、背景与动机

想象一下这个场景：你刚做完一道菜，想识别一下热量——打开APP拍个照，卡路里就出来了；开车时想发条消息——语音助手帮你转成文字直接发送；购物时不知道买什么——推荐系统精准推送你感兴趣的商品。

这些看似"魔法"的功能，背后都是AI在默默工作。但问题来了：自己搞AI？ 从数据标注到模型训练再到部署优化，没有个半年根本搞不定。更别提端侧推理的性能优化了，那是个深坑。

HMS Core的出现，就是为了解决这个痛点。华为把自家多年积累的AI能力打包成SDK开放出来，你只需要几行代码就能调用——语音识别、文字识别、图像分类、语义理解、智能推荐……开箱即用，不用自己炼丹。

那为什么要在HarmonyOS上特别关注HMS Core AI？ 因为HarmonyOS的分布式架构让AI能力的调用方式有了质的变化——设备间可以协同推理，端云可以无缝切换，这在其他平台上是做不到的。

二、核心原理

2.1 HMS Core AI能力全景

HMS Core AI能力覆盖了六大核心领域：

2.2 架构设计

HMS Core AI在HarmonyOS上的集成架构分为三层：

graph TB
    subgraph APP["应用层"]
        A1[ArkTS业务代码]
        A2[UI交互组件]
        A3[数据处理逻辑]
    end

    subgraph SDK["HMS Core SDK层"]
        B1[ML Kit语音服务]
        B2[ML Kit视觉服务]
        B3[ML Kit NLP服务]
        B4[推荐服务SDK]
        B5[预测引擎SDK]
    end

    subgraph ENGINE["推理引擎层"]
        C1[端侧推理引擎]
        C2[云侧推理服务]
        C3[模型管理器]
        C4[分布式协同推理]
    end

    A1 --> B1 & B2 & B3 & B4 & B5
    B1 & B2 & B3 & B4 & B5 --> C1 & C2 & C3 & C4

    classDef primary fill:#4A90D9,stroke:#2C5F8A,color:#fff
    classDef warning fill:#F5A623,stroke:#C77D05,color:#fff
    classDef error fill:#D0021B,stroke:#8B0000,color:#fff
    classDef info fill:#7B68EE,stroke:#5B48C2,color:#fff
    classDef purple fill:#9B59B6,stroke:#6C3483,color:#fff

    class A1,A2,A3 primary
    class B1,B2,B3,B4,B5 warning
    class C1,C2,C3,C4 info

关键设计理念：

1. 端云协同：简单任务走端侧推理（低延迟、离线可用），复杂任务走云侧推理（高精度、大模型）
2. 分布式推理：HarmonyOS设备组网后，可将推理任务分配到多个设备并行执行
3. 模型热更新：通过模型管理器，可以在不更新APP的情况下更新AI模型

2.3 集成流程总览

flowchart LR
    A[注册开发者账号] --> B[创建应用获取AppID]
    B --> C[集成HMS Core SDK]
    C --> D[配置权限与签名]
    D --> E[初始化ML Kit]
    E --> F[调用AI能力]
    F --> G{端侧 or 云侧?}
    G -->|端侧| H[本地模型推理]
    G -->|云侧| I[云端API调用]
    H --> J[结果处理与UI展示]
    I --> J

    classDef primary fill:#4A90D9,stroke:#2C5F8A,color:#fff
    classDef warning fill:#F5A623,stroke:#C77D05,color:#fff
    classDef error fill:#D0021B,stroke:#8B0000,color:#fff
    classDef info fill:#7B68EE,stroke:#5B48C2,color:#fff
    classDef purple fill:#9B59B6,stroke:#6C3483,color:#fff

    class A,B,C primary
    class D,E warning
    class F,G info
    class H,I,J purple

三、代码实战

3.1 示例一：文字识别（OCR）集成

文字识别是最常用的AI能力之一，我们来实现一个拍照识别文字的功能。

// OCR文字识别服务 - 完整实现
import { mlTextRecognition } from '@hms.core/ml-kit';
import { camera } from '@kit.CameraKit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

// OCR识别结果数据模型
interface OCRResult {
  text: string;           // 识别出的文字
  confidence: number;     // 置信度 0-1
  language: string;       // 检测到的语言
  blocks: OCRBlock[];     // 文字块列表
}

interface OCRBlock {
  text: string;           // 块文字内容
  bounds: Rect;           // 文字区域边界
}

interface Rect {
  left: number;
  top: number;
  right: number;
  bottom: number;
}

@Entry
@Component
struct OCRRecognitionPage {
  @State resultText: string = '等待识别...';
  @State isProcessing: boolean = false;
  @State confidence: number = 0;
  @State detectedLanguage: string = '';
  @State ocrBlocks: OCRBlock[] = [];

  // 初始化文字识别器
  private textRecognizer: mlTextRecognition.MLTextRecognition | null = null;

  aboutToAppear(): void {
    this.initRecognizer();
  }

  // 初始化识别器配置
  private initRecognizer(): void {
    try {
      const config: mlTextRecognition.MLTextRecognitionConfig = {
        // 设置支持的语言，中文+英文是最常用的组合
        languages: ['zh', 'en'],
        // 开启密集文字模式，适合文档类图片
        enableDenseMode: true,
        // 开启文字边界框返回
        enableBorder: true,
      };
      this.textRecognizer = mlTextRecognition.MLTextRecognition.create(config);
      console.info('[OCR] 文字识别器初始化成功');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[OCR] 初始化失败: ${err.code} - ${err.message}`);
    }
  }

  // 从图片进行OCR识别
  private async recognizeFromImage(pixelMap: image.PixelMap): Promise<void> {
    if (!this.textRecognizer) {
      console.error('[OCR] 识别器未初始化');
      return;
    }

    this.isProcessing = true;
    this.resultText = '识别中...';

    try {
      // 将PixelMap转为ML可用的输入格式
      const mlImage = mlTextRecognition.MLImage.fromPixelMap(pixelMap);

      // 执行文字识别
      const result: mlTextRecognition.MLTextRecognitionResult =
        await this.textRecognizer.recognize(mlImage);

      // 解析识别结果
      this.parseResult(result);
      console.info('[OCR] 识别完成');
    } catch (error) {
      const err = error as BusinessError;
      this.resultText = `识别失败: ${err.message}`;
      console.error(`[OCR] 识别错误: ${err.code} - ${err.message}`);
    } finally {
      this.isProcessing = false;
    }
  }

  // 解析OCR结果
  private parseResult(result: mlTextRecognition.MLTextRecognitionResult): void {
    // 提取完整文本
    this.resultText = result.text || '';
    this.confidence = result.confidence || 0;
    this.detectedLanguage = result.language || 'unknown';

    // 提取文字块信息
    this.ocrBlocks = [];
    if (result.blocks && result.blocks.length > 0) {
      for (const block of result.blocks) {
        this.ocrBlocks.push({
          text: block.text || '',
          bounds: block.border || { left: 0, top: 0, right: 0, bottom: 0 },
        });
      }
    }
  }

  // 释放识别器资源
  aboutToDisappear(): void {
    if (this.textRecognizer) {
      this.textRecognizer.release();
      this.textRecognizer = null;
    }
  }

  build() {
    Column() {
      // 标题栏
      Text('文字识别')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 20 })

      // 识别结果展示区
      Scroll() {
        Column() {
          Text(this.resultText)
            .fontSize(16)
            .width('100%')
            .padding(16)
            .backgroundColor('#1a1a2e')
            .borderRadius(12)
            .fontColor('#e0e0e0')
        }
      }
      .layoutWeight(1)
      .width('100%')

      // 置信度和语言信息
      Row() {
        Text(`置信度: ${(this.confidence * 100).toFixed(1)}%`)
          .fontSize(14)
          .fontColor('#7B68EE')
        Text(`语言: ${this.detectedLanguage}`)
          .fontSize(14)
          .fontColor('#4A90D9')
          .margin({ left: 20 })
      }
      .width('100%')
      .padding({ left: 16, right: 16, top: 8, bottom: 8 })

      // 识别按钮
      Button(this.isProcessing ? '识别中...' : '拍照识别')
        .width('80%')
        .height(50)
        .fontSize(18)
        .backgroundColor(this.isProcessing ? '#666' : '#4A90D9')
        .borderRadius(25)
        .enabled(!this.isProcessing)
        .margin({ top: 16, bottom: 32 })
        .onClick(() => {
          // 实际项目中这里调起相机拍照，此处简化为示例
          console.info('[OCR] 开始识别');
        })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor('#0d0d1a')
  }
}

3.2 示例二：语音识别与语音合成联动

实现一个语音对话助手：语音输入→识别文字→处理→语音播报结果。

// 语音识别+合成联动服务
import { mlSpeechRecognition } from '@hms.core/ml-kit';
import { mlSpeechSynthesis } from '@hms.core/ml-kit';
import { BusinessError } from '@kit.BasicServicesKit';

// 语音对话消息模型
interface VoiceMessage {
  id: string;
  content: string;       // 消息内容
  isUser: boolean;       // 是否为用户消息
  timestamp: number;     // 时间戳
}

@Entry
@Component
struct VoiceAssistantPage {
  @State messages: VoiceMessage[] = [];
  @State isListening: boolean = false;
  @State isSpeaking: boolean = false;
  @State recognizedText: string = '';

  private speechRecognizer: mlSpeechRecognition.MLSpeechRecognition | null = null;
  private speechSynthesizer: mlSpeechSynthesis.MLSpeechSynthesis | null = null;

  aboutToAppear(): void {
    this.initSpeechServices();
  }

  // 初始化语音服务
  private initSpeechServices(): void {
    try {
      // 配置语音识别器
      const asrConfig: mlSpeechRecognition.MLSpeechRecognitionConfig = {
        language: 'zh-CN',          // 中文识别
        enablePunctuation: true,    // 开启自动标点
        enableSentenceTimeout: true, // 句级超时
      };
      this.speechRecognizer = mlSpeechRecognition.MLSpeechRecognition.create(asrConfig);

      // 配置语音合成器
      const ttsConfig: mlSpeechSynthesis.MLSpeechSynthesisConfig = {
        language: 'zh-CN',          // 中文合成
        person: mlSpeechSynthesis.MLSpeaker.FEMALE_ZH, // 女声
        speed: 1.0,                 // 正常语速
        volume: 1.0,                // 正常音量
      };
      this.speechSynthesizer = mlSpeechSynthesis.MLSpeechSynthesis.create(ttsConfig);

      console.info('[Voice] 语音服务初始化成功');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[Voice] 初始化失败: ${err.code} - ${err.message}`);
    }
  }

  // 开始语音识别
  private async startListening(): Promise<void> {
    if (!this.speechRecognizer || this.isListening) {
      return;
    }

    this.isListening = true;
    this.recognizedText = '';

    try {
      // 监听识别结果
      this.speechRecognizer.on('recognitionResult', (result) => {
        if (result.isFinal) {
          // 最终识别结果
          this.recognizedText = result.text;
          this.addMessage(result.text, true);
          // 自动处理并回复
          this.processAndReply(result.text);
        } else {
          // 中间结果（实时显示）
          this.recognizedText = result.text;
        }
      });

      // 开始识别
      await this.speechRecognizer.start();
      console.info('[Voice] 开始语音识别');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[Voice] 识别启动失败: ${err.code} - ${err.message}`);
      this.isListening = false;
    }
  }

  // 停止语音识别
  private async stopListening(): Promise<void> {
    if (!this.speechRecognizer || !this.isListening) {
      return;
    }

    try {
      await this.speechRecognizer.stop();
      this.isListening = false;
      console.info('[Voice] 停止语音识别');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[Voice] 停止失败: ${err.code} - ${err.message}`);
    }
  }

  // 处理用户输入并生成回复
  private async processAndReply(userText: string): Promise<void> {
    // 简单的本地规则回复（实际项目中可对接大模型）
    let reply: string;
    if (userText.includes('天气')) {
      reply = '今天天气晴朗，温度25度，适合外出活动。';
    } else if (userText.includes('时间')) {
      const now = new Date();
      reply = `现在是${now.getHours()}点${now.getMinutes()}分。`;
    } else if (userText.includes('你好') || userText.includes('嗨')) {
      reply = '你好呀！我是你的语音助手，有什么可以帮你的吗？';
    } else {
      reply = `我听到了你说"${userText}"，让我想想怎么回答你...`;
    }

    // 添加回复消息
    this.addMessage(reply, false);

    // 语音播报回复
    await this.speak(reply);
  }

  // 语音合成播报
  private async speak(text: string): Promise<void> {
    if (!this.speechSynthesizer) {
      return;
    }

    this.isSpeaking = true;
    try {
      await this.speechSynthesizer.speak(text);
      console.info('[Voice] 语音播报完成');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[Voice] 播报失败: ${err.code} - ${err.message}`);
    } finally {
      this.isSpeaking = false;
    }
  }

  // 添加消息到列表
  private addMessage(content: string, isUser: boolean): void {
    this.messages.push({
      id: Date.now().toString(),
      content: content,
      isUser: isUser,
      timestamp: Date.now(),
    });
  }

  aboutToDisappear(): void {
    this.speechRecognizer?.release();
    this.speechSynthesizer?.release();
  }

  build() {
    Column() {
      // 对话消息列表
      List() {
        ForEach(this.messages, (msg: VoiceMessage) => {
          ListItem() {
            Row() {
              if (msg.isUser) {
                // 用户消息靠右
                Text(msg.content)
                  .fontSize(16)
                  .padding(12)
                  .backgroundColor('#4A90D9')
                  .borderRadius({ topLeft: 16, topRight: 4, bottomLeft: 16, bottomRight: 16 })
                  .fontColor('#fff')
                  .constraintSize({ maxWidth: '70%' })
              } else {
                // 助手消息靠左
                Text(msg.content)
                  .fontSize(16)
                  .padding(12)
                  .backgroundColor('#2a2a4a')
                  .borderRadius({ topLeft: 4, topRight: 16, bottomLeft: 16, bottomRight: 16 })
                  .fontColor('#e0e0e0')
                  .constraintSize({ maxWidth: '70%' })
              }
            }
            .width('100%')
            .justifyContent(msg.isUser ? FlexAlign.End : FlexAlign.Start)
            .padding({ left: 16, right: 16, top: 4, bottom: 4 })
          }
        }, (msg: VoiceMessage) => msg.id)
      }
      .layoutWeight(1)
      .width('100%')

      // 实时识别文字
      if (this.isListening && this.recognizedText) {
        Text(`正在听: ${this.recognizedText}`)
          .fontSize(14)
          .fontColor('#7B68EE')
          .padding(8)
      }

      // 语音控制按钮
      Row() {
        Button(this.isListening ? '停止' : '开始说话')
          .width(160)
          .height(50)
          .fontSize(18)
          .backgroundColor(this.isListening ? '#D0021B' : '#4A90D9')
          .borderRadius(25)
          .onClick(() => {
            if (this.isListening) {
              this.stopListening();
            } else {
              this.startListening();
            }
          })

        if (this.isSpeaking) {
          Text('🔊 播报中...')
            .fontSize(14)
            .fontColor('#F5A623')
            .margin({ left: 16 })
        }
      }
      .margin({ top: 16, bottom: 32 })
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#0d0d1a')
  }
}

3.3 示例三：图像分类与端侧模型管理

实现一个智能相册分类功能，利用端侧模型对图片进行分类，并支持模型热更新。

// 图像分类与模型管理服务
import { mlImageClassification } from '@hms.core/ml-kit';
import { mlModelManager } from '@hms.core.ml-kit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// 分类结果模型
interface ClassificationResult {
  category: string;      // 分类名称
  confidence: number;    // 置信度
  categoryId: number;    // 分类ID
}

// 模型信息模型
interface ModelInfo {
  modelId: string;       // 模型标识
  version: string;       // 模型版本
  size: number;          // 模型大小(KB)
  isLatest: boolean;     // 是否最新版本
  downloadStatus: number; // 下载状态 0-未开始 1-下载中 2-已完成
}

@Entry
@Component
struct ImageClassificationPage {
  @State classifications: ClassificationResult[] = [];
  @State isClassifying: boolean = false;
  @State modelList: ModelInfo[] = [];
  @State currentModelVersion: string = 'v1.0.0';
  @State isUpdating: boolean = false;
  @State updateProgress: number = 0;

  private classifier: mlImageClassification.MLImageClassification | null = null;
  private modelManager: mlModelManager.MLModelManager | null = null;
  private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;

  aboutToAppear(): void {
    this.initClassifier();
    this.loadModelList();
  }

  // 初始化图像分类器
  private initClassifier(): void {
    try {
      // 使用端侧推理模式
      const config: mlImageClassification.MLImageClassificationConfig = {
        // 端侧分类，无需网络
        inferenceType: mlImageClassification.InferenceType.ON_DEVICE,
        // 设置最大返回分类数
        maxResults: 5,
        // 置信度阈值
        minConfidence: 0.1,
      };

      this.classifier = mlImageClassification.MLImageClassification.create(config);
      console.info('[Classification] 分类器初始化成功');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[Classification] 初始化失败: ${err.code} - ${err.message}`);
    }
  }

  // 加载可用模型列表
  private async loadModelList(): Promise<void> {
    try {
      this.modelManager = mlModelManager.MLModelManager.create(this.context);
      const models = await this.modelManager.getModelList();

      this.modelList = models.map((model) => ({
        modelId: model.modelId,
        version: model.version,
        size: model.size,
        isLatest: model.isLatest,
        downloadStatus: model.isDownloaded ? 2 : 0,
      }));

      console.info('[Model] 模型列表加载完成，共' + this.modelList.length + '个模型');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[Model] 加载模型列表失败: ${err.code} - ${err.message}`);
    }
  }

  // 执行图像分类
  private async classifyImage(pixelMap: image.PixelMap): Promise<void> {
    if (!this.classifier) {
      return;
    }

    this.isClassifying = true;
    this.classifications = [];

    try {
      const mlImage = mlImageClassification.MLImage.fromPixelMap(pixelMap);
      const results = await this.classifier.classify(mlImage);

      // 解析分类结果
      this.classifications = results.map((item) => ({
        category: item.className || '未知',
        confidence: item.confidence || 0,
        categoryId: item.classId || 0,
      }));

      // 按置信度降序排列
      this.classifications.sort((a, b) => b.confidence - a.confidence);
      console.info('[Classification] 分类完成，共' + this.classifications.length + '个结果');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[Classification] 分类失败: ${err.code} - ${err.message}`);
    } finally {
      this.isClassifying = false;
    }
  }

  // 检查并更新模型
  private async checkAndUpdateModel(): Promise<void> {
    if (!this.modelManager) {
      return;
    }

    this.isUpdating = true;
    this.updateProgress = 0;

    try {
      // 检查是否有新版本模型
      const updateInfo = await this.modelManager.checkUpdate('image_classification_v1');

      if (updateInfo.hasUpdate) {
        console.info(`[Model] 发现新版本: ${updateInfo.latestVersion}`);

        // 监听下载进度
        this.modelManager.on('downloadProgress', (progress) => {
          this.updateProgress = Math.floor(progress.percent * 100);
        });

        // 下载新模型
        await this.modelManager.download(updateInfo.modelId);
        this.currentModelVersion = updateInfo.latestVersion;
        console.info('[Model] 模型更新完成');
      } else {
        console.info('[Model] 当前模型已是最新版本');
      }
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[Model] 模型更新失败: ${err.code} - ${err.message}`);
    } finally {
      this.isUpdating = false;
    }
  }

  aboutToDisappear(): void {
    this.classifier?.release();
    this.modelManager?.release();
  }

  build() {
    Scroll() {
      Column() {
        // 标题
        Text('智能图像分类')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .fontColor('#e0e0e0')
          .margin({ bottom: 20 })

        // 分类结果列表
        if (this.classifications.length > 0) {
          Text('分类结果')
            .fontSize(18)
            .fontColor('#7B68EE')
            .margin({ bottom: 12 })

          ForEach(this.classifications, (item: ClassificationResult, index: number) => {
            Row() {
              Text(item.category)
                .fontSize(16)
                .fontColor('#e0e0e0')
                .layoutWeight(1)

              // 置信度进度条
              Progress({ value: item.confidence * 100, total: 100, type: ProgressType.Linear })
                .width(120)
                .color('#4A90D9')

              Text(`${(item.confidence * 100).toFixed(1)}%`)
                .fontSize(14)
                .fontColor('#F5A623')
                .width(60)
                .textAlign(TextAlign.End)
            }
            .width('100%')
            .padding(12)
            .backgroundColor('#1a1a2e')
            .borderRadius(8)
            .margin({ bottom: 8 })
          }, (item: ClassificationResult, index: number) => `${index}`)
        }

        // 模型管理区域
        Divider().margin({ top: 20, bottom: 20 })

        Text('模型管理')
          .fontSize(18)
          .fontColor('#7B68EE')
          .margin({ bottom: 12 })

        // 当前模型版本
        Row() {
          Text('当前版本:')
            .fontSize(14)
            .fontColor('#999')
          Text(this.currentModelVersion)
            .fontSize(14)
            .fontColor('#4A90D9')
            .margin({ left: 8 })
        }
        .width('100%')
        .margin({ bottom: 12 })

        // 更新进度
        if (this.isUpdating) {
          Progress({ value: this.updateProgress, total: 100, type: ProgressType.Linear })
            .width('100%')
            .color('#F5A623')
            .margin({ bottom: 8 })
          Text(`更新进度: ${this.updateProgress}%`)
            .fontSize(12)
            .fontColor('#999')
        }

        // 操作按钮
        Row() {
          Button('选择图片分类')
            .height(44)
            .fontSize(16)
            .backgroundColor('#4A90D9')
            .borderRadius(22)
            .enabled(!this.isClassifying)
            .onClick(() => {
              console.info('[Classification] 选择图片');
            })

          Button('检查模型更新')
            .height(44)
            .fontSize(16)
            .backgroundColor('#7B68EE')
            .borderRadius(22)
            .enabled(!this.isUpdating)
            .margin({ left: 12 })
            .onClick(() => {
              this.checkAndUpdateModel();
            })
        }
        .margin({ top: 16, bottom: 32 })
      }
      .width('100%')
      .padding(20)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#0d0d1a')
  }
}

四、踩坑与注意事项

4.1 权限配置踩坑

HMS Core AI能力需要一系列权限，最容易被遗漏的是网络权限和相机权限。在module.json5中必须配置：

{
  "requestPermissions": [
    { "name": "ohos.permission.INTERNET" },
    { "name": "ohos.permission.CAMERA" },
    { "name": "ohos.permission.MICROPHONE" },
    { "name": "ohos.permission.READ_MEDIA" }
  ]
}

踩坑点：语音识别需要MICROPHONE权限，OCR需要CAMERA权限，如果忘记配置，不会报编译错误，但运行时会静默失败。建议在调用AI能力前先做权限检查。

4.2 端侧模型下载时机

端侧AI能力首次使用时需要下载模型文件（通常5-50MB），千万不要在用户点击识别按钮时才下载。正确的做法是：

• 在APP启动或WiFi连接时后台预下载
• 提供模型管理页面让用户手动更新
• 使用MLModelManager检查模型状态

4.3 内存泄漏问题

MLTextRecognition、MLSpeechRecognition等对象持有系统资源，必须在页面销毁时调用release()。否则在频繁切换页面时会导致内存持续增长，最终OOM崩溃。

4.4 云侧API调用频率限制

云侧AI能力有QPS限制（通常免费版10 QPS），高频调用场景务必做好限流和重试：

// 简单的限流工具
class RateLimiter {
  private timestamps: number[] = [];
  private maxQPS: number;

  constructor(maxQPS: number) {
    this.maxQPS = maxQPS;
  }

  async acquire(): Promise<void> {
    const now = Date.now();
    // 清理1秒前的时间戳
    this.timestamps = this.timestamps.filter(t => now - t < 1000);

    if (this.timestamps.length >= this.maxQPS) {
      // 等待到最早的时间戳过期
      const waitTime = 1000 - (now - this.timestamps[0]);
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }

    this.timestamps.push(Date.now());
  }
}

4.5 HarmonyOS分布式场景注意事项

在分布式设备间调用AI能力时，要注意：

• 远端设备可能不支持某些AI能力，调用前需要做能力查询
• 分布式推理的数据传输有延迟，不适合实时性要求高的场景
• 跨设备调用需要额外的权限声明

五、HarmonyOS 6适配

5.1 API变更

HarmonyOS 6对HMS Core AI的API做了以下调整：

5.2 迁移指南

// HarmonyOS 5 写法
const recognizer = mlTextRecognition.MLTextRecognition.create(config);

// HarmonyOS 6 推荐写法（异步创建，避免主线程阻塞）
const recognizer = await mlTextRecognition.MLTextRecognition.createAsync(config);

// HarmonyOS 6 新增的AI权限组检查
import { aiPermission } from '@hms.core.ml-kit';

const hasPermission = await aiPermission.checkAIPermissionGroup([
  aiPermission.Permission.VOICE_RECOGNITION,
  aiPermission.Permission.IMAGE_ANALYSIS,
]);

5.3 性能优化

HarmonyOS 6新增了AI推理加速框架，在支持的设备上可以自动利用NPU加速：

// HarmonyOS 6 推理加速配置
const config: mlTextRecognition.MLTextRecognitionConfig = {
  languages: ['zh', 'en'],
  // 新增：启用NPU加速
  accelerator: mlTextRecognition.Accelerator.NPU_PREFERRED,
  // 新增：推理精度模式
  precisionMode: mlTextRecognition.PrecisionMode.PREFER_PERFORMANCE,
};

六、总结

本文系统讲解了HMS Core AI能力在HarmonyOS上的集成方法，核心知识点如下：

HMS Core AI集成知识图谱
├── 能力全景
│   ├── 语音服务（识别/合成/唤醒）
│   ├── 视觉服务（OCR/分类/检测/人脸）
│   ├── NLP服务（翻译/语义/实体）
│   ├── 推荐服务
│   ├── 安全服务（活体/风控）
│   └── 基础服务（预测引擎/模型管理）
├── 架构设计
│   ├── 三层架构：应用层→SDK层→引擎层
│   ├── 端云协同推理
│   ├── 分布式协同推理
│   └── 模型热更新
├── 集成流程
│   ├── 注册开发者→创建应用→集成SDK
│   ├── 配置权限→初始化→调用能力
│   └── 端侧/云侧选择策略
├── 踩坑要点
│   ├── 权限配置（MICROPHONE/CAMERA）
│   ├── 模型预下载时机
│   ├── 资源释放防泄漏
│   ├── 云侧API限流
│   └── 分布式能力查询
└── HarmonyOS 6适配
    ├── createAsync异步创建
    ├── AI权限分组
    ├── MLModelStore模型管理
    ├── NPU推理加速
    └── 自动最优设备发现

一句话总结：HMS Core AI能力让HarmonyOS开发者无需从零构建AI基础设施，几行代码即可获得语音、视觉、NLP等核心AI能力，端云协同+分布式推理是其在HarmonyOS上的独特优势。