RTOS C SDK

前提条件

开通阿里云百炼实时多模交互应用，获取Workspace ID、APP ID和API Key。

多模态实时交互服务接入架构

下载安装

接口说明

create_conversation

创建交互，设置回调。对应销毁接口为destroy_conversation。

/**
 * @brief 创建交互，设置回调。对应销毁接口为destroy_conversation
 * @param on_message : 各事件监听回调，参见下文具体回调
 * @param user_data : 回调返回
 * @return conv_instance_t : Conversation单例指针
 */
conv_instance_t create_conversation(const conv_event_callback_t on_message,
                                    void* user_data);

其中conv_event_callback_t类型如下：

conv_event_callback_t SDK事件回调

/**
 * @brief SDK各事件回调
 * @param conv_event_t*
 * ：回调事件，可通过调用其中具体方法获得事件及相关信息。具体方法见下方conv_event_t
 * @param void* ：用户设置的user_data
 */
typedef void (*conv_event_callback_t)(conv_event_t *, void *);

conv_event_t 成员列表

typedef enum {
  DIALOG_STATE_NONE = -1,
  DIALOG_STATE_IDLE = 0,
  DIALOG_STATE_LISTENING,
  DIALOG_STATE_RESPONDING,
  DIALOG_STATE_THINKING
} dialog_state_changed_t;

conv_event_type_t 事件类型

destroy_conversation

销毁交互。对应创建接口为create_conversation。

/**
 * @brief 销毁交互，若交互进行中，则内部完成conversation_disconnect
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t destroy_conversation();

conversation_connect

组装一个start请求，用于发起对服务端的链接。返回成功并不代表与语音对话服务链接成功，仅代表发起Start请求构建成功，是否链接成功以返回的Response为准。

/**
 * @brief 与服务端建立链接
 * @param params ：json string形式的初始化参数
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t conversation_connect(const char* params);

参数设置说明

typedef enum {
  CONV_LOG_LEVEL_VERBOSE,
  CONV_LOG_LEVEL_DEBUG,
  CONV_LOG_LEVEL_INFO,
  CONV_LOG_LEVEL_WARNING,
  CONV_LOG_LEVEL_ERROR,
  CONV_LOG_LEVEL_NONE
} conv_log_level_t;

conversation_disconnect

组装一个stop请求，用于发送指令告诉服务端中止链接。返回成功并不代表与VoiceChat Server断链成功，仅代表发起stop请求构建成功，是否断链成功以返回的Response为准。

/**
 * @brief 断开链接
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t conversation_disconnect();

conversation_interrupt

打断交互，使AI进入听状态。

/**
 * @brief 按键(Tap)打断。正在播放时，调用此接口请求打断播放。
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t conversation_interrupt();

conversation_send_audio_data

推送实时采集的音频数据。

/**
 * @brief 推送音频数据
 * @param data : 音频数据，PCM格式
 * @param data_size : 音频数据字节数
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t conversation_send_audio_data(const uint8_t* data,
                                             size_t data_size);

conversation_send_ref_data

推送参考音频数据，在音频数据送给播放器时推送。暂不启用此接口。

/**
 * @brief 推送参考音频数据，在音频数据送给播放器时推送
 * @param data : 音频数据，PCM格式
 * @param data_size : 音频数据字节数
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t conversation_send_ref_data(const uint8_t* data,
                                           size_t data_size);

conversation_send_response_data

Listening/Idle状态下，通知服务端与用户主动交互，可以直接把上传的文本转换为语音下发，也可以上传文本调用大模型，返回的结果再转换为语音下发。

/**
 * @brief
 * 通知服务端与用户主动交互，可以直接把上传的文本转换为语音下发，也可以上传文本调用大模型，返回的结果再转换为语音下发
 * @param params ：json string形式的初始化参数
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t conversation_send_response_data(const char* params);

params参数设置

parameters示例

{
  	"text": "今天天气怎么样？",
	"type": "transcript",
	"parameters": {
		"biz_params": {
			"user_defined_params": {},
			"videos": [{
				"action": "connect",
				"type": "voicechat_video_channel"
			}, {
				"action": "exit",
				"type": "voicechat_video_channel"
			}]
		},
		"images": [{
			"type": "base64",
			"value": "base64String"
		}]
	}
}

conversation_update_message

此接口为万能接口，可更新内部参数，或者直接发送定制事件，如UpdateInfo。

/**
 * @brief 发送如P2T相关的参数
 * @param params : 参数
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t conversation_update_message(const char* params);

发送参数（UpdateInfo）

百炼协议参数

百炼协议示例

{
  	"type": "update_info",
	"parameters": {
		"biz_params": {},
		"client_info": {
			"status": {
				"bluetooth_announcement": {
					"status": "stopped"
				}
			}
		},
		"images": [{
			"type": "base64",
			"value": "base64String"
		}]
	}
}

发送万能参数

{
	"type": "update_custom_message",
	"header": {
		"TEST1": "XXX"
	},
	"payload": {
		"TEST2": "YYY"
	}
}
返回的对应消息
{
	"header": {
		"TEST1": "XXX",
		"dialog_id": "2b9bea3d2b2749a0808bae06a9da493c",
		"namespace": "VoiceChat",
		"request_id": "c48cfe7bbadd485db2e387136ce6608c",
		"task_id": "fffffff707fe4c288869931b0eeeeeee"
	},
	"payload": {
		"TEST2": "YYY"
	}
}

conversation_set_action

需要有一个音频（播放）开始/结束事件告知到SDK。

/**
 * @brief 触发SDK动作，比如音频（播放）开始/结束事件告知到SDK
 * @param action : 触发的动作类型
 * @param data : 此次SDK动作附带的数据, 比如音频数据比如json字符串
 * @param data_size : 此次SDK动作附带的数据的字节数
 * @return conv_ret_code_t : 状态码
 */
conv_ret_code_t conversation_set_action(conv_action_t action,
                                        const uint8_t* data, size_t data_size);

conv_action_t

conversation_get_state

获得当前各种状态。

/**
 * @brief 获得当前状态
 * @param type : 状态类型
 * @return conv_ret_code_t : 状态码
 */
int conversation_get_state(state_type_t type);

state_type_t

dialog_state_changed_t

代码示例

语音对话初始化

这一步通过设置回调函数来接收交互过程中的所有事件，包括对话状态、对话结果等。

void event_callback(conv_event_t* event, void* param) {
  if (event->msg_type == CONV_EVENT_BINARY) {
    // 写入缓存或直接进行播放
  } else {
    printf("== %s ==\n", get_conv_event_type_string(event->msg_type));
    if (event->msg_type == CONV_EVENT_DIALOG_STATE_CHANGED) {
      // 可通过对话状态event->dialog_state进行相关业务逻辑操作
      printf("- DIALOG_STATE_CHANGED: %s -\n",
          get_dialog_state_changed_string(event->dialog_state));
    } else if (event->msg_type == CONV_EVENT_RESPONDING_STARTED) {
      // 后续将接收语音合成数据, 这里可启动播放器。
      // 播放器启动后需要通知SDK
      // conversation_set_action(ACTION_PLAYER_STARTED, NULL, 0);
    } else if (event->msg_type == CONV_EVENT_RESPONDING_ENDED) {
      // 接收语音合成数据完成, 这里需要通知播放器已经送完数据。
      // 注意, 这里只是接收完语音合成数据, 而非播放完成, 缓存或播放器中还有大量数据待播放。
      // 完全播放完后必须通知SDK
      // conversation_set_action(ACTION_PLAYER_STOPPED, NULL, 0);
    } else if (event->msg_type == CONV_EVENT_SPEECH_CONTENT ||
               event->msg_type == CONV_EVENT_RESPONDING_CONTENT) {
      cJSON* response_json = cJSON_Parse(event->msg);
      if (response_json != NULL) {
        cJSON* payload = cJSON_GetObjectItem(response_json, "payload");
        if (payload == NULL) {
          goto OUT_CONTENT;
        }
        cJSON* output = cJSON_GetObjectItem(payload, "output");
        if (output == NULL) {
          goto OUT_CONTENT;
        }
        cJSON* text = cJSON_GetObjectItem(output, "text");
        if (text == NULL) {
          goto OUT_CONTENT;
        }
        printf("%s: %s\n",
               event->msg_type == CONV_EVENT_SPEECH_CONTENT ? "HUMAN" : "AI",
                 text->valuestring);

      OUT_CONTENT:
        cJSON_Delete(response_json);
      }
    } else if (event->msg_type == CONV_EVENT_INTERRUPT_ACCEPTED) {
      // 允许打断, 这里可以关闭正在播放的音频
    } else if (event->msg_type == CONV_EVENT_CONVERSATION_FAILED ||
               event->msg_type == CONV_EVENT_CONNECTION_DISCONNECTED ||
               event->msg_type == CONV_EVENT_CONVERSATION_COMPLETED) {
      // 对话中止, 进行相关业务逻辑操作
    }

    // 可通过接收到的事件event->msg_type进行相关业务逻辑操作
  }
}

// 创建语音对话单例, SDK内部管理此单例
create_conversation(event_callback, NULL);

语音对话发起建连

建连参数把包括账号信息以json的形式构建，具体参考接口文档。PushToTalk模式下，建连成功后对话状态处于Idle状态。

const char* genInitParams() {
  cJSON* root = cJSON_CreateObject();
  
  cJSON_AddStringToObject(root, "apikey", "sk-");
  cJSON_AddStringToObject(root, "url", CONFIG_DEFAULT_URL);
  
  cJSON_AddStringToObject(root, "app_id", "user_app_id");
  cJSON_AddStringToObject(root, "workspace_id", "user_workspace_id");
  
  cJSON_AddStringToObject(root, "model", CONFIG_DEFAULT_PROTOCOL_MODEL);

  cJSON_AddNumberToObject(root, "chain_mode", CONFIG_DEFAULT_CONV_CHAIN_MODE);
  cJSON_AddNumberToObject(root, "ws_protocol_ver",
                          CONFIG_DEFAULT_WS_PROTOCOL_VER);
  cJSON_AddStringToObject(root, "mode", CONFIG_DEFAULT_CONV_SERVICE_MODE);
  cJSON_AddStringToObject(root, "task_group",
                          CONFIG_DEFAULT_PROTOCOL_TASK_GROUP);
  cJSON_AddStringToObject(root, "task", CONFIG_DEFAULT_PROTOCOL_TASK);
  cJSON_AddStringToObject(root, "function", CONFIG_DEFAULT_PROTOCOL_FUNCTION);
  cJSON_AddNumberToObject(root, "log_level", CONV_LOG_LEVEL_VERBOSE);

  cJSON* upstream = cJSON_CreateObject();
  cJSON_AddStringToObject(upstream, "type", CONFIG_DEFAULT_UPSTREAM_TYPE);
  cJSON_AddStringToObject(upstream, "mode", CONFIG_DEFAULT_CONV_SERVICE_MODE);
  cJSON_AddStringToObject(upstream, "audio_format",
                          CONFIG_DEFAULT_RECORDER_FORMAT);
  cJSON_AddItemToObject(root, "upstream", upstream);

  cJSON* downstream = cJSON_CreateObject();
  cJSON_AddStringToObject(downstream, "type", CONFIG_DEFAULT_DOWNSTREAM_TYPE);
  cJSON_AddStringToObject(downstream, "audio_format",
                          CONFIG_DEFAULT_PLAYER_FORMAT);
  cJSON_AddStringToObject(downstream, "voice", "longcheng_v2");
  cJSON_AddStringToObject(downstream, "intermediate_text",
                          CONFIG_DEFAULT_DOWNSTREAM_INTERMEDIATE_TEXT);
  cJSON_AddItemToObject(root, "downstream", downstream);

  cJSON* client_info = cJSON_CreateObject();
  cJSON_AddStringToObject(client_info, "user_id", "empty_user_id");
  cJSON_AddItemToObject(root, "client_info", client_info);

  cJSON* dialog_attributes = cJSON_CreateObject();
  cJSON_AddStringToObject(dialog_attributes, "prompt",
                          CONFIG_DEFAULT_DIALOG_ATTRIBUTES_PROMPT);
  cJSON_AddItemToObject(root, "dialog_attributes", dialog_attributes);

  char* result_json = cJSON_Print(root);
  cJSON_Delete(root);

  return result_json;
}

// 发起建连, 可通过返回值判断是否建连成功。
// 若建连失败可通过返回值和回调信息进行判断。
conv_ret_code_t ret = conversation_connect(genInitParams());

PushToTalk模式用户开始说话

对话状态处于Idle状态时调用此接口，对话状态进入Listening。若对话状态处于Responding和Thinking，则打断当前状态重新进入Listening。调用接口成功后，用户所说的话持续送给服务端进行交互，直到停止。

conv_ret = conversation_set_action(ACTION_START_HUMAN_SPEECH, NULL, 0);

PushToTalk模式用户结束说话

用户所说的话持续送给服务端进行交互，直到调用此接口，AI将根据用户所说的话进行对应的反馈。

conv_ret = conversation_set_action(ACTION_STOP_HUMAN_SPEECH, NULL, 0);

文本合成TTS

SDK支持通过文本直接请求服务端合成音频。

您需要在客户端处于Listening状态下发送conversation_send_response_data()请求。

若当前状态非Listening，需要先调用conversation_interrupt()接口打断当前播报。

cJSON *root = cJSON_CreateObject();
cJSON_AddItemToObject(root, "text", cJSON_CreateString("幸福是一种技能，是你摒弃了外在多余欲望后的内心平和。"));
cJSON_AddItemToObject(root, "type", cJSON_CreateString("transcript"));
char *json_str = cJSON_PrintUnformatted(root);

conv_ret_code_t ret = conversation_send_response_data(json_str);

cJSON_Delete(root);
free(json_str);

VQA交互发送图片实现多模交互

VQA 是在对话过程中通过发送图片实现图片+语音的多模交互的功能。

核心过程是语音或者文本通过conversation_send_response_data()接口发送多模交互指令。

cJSON *root = cJSON_CreateObject();

cJSON_AddItemToObject(root, "text", cJSON_CreateString("看看图片里是什么？"));
cJSON_AddItemToObject(root, "type", cJSON_CreateString("prompt"));

cJSON *parameters = cJSON_CreateObject();
cJSON_AddItemToObject(root, "parameters", parameters);

cJSON *biz_params = cJSON_CreateObject();
cJSON_AddItemToObject(parameters, "biz_params", biz_params);

cJSON *user_defined_params = cJSON_CreateObject();
cJSON_AddItemToObject(biz_params, "user_defined_params", user_defined_params);

cJSON *videos = cJSON_CreateArray();
cJSON_AddItemToObject(biz_params, "videos", videos);

// video1: 进入视频模式
cJSON *video1 = cJSON_CreateObject();
cJSON_AddItemToObject(video1, "action", cJSON_CreateString("connect"));
cJSON_AddItemToObject(video1, "type", cJSON_CreateString("voicechat_video_channel"));
cJSON_AddItemToArray(videos, video1);

// video2: 退出视频模式
cJSON *video2 = cJSON_CreateObject();
cJSON_AddItemToObject(video2, "action", cJSON_CreateString("exit"));
cJSON_AddItemToObject(video2, "type", cJSON_CreateString("voicechat_video_channel"));
cJSON_AddItemToArray(videos, video2);

cJSON *images = cJSON_CreateArray();
cJSON_AddItemToObject(parameters, "images", images);

// 这里演示两种上传base64数据和url的形式
// image1: base64
cJSON *image1 = cJSON_CreateObject();
cJSON_AddItemToObject(image1, "type", cJSON_CreateString("base64"));
cJSON_AddItemToObject(image1, "value", cJSON_CreateString("xxxxxxxx"));
cJSON_AddItemToArray(images, image1);
// image2: url
cJSON *image2 = cJSON_CreateObject();
cJSON_AddItemToObject(image2, "type", cJSON_CreateString("url"));
cJSON_AddItemToObject(image2, "value", cJSON_CreateString("https://xxxx"));
cJSON_AddItemToArray(images, image2);

char *json_str = cJSON_PrintUnformatted(root);
    
conv_ret_code_t ret = conversation_send_response_data(json_str);

cJSON_Delete(root);
free(json_str);

LiveAI交互发送图片实现多模交互

若使用此功能，需要Connect()入参中upstream.type设置为AudioAndVideo，即通过UpdateInfo接口持续发送图片数据来实现图片+语音的多模交互。图片大小只支持720p、480p。视频模式每500ms传一次。

// 发送图片base64数据的示例
const char *base64_content = "xxxxxxxx";

cJSON *root = cJSON_CreateObject();
cJSON_AddItemToObject(root, "type", cJSON_CreateString("update_info"));

cJSON *parameters = cJSON_CreateObject();
cJSON_AddItemToObject(root, "parameters", parameters);

cJSON *biz_params = cJSON_CreateObject();
cJSON_AddItemToObject(parameters, "biz_params", biz_params);

cJSON *client_info = cJSON_CreateObject();
cJSON_AddItemToObject(parameters, "client_info", client_info);
cJSON *bluetooth_announcement = cJSON_CreateObject();
cJSON_AddItemToObject(bluetooth_announcement, "status", cJSON_CreateString("stopped"));
cJSON *status = cJSON_CreateObject();
cJSON_AddItemToObject(status, "bluetooth_announcement", bluetooth_announcement);
cJSON_AddItemToObject(client_info, "status", status);

cJSON *images = cJSON_CreateArray();
cJSON_AddItemToObject(parameters, "images", images);

cJSON *image = cJSON_CreateObject();
cJSON_AddItemToObject(image, "type", cJSON_CreateString("base64"));
cJSON_AddItemToObject(image, "value", cJSON_CreateString(base64_content));
cJSON_AddNumberToObject(image, "width", 480);
cJSON_AddNumberToObject(image, "height", 720);
cJSON_AddItemToArray(images, image);

char *json_str = cJSON_PrintUnformatted(root);

conv_ret_code_t ret = conversation_update_message(json_str);

cJSON_Delete(root);
free(json_str);

自定义提示词变量和传值

• 在管控台项目【提示词】配置自定义变量。

如下图示例，定义了一个user_name字段代表用户昵称。并将变量user_name以占位符形式${user_name} 插入到Prompt 中。

• 在代码中设置变量。

如下示例，设置"user_name" = "大米"。

/* 以下示例在<语音对话发起建连>的示例上, 新增传入参数biz_params */
const char* genInitParams() {
  /* 其他初始化参数不再赘述, 请看<语音对话发起建连> */

  cJSON* biz_params = cJSON_CreateObject();
  cJSON_AddStringToObject(biz_params, "user_name", "大米");
  cJSON_AddItemToObject(root, "biz_params", biz_params);
  
  char* result_json = cJSON_Print(root);
  cJSON_Delete(root);

  return result_json;
}

// 发起建连, 可通过返回值判断是否建连成功。
// 若建连失败可通过返回值和回调信息进行判断。
conv_ret_code_t ret = conversation_connect(genInitParams());

语音对话结束

conv_ret ret = conversation_disconnect();

语音对话释放

conv_ret ret = destroy_conversation()

SDK错误码

时序图说明

push2talk

tap2talk