HarmonyOS SDK 实时多模交互接口

// 发布产物工程 entry/oh-package.json5
"dependencies": {
  "@ali/convsdk": "file:./libs/convsdk.har",             // 语音对话 SDK
  "@ali/mmsdk": "file:./libs/multimodal_sdk.har"         // 多模态对话 SDK
}

/**
  * 初始化对话类
  * @param url: 服务端地址
  * @param chainMode: 链路模式
  * @param workspaceId: 工作空间 ID
  * @param appId: 应用 id
  * @param dialogMode: 对话模式
  */
constructor(url: string, chainMode: ChainMode, workspaceId: string, appId: string, dialogMode: DialogMode)

/**
 * 设置应用上下文，供 NativeConversation 资源拷贝等使用。
 * 在使用 createConversation 前必须先调用本方法。
 * @param context 应用上下文
 */
setContext(context: common.UIAbilityContext): void

/**
  * 创建会话
  * @param requestParam 请求参数
  * @param chatCallback 对话回调
  */
async createConversation(params: MultiModalRequestParam, chatCallback: IDialogCallback): Promise<void>

/**
 * 连接、启动对话
 * @param apiKey   API Key
 * @param dialogId 对话 ID，新会话传空字符串
 * @param taskId   任务 ID
 */
start(apiKey: string, dialogId: string, taskId: string): void

// 便捷方法：不传 taskId（等价于 start(apiKey, dialogId, "")）
startTwo(apiKey: string, dialogId: string): void

/**
  * 断开、结束对话
  */
stop(): void

/**
  * 销毁实例
  */
destroy(): void

/**
  * 设置对话超时时间，当服务未在指定时间内检出用户说话时上报 timeout 事件
  * @param timeout 超时时间，单位 ms
  */
setDialogTimeout(timeout: number): void

/**
  * 打断 AI 说话
  */
interrupt(): void

/**
 * 通知服务端开始上传音频，注意需要在 Listening 状态才可以调用。
 * 只需要在 Push2Talk 模式下调用。
 */
startSpeech(): void

/**
 * 通知服务端结束上传音频。只需要在 Push2Talk 模式下调用。
 * Push2Talk 用户结束说话。
 */
stopSpeech(): void

/**
 * Push2Talk 用户取消说话
 */
cancelSpeech(): void

/**
  * 上传音频。
  * @param audioData 音频帧数据
  */
sendAudioData(audioData: Uint8Array | null): void

/**
 * 发送参考音频（回声消除 AEC 参考）
 * @param audioData 参考音频数据（需与播放数据一致）
 */
sendRefData(audioData: Uint8Array | null): void

/**
 * 请求服务端回答指定问题或做 TTS 播放出来
 * @param type   transcript 表示直接把文本转语音，prompt 表示把文本送大模型回答，
 *               visual_qa 表示图片识别
 * @param text   对应的文本；visual_qa 时为图片链接或 base64（≤180KB）
 * @param params 额外参数
 */
requestToRespond(type: string, text: string, params: Record<string, Object>): void

/**
 * 推送视频帧
 * @param videoFrame 视频帧数据
 * @param callback   送帧结果回调
 */
sendVideoFrame(videoFrame: TYVideoFrame, callback: IVideoChatPushFrameCallback): void

/**
 * 发送语音回复开始
 */
sendResponseStarted(): void

/**
 * 发送语音回复结束
 */
sendResponseEnded(): void

/**
 * 当前配置是否是双工模式
 */
isDuplexMode(): boolean

/**
 * 当前配置是否是 Push2Talk 模式（仅在 Push2Talk 下返回 true）
 */
isPush2TalkMode(): boolean

/**
 * 当前配置是否是 Tap2Talk 模式（仅在 Tap2Talk 下返回 true）
 */
isTap2TalkMode(): boolean

/**
 * 获取当前对话状态
 */
getDialogState(): DialogState

/**
 * 获取当前网络质量
 */
getNetworkQuality(): number

/**
 * 恢复/继续交互
 */
beginInteraction(): void

/**
 * 更新对话信息
 * @param paramValue 更新参数
 */
updateInfo(paramValue: Record<string, Object>): void

/**
 * 发送心跳
 */
sendHearBeat(): void

/**
 * 是否使用 RTC 内置音频采集（默认 true）
 */
static isRtcUseInternalAudio(): boolean
static setRtcUseInternalAudio(useInternal: boolean): void

/**
 * 是否使用 RTC 内置视频采集（默认 true）
 */
static isRtcUseInternalVideo(): boolean
static setRtcUseInternalVideo(useInternal: boolean): void

/**
 * 对话回调接口
 */
export interface IDialogCallback {
  /**
   * 对话启动结果
   */
  onStartResult(isSuccess: boolean, errorInfo: TYError | null): void;

  /**
   * 主动打断结果
   */
  onInterruptResult(isSuccess: boolean, errorInfo: TYError | null): void;

  /**
   * 对话准备完成，多端加入通道后回调，此时才能调用业务接口
   * @param dialogId 会话 ID
   */
  onReadyToSpeech(dialogId: string): void;

  /**
   * 状态切换回调，包含 DIALOG_IDLE / DIALOG_LISTENING / DIALOG_THINKING / DIALOG_RESPONDING
   */
  onConvStateChangedCallback(state: DialogState): void;

  /**
   * 音量强度回调 0-100
   * @param audioLevel 音量强度 0-100
   * @param audioType  音量来源：MIC 本地采集 / PLAYER 远端 TTS
   */
  onConvSoundLevelCallback(audioLevel: number, audioType: TYVolumeSourceType): void;

  /**
   * 对话超时回调
   * @param timeout 超时时间，单位 ms
   */
  onSpeechTimeout(timeout: number): void;

  /**
   * 播放音频数据回传
   */
  onPlaybackAudioData(bytes: Uint8Array): void;

  /**
   * 对话过程中的异常信息
   */
  onErrorReceived(errorInfo: TYError): void;

  /**
   * 对话事件回调
   */
  onConvEventCallback(var1: ConvEvent | null): void;

  /**
   * 调试信息回传
   */
  onDebugInfoTrack(level: number, type: TYDebugInfoType, debugInfo: string): void;

  /**
   * 下行合成语音数据回调
   */
  onSynthesizedSpeech(bytes: Uint8Array): void;

  /**
   * 唤醒词命中回调
   */
  onKeyWordSpotted(word: string, type: KeyWordsType): void;
}

{
  "header": { "request_id": "9B32878****************3D053", "status_code": 200 },
  "payload": {
    "output": {
      "event": "SpeechContent",
      "dialog_id": "b39398c9dd8147***35cdea81f7",
      "text": "一二三",
      "finished": false
    }
  }
}

{
  "header": { "request_id": "9B32878****************3D053", "status_code": 200 },
  "payload": {
    "output": {
      "event": "AIResponse",
      "dialog_id": "b39398c9dd8147***35cdea81f7",
      "text": "好的，这是一个测试。",
      "finished": true
    }
  }
}

/**
  * 对话异常
  * @param errorInfo: 错误信息
  */
onErrorReceived(errorInfo: TYError): void;

// 开启双工模式
let dialog = new MultiModalDialog(url, ChainMode.WEBSOCKET, workspaceId, appId, DialogMode.DUPLEX)
dialog.setContext(context)
MultiModalDialog.wsUseInternalAEC = true
let requestParam = MultiModalRequestParam.builder().build()
await dialog.createConversation(requestParam, this)

// 输入麦克风录音（录音文件如为服务器识别需要，注意采样率 16k、PCM）
dialog.sendAudioData(audioData)

// 在 onSynthesizedSpeech 回调中，将下行 TTS 数据作为 AEC 参考上送
// bytes 为该回调收到的数据，同时交给应用播放器播放
dialog.sendRefData(bytes)

// 应用播放器的采样率需与下行 TTS 采样率一致

// 收到 "visual_qa" 指令
private handleVisualQaCommand() {
  // 1. 拍照或从相册取图
  let imageUrl = uploadImageToOSS()      // 生成图片公共链接
  // 2. 发送图片链接请求图片识别
  dialog.requestToRespond("visual_qa", imageUrl, {})

  // 3. 或直接上送 base64 图片（≤180KB）
  let imageBase64 = getLocalImageBase64()
  dialog.requestToRespond("visual_qa", imageBase64, {})
}

// 1. 设置交互类型为 AudioAndVideo
let dialog = new MultiModalDialog(url, ChainMode.WEBSOCKET, workspaceId, appId, DialogMode.DUPLEX);
// 交互类型通过上行参数 UpStream.type 设置为AudioAndVideo
// UpStream 默认为 AudioOnly；LiveAI 视频通话必须显式设置为 AudioAndVideo
let requestParam = MultiModalRequestParam.builder()
  .upStream(UpStream.builder().type('AudioAndVideo').build())
  .build()

// 2. 对话建立后每 500ms 上送一张视频帧
// sendVideoFrame 需要携带送帧结果回调（IVideoChatPushFrameCallback）
class VideoFramePushCb implements IVideoChatPushFrameCallback {
  onFinishPushFrame(isSuccess: boolean, errorMsg: string): void {
    //处理送帧结果，例如失败时打印日志并重试
  }
}
setInterval(() => {
  dialog.sendVideoFrame(getNextVideoFrame(), new VideoFramePushCb())   // LiveAI 视频帧
}, 500)

// 在 Listening 状态请求 TTS 合成
dialog.requestToRespond("transcript", "幸福是一种技能，是你摒弃了外在多余欲望后的内心平和。", {})

// 设置用户自定义提示词变量
let requestParam = MultiModalRequestParam.builder()
  .bizParams(BizParams.builder()
    .userPromptParams({ user_name: "大米" })
    .build())
  .build()

// 设置 ASR 纠错词表
let requestParam = MultiModalRequestParam.builder()
  .upStream(UpStream.builder()
    .asrPostProcessing([
      ReplaceWord.builder()
        .source("1加1")
        .target("一加一")
        .matchMode("partial")
        .build()
    ])
    .build())
  .build()