操作步骤 在Dify界面右上角单击用户头像，选择“设置”。 在“设置”页面左侧，选择“模型供应商”页签，找到“ OpenAI-API-compatible”供应商，单击添加模型。 在弹窗中，配置MaaS对应的模型名称、API Key、API Endpoint URL、Function calling等信息。 表1 配置说明 配置项 说明 模型名称 MaaS服务调用界面显示的模型名称。 API Key MaaS鉴权管理界面中创建的API Key。具体操作，请参见步骤1：获取API Key。 API Endpoint URL 服务调用界面中MaaS服务的基础API地址，需要去掉地址尾部的“/chat/completions” 。具体操作，请参见步骤2：调用MaaS模型服务进行预测。 Function calling 设置为“Tool Call”。 Stream function calling 暂不支持。 在Dify中创建Agent进行编排，在右上角单击“Agent 设置”，选择上一步配置好的模型进行使用。 在Agent设置中可以看到Dify已自动将Agent Mode切换到了Function Calling模式。 图1 Agent设置 在“编排”页面的“提示词”文本框，输入以下信息。 你是一位乐于助人的AI助手。在回答用户问题时，你需要：1. 始终使用自然语言解释你将要采取的行动 2. 在调用工具之前，说明你要使用哪个工具以及原因 3. 在获取信息的过程中，清晰地描述你正在做什么 4. 永远不要返回空的回复 - 确保用自然语言解释你的每个步骤，比如当查询天气时，你应该先说'让我使用天气工具为您查询...'，然后再进行工具调用。记住：先表达你的理解和计划，再使用工具。每次回复都必须包含对用户的清晰解释。 图2 输入提示词 在“编排”页面的“工具”区域右侧，单击“添加”，按需添加工具并与模型进行对话调用。 Dify内置有丰富的插件，同时支持自定义工具的创建。 图3 添加工具

角色 角色界面详情，如图1所示。 图1 角色界面 角色界面说明，如表1所示。 表1 界面元素说明 界面元素 说明 定制数字人 单击“定制数字人”，跳转至形象制作页面，界面详情和操作指导，详见创建分身数字人定制任务。 数字人搜索框，可输入数字人名称进行精准搜索。 示例：云岚。 刷新图标。如果有关键词，按照关键词进行刷新展示；如果没有关键词，恢复为默认展示。 筛选条件 支持通过角色、性别、姿势、行业、区域和分辨率，筛选数字人。 数字人卡片 默认展示全量数字人卡片。单击数字人形象，自动替换至当前画面中。

背景 背景界面详情，如图2所示。 上传后的背景图片不支持修改。如需修改图片内容，需本地修改完成后，再上传至控制台使用。 图2 背景界面 背景界面说明，如表2所示。 表2 界面元素说明 界面元素 说明 本地导入 单击“本地导入”，从本地选择PNG、JPG、JPEG和BMP格式的图片上传。也可直接将图片拖拽至图片列表区域。 背景搜索框，可输入背景名称进行精准搜索。 示例：科技。 筛选条件 支持通过来源筛选展示背景图片。 图片列表 默认展示全量背景图片。单击图片，自动替换至当前画面中。 第一张图为透明背景，单击透明背景后，仅智能交互预览页面会替换为透明背景。如果需要透明背景正式生效，还需要设置如下智能交互SDK的任一参数。 须知： 进行智能交互时，透明背景支持的浏览器及版本，详见客户端SDK参考-快速入门-表3。 设置create接口参数config内的配置参数useDefaultBackground，其默认值为true，需修改为false。 代码示例，如下所示： HwI CS UiSdk.create({ serverAddress: 'serverAddress', onceCode: 'onceCode', robotId: 'robotId', containerId: 'ics-root', config: { useDefaultBackground: false }, }); 设置setConfig接口参数useDefaultBackground，其默认值为true，需修改为false。 代码示例，如下所示： HwICSUiSdk.setConfig({ useDefaultBackground: false });

使用场景 大语言模型的Function Calling能力允许模型调用外部函数或服务，以扩展其自身的能力，执行它本身无法完成的任务。以下是一些Function Calling的使用场景： 表1 Function Calling使用场景说明 使用场景 说明 增强能力 大模型通过Function Calling可以调用外部工具或服务，例如实时数据检索、文件处理、数据库查询等，从而扩展其能力。 实时数据访问 由于大模型通常基于静态数据集训练，不具备实时信息。Function Calling允许模型访问最新的数据，提供更准确、更及时的回答。 提高准确性 在需要精确计算或特定领域知识时，大模型可以通过调用专门的函数来提高回答的准确性，例如调用数学计算函数、翻译服务或专业知识库。

使用方式 方式一：在请求体中添加相关函数。 "tools": [ { 'type': 'function', 'function': { 'name': '对应到实际执行的函数名称', 'description': '此处是函数相关描述', 'parameters': { '_comments': '此处是函数参数相关描述' }, } }, { '_comments': '其他函数相关说明' }] 方式二：通过OpenAI库发起请求。 response = client.chat.completions.create( model="MaaS模型名称", messages = messages, tools=[ { 'type': 'function', 'function': { 'name': '对应到实际执行的函数名称', 'description': '此处是函数相关描述', 'parameters': { // 此处是函数参数相关描述 }, } }, { // 其他函数相关说明 } ] // chat.completions 其他参数)

概述 SSML 是一种基于 XML 的 语音合成 标记语言。使用 SSML 可以更加准确、具体的定义合成音频的效果，包括控制断句分词方式、发音、速度、停顿、声调和音量等特征。相比文本输入进行合成，有更好的操作灵活性。 华为云语音合成服务的SSML实现，基于W3C的语音合成标记语言版本1.1，但并不支持W3C包含的所有的标记类型。目前仅华小飞，华小美，华小龙，华小蕊，华小闽合成支持 SSML功能。该特性与语言无关。发音人property取值详见语音合成。 华小飞（朝气男声）：chinese_huaxiaofei_common，支持8k/16k采样率。 华小美（温柔女声）：chinese_huaxiaomei_common，支持8k/16k采样率。 华小龙（朝气男声）：chinese_huaxiaolong_common，支持16k采样率。 华小蕊（知性女声）：chinese_huaxiaorui_common，支持16k采样率。 华小闽（闽南女生）：chinese_huaxiaomin_common，支持8k/16k采样率。

请求参数 表3 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 用户Token。 用于获取操作API的权限。获取方法请参见认证鉴权。响应消息头中X-Subject-Token的值即为Token。 Enterprise-Project-Id 否 String 企业项目ID。SIS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。 获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。 企业项目创建步骤请参见用户指南。 说明： 账户创建企业项目后，在传参时，有以下三类场景。 携带正确的ID，正常使用SIS服务，账单归到企业ID对应的企业项目中。 携带错误的ID，正常使用SIS服务，账单的企业项目会被分类为“default”。 不携带ID，正常使用SIS服务，账单的企业项目会被分类为“default”。 表4 请求Body参数 参数 是否必选 参数类型 描述 config 是 TranscriberConfig object 录音文件识别配置信息。 data_url 是 String 存放录音文件地址： 推荐使用华为云OBS：授权配置请参见配置OBS服务。 您也可以把录音文件放在自行搭建服务器上，提供下载文件的地址。URL不能使用IP地址，只能使用 域名 ，请尽量避免中文。 表5 TranscriberConfig 参数 是否必选 参数类型 描述 audio_format 否 String 支持语音的格式，请参考表 audioformat取值范围。 property 是 String 所使用的模型特征串。通常是“语种_采样率_领域”的形式，例如chinese_8k_common。 采样率需要与音频采样率保持一致。 当前支持如下模型特征串： chinese_8k_general（区域支持cn-north-4, cn-east-3，最新端到端通用模型，强烈推荐使用） chinese_16k_media（音视频领域，区域仅支持cn-north-4，cn-east-3，强烈推荐使用） chinese_8k_common（中文普通话 语音识别 ） chinese_16k_conversation（会议场景的中文普通话语音识别） sichuan_8k_common（四川话识别，区域支持cn-north-4，cn-east-3） chinese_8k_bank（银行领域，区域仅支持cn-north-4） chinese_8k_insurance（保险领域，区域仅支持cn-north-4） add_punc 否 String 表示是否在识别结果中添加标点，取值为yes 、 no，默认no。 callback_url 否 String 表示回调 url，即用户用于接收识别结果的服务器地址，不支持IP地址方式调用，url长度小于2048字节。服务请求方法为POST，请求体参见表 响应参数。 如果用户使用回调方式获取识别结果，需填写该参数，处理成功后用户服务器需返回状态码“200”。 如果用户使用轮询方式获取识别结果，则无需填写该参数。 digit_norm 否 String 表示是否将语音中的数字识别为阿拉伯数字，取值为yes 、 no，默认为yes。 need_analysis_info 否 AnalysisInfo object 该参数用于设置质检分析参数，是否需要输出质检分析内容以及会议场景多说话人分离，如果为null , 表示不需要。 vocabulary_id 否 String 热词表id，不使用则不填写。 创建热词表信息请参考创建热词表。 need_word_info 否 String 表示是否在识别结果中输出分词结果信息，取值为“yes”和“no”，默认为“no”。 表6 AnalysisInfo 参数 是否必选 参数类型 描述 diarization 否 Boolean 是否需要做话者分离。 默认为true，表示会进行话者分离，识别结果中会包含role项（角色）。 如果diarization为false，那么结果中不会出现role项。 说明： 本表中的参数对audio_format格式中采样率为8k和16k的音频有效。对于8k单声道音频，8k双声道音频以及16k双声道音频仅支持两个说话人分离；对于16k单声道音频，自动识别说话人个数，返回结果最多支持10个说话人，并且property仅支持chinese_16k_media，区域仅支持cn-east-3。 channel 否 String 语音文件声道信息，默认为MONO，可设置为MONO，LEFT_AGENT, RIGHT_AGENT。 如果channel 为MONO，那么原始文件需要为单声道文件。 如果为双声道文件，系统会将其转换成单声道文件，可能会影响识别效果。 如果 channel 为 LEFT_AGENT或RIGHT_AGENT, 则原始文件需要为双声道文件，如果为单声道文件，系统会将其转换成双声道文件，识别结果会出现两条内容完全一致的文本。 当channel 为 LEFT_AGENT或RIGHT_AGENT，且diarization为true时，系统会按照配置给出对应角色。其中： LEFT_AGENT 指定左声道语音为agent（坐席）。 RIGHT_AGENT 指定右声道为agent（坐席）。 emotion 否 Boolean 是否需要做情绪检测，默认为true。仅对audio_format格式中采样率为8k的音频有效。 目前支持NORMAL（正常）、ANGRY（愤怒）和UNKNOWN（未知）情绪识别。 speed 否 Boolean 是否需要输出语速信息，默认为true。 表7 audio_format取值范围 audio_format取值 描述 auto 默认格式，系统自动判断，支持的音视频格式如下：WAV（内部支持pcm/ulaw/alaw/adpcm编码格式）、AMR、FLAC、M4A、MP3、OGG、WEBM、AAC、AC3、MOV、WMA、MP4、AVI、RMVB、MKV、FLV、F4V、WMV、3GP。支持双声道的音视频。 pcm16k16bit 16k16bit裸音频录音数据。 pcm8k16bit 8k16bit裸音频录音数据。 ulaw16k8bit 16k8bit ulaw 裸音频录音数据。 ulaw8k8bit 8k8bit ulaw 裸音频录音数据。 alaw16k8bit 16k8bit alaw 裸音频录音数据。 alaw8k8bit 8k8bit alaw 裸音频录音数据。

请求示例 “endpoint”即调用API的请求地址，不同服务不同区域的“endpoint”不同，具体请参见终端节点。 提交录音文件识别任务 POST https://{endpoint}/v1/1609d8170cd86660a81281e5a3a03f8b/asr/transcriber/jobsRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body:{ "config": { "audio_format": "auto", "property": "chinese_8k_general", "add_punc": "yes", "need_analysis_info": { "diarization": true, "channel": "LEFT_AGENT", "emotion": true }, "need_word_info": "yes" }, "data_url":"https://****_voip.obs.myxxxcloud.com/VOIP/***.wav"} 使用Python3语言提交录音 文字识别 任务 # -*- coding: utf-8 -*-# 此demo仅供测试使用，强烈建议使用sdk。需提前安装requests，执行pip install requestsimport requestsimport timeimport jsondef lasr_demo(): url = 'https://{{endpoint}}/v1/{{project_id}}/asr/transcriber/jobs' # endpoint和project_id需替换 token = '用户对应region的token' obs_url = 'obs路径' header = { 'Content-Type': 'application/json', 'X-Auth-Token': token } body = { 'data_url': obs_url, 'config': { 'property': 'chinese_8k_general', 'audio_format': 'auto' } } resp = requests.post(url, data=json.dumps(body), headers=header) job_id = json.loads(resp.text, encoding='utf-8')['job_id'] query_task(header, job_id)def query_task(header, job_id): # endpoint和project_id需替换 url = 'https://{{endpoint}}/v1/{{project_id}}/asr/transcriber/jobs/' + job_id for _ in range(1000): resp = requests.get(url, headers=header) print(resp.text) if resp.text.find('segments') != -1: break time.sleep(1)if __name__ == '__main__': lasr_demo() 使用Java语言提交录音文件识别任务 import java.io.BufferedReader;import java.io.InputStream;import java.io.InputStreamReader;import java.io.OutputStreamWriter;import java.net.HttpURLConnection;import java.net.URL;/** * 此demo仅供测试使用，强烈建议使用SDK */public class LasrDemo { public void lasrDemo() { try { // endpoint和projectId需要替换成实际信息。 URL url = new URL("https://{{endpoint}}/v1/{{project_id}}/asr/transcriber/jobs"); String token = "对应region的token"; String obsUrl = "音频在obs的路径"; HttpURLConnection connection = (HttpURLConnection)url.openConnection(); connection.setRequestMethod("POST"); connection.setDoInput(true); connection.setDoOutput(true); connection.addRequestProperty("Content-Type", "application/json"); connection.addRequestProperty("X-Auth-Token", token); OutputStreamWriter osw = new OutputStreamWriter(connection.getOutputStream(), "UTF-8"); String body = "{\"data_url\":\"" + obsUrl + "\", \"config\": { \"audio_format\": \"auto\", " + "\"property\":\"chinese_8k_general\"}}"; osw.append(body); osw.flush(); InputStream is = connection.getInputStream(); BufferedReader br = new BufferedReader(new InputStreamReader(is, "UTF-8")); String jobId = ""; while (br.ready()) { String line = br.readLine().trim(); jobId = line.replace("{\"job_id\":\"", "").replace("\"}", ""); } queryTask(token, jobId); } catch (Exception e) { e.printStackTrace(); } } private void queryTask(String token, String jobId) { try { // endpoint和projectId需要替换成实际信息。 URL url = new URL("https://{{endpoint}}/v1/{{project_id}}/asr/transcriber/jobs/" + jobId); while (true) { HttpURLConnection connection = (HttpURLConnection)url.openConnection(); connection.setRequestMethod("GET"); connection.setDoInput(true); connection.setDoOutput(true); connection.addRequestProperty("Content-Type", "application/json"); connection.addRequestProperty("X-Auth-Token", token); InputStream is = connection.getInputStream(); BufferedReader br = new BufferedReader(new InputStreamReader(is, "UTF-8")); if (br.ready()) { String line = br.readLine(); System.out.println(line); if (line.contains("segments")) { break; } } Thread.sleep(2000); } } catch (Exception e) { e.printStackTrace(); } } public static void main(String[] args) { LasrDemo lasrDemo = new LasrDemo(); lasrDemo.lasrDemo(); }}

响应参数 状态码： 200 表8 响应Body参数 参数 是否必选 参数类型 描述 job_id 否 String 创建的任务标识, 如果创建任务成功时必须存在。 由于录音文件识别通常会需要较长的时间，因此识别是异步的，即接口分为创建识别任务和查询任务状态两个接口。 创建识别任务接口创建任务完成后返回job_id参数，然后用户通过调用录音文件识别状态查询接口来获得转写状态和结果。 状态码： 400 表9 响应Body参数 参数 参数类型 描述 error_code String 调用失败时的错误码。 调用成功时无此字段。 error_msg String 调用失败时的错误信息。 调用成功时无此字段。

接口约束 录音时长不超过5小时，文件大小不超过300M。8k采样率音频最小为1.6kb，16k采样率音频最小为3.2kb，即音频时长至少0.1s以上。 需要将识别的录音文件存放在某服务上，可以通过URL访问。 推荐使用华为云OBS：授权配置请参见配置OBS服务，优先推荐使用与请求服务同一region的私有桶文件，如果region不一致，可考虑使用obs签名。 您也可以把录音文件放在自行搭建服务器上，提供下载文件的地址。URL不能使用IP地址，只能使用域名，请尽量避免中文。 音频转写时长受音频时长和排队任务数量影响，音频时长和理论返回时间可参见表 音频转写时长参考表。如果转写耗时比理论时延长，大概率表示当前时间段出现转写高峰，请耐心等待，我们承诺最大转写时长不超过6小时。 表1 音频转写时长参考表 音频时长 参考返回时间 小于10分钟 小于2分钟 10分钟-60分钟 2分钟-12分钟 大于60分钟 12 分钟-60分钟 识别结果保存72小时（从识别完成的时间算起）。72小时后如果再访问，将会返回 "task id is not found"错误。

功能介绍 该接口用于提交录音文件识别任务，其中录音文件保存在用户的OBS桶中或公网可访问的服务器上（需保证可使用域名访问）。用户开通 录音识别 服务时，如果录音文件存放在OBS桶中，需授权录音文件引擎读取用户OBS桶权限，授权方法见配置OBS访问权限。该接口的使用限制请参见约束与限制，详细使用指导请参见SIS服务使用简介章节。 SIS服务控制台提供了录音文字识别的在线使用页面，用户无需编程即可使用服务功能。 图1 在线使用

响应信息 表1 响应参数 名称 参数类型 说明 resp_type String 响应类型。参数值为RESULT。 trace_id String 服务内部的令牌，可用于在日志中追溯具体流程。 result List 时间戳信息 表2 result数据结构 名称 参数类型 说明 start_time Integer 文本对应的合成音频的开始时间戳，单位是ms。 end_time Integer 文本对应的合成音频的结束时间戳，单位是ms。 text String 文本信息。 word_index Integer 文本在整句中的位置，从0开始计数。 phonemes List 音素时间戳信息，当subtitle取值为phoneme_level时，返回该信息。 表3 phonemes数据结构 名称 参数类型 说明 phoneme String 音素文本信息。 start_time Integer 音素对应的合成音频的开始时间戳，单位是ms。 end_time Integer 音素对应的合成音频的结束时间戳，单位是ms。 phoneme_index Integer 音素位置信息，从0开始。

AK/SK认证 AK/SK签名认证方式仅支持消息体在12M以内，12M以上的请求请使用Token认证。 AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。 AK(Access Key ID)：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥ID和私有访问密钥一起使用，对请求进行加密签名。 SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，可标识发送方，并防止请求被修改。 使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。 签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。 AK/SK获取方式请参考获取AK/SK。

Token认证 Token的有效期为24小时，需要使用同一个Token鉴权时，可以缓存起来，避免频繁调用。 Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。 代码中加粗的斜体字段需要根据实际值填写username、domainname、project name，可登录控制台“我的凭证”页面获取。password为用户密码。 伪码 POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokensContent-Type: application/json { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "cn-north-4" } } } } Python import requestsimport jsonurl = "https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens"payload = json.dumps({ "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "cn-north-4" } } }})headers = { 'Content-Type': 'application/json'}response = requests.request("POST", url, headers=headers, data=payload)print(response.headers["X-Subject-Token"]) 图1 获取Token 示例 获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”的值。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token: ABCDEFJ....”加到请求消息头即可，如下所示。 Content-Type: application/jsonX-Auth-Token: ABCDEFJ....

响应参数 状态码： 200 表7 响应参数 参数 是否必选 参数类型 描述 trace_id 是 String trace_id可用于在日志中追溯具体流程，调用失败无此字段。 在某些错误情况下可能没有此令牌字符串。 audio_duration 是 Integer 音频时长，单位毫秒。 flash_result 是 Array of FlashResult objects 调用成功表示识别结果，调用失败时无此字段。 表8 FlashResult 参数 是否必选 参数类型 描述 channel_id 否 Integer 声道Id。 sentences 否 Array of Sentences objects 分句信息列表。 表9 Sentences 参数 是否必选 参数类型 描述 start_time 否 Integer 一句话开始时间，单位毫秒。 result 否 Result object 分句结果信息。 end_time 否 Integer 一句话结束时间，单位毫秒。 表10 Result 参数 是否必选 参数类型 描述 text 是 String 调用成功表示识别出的内容。 score 是 Double 调用成功表示识别出的置信度（0-1之间）。 word_info 否 Array of WordInfo objects 分词信息列表。 表11 WordInfo 参数 是否必选 参数类型 描述 start_time 否 Integer 起始时间。 end_time 否 Integer 结束时间。 word 否 String 分词。 状态码： 400 表12 响应Body参数 参数 参数类型 描述 error_code String 调用失败时的错误码。 调用成功时无此字段。 error_msg String 调用失败时的错误信息。 调用成功时无此字段。