Linux C++ SDK

前提条件

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

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

下载安装

音频格式说明

Websocket 链路音频格式说明：

• 上行：支持 pcm 和 opus 格式音频进行语音识别。仅支持用户送入pcm格式音频（16K采样率，16bit，单通道），opus格式音频由SDK内部自动完成编码。

• 下行：支持单通道 pcm、mp3和opus 音频流。其中opus音频流将会在SDK内部进行解码，用户收到的将是对应格式的pcm数据。

接口说明

CreateConversation

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

/**
 * @brief 创建交互，设置回调。对应销毁接口为DestroyConversation
 * @param onMessage : 各事件监听回调，参见下文具体回调
 * @param onEventTrackMessage : 用于SDK内部日志(info以上)通过回调送给上层
 * @param user_data : 回调返回
 * @return Conversation* : Conversation单例指针
 */
static Conversation* CreateConversation(
    const ConversationCallbackMethod onMessage,
    const EventTrackCallbackMethod onEventTrackMessage,
    void* user_data = NULL);

其中ConversationCallbackMethod类型如下：

ConversationCallbackMethod

SDK事件回调

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

ConvEvent

方法列表

ConvEventType

NetworkEventType

其中EventTrackCallbackMethod类型如下：

EventTrackCallbackMethod

获得关键埋点信息日志

/**
 * @brief SDK内部日志通过回调送给用户处理
 * @param ConvLogLevel ：返回日志的日志级别
 * @param const char* ：具体日志字符串
 * @param void* ：用户设置的user_data
 */
typedef void (*EventTrackCallbackMethod)(ConvLogLevel, const char*, void*);

enum ConvLogLevel {
  kConvLogLevelVerbose,
  kConvLogLevelDebug,
  kConvLogLevelInfo,
  kConvLogLevelWarning,
  kConvLogLevelError,
  kConvLogLevelNone,
};

DestroyConversation

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

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

Connect

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

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

百炼参数设置说明

{
	"word_list": [{
		"name": "小云",
		"type": "main"
	}]
}

{
  "nls_rule": {
    "header": [
      "Start_custom1"
    ],
    "payload":[
      "Start_task_group", 
      "Start_task"
    ]
  }
}

{
	"nls_params": {
		"Start_custom1": {
			"test": 1
		},
		"Start_task_group": "aigc",
		"Start_task": "multimodal-generation",
		"Start_function": "generation",
		"Start_model": "multimodal-dialog"
	}
}

Disconnect

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

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

Interrupt

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

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

SendAudioData

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

/**
 * @brief 推送音频数据
 * @param data : 音频数据，PCM格式
 * @param data_size : 音频数据字节数
 * @param type : 音频数据编码设置，暂未启用，设置无效。
 * @param timestamp : 此数据包的时间戳(ms)。
 * @return ConvRetCode : 状态码
 */
ConvRetCode SendAudioData(const uint8_t* data, size_t data_size,
                          EncoderType type = kEncoderNone,
                          uint64_t timestamp = 0);

SendRefData

推送参考音频数据，在音频数据送给播放器时推送。

/**
 * @brief 推送参考音频数据，在音频数据送给播放器时推送
 * @param data : 音频数据，PCM格式
 * @param data_size : 音频数据字节数
 * @param timestamp : 此数据包的时间戳(ms)。
 * @return ConvRetCode : 状态码
 */
ConvRetCode SendRefData(const uint8_t* data, size_t data_size,
                          uint64_t timestamp = 0);

SendResponseData

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

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

parameters参数设置

parameters示例

切换到视频模式

{
	"type": "prompt",
	"parameters": {
		"biz_params": {
			"videos": [{
				"action": "connect",
				"type": "voicechat_video_channel"
			}]
		}
	}
}

退出视频模式

{
	"type": "prompt",
	"parameters": {
		"biz_params": {
			"videos": [{
				"action": "exit",
				"type": "voicechat_video_channel"
			}]
		}
	}
}

发送图片进行问答

# 发送图片base64数据(支持小于180KB图片)
{
	"type": "prompt",
	"parameters": {
		"images": [{
			"type": "base64",
			"value": "base64String"
		}]
	}
}

# 发送图片链接
{
	"type": "prompt",
	"parameters": {
		"images": [{
			"type": "url",
			"value": "https://xxxxxxx"
		}]
	}
}

UpdateMessage

更新参数，如p2t参数，或者发送参数，如UpdateInfo。

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

更新自定义唤醒词（仅kws_duplex有效）

{
	"type": "update_local_modules",
	"work": "update_keywords_list",
	"wuw": {
		"word_list": [{
			"name": "小云",
			"type": "main"
		}]
	}
}

更新其他参数

{"type":"update_nls_parameters", "avatar":{}}
{"type":"update_nls_parameters", "client_info":{}}
{"type":"update_nls_parameters", "agent_chat":{}}

//【SDK V1.2.4 新增】
{"type":"update_nls_parameters", "extra_info":{}, "context":{}}

更新参数万能方法

用户自定义服务端交互参数，"type": "update_custom_nls_parameters" 表示使用用户自定义参数功能。

nls_rule 中规定参数在协议中添加的位置，如"payload": ["Start_custom2", "SendSpeech_custom3"] 表示在向服务端发送"Start"协议时，payload中添加参数"custom2":{"test":2}；"header": ["Start_custom1"] 表示在向服务端发送"Start"协议时，header中添加参数"custom1":{"test":1}。

{
	"type": "update_custom_nls_parameters",
	"nls_rule": {
		"header": ["Start_custom1"],
		"payload": ["Start_custom2", "SendHumanSpeech_custom3"],
		"context": ["Stop_custom4"]
	},
	"nls_params": {
		"Start_custom1": {
			"test": 1
		},
		"Start_custom2": {
			"test": 2
		},
       "SendHumanSpeech_custom3": {
			"test": 3
		},
		"Stop_custom4": {
			"test": 4
		}
	}
}

发送参数（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"
	}
}

SetAction

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

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

ConvAction

{
	"keyword_str": "小云",
	"keyword_tag": "other_keyword"
}

GetState

获得当前各种状态。

/**
 * @brief 获得当前状态
 * @param type : 状态类型
 * @return ConvRetCode : 状态码
 */
int GetState(StateType type);

StateType

DialogState

GetResponse

向SDK送入通过RTC获得的VoiceChat相关response。response将在VideoChat Native SDK内部进行解析，转成交互状态和相关事件给APP。

/**
 * @brief
 * 向SDK送入通过RTC获得的VoiceChat相关response。response将在VideoChat Native
 * SDK内部进行解析，转成交互状态和相关事件给APP。
 * @param params ：json string形式的初始化参数
 * @return ConvRetCode : 状态码
 */
ConvRetCode GetResponse(const char* params);

另外，如AvatarStateChanged请求的组装，处理通过updateMessage()，用此getResponse()也可，传入的格式如下：

{"type":"rtc","from_state":"2","seq_id":"1","to_state":"0"}
或
{"from_state":"2","seq_id":"1","to_state":"0"}
或
{"from_state":2,"seq_id":1,"to_state":0}
或
{"header":{"name":"AvatarStateChanged","namespace":"Conversation"},"payload":{"from_state":2,"seq_id":2,"to_state":0}}
或
{"header":{"name":"AvatarStateChanged","namespace":"Conversation"},"payload":{"from_state":"2","seq_id":"2","to_state":"0"}}

代码示例

语音对话初始化

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

void onMessage(ConvEvent* event, void* param) {
  ConvEvent::ConvEventType event_type = event->GetMsgType();
  int dialog_state = event->GetDialogStateChanged();

  if (event_type != ConvEvent::kSoundLevel &&
      event_type != ConvEvent::kBinary) {
    std::cout << "trigger onMessage -->>\n"
              << "  session id: " << event->GetSessionId() << "\n"
              << "  messge type: " << event->GetMsgTypeString() << "\n"
              << "  dialog state: " << dialog_state << "\n"
              << "  response: " << event->GetAllResponse() << std::endl;
  }

  switch (event_type) {
    case ConvEvent::kConversationFailed:
      // 对话发生错误
      break;
    case ConvEvent::kConversationStarted:
      // 对话建连成功
      break;
    case ConvEvent::kConversationCompleted:
      break;
    case ConvEvent::kSentenceBegin:
      break;
    case ConvEvent::kSentenceEnd:
      break;
    case ConvEvent::kDataOutputStarted:
      // 后续将接收语音合成数据, 这里可启动播放器。
      // 播放器启动后需要通知SDK
      break;
    case ConvEvent::kDataOutputCompleted:
      // 接收语音合成数据完成, 这里需要通知播放器已经送完数据。
      // 注意, 这里只是接收完语音合成数据, 而非播放完成, 缓存或播放器中还有大量数据待播放。
      // 完全播放完后必须通知SDK
      break;
    case ConvEvent::kBinary:
      break;
    case ConvEvent::kSoundLevel:
      break;
    case ConvEvent::kDialogStateChanged:
      // 可通过对话状态进行相关业务逻辑操作
      break;
    case ConvEvent::kInterruptAccepted:
      // 允许打断, 这里可以关闭正在播放的音频
      break;
    case ConvEvent::kInterruptDenied:
      break;
    case ConvEvent::kVoiceInterruptAccepted:
      // 允许打断, 这里可以关闭正在播放的音频
      break;
    case ConvEvent::kVoiceInterruptDenied:
      break;
    case ConvEvent::kHumanSpeakingDetail:
      break;
    case ConvEvent::kRespondingDetail:
      break;
  }
}

void onEtMessage(ConvLogLevel level, const char* log, void* user_data) {
  std::cout << " ==>> [" << level << "] " << log << std::endl;
}

ConversationCallbackMethod on_message_callback = onMessage;
EventTrackCallbackMethod on_et_callback = onEtMessage;
Conversation* conversation = Conversation::CreateConversation(on_message_callback,
                                                              on_et_callback, NULL);

语音对话发起建连

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

std::string gen_init_params() {
  Json::FastWriter writer;
  Json::Value root;
  Json::Value agent_chat;
  root["mode"] = g_mode;
  root["chain_mode"] = "ws";
  root["ws_version"] = 3;

  root["debug_mode"] = "xxxxxxx";
  root["workspace"] = "xxxxxxx";
  root["save_log"] = true;
  root["save_wav"] = true;
  root["log_level"] = g_log_level;

  root["url"] = "";
  root["apikey"] = "";
  root["app_id"] = "";
  root["workspace_id"] = "";

  Json::Value upstream;
  upstream["type"] = "AudioOnly";
  upstream["audio_format"] = "opus";  // asr格式，支持pcm,opus
  root["upstream"] = upstream;

  Json::Value downstream;
  downstream["type"] = "Audio";
  downstream["voice"] = "longxiaoxia_v2";
  downstream["sample_rate"] = 24000;  // default tts sample_rate is 24000
  downstream["audio_format"] = "pcm";  // 下发的音频编码格式，支持opu,pcm
  downstream["intermediate_text"] = "transcript,dialog";
  downstream["debug"] = true;
  root["downstream"] = downstream;

  Json::Value client_info; /* 额外扩充的用户信息 */
  client_info["user_id"] = "bin23439207";
  root["client_info"] = client_info;

  Json::Value dialog_attributes;
  dialog_attributes["prompt"] = "你是个有用的助手。";
  root["dialog_attributes"] = dialog_attributes;

  Json::Value acoustic_echo_cancelling_attributes;
  acoustic_echo_cancelling_attributes["enable_external_aec_module"] = false;
  root["acoustic_echo_cancelling_attributes"] =
      acoustic_echo_cancelling_attributes;

  Json::Value voice_activity_detection_attributes;
  voice_activity_detection_attributes["enable_external_vad_module"] = false;
  root["voice_activity_detection_attributes"] =
      voice_activity_detection_attributes;

  Json::Value key_words_spotting_attributes;
  key_words_spotting_attributes["enable_external_kws_module"] = false;
  key_words_spotting_attributes["independent_kws_mode"] = false;
  root["key_words_spotting_attributes"] = key_words_spotting_attributes;

  std::string result = writer.write(root);
  std::cout << "init params: " << result.c_str() << std::endl;
  return result;
}

// 发起建连, 可通过返回值判断是否建连成功。
// 若建连失败可通过返回值和回调信息进行判断。
ConvRetCode ret = conversation->Connect(gen_init_params().c_str());

语音对话结束

ConvRetCode ret = conversation->Disconnect();

语音对话释放

conversation->DestroyConversation();
conversation = NULL;

打断当前语音对话

对话正处于Responding状态可调用此接口打断，并进入Listening状态。

ConvRetCode ret = conversation->Interrupt();

PushToTalk模式用户开始说话

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

ConvRetCode ret = conversation->SetAction(kStartHumanSpeech);

PushToTalk模式用户结束说话

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

ConvRetCode ret = conversation->SetAction(kStopHumanSpeech);

文本合成TTS

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

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

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

Json::Value root;
root["text"] = "幸福是一种技能，是你摒弃了外在多余欲望后的内心平和。";
root["type"] = "transcript";

Json::StreamWriterBuilder writer;
writer["indentation"] = "";

ConvRetCode ret = conversation->SendResponseData(Json::writeString(writer, root).c_str());

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

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

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

Json::Value root;
root["text"] = "看看图片里是什么？";
root["type"] = "prompt";

Json::Value parameters;
Json::Value biz_params;

biz_params["user_defined_params"] = Json::Value(Json::objectValue);
Json::Value videos(Json::arrayValue);
{
    Json::Value video1;
    video1["action"] = "connect";//进入视频模式
    video1["type"] = "voicechat_video_channel";
    videos.append(video1);

    Json::Value video2;
    video2["action"] = "exit";//退出视频模式
    video2["type"] = "voicechat_video_channel";
    videos.append(video2);
}
biz_params["videos"] = videos;
parameters["biz_params"] = biz_params;

Json::Value images(Json::arrayValue);
{
    Json::Value image;
    // 发送图片base64数据的示例
    // 这里base64encode可借用SDK的辅助接口也可自行实现
    ConversationUtils utils;
    image["type"] = "base64";
    image["value"] = utils.Base64EncodeFromFilePath(path/*图片路径*/);
    
    // 发送图片链接的示例
    image["type"] = "url";
    image["value"] = "https://xxxx";
    
    images.append(image);
}
parameters["images"] = images;

root["parameters"] = parameters;

Json::StreamWriterBuilder writer;
writer["indentation"] = "";
ConvRetCode ret = conversation->SendResponseData(Json::writeString(writer, root).c_str());

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

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

// 发送图片base64数据的示例
// 这里base64encode可借用SDK的辅助接口也可自行实现
ConversationUtils utils;
std::string base64_content = utils.Base64EncodeFromFilePath(path/*图片路径*/);
if (!base64_content.empty()) {
  Json::Value root;
  root["type"] = "update_info";
  Json::Value parameters;
  parameters["biz_params"] = Json::objectValue;

  Json::Value client_info;
  Json::Value status;
  Json::Value bluetooth_announcement;
  bluetooth_announcement["status"] = "stopped";
  status["bluetooth_announcement"] = bluetooth_announcement;
  client_info["status"] = status;
  parameters["client_info"] = client_info;

  Json::Value image;
  image["type"] = "base64";
  image["value"] = base64_content;
  image["width"] = 480;
  image["height"] = 720;
  Json::Value images(Json::arrayValue);
  images.append(image);
  parameters["images"] = images;
  root["parameters"] = parameters;

  Json::StreamWriterBuilder writer;
  writer["indentation"] = "";
  conversation->UpdateMessage(Json::writeString(writer, root).c_str());
}

自定义提示词变量和传值

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

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

在控制台提示词编辑区顶部可通过自定义变量入口添加变量字段，并在Prompt正文中以${变量名}占位符形式引用。

• 在代码中设置变量。

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

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

  Json::Value biz_params;
  Json::Value user_prompt_params;
  user_prompt_params["user_name"] = "大米";
  biz_params["user_prompt_params"] = user_prompt_params;
  root["biz_params"] = biz_params;

  std::string result = writer.write(root);
  std::cout << "init params: " << result.c_str() << std::endl;
  return result;
}

// 发起建连, 可通过返回值判断是否建连成功。
// 若建连失败可通过返回值和回调信息进行判断。
ConvRetCode ret = conversation->Connect(gen_init_params().c_str());

自定义对话变量和传值

• 在管控台项目【对话变量】配置自定义变量。

添加一个name变量代表面前的人，添加一个emotion变量代表用户的心情。

在控制台提示词编辑区下方的对话变量面板中，单击右上角+ 添加按钮，依次录入变量名（如name、emotion）和对应描述（如面前的人、用户的心情）。

• 在代码中设置变量。

如下示例，设置"name" = "张三"和"emotion" = "难过"。

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

  Json::Value biz_params;
  Json::Value user_query_params;
  user_query_params["name"] = "张三";
  user_query_params["emotion"] = "难过";
  biz_params["user_query_params"] = user_query_params;
  root["biz_params"] = biz_params;

  std::string result = writer.write(root);
  std::cout << "init params: " << result.c_str() << std::endl;
  return result;
}

// 发起建连, 可通过返回值判断是否建连成功。
// 若建连失败可通过返回值和回调信息进行判断。
ConvRetCode ret = conversation->Connect(gen_init_params().c_str());

SDK错误码

时序图说明

duplex

push2talk

tap2talk