腾讯云智聆口语评测完整对接使用指南：从开通服务到生产级应用

一、智聆口语评测产品概述

腾讯云智聆口语评测（Smart Oral Evaluation，简称SOE）是腾讯云推出的一款中英文语音评测产品，由微信智聆语音团队研发。该产品基于腾讯云先进的语音处理技术，应用特征提取、声学模型和语音识别算法，能够对学习者的发音进行自动化评测打分，检测发音中存在的错误。

智聆口语评测支持从儿童到成人全年龄覆盖的语音评测，提供字、词、句、段落、自由说、多分支、关键词等多种评测模式。在评分维度上，该产品可从发音准确度、流利度、完整度、重音、声调、音素等多个维度对发音进行全方位评价，与专家打分相似度达到95%以上。

目前智聆口语评测提供基础版和新版两个版本。基础版的中文版与英文版计费不通用，但使用相同的API接口，通过ServerType参数进行区分。新版的中文版与英文版计费通用，同样通过ServerType区分语言类型。值得注意的是，基础版即将下线，官方推荐新用户直接接入新版。

该产品被广泛应用于中英文口语对话、教学、练习等场景。英语在线培训机构接入智聆口语评测后，可通过后台数据读取对比，了解学生在课堂内容的掌握程度和学习进度，评估课堂教学质量。此外，该产品还可用于普通话教学、口语作业自动批改、面试口语评估等多种场景。

二、开通服务与准备工作

2.1 注册腾讯云账号并完成实名认证

要使用智聆口语评测服务，首先需要注册腾讯云账号并完成实名认证。实名认证是使用腾讯云所有付费服务的前提条件，个人用户和企业用户均可完成认证。

需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联

2.2 开通智聆口语评测服务

完成账号注册和实名认证后，需要进入智聆口语评测控制台开通服务。基础版用户进入智聆口语评测控制台开通；新版用户进入智聆口语评测（新版）控制台开通。开通时需要注意选择中文版还是英文版——基础版的中英文计费不通用，需要分别开通。

2.3 购买服务套餐

开通服务后，需要购买相应的调用次数。初次使用推荐购买9.9元的套餐包进行开发调试。智聆口语评测提供预付费（套餐包）和后付费两种付费方式。

预付费套餐包的价格梯度如下：

• 1万次套餐包：9.9元（限时优惠，仅可购1个，折合0.99元/千次），有效期1个月
• 15万次套餐包：600元（即4元/千次），有效期1年
• 100万次套餐包：3750元（即3.75元/千次），有效期1年
• 500万次套餐包：17500元（即3.5元/千次），有效期1年
• 5000万次套餐包：162500元（即3.25元/千次），有效期1年
• 1亿次套餐包：300000元（即3元/千次），有效期1年

后付费方式单价为0.005元/次，即5元/千次。

2.4 获取API密钥

接入智聆口语评测需要获取API密钥，包括SecretId和SecretKey。登录腾讯云后，进入访问管理控制台 > API密钥管理页面获取。新版口语评测还需要获取AppID。

SecretId和SecretKey是使用SDK的安全凭证。客户端SDK建议用户使用临时访问凭证调用SDK，通过临时授权的方式进一步提高SDK使用的安全性。服务端SDK建议用户使用子账号密钥加环境变量的方式调用SDK。为子账号授权时，应遵循最小权限指引原则，防止泄露其他资源。

密钥属于敏感信息，正式密钥仅可在调试时使用。线上环境下，为了防止他人盗取，应使用安全凭证服务获取联合身份临时访问凭证。临时访问凭证有期限，默认30分钟，过期需要重新获取。

三、对接方式总览

智聆口语评测提供三种主要的对接方式，开发者可以根据自己的应用场景选择合适的接入方案。

3.1 API接口调用

智聆口语评测的API接口采用WebSocket协议，对实时音频流进行评测，同步返回识别结果，达到“边说边评测发音”的效果。这种方式适合需要实时反馈的场景，如在线口语课堂、互动式语言学习应用等。

3.2 SDK集成

智聆口语评测SDK支持以下平台和语言：

• 移动端：Android（4.0以上）、iOS（8.0以上）
• Web端：支持Web浏览器、微信浏览器、微信小程序
• 服务端语言：Python（2.7、3.6-3.9）、Java（JDK7及以上）、Go（1.9及以上）

SDK通过封装API接口的签名方法，减少计算签名步骤，可以更快速接入。如果SDK不满足需求，也可以直接调用API文档中的接口。

客户端SDK通过封装TransmitOralProcessWithInit接口，通过SDK内部计算签名，减少相关报错情况，提供音频录制和音频文件上传等功能。服务端SDK通过封装API文档，通过SDK内部计算签名，减少相关报错情况。

3.3 微信小程序插件

智聆口语评测还提供了微信小程序插件，开发者只需在第三方服务插件管理中搜索并添加智聆语音评测插件即可快速集成。小程序插件目前开放了单词和句子评估两种模式。评测人群支持从儿童到成人年龄全覆盖。

使用小程序插件的步骤如下：

1. 登录微信公众平台
2. 进入设置 > 第三方服务 > 插件管理 > 添加插件
3. 搜索并添加智聆语音评测插件
4. 在需要使用插件的小程序app.json中指明需要使用的插件版本等信息

四、API接口详解

4.1 接口地址与协议

智聆口语评测（新版）的API接口采用WSS协议（WebSocket Secure），请求地址为：

wss://soe.cloud.tencent.com/soe/api/{appid}?{请求参数}

其中{appid}需替换为腾讯云注册账号的AppID，{请求参数}格式为key1=value1&key2=value2。

4.2 接口要求

集成实时语音识别API时，需按照以下要求：

数据发送建议每40ms发送40ms时长的数据包，对应16k采样率的pcm大小为1280字节。音频发送速率过快超过1:1实时率或者音频数据包之间发送间隔超过6秒，可能导致引擎出错，后台将返回错误并主动断开连接。

并发限制方面，默认单账号限制并发数为50路。

4.3 接口调用流程

接口调用流程分为两个阶段：握手阶段和识别阶段。两阶段后台均返回text message，内容为JSON序列化字符串。

返回结果主要字段说明：

• code：状态码，0代表正常，非0值表示发生错误
• message：错误说明
• voice_id：音频流唯一id
• message_id：本message唯一id
• result：最新评测结果
• final：该字段返回1时表示音频流全部识别结束

4.4 请求参数详解

握手阶段的请求参数主要包括：

4.5 评测模式

智聆口语评测（基础版）目前支持8种英文和8种中文评测模式。每种模式的使用场景和参数限制有所不同：

• 单词模式：支持单词（缩写、组合词）或单字评测
• 句子模式：支持30个单词以下的文本
• 段落模式：支持最长300秒的评测时长
• 自由说模式：无需上传参考文本，可对用户的自由发言进行评测
• 多分支模式：适用于选择题、问答题等多选一场景
• 关键词模式：支持主题词和关键词检测

4.6 指定发音与音标评测

当需要使用音标评测或文本中出现不常见人名、地名时，需要指定单词发音，否则会按照词库生成发音或报错。使用指定发音需要设置text_mode=1，使用Wordlist的结构来表示音素结构。

音素结构Word需要填写指定的单词，Pron需要填写智聆音素。没有Pron则不指定发音，Pron为空或非智聆音素会报错。智聆音素可以参考音素映射表。

例如，指定单词发音的ref_text格式为：

{"wordlist": [{"word": "english"},{"word": "tencent","pron": [["t","ah","n","s","ah","n","t"]]},{"word": "smart oral evaluation"}]}

五、代码示例

5.1 使用API Explorer快速调试

腾讯云提供了API Explorer工具，可以帮助开发者快速调试和生成代码。操作步骤如下：

1. 进入API Explorer智聆口语评测界面
2. 单击参数说明和查看文档，了解参数使用方法
3. 填入相应的请求参数：SeqId（流式数据包序号）、IsEnd（是否传输完毕）、VoiceFileType（语音文件类型）、VoiceEncodeType（语音编码类型）、UserVoiceData（Base64编码的语音数据）、SessionId（语音段唯一标识）、RefText（参考文本）、ServerType（评估语言）、WorkMode（语音输入模式）、EvalMode（评测模式）、ScoreCoeff（评价苛刻指数）
4. 单击发起调用，查看响应结果
5. 单击代码生成，选择编程语言获取代码示例
6. 按照SDK安装命令安装SDK
7. 下载工程或复制代码到本地，填入密钥后运行

5.2 Python SDK示例

以下是一个使用Python SDK调用智聆口语评测的完整示例代码：

# -*- coding: utf-8 -*-
import json
import uuid
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.soe.v20180724 import soe_client, models

# 配置密钥
secret_id = "您的SecretId"
secret_key = "您的SecretKey"
cred = credential.Credential(secret_id, secret_key)

# 配置HTTP
httpProfile = HttpProfile()
httpProfile.endpoint = "soe.tencentcloudapi.com"

# 配置客户端
clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile
client = soe_client.SoeClient(cred, "ap-guangzhou", clientProfile)

# 构建请求
req = models.TransmitOralProcessWithInitRequest()
params = {
    "SeqId": 1,
    "IsEnd": 1,
    "VoiceFileType": 3,  # 3表示mp3格式
    "VoiceEncodeType": 1,
    "UserVoiceData": "Base64编码的音频数据",
    "SessionId": str(uuid.uuid4()),
    "RefText": "hello world",
    "ServerType": 0,  # 0表示英文
    "WorkMode": 1,
    "EvalMode": 1,  # 1表示句子模式
    "ScoreCoeff": 1.0
}
req.from_json_string(json.dumps(params))

# 发起调用
resp = client.TransmitOralProcessWithInit(req)
print(resp.to_json_string())

5.3 Java SDK示例

import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.profile.ClientProfile;
import com.tencentcloudapi.common.profile.HttpProfile;
import com.tencentcloudapi.soe.v20180724.SoeClient;
import com.tencentcloudapi.soe.v20180724.models.TransmitOralProcessWithInitRequest;
import com.tencentcloudapi.soe.v20180724.models.TransmitOralProcessWithInitResponse;

public class SoeDemo {
    public static void main(String[] args) {
        try {
            // 配置密钥
            Credential cred = new Credential("您的SecretId", "您的SecretKey");
            
            // 配置HTTP
            HttpProfile httpProfile = new HttpProfile();
            httpProfile.setEndpoint("soe.tencentcloudapi.com");
            
            // 配置客户端
            ClientProfile clientProfile = new ClientProfile();
            clientProfile.setHttpProfile(httpProfile);
            SoeClient client = new SoeClient(cred, "ap-guangzhou", clientProfile);
            
            // 构建请求
            TransmitOralProcessWithInitRequest req = new TransmitOralProcessWithInitRequest();
            req.setSeqId(1L);
            req.setIsEnd(1L);
            req.setVoiceFileType(3L);
            req.setVoiceEncodeType(1L);
            req.setUserVoiceData("Base64编码的音频数据");
            req.setSessionId(java.util.UUID.randomUUID().toString());
            req.setRefText("hello world");
            req.setServerType(0L);
            req.setWorkMode(1L);
            req.setEvalMode(1L);
            req.setScoreCoeff(1.0f);
            
            // 发起调用
            TransmitOralProcessWithInitResponse resp = client.TransmitOralProcessWithInit(req);
            System.out.println(TransmitOralProcessWithInitResponse.toJsonString(resp));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

5.4 Web端JavaScript示例

Web端可以通过引入TencentSOE SDK来实现口语评测功能：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>智聆口语评测示例</title>
</head>
<body>
    <button onclick="startEvaluation()">开始评测</button>
    <div id="result"></div>
    
    <script>
        // 初始化评测实例
        const recorder = new TencentSOE({
            InitUrl: 'https://your-server.com/cgi/init',
            TransUrl: 'https://your-server.com/cgi/trans'
        });
        
        function startEvaluation() {
            // 配置评测参数
            const config = {
                refText: 'hello world',
                evalMode: 1,  // 句子模式
                serverType: 0, // 英文
                scoreCoeff: 1.0
            };
            
            // 开始录音并评测
            recorder.start(config, function(result) {
                document.getElementById('result').innerHTML = 
                    '总分: ' + result.SuggestedScore + '<br>' +
                    '准确度: ' + result.PronAccuracy + '<br>' +
                    '流利度: ' + result.PronFluency + '<br>' +
                    '完整度: ' + result.PronCompletion;
            });
        }
    </script>
</body>
</html>

六、音频格式与文本规范

6.1 音频文件规范

智聆口语评测在流式或非流式评测下都需要开发者按指定格式上传音频数据。具体要求如下：

需要注意以下几点：

• 需要满足音频属性要求，如有不一致可能导致评估不准确或失败
• 比特率的控制模式推荐使用CBR（固定码率）
• 如果是mp3文件，码率要高于48kbps，否则评分可能会出现偏低或者0分

6.2 RefText文本规范

智聆口语评测支持GBK编码集内的所有文本。RefText的转换标准如下：

文本过滤规则方面：

• 支持GBK编码集内的所有文本
• 标点符号会被过滤，不影响评测结果
• 不支持当前评测模式以外的语言（如日、韩语等）
• 不支持填写开发语言（如前端语言）
• {}仅在可支持语法格式中使用，不能单独使用
• 评测文本均不区分大小写

七、计费说明

7.1 计费方式

腾讯云智聆口语评测按调用量计费。英文版和中文版分开计费，资源不共享。基础版的中英文计费不通用，新版的中英文计费通用。

计费提供预付费和后付费两种付费形式。预付费方式需要先购买套餐包再调用服务，相应调用量将在所购买的资源包中扣除。后付费方式是在未购置套餐包或套餐包次数耗尽的情况下调用服务，按后付费价格进行费用统计。

7.2 调用次数计算

每次请求将按上传的文本长度计算调用次数。当上传文本长度不超过20个单词（中文为字）时，均计作1次；当超过20个单词（中文为字）时，每20单词（中文为字）计作1次，不足20的以20计算。

例如某次请求上传文本长度为62个单词，则调用次数为62 ÷ 20 = 3.1，计作4次。英文版以空格区分单词数量，中文版以汉字或数字区分字的数量，标点符号均不计。

7.3 预付费规则

购买预付费套餐包后，将默认开启预付费服务。当预付费套餐包存在多个时，将优先使用最快到期的套餐包。套餐包次数仅在有效期内可用，过期则作废。

若套餐包次数全部用尽或到期后仍产生用量，且无其他可用的套餐包，将自动转为后付费服务。已产生的后付费部分不支持用续购的套餐包抵扣。

当套餐包次数即将用尽或即将到期时，腾讯云会发送站内信、邮件和短信进行通知提示。

八、安全最佳实践

8.1 密钥安全管理

密钥属于敏感信息，正式密钥仅可在调试时使用。线上环境应使用安全凭证服务获取联合身份临时访问凭证。临时访问凭证有期限，默认30分钟，过期需要重新获取。

密钥一般存放在服务端，不应在客户端代码中硬编码。服务端SDK建议使用子账号密钥加环境变量的方式调用SDK。

8.2 权限最小化原则

为子账号授权时，应遵循最小权限指引原则，只授予必要的权限。如果一定要使用永久密钥，也应对永久密钥的权限范围进行限制。

8.3 SDK合规使用

在使用智聆口语评测SDK时，需要遵循合规使用指南。腾讯云高度重视SDK的功能优化、个人信息安全和保护，会适时升级迭代SDK版本以提升产品的安全性和稳定性。强烈建议开发者升级使用最新版本SDK。

智聆口语评测SDK向开发者提供了可选个人信息及权限的控制开关，开发者可以根据App所需的SDK功能服务自行配置打开或关闭隐私信息请求开关。

九、常见问题解答

问题一：智聆口语评测支持哪些平台？

智聆口语评测SDK支持Android、iOS、Web、微信等主流平台，也支持Python、Java、Go等多种服务端语言。此外，还提供了微信小程序插件，方便小程序开发者快速集成。

问题二：基础版和新版有什么区别？

基础版的中文版与英文版计费不通用，新版的中文版与英文版计费通用。两者使用相同的API接口，通过ServerType参数区分语言类型。基础版即将下线，官方推荐新用户直接接入新版。

问题三：音频文件有什么格式要求？

音频文件需要满足16kHz采样率、16bit位深、单声道的要求。支持的格式包括pcm、wav、mp3、speex。如果是mp3文件，码率要高于48kbps。

问题四：如何计算调用次数？

每次请求按上传的文本长度计算调用次数。不超过20个单词（中文为字）计作1次，超过20个单词时每20个计作1次，不足20的以20计算。

问题五：评测结果包含哪些维度？

评测结果包含SuggestedScore（总分）、PronAccuracy（准确度）、PronFluency（流利度）、PronCompletion（完整度）、Phone（音素）、DetectedStress（用户是否重音）、Stress（是否应该重音）、MatchTag（当前词匹配情况）等维度。

问题六：智聆口语评测的技术原理是什么？

智聆口语评测基于腾讯云的语音处理技术，应用特征提取、声学模型和语音识别算法，为儿童和成人提供高准确度的语音发音评测。评测打分结果与专家打分拟合度在95%以上。