3.2.2 参数配置说明

<div style="max-width: 100%; margin: 20px auto;">
    
    <div style="background-color: #ffffff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); overflow: hidden; font-family: 'Comic Sans MS', cursive, sans-serif;">
        
        
        <div style="background-color: #F4F8FA; padding: 1px 10px; border-bottom: 1px solid #dee2e6; display: flex; justify-content: space-between; align-items: center;">
            <div style="color: #0E42D2; font-weight: bold;font-size: 1.3rem;">AIUI基础参数概述</div>
            <div>
            </div>
        </div>
        
        <div style="padding: 25px; line-height: 29px; background-image: linear-gradient(transparent 26px, #dee2e6 27px, #dee2e6 27px, transparent 27px); background-size: 100% 28px; min-height: 100px; color: #333;">
		<div>AIUI SDK工作时，先通过读取配置文件（aiui.cfg）加载内置的参数进行初始化工作。配置文件参数设置属于<strong>静态参数设置</strong>，SDK加载后本地默认构建参数结构体，每次会话进行携带。当用户需要再对话过程中对业务参数进行动态修改时，AIUI SDK也提供<strong>动态参数设置</strong>方式。</div>
		<a href="#AIUI静态基础参数设置" style="color: #6f42c1; font-weight: 500;">
		<strong>- AIUI静态基础参数设置>>>点击跳转&emsp;&emsp;&emsp;</strong></a>
		&emsp;&emsp;<a href="#AIUI动态参数设置概述" style="color: #6f42c1; font-weight: 500;"><strong>- AIUI动态参数设置概述>>>点击跳转&emsp;&emsp;&emsp;</strong></a>
        </div>
        
        </div>
    </div>
</div>

<div style="display: flex; align-items: flex-start; gap: 16px; padding: 16px; background: #fff5f6; border-radius: 5px; border-left: 4px solid #e83e8c; box-shadow: 0 4px 12px rgba(255, 215, 0, 0.08); margin-bottom: 16px; transition: transform 0.2s ease, box-shadow 0.2s ease;">
  <div>
    <div style="font-weight: 600; margin-bottom: 4px;">温馨提示</div>
    <div style="font-size: 14px; line-height: 1.5;">动态参数设置仅支持交互服务业务相关参数设置，SDK非业务参数不支持动态修改，例如appid等信息。</div>
  </div>
</div>

## 1. AIUI静态基础参数设置
AIUI SDK基础参数主要分为以下模块：
- 登录参数：login
- 全局参数：global
- 交互控制参数：interact
- 业务参数：speech
- 本地vad参数：vad
- 用户自定义参数：userparams
- 音频交互参数：audioparams
- 语音识别参数：iat
- 语音合成参数：tts
- 语音唤醒：ivw
- 录音控制参数：recorder
- SDK日志设置参数：log

### 1.1. 配置文件示例
AIUI初始化时会读取cfg配置，格式是json，参数如下：
~~~ json
{
    "login":{
        "appid": "",
        "key":"",
        "api_secret": ""
    },
	"global":{
		"scene":"main_box",
		"clean_dialog_history":"auto",
		/* 1：传统语义 、2：通用大模型、3：极速超拟人 */
		"aiui_ver": "1"
	},
	"interact":{
		"interact_timeout":"60000",
		"result_timeout":"5000"
	},
	"speech":{
		"data_source": "sdk",
		"wakeup_mode": "vtn",
		"interact_mode": "oneshot",
		"work_mode": "intent",
		"audio_source": 7
	},
	"vad":{
		"vad_enable":"1",
    	"engine_type":"evad",
    	"res_type":"assets",
    	"res_path":"vad/evad_16k.jet",
    	"vad_bos":"5000",
    	"vad_eos":"1000",
    	"threshold":"0.7",
    	"speech_timeout":"5000"
	},
	/* 用户参数，透传到后处理(非必须)*/
	"userparams":{
		"xxxx": "xxx" //自定义键值对参数或json数据
	},
	/*音频交互参数*/
	"audioparams":{
		"msc.lng": "117.16334474",  // 经度
		"msc.lat":"31.82102191"     // 纬度
	},
	// 识别（音频输入）参数
	"iat":{
		"sample_rate":"16000"
	},
	// 合成和播报参数
	"tts": {
		"engine_type": "cloud",
		"vcn": "x2_xiaojuan",
		"play_mode": "sdk",
		"buffer_time": "0",
		"stream_type": "3",
		"audio_focus": "0"
	},
    // 唤醒参数
    "ivw":{
        "mic_type": "mic1",
        "res_type": "path",
        "res_path": "/sdcard/AIUI/ivw/vtn/vtn.ini"
    },
    // 录音参数
 	"recorder":{
 	    "channel_count": 1,
 	    "channel_filter": "0,-1"
 	},
	/* 日志设置
    "log": {
        "debug_log": "0",
        "save_datalog": "0",
        "datalog_path": "",
        "datalog_size": 1024,
        "raw_audio_path": ""
    }
}
~~~

### 1.2. 配置字段说明

<table>
	<tr>
		<td colspan="2" align="center"><b>模块名称</b></td>
		<td colspan="3" align="center"><b>模块说明</b></td>
	</tr>
	<tr>
		<td><b>模块名称</b></td>
		<td><b>模块说明</b></td>
		<td><b>参数名称</b></td>
		<td><b>是否必传</b></td>
		<td><b>参数和取值说明</b></td>
	</tr>
	<tr>
		<td rowspan="3"><b>login</b></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"><b>global</b></td>
		<td rowspan="3">全局参数</td>
		<td>scene</td>
		<td>是</td>
		<td>AIUI应用情景模式</td>
	</tr>
	<tr>
		<td>aiui_ver</td>
		<td>否</td>
		<td><b>AIUI交互链路指定</b><br>1：传统语义链路<br>2：大模型语义链路（6.6.xxx及以上版本支持）<br>3：极速超拟人链路（6.8.xxx及以上版本支持）<br></td>
	</tr>
	<tr>
		<td>clean_dialog_history</td>
		<td>否</td>
		<td><b>清除交互历史设置</b><br>auto：自动清除历史（默认模式）<br>user：用户手动清除历史<br></td>
	</tr>
	<tr>
		<td rowspan="2"><b>interact</b></td>
		<td rowspan="2">交互控制参数</td>
		<td>interact_timeout</td>
		<td>否</td>
		<td><b>交互超时(单位：ms)</b><br>即唤醒之后，如果在这段时间内无有效交互则重新进入待唤醒状态，<br>取值：[10000,180000)。<br>默认为1min。</td>
	</tr>
	<tr>
		<td>result_timeout</td>
		<td>否</td>
		<td><b>结果超时(单位：ms)</b><br>即检测到语音后端点后一段时间内无结果返回则抛出10120错误码。<br>默认值：5000。</td>
	</tr>
	<tr>
		<td rowspan="6"><b>speech</b></td>
		<td rowspan="6">业务相关参数</td>
		<td>data_source</td>
		<td>是</td>
		<td><b>录音数据来源配置</b><br>sdk：sdk内部录音<br>user： 外部录音</td>
	</tr>
	<tr>
		<td>wakeup_mode</td>
		<td>否</td>
		<td><b>唤醒设置</b><br>off：关闭唤醒<br>vtn：vtn2.0版本唤醒开关</td>
	</tr>
	<tr>
		<td>interact_mode</td>
		<td>是</td>
		<td><b>交互模式设置</b><br>continuous：持续交互，对于语音即“一次唤醒，多次交互”<br>oneshot：（默认模式）一次交互，对于语音即“一次唤醒，一次交互”</td>
	</tr>
	<tr>
		<td>work_mode</td>
		<td>否</td>
		<td><b>SDK工作模式设置</b><br>intent：默认取值，SDK进行音频数据上传获取交互意图<br>rec_only：只录音，开发者仅需要语音唤醒时可配</td>
	</tr>
	<tr>
		<td>audio_source</td>
		<td>否</td>
		<td><b>系统录音设置：Android系统配置</b><br>1：对应安卓的AudioSource取值为MIC<br>7：（安卓的AudioSource取值为VOICE_COMMUNICATION（带回声消除，但某些机型不支持）</td>
	</tr>
	<tr>
		<td>audio_captor</td>
		<td>否</td>
		<td><b>音频源设置</b><br>system：系统录音<br>portaudio：设备具有独立声卡时配置成portaudio，仅支持windows/linux平台</td>
	</tr>
	<tr>
		<td rowspan="10"><b>vad</b></td>
		<td rowspan="10">音频端点检测参数</td>
		<td>vad_enable</td>
		<td>是</td>
		<td><b>VAD启用设置</b><br>1：(默认参数)开启vad<br>0：关闭vad</td>
	</tr>
	<tr>
		<td>engine_type</td>
		<td>是</td>
		<td><b>VAD引擎类型</b><br>取值有 meta、evad，注意该参数与实际加载的vad资源要对应			</td>
	</tr>
	<tr>
		<td>res_type</td>
		<td>是</td>
		<td><b>VAD资源类型</b><br>使用模型vad时必须设置，取值说明如下<br>assets：assets资源（apk工程的assets文件）<br>res：res资源（apk工程的res文件）<br>path：path资源（sdcard文件）			</td>
	</tr>
	<tr>
		<td>res_path</td>
		<td>是</td>
		<td><b>VAD资源文件路径</b><br>使用模型vad时必须设置。</td>
	</tr>
	<tr>
		<td>vad_bos</td>
		<td>否</td>
		<td><b>VAD前端超时时间</b><br>单位：毫秒 取值范围：[1000,10000] 默认值： "5000"			</td>
	</tr>
	<tr>
		<td>vad_eos</td>
		<td>否</td>
		<td><b>VAD后端超时时间</b><br>单位：毫秒 取值范围：[0,10000] 默认值："1000"</td>
	</tr>
	<tr>
		<td>cloud_vad_eos</td>
		<td>否</td>
		<td><b>云端VAD后端超时时间</b><br>单位：毫秒 示例 "3000"</td>
	</tr>
	<tr>
		<td>cloud_vad_gap</td>
		<td>否</td>
		<td><b>云端VAD分句间隔</b><br>单位：毫秒 示例 "400"</td>
	</tr>
	<tr>
		<td>threshold</td>
		<td>否</td>
		<td><b>VAD检测阈值</b><br>控制VAD模块检测程度的，取值范围[0.1,0.9]， 值越大越难触发vad	</td>
	</tr>
	<tr>
		<td>speech_timeout</td>
		<td>否</td>
		<td><b>对话超时时间</b><br>vad_bos开始说话时计时，超过设置的时间自动结束对话并回调vad_eos，单位：毫秒，示例 "500"（默认值60000）</td>
	</tr>
	<tr>
		<td><b>userparams</b></td>
		<td>用户自定义参数</td>
		<td>用户自定义key</td>
		<td>否</td>
		<td><b>用户自定义value</b><br>无固定取值限制，开发者自定义健值对符合json格式即可			</td>
	</tr>
	<tr>
		<td rowspan="2"><b>audioparams</b></td>
		<td rowspan="2">音频透传参数</td>
		<td>msc.lng</td>
		<td>否</td>
		<td><b>经度</b><br>示例：117.16334474（不超过8位精度）</td>
	</tr>
	<tr>
		<td>msc.lat</td>
		<td>否</td>
		<td><b>纬度</b><br>示例：31.82102191（不超过8位精度）</td>
	</tr>
	<tr>
		<td><b>iat</b></td>
		<td>识别音频参数</td>
		<td>sample_rate</td>
		<td>否</td>
		<td><b>采样率</b><br>16000</td>
	</tr>
	<tr>
		<td rowspan="8"><b>tts</b></td>
		<td rowspan="8">合成和播放控制参数</td>
		<td>engine_type</td>
		<td>否</td>
		<td><b>主动合成引擎模型</b><br>cloud：云端合成，默认取值<br>local：本地合成</td>
	</tr>
	<tr>
		<td>res_type</td>
		<td>否</td>
		<td><b>离线资源加载方式，离线合成时必须配置</b><br>assets：android程序assets目录<br>path：外部绝对路径</td>
	</tr>
	<tr>
		<td>res_path</td>
		<td>否</td>
		<td><b>离线资源路径，离线合成时必须配置</b><br>注意资源构建方式为,每个资源用分号隔开，可一次加载多个离线发音人资源：引擎资源;发音人;发音人……<br>xtts/xtts_common.jet;xtts/xtts_xiaoxue.jet;xtts/xtts_xiaofeng.jet</td>
	</tr>
	<tr>
		<td>vcn</td>
		<td>否</td>
		<td><b>合成发音人</b><br>在线发音人按照云端发音人传如：x2_xiaojuan<br>离线发音人按照实际资源名称传如：xiaoxue</td>
	</tr>
	<tr>
		<td>play_mode</td>
		<td>否</td>
		<td><b>播放控制</b><br>sdk：内部SDK托管播放（默认取值)<br>user：外部自行播放</td>
	</tr>
	<tr>
		<td>buffer_time</td>
		<td>否</td>
		<td><b>音频缓冲时长</b><br>当缓冲音频大于该值时才开始播放，默认值：0ms</td>
	<tr>
		<td>stream_type</td>
		<td>否</td>
		<td><b>播放音频流类型</b><br>取值参考AudioManager类，默认值：3</td>
	</tr>
	<tr>
		<td>audio_focus</td>
		<td>否</td>
		<td><b>播放音频时是否抢占焦点</b><br>1：抢占焦点<br>0：不抢占焦点（默认值）</td>
	</tr>
	<tr>
		<td rowspan="3"><b>ivw</b></td>
		<td rowspan="3">语音唤醒参数</td>
		<td>mic_type</td>
		<td>否</td>
		<td><b>唤醒依赖库</b><br>mic1：代表托管AIUI SDK加载单麦唤醒库libvtn_mic1.so(取值xxx，代表SDK加载 libvtn_xxx.so),</td>
	</tr>
	<tr>
		<td>res_type</td>
		<td>否</td>
		<td><b>唤醒配置文件路径读取类型</b><br>path：path资源（sdcard文件）</td>
	</tr>
	<tr>
		<td>res_path</td>
		<td>否</td>
		<td><b>唤醒配置文件路劲</b><br>/sdcard/AIUI/ivw/vtn/vtn.ini</td>
	</tr>
	<tr>
	<tr>
		<td rowspan="2"><b>recorder</b></td>
		<td rowspan="2"><br>音频通道参数<br>用唤醒时必传</td>
		<td>channel_count</td>
		<td>否</td>
		<td><b>通道数量</b><br>1：单唤醒不接麦克风阵列时一般为1</td>
	</tr>
	<tr>
		<td>channel_filter</td>
		<td>否</td>
		<td><b>通道过滤参数</b><br>0,-1：单唤醒固定取值2通道音频（从原始数据中取相应的通道组成新阵列数据：非负数字代表原始音频的通道号，-1代表填充一个全0通道）</td>
	</tr>
		<td rowspan="5"><b>log</b></td>
		<td rowspan="5">日志设置</td>
		<td>debug_log</td>
		<td>否</td>
		<td><b>Debug日志开关</b><br>取值：1（打开），0（关闭），默认值：0。<br>日志打开时会向logcat打印调试日志。</td>
	</tr>
	<tr>
		<td>save_datalog</td>
		<td>否</td>
		<td><b>是否保存数据日志</b><br>取值：1（打开），0（关闭），默认值：0。<br>打开之后会将所有上传到云端的音频和云端返回的结果保存到本地，保存的路径位于/sdcard/AIUI/data/，每一次唤醒后的交互音频都保存在此目录下wakeXX开始的文件夹下。</td>
	<tr>
		<td>datalog_path</td>
		<td>否</td>
		<td><b>数据日志的保存路径</b><br>当不设置或者为空值时，使用默认值：“/sdcard/AIUI/data/”。</td>
	<tr>
		<td>datalog_size</td>
		<td>否</td>
		<td><b>数据日志的大小限制（单位：MB）</b><br>取值：[-1，+∞)<br>默认值：-1（表示无大小限制）。<br>注意：设置成-1可能会造成SD卡被日志写满，从而导致AIUI性能下降，影响体验效果。</td>
	</tr>
	<tr>
		<td>raw_audio_path</td>
		<td>否</td>
		<td><b>原始音频保存路径</b><br>当不设置或者为空值时，使用默认值：“/sdcard/AIUI/audio/”。</td>
	<tr>
</table>

## 2. AIUI动态参数设置概述
动态参数设置核心原理就是改变AIUI SDK初始化后默认加载生成的内部参数结构相关参数取值。AIUI SDK提供固定事件（CMD_SET_PARAMS）来进行参数更新。
开发者在对话过程中，如果遇到相关业务处理需要更新参数可以参考下面示例进行处理。

<div style="display: flex; align-items: flex-start; gap: 16px; padding: 16px; background: #fff5f6; border-radius: 5px; border-left: 4px solid #e83e8c; box-shadow: 0 4px 12px rgba(255, 215, 0, 0.08); margin-bottom: 16px; transition: transform 0.2s ease, box-shadow 0.2s ease;">
  <div>
    <div style="font-weight: 600; margin-bottom: 4px;">温馨提示</div>
    <div style="font-size: 14px; line-height: 1.5;">1、如有动态参数设置不明确或需要更多动态参数设置，可以咨询AIUI平台技术同事。</div>
    <div style="font-size: 14px; line-height: 1.5;">2、由于SDK交互再首帧携带参数，如果本次对话已经进行中，动态参数设置后将在下一次对话才生效。</div>
    <div style="font-size: 14px; line-height: 1.5;">3、动态参数设置以后，在SDK保活期间，设置的参数将永久有效。SDK销毁或覆盖更新，参数才会回复默认或切换为新设置参数。</div>
  </div>
</div>

在基础参数中，动态参数设置常用在一下参数更新中：
- 全局参数相关（global）：scene
- 语音交互相关（audioparams）：msc.lng、msc.lat
- 自定义参数相关（userparams）：自定义取值
- 全链路合成相关（audioparams）：vcn、speed（语速）、volume（音量）、pitch（语调）

不是所有参数都支持动态设置，常见如AIUI SDK启动加载的本地参数就不支持，如：
- AIUI应用秘钥参数（login配置项）
- 本地vad模块相关参数（vad配置项）
- tts播放器控制相关参数：play_mode 等

### 2.1. **Android 示例代码**

~~~ java
// 1. 情景模式动态设置
String setParams = "{\"global\":{\"scene\":\"main\"}}";
AIUIMessage setMsg = new AIUIMessage(AIUIConstant.CMD_SET_PARAMS, 0 , 0, setParams, null);
mAIUIAgent.sendMessage(setMsg);

// 2. 经纬度参数动态设置
// 注意经纬度取值：精确位数不要超过8位
String gpsParams = "{\"audioparams\":{\"msc.lng\":\"117.16334474\",\"msc.lat\":\"31.82102191\"}}"
AIUIMessage setMsg = new AIUIMessage(AIUIConstant.CMD_SET_PARAMS, 0 , 0, gpsParams, null);
mAgent.sendMessage(setMsg);

// 3. 自定义参数动态设置
String userParams = "{\"userparams\":{\"k1\":\"v1\",\"k2\":\"v2\"}}";
AIUIMessage setMsg = new AIUIMessage(AIUIConstant.CMD_SET_PARAMS, 0 , 0, userParams, null);
mAgent.sendMessage(setMsg);

// 4. 云端合成发音人参数动态设置（全链路合成时指定）
String ttsParams = "{\"audioparams\":{\"vcn\":\"xxx\",\"speed\":\"50\",\"volume\":\"50\",\"pitch\":\"50\"}}";
AIUIMessage setMsg = new AIUIMessage(AIUIConstant.CMD_SET_PARAMS, 0 , 0, ttsParams, null);
mAIUIAgent.sendMessage(setMsg);

~~~

### 2.2. **iOS/Linux/Windows 示例代码**
~~~ c
// 1.情景模式动态设置
const char* setParams = "{\"global\":{\"scene\":\"main\"}}";
IAIUIMessage* writeMsg=IAIUIMessage::create(AIUIConstant::CMD_SET_PARAMS, 0, 0, setParams, NULL);
m_angent->sendMessage(writeMsg);
writeMsg->destroy();

// 2. 经纬度参数动态设置
// 注意经纬度取值：精确位数不要超过8位
const char* gpsParams = "{\"audioparams\":{\"msc.lng\":\"117.16334474\",\"msc.lat\":\"31.82102191\"}}"
IAIUIMessage* writeMsg=IAIUIMessage::create(AIUIConstant::CMD_SET_PARAMS, 0, 0, gpsParams, NULL);
m_angent->sendMessage(writeMsg);
writeMsg->destroy();

// 3. 自定义参数动态设置
const char* userParams = "{\"userparams\":{\"k1\":\"v1\",\"k2\":\"v2\"}}";
IAIUIMessage* writeMsg=IAIUIMessage::create(AIUIConstant::CMD_SET_PARAMS, 0, 0, userParams, NULL);
m_angent->sendMessage(writeMsg);
writeMsg->destroy();

// 4. 云端合成发音人参数动态设置（全链路合成时指定）
const char* ttsParams = "{\"audioparams\":{\"vcn\":\"xxx\",\"speed\":\"50\",\"volume\":\"50\",\"pitch\":\"50\"}}";
IAIUIMessage* writeMsg=IAIUIMessage::create(AIUIConstant::CMD_SET_PARAMS, 0, 0, ttsParams, NULL);
m_angent->sendMessage(writeMsg);
writeMsg->destroy();

~~~