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

apphuang2026年07月03日 20:33:403

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

腾讯云智聆口语评测（Smart Oral Evaluation，简称SOE）是腾讯云推出的中英文语音评测产品，由微信智聆语音团队研发。该产品支持从儿童到成人全年龄覆盖的语音评测，提供字、词、句、段落、自由说、多分支、关键词等多种评测模式。在评分维度上，智聆口语评测可从发音准确度、流利度、完整度、重音、声调、音素等多个维度对发音进行全方位评价，与专家打分相似度达到95%以上。

智聆口语评测目前提供基础版和新版两个版本。基础版（SOE-B）的中文版与英文版计费不通用，但使用相同的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年

后付费方式为5元/千次。当套餐包次数用尽或到期后仍产生用量时，会自动转为后付费服务。

2.4 获取API密钥

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

在密钥管理上需要注意以下几点：

客户端SDK建议使用临时访问凭证调用，通过临时授权提高安全性
服务端SDK建议使用子账号密钥配合环境变量方式调用
为子账号授权时，应遵循最小权限指引原则，防止泄露其他资源
如必须使用永久密钥，也应对永久密钥的权限范围进行限制

三、接入方式选择

智聆口语评测提供多种接入方式，开发者可以根据自己的技术栈和应用场景选择最适合的方案。

3.1 SDK接入（推荐）

腾讯云官方推荐使用SDK接入。SDK通过封装API接口的签名方法，减少了计算签名的步骤，可以更快速地完成接入。智聆口语评测SDK支持以下平台和语言：

移动端：Android（4.0以上）、iOS（8.0以上）
Web端：支持Web浏览器、微信浏览器、微信小程序
服务端语言：Python（2.7、3.6-3.9）、Java（JDK7及以上）、Go（1.9及以上）、PHP（5.6.0及以上）、Node.js（10.0.0及以上）、.NET（standard 2.0）

SDK的核心功能包括：

内部录制：提供语音录制、静音检测、流式分片、分片缺失重试、评测超时重试、本地存储、签名鉴权
外部录制：提供语音数据传入，支持多种音频格式，签名鉴权

3.2 API直接调用

如果SDK不满足特定需求，也可以直接调用API接口。基础版API通过TransmitOralProcessWithInit接口实现评测，新版API则采用WebSocket协议进行实时评测。

3.3 小程序插件接入

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

四、服务端SDK接入详解

本节以Python语言为例，详细介绍智聆口语评测服务端SDK的接入流程。

4.1 安装SDK

使用pip安装腾讯云SDK：

pip install tencentcloud-sdk-python

4.2 基础版评测调用示例

以下是一个完整的Python调用示例，演示如何对一段语音和一段参考文本进行发音评估：

import json
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

# 初始化认证信息
cred = credential.Credential("您的SecretId", "您的SecretKey")

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

clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile

# 创建客户端
client = soe_client.SoeClient(cred, "ap-beijing", clientProfile)

# 构造请求
req = models.TransmitOralProcessWithInitRequest()

# 设置评测参数
req.SeqId = 1  # 流式分片序号
req.IsEnd = 1  # 是否最后一帧，1表示是
req.VoiceFileType = 3  # 音频格式：3表示mp3
req.VoiceEncodeType = 1  # 编码类型：1表示pcm
req.UserVoiceData = "base64编码的音频数据"
req.SessionId = "unique_session_id"  # 会话ID，唯一标识一次评测
req.RefText = "Hello world"  # 参考文本
req.WorkMode = 1  # 工作模式：1表示流式，0表示非流式
req.EvalMode = 0  # 评测模式：0表示单词模式，1表示句子模式
req.ScoreCoeff = 1.0  # 评分系数

# 发起请求
resp = client.TransmitOralProcessWithInit(req)

# 输出结果
print(json.dumps(resp.to_json_object(), indent=2))

4.3 关键参数说明

在调用API时，以下几个参数尤为关键：

WorkMode：工作模式。1为流式评测（将语音分成若干段分片请求），0为非流式评测（将语音一次性请求）
EvalMode：评测模式。0为单词模式，1为句子模式，不同模式对应不同的评测维度和返回结果
IsEnd：是否最后一帧。在流式评测中，需要在最后一次POST请求时将IsEnd设置为1，服务端才会返回完整的评估结果
SeqId：流式分片序号，取值范围为1-3000的整数
ServerType：服务类型。0表示英文版，1表示中文版

五、新版WebSocket实时评测接入

新版智聆口语评测采用WebSocket协议，支持对实时音频流进行评测，同步返回识别结果，实现“边说边评测发音”的效果。

5.1 WebSocket接口要求

新版WebSocket接口有以下要求：

语言种类：支持中文普通话和英语，通过server_engine_type参数设置（16k_zh表示中文标准版，16k_en表示英文标准版）
音频属性：采样率16kHz、采样精度16bits、单声道
音频格式：pcm、wav、mp3、speex
请求协议：WSS（WebSocket Secure）协议
请求地址：wss://soe.cloud.tencent.com/soe/api/?{请求参数}
数据发送：建议每40ms发送40ms时长的数据包，对应16k采样率的pcm大小为1280字节
并发限制：默认单账号限制并发数为50路

5.2 握手阶段

客户端主动发起WebSocket连接请求，URL格式为：

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

其中<appid>需替换为腾讯云注册账号的AppID。请求参数包括：

secretid：腾讯云账号的SecretId
timestamp：当前UNIX时间戳（秒）
expired：签名有效期截止时间（秒），必须大于timestamp且差值小于90天
nonce：随机正整数（最长10位）
server_engine_type：模型引擎类型（16k_zh或16k_en）
voice_id：音频流唯一标识

5.3 识别阶段

握手成功后进入识别阶段。后台返回的响应为JSON格式，包含以下字段：

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

六、评测模式详解

智聆口语评测（基础版）支持8种英文和8种中文评测模式，不同模式适用于不同的教学场景。

6.1 英文评测模式

英文评测模式包括：

重音检测（原始单词）：文本为1个单词，音频≤60秒。评测维度包括单词发音的精准度、流利度、时间，以及音素的精准度、重音、时间。适用于线上教学、翻译跟读场景
实时评测（原始单词）：文本≤30个单词，音频≤60秒。评测维度包括句子发音的精准度、流利度、完整度，以及单词和音素的精准度。适用于词组和句子评测
实时评测（多组文本）：文本≤120个单词，音频≤300秒。评测维度包括段落发音的精准度、流利度、完整度。适用于文章评测
实时评测（标点符号）：文本字数不限，音频≤300秒。评测维度包括句子发音的精准度、流利度。适用于不在意说话内容、在意发音准确度的场景（如面试）
多组分支：每个分支≤30个单词，音频≤60秒。评测维度包括正向主题词的切题度、与答案最大匹配句子的精准度等。适用于问答题、故事复述、看图说话等需要多选一的场景

6.2 中文评测模式

中文评测模式包括：

指定发音：文本为1个汉字，音频≤60秒。评测维度包括单词发音的精准度、流利度、时间，以及音素的精准度、重音、时间。适用于汉字评测
实时评测（声调检测）：文本≤30个汉字，音频≤60秒。评测维度包括声调检测

七、音频与文本规范

7.1 音频文件规范

智聆口语评测对上传的音频文件有严格要求：

音频压缩格式：pcm、wav、mp3、speex
采样率：16kHz
声道：单声道
位深：16bit
比特率：pcm格式需256kbps以上，mp3格式需32kbps以上，speex格式需24kbps以上
比特率控制模式推荐使用CBR（固定码率）
评测时长最长支持300秒

如果音频属性不满足上述要求，可能导致评估不准确或失败。

7.2 评测文本规范

评测文本主要由命令块、评测文本和发音块三部分组成。命令块可在部分模式实现附加模块开关，发音块可在部分模式实现指定发音。

RefText（参考文本）的转换标准如下：

普通单词（a-z、0-9的组合）：不转换，如"apple"保持不变
单词缩写（包含"'"的单词）：不转换，如"it's"保持不变
常见组合词（由"-"连接）：不转换；OOV组合词在单词模式不转换，其他模式拆分为两个单词
整数（0-99）：转换为对应单词，如"23"→"twenty three"；其他数字转换为数字序列，如"123"→"one two three"
浮点数：分别转换整数和小数部分，小数点转换为"point"，如"1.23"→"one point two three"
序数词（1st-99th）：转换为对应单词，如"1st"→"first"
时间（小时:分钟）：按英语顺序读法转换，如"09:00"→"nine o'clock"

文本过滤规则方面：

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

八、应用管理与合规使用

8.1 应用管理

智聆口语评测控制台提供了应用管理功能，通过不同的SOEAPPID来区分不同的产品或应用平台，方便用户管理服务。操作步骤如下：

登录智聆口语评测控制台，单击导航栏左侧的系统设置
系统设置默认在应用管理界面，应用列表中存在默认应用，可以在所有应用平台调用服务
单击新建应用，填入应用名称（只能包含数字、中英文字符和下划线，不超过30个字）、应用简介（不超过300个字）和应用平台（仅用作标记）

8.2 SDK合规使用

在使用智聆口语评测SDK时，需要遵循合规使用指南。主要注意以下几点：

接入或升级至满足监管新规的最新SDK版本
在App隐私政策中明确披露集成了第三方SDK服务
告知用户SDK收集使用个人信息的目的、方式和范围
在App首次运行时通过弹窗等方式告知用户隐私政策

SDK处理的个人信息类型包括：Wi-Fi状态、IP地址、系统属性、设备型号、操作系统、相机、录音。所需权限包括：摄像头拍照、麦克风声音采集、网络、网络信息状态、读取外部存储、写入外部存储。

数据传输方面，SDK采用SSL协议加密及HTTPS传输加密技术保障安全，并采取加密、去标识化等安全措施对数据进行脱敏处理。

九、计费方式与成本优化

9.1 调用次数计算

每次请求按上传的文本长度计算调用次数：

文本长度不超过20个单词（中文为字）时，计作1次
超过20个单词（中文为字）时，每20个单词（中文为字）计作1次，不足20的按20计算
例如某次请求上传文本长度为62个单词，则调用次数为62÷20=3.1，计作4次
英文版以空格区分单词数量，中文版以汉字或数字区分字的数量
标点符号不计入字数

调用次数计算目前只适用于段落模式和自由说模式。

9.2 计费示例

以下为计费示例：

示例一：用户预计一年内调用英语口语评测2000万次，可购置500万次规格的套餐包4个，所需支付费用为17500×4=70000元
示例二：用户预计一年调用英语口语评测2000万次，实际调用2200万次，已购买500万次套餐包4个，超出200万次按后付费计算，总费用为17500×4+2000000×0.005=80000元

9.3 成本优化建议

为了有效控制成本，建议：

根据实际调用量选择合适的套餐包规格，避免购买过多或过少
关注套餐包有效期，避免过期浪费
注意套餐包用尽后的自动转后付费提醒，及时续购
优化评测文本长度，合理控制单次请求的调用次数

十、常见问题解答

问1：智聆口语评测基础版和新版有什么区别？

基础版的中文版与英文版计费不通用，需要分别开通和购买；新版的中文版与英文版计费通用。此外，新版采用WebSocket协议支持实时评测，基础版即将下线，新用户建议直接接入新版。

问2：智聆口语评测支持哪些音频格式？

支持pcm、wav、mp3、speex四种音频格式。音频需满足16kHz采样率、单声道、16bit位深的要求。比特率控制模式推荐使用CBR（固定码率）。

问3：智聆口语评测的调用次数如何计算？

按上传的文本长度计算，不超过20个单词（中文为字）计作1次，超过20个时每20个计作1次，不足20的按20计算。标点符号不计入字数。

问4：客户端SDK接入时如何保证密钥安全？

客户端SDK建议使用临时访问凭证调用，而非永久密钥。临时访问凭证有期限限制（默认30分钟），过期需要重新获取。服务端SDK建议使用子账号密钥配合环境变量方式调用。

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

支持Android（4.0以上）、iOS（8.0以上）、Web浏览器、微信浏览器、微信小程序等前端平台，以及Python、Java、Go、PHP、Node.js、.NET等服务端语言。

问6：如何查看评测结果和套餐包余量？

可以进入智聆口语评测控制台查询当前调用次数及套餐包余量。异步评测模式下，还可以查询10分钟内的评测结果。