rtos平台极速交互SDK接入

**目 录**
1. 接入流程
2. SDK介绍
3. 参数配置说明
4. 功能模块说明
5. 快速集成体验
6. 注意事项
7. 名词解释

## 1. 接入流程

- 登陆[AIUI开放平台](https://aiui.xfyun.cn/)，创建应用
- 进入创建的应用，从应用信息中获取appid和相关密钥信息。新应用免费赠送1000次对话。如需增加授权，可联系讯飞（aiui_support@iflytek.com）申请。
- 下载[【附件】AIUI极速超拟人交互源码_v2.0.zip](/media/attachment/2025/07/AIUI%E6%9E%81%E9%80%9F%E8%B6%85%E6%8B%9F%E4%BA%BA%E4%BA%A4%E4%BA%92%E6%BA%90%E7%A0%81_v2.0.zip)进行对接开发，解压密码:123456

## 2. SDK介绍
- SDK接口说明：

| 名称              | 说明                                                       |
  |:----------------|:---------------------------------------------------------|
  | aiui_init       | 初始化AIUI实例                                                |
  | aiui_start      | 开启会话，一般在唤醒或者按键响应之后调用                                     |
  | aiui_send_audio | 发送音频数据（1ch 16k 16bit pcm音频数据流, 建议每次发送40ms音频量, 也就是1280字节） |
  | aiui_stop       | 停止数据发送, 断开会话                                             |
  | aiui_uninit     | 销毁AIUI交互实例, 释放相应资源                                       |

- aiui 事件回调函数原型:
  `typedef void (*aiui_event)(const void *user_param, aiui_callback_event_t *event);`
    - user_param：用户在调用 `aiui_init` 函数传入的自定义参数
    - event：事件数据结构体指针
      - event_type: 事件类型
      - result: 事件类型对应的数据结果. 具体的参见 `demo.c` 中 `process_aiui_event` 函数中的解析流程.

- SDK调用流程：
  * 持续对话: 适用于有回消且持续对话的场景, 通常使用唤醒词触发流程
    > 初始化(`aiui_init`) `-->` 启动会话(`aiui_start`) `-->` 写音频(`aiui_send_audio`) `-->` 回调收到tts音频送到播放器播放.
    >  * `-->` 若收到云端 Vad:Bos 前端点事件, 则清空当前播放的tts音频流, 打断停止播放
    >  * `-->` 若收到云端错误码(比如触发敏感词审核), 则关闭会话(`aiui_stop`), 如需开启新会话则调用`aiui_start`.
    >  * `-->` 若不再需要交互, 释放资源(`aiui_uninit`)
  * 单次交互: 适用于无回消, 或按键触发交互的场景
    > 初始化(`aiui_init`) `-->` 按键触发启动会话(`aiui_start`) `-->` 写音频(`aiui_send_audio`) `-->` 回调收到tts音频送到播放器播放, 若收到最后一帧音频(dts==2)时断开会话(aiui_stop)
    >  * `-->` 如需继续交互或者等按键再次触发时, 再次启动会话(`aiui_start`) `-->` ...
    >  * `-->` 若不再需要交互, 释放资源(`aiui_uninit`)

- 源代码说明（SDK以源码方式提供, 需要直接将源文件加入到工程中编译）:

| 头文件                                | 内容说明                                                                                                      |
  |:-----------------------------------|:----------------------------------------------------------------------------------------------------------|
  | aiui_api.h                         | aiui交互接口                                                                                                  |
  | aiui_log.h                         | log打印接口                                                                                                   |
  | aiui_socket_api.h                  | socket接口的二次封装, 某些平台需要在.c文件自行实现相应函数                                                                        |
  | aiui_http_api.h                    | http相关接口, 调用 aiui_socket_api.h  实现.                                                                       |
  | aiui_websocket_api.h               | websocket相关接口, 基于 aiui_http_api.h  实现, 若所处设备平台提供了websocket接口, 可将 aiui_websocket_api.c 中的实现指向平台websocket接口 |
  | aiui_message_parse.h               | 对云端下发的json数据进行解析, 解析出识别(iat), 语义(nlp), 合成(tts)结果                                                          |
  | base64.h, cjosn.h, md5.h, sha256.h | base64编解码, json解析以及Hash计算。如果与系统本身自带的函数有冲突, 先删掉, 然后在代码中引用系统自带接口即可                                          |

与头文件对应的`.c`文件在`src/aiui`目录下。

## 3. 参数配置说明

在 `tool/deploy/bin/aiui.json` 配置文件中定义了SDK配置参数
```json
{
    "login": {
        "appid": "",
        "key": "",
        "api_secret": ""
    },
    "global": {
        "scene": "main_box",
        "aiui_ver": "3",
        "uid": "12345678abcdefgh"
    },
    "tts": {
        "voice_name": "",
        "data_encoding": "raw"
    }
}
```

<table>
	<tr>
		<td>模块名称</td>
		<td>模块说明</td>
		<td>参数名称</td>
		<td>是否必传</td>
		<td>参数和取值说明</td>
	</tr>
	<tr>
		<td rowspan="3">login</td>
		<td rowspan="3">登录参数</td>
		<td>appid</td>
		<td>是</td>
		<td>AIUI应用信息appid</td>
	</tr>
	<tr>
		<td>key</td>
		<td>是</td>
		<td>AIUI应用信息appKey</td>
	</tr>
	<tr>
		<td>api_secret</td>
		<td>是</td>
		<td>AIUI应用信息apiSecret</td>
	</tr>
	<tr>
		<td rowspan="3">global</td>
		<td rowspan="3">全局参数</td>
		<td>scene</td>
		<td>是</td>
		<td>AIUI应用情景模式 示例：main_box</td>
	</tr>
	<tr>
		<td>aiui_ver</td>
		<td>是</td>
		<td>AIUI交互链路指定 3：极速交互 </td>
	</tr>
	<tr>
		<td>uid</td>
		<td>是</td>
		<td>用户唯一标识 不超过32字符长度（数字、字母） </td>
	</tr>
	<tr>
		<td rowspan="2">tts</td>
		<td rowspan="2">合成控制参数</td>
		<td>voice_name</td>
		<td>是</td>
		<td>合成发音人 x5_lingxiaoyue_flow</td>
	</tr>
	<tr>
		<td>data_encoding</td>
		<td>是</td>
		<td>合成音频格式 raw：原始pcm音频流</td>
	</tr>
	<tr>
</table>

## 4. 功能模块说明

| 模块         | 说明                                                                                                                          |
|:-----------|:----------------------------------------------------------------------------------------------------------------------------|
| 录音实现       | 实现Ubuntu环境系统录音处理，提供 1ch 16K 16bit PCM音频录音参考（开发者可基于该实现逻辑参考实现自己设备端录音实现）, linux 录音可参考 `src/audio_player`                       |
| socket通信   | 定义在 `aiui_socket_api.c` 中的接口实现websocket通信（开发者可基于自己设备平台做相应修改，大部分平台都不需要适配可直接使用）                                               |
| 播放实现       | 实现Ubuntu环境系统播放器处理，支持播放 1ch 16K 16bit合成pcm音频流（ 开发者可基于该实现逻辑参考适配自己设备端播放器控制）, linux 播音可参考 `src/audio_recorder`                  |
| OS相关接口     | 定义在 `aiui_wrappers_os.h` 中, 包括内存分配与释放/信号量/锁和线程等接口, 需要开发者针对特定的平台实现。`aiui_os_linux.c` 即为针对linux实现的参考示例代码                      |
| 加密交互       | 若需要对流量进行加密, 则需要提供依赖mbedtls实现SSL加密通信方式（程序默认关闭不启用）, 在设备端环境支持的情况下开发者如需使用SSL, 可以在 aiui_socket_api.c 中的将 `AIUI_SUPPORT_SSL` 宏打开。 |

## 5. 快速集成体验

- 在Ubuntu linux 快速体验

- 下载SDK开发包

- 安装必需软件：
      ```shell
      sudo apt install cmake libjack-jackd2-dev libasound2-dev pkg-config libpulse-dev
      ```

- 编译、运行：
      ```shell
      cd aiui_embedded_sdk
      mkdir build
      cd build
      cmake ..
      make
      cd ../tool/deploy/bin/
      ./aiui_demo
      ```

- 语音直接对话交互体验

> `aiui_demo` 会在启动后读取设备默认的声卡, 使用1c16k16b参数读取麦克风音频送入云端, 并将收到的TTS音频通过声卡播放出来。

- 非linux平台, 拷贝 `src/aiui` 源码到设备, 适配 `aiui_wrapper_os.h` 中的内存分配释放/信号量/线程接口，主要需要注意：

- 录音 适配
  - websocket 通信接口适配(若平台没有websocket实现, 且平台支持标准 BSD socket 也可使用SDK自带的实现)
  - 播放器 适配: 播放TTS音频流

## 6. 注意事项
- 设备与云端的系统时间误差不应超过`+-3`分钟, 否则设备在发起连接时会失败, 云端会校验当前时间与设备之间的差值, 超过指定的误差会被拒绝连接.
  > - 具体的连接错误信息可以在日志打印中查看.   
  >   - 常见的时间误差较大在连接时, 云端会返回 `403 Forbidden`. 
  >   - 若是appid信息授权错误, 云端会返回 `401 Unauthorized`. 
  > - 所以最佳实践是设备在联网成功后先对设备进行校时(比如使用NTP校时), 校时成功后再调用AIUI.   
  >   另外通过校时也可以初步判断网络的连通性, 如果校时都不成功, 那基本可以断定网络是不通的, 也没必要调用AIUI了.

- 极速交互只支持音频上传, 下发TTS音频播报. **不支持**文本交互和文本合成.

-  调用 `aiui_start` 到收到 `AIUI_EVENT_CONNECTED_TO_SERVER` 事件会有一定延迟, 所以在调用 `aiui_start` 后, 开始采集录音并保存到缓存队列中,
    收到 `AIUI_EVENT_CONNECTED_TO_SERVER`, 才开始从缓存队列中获取数据, 调用 `aiui_send_audio` 向云端发送数据,
    收到云端错误码(通常是命中审核,敏感词类, 服务异常)应主动断连(`aiui_stop`), 停止发送数据。
    若需要继续交互, 请在 `aiui_stop` 之后再次调用 `aiui_start`.

- 场景参数scene设置。一般地, 对于平台上创建的场景A, scene=A表示使用正式环境, scene=A_box则会使用测试环境。示例 main_box、main。

- 送入云端的音频应该是做过回声消除的音频, 否则设备会陷入自播自答的情况. 若设备没有接入回消算法, 可联系我司提供回消算法技术支持 <aiui_support@iflytek.com>

## 7. 名词解释

| sub 名称       | 说明                                                                                           |
|:-------------|:---------------------------------------------------------------------------------------------|
| event        | 云端下发的事件, 通常是人声Vad事件. Bos: 是开始说话; Eos: 是结束说话                                                  |
| iat          | 识别结果.                                                                                        |
| cbm_tidy     | 语义规整结果：请求包含多个问题时, 大模型会进行关键信息提取做意图拆分                                                          |
| cbm_semantic | 结构化语义结果：提供技能匹配结构化结果。当语义规整中吧请求结果拆分成多个意图时，可通过 `payload.cbm_meta.text` 中 `intent` 取值当前结果对应哪个意图。 |
| nlp          | 大模型语义结果：流式下发                                                                                 |
| tts          | 合成结果：流式下发合成音频流                                                                               |