
通义听悟
开通通义听悟开发套件并跑通第一个语音转写项目
面向需要把语音转写能力接入自有系统的开发者,讲清通义听悟开发套件的开通流程:注册与开通服务、试用与商用两种模式的区别、RAM 子账户的权限策略配置、项目创建时 OSS 与回调方式的绑定,以及用麦克风或音频文件验证识别效果。
通义听悟开发套件是把语音转写能力做成接口供程序调用的服务:实时记录处理麦克风或实时音频流,音视频文件记录处理已经上传的录音、录像文件,处理结果写入你指定的对象存储 Bucket,任务状态通过回调或轮询获取。它适合需要把会议转写、录音整理、字幕生成等能力嵌入自有系统的开发者,而不是只想在网页上手动转一段音频的普通用户。开通与配置的完整流程可以在通义听悟相关页面配合本文对照操作。下面按「账号 → 开通 → 授权 → 建项目 → 验证 → 接入」的顺序走一遍,每一步都给出实际要填的内容。
准备工作
在动手之前,先把下面几样东西确认清楚,能省掉后面反复返工的时间。
- 阿里云账号:主账号可以直接使用;如果团队用 RAM 子账号操作,需要额外做权限授权,见后文专门一节。
- 对象存储 OSS Bucket:项目必须绑定一个 Bucket,转写结果会写到这个 Bucket 下。建议 Bucket 与项目处于同一 Region,跨 Region 会降低数据存储成功率。
- 回调通道(可选):如果不想主动轮询,需要准备一个能接收 HTTP POST 的 URL,或者一个 Rocket MQ 4.0 实例。不设置回调也可以,改用轮询接口取结果。
- 对计费方式的心理预期:试用与商用是两条不同的路径,试用有每日额度与并发上限,商用按接口请求时长后付费。具体价格与额度以官网当前信息为准。
操作步骤
第一步:注册并登录账号
访问阿里云官网,在页面右上角点击「登录/注册」,按提示完成账号注册。已有账号的直接登录即可。后续所有控制台操作都在登录状态下进行。
第二步:开通通义听悟开发套件服务
登录通义听悟控制台,在概览页点击「立即开通」,进入产品开通页面。这里需要先选择服务类型,两条路径的差别很大,选之前先看清楚:
| 服务类型 | 适用场景 | 额度与限制 | 额度用完后 |
|---|---|---|---|
| 试用 | 验证效果、做小规模联调 | 新开通用户可免费试用 90 天;实时记录每天 48 小时、并发 2 路;音视频文件记录每天 2 小时(按音频时长)、并发 1 路;麦克风无使用限制 | 当日额度用完后需等 24 小时才能重新使用;也可升级为商用版 |
| 商用 | 正式业务接入 | 按接口请求的时长计量,从阿里云账户余额扣费 | — |
选择「试用」后即可开始联调。如果确定要直接上生产,选择「商用」,开通后进入后付费按时长计费模式。两种模式都可以在「服务管理与开通」页面把对应的服务(实时记录服务、音视频文件记录服务)单独升级为商用版,也就是说可以先用试用跑通,再按需把某一路服务转成商用。
最后勾选「通义听悟开发套件服务协议」,点击「立即开通」完成开通。商用版的详细计费规则请以控制台计费说明页面的当前信息为准。
第三步:为 RAM 子账户配置权限策略
主账号使用通义听悟可以跳过这一步。使用 RAM 子账户时,开发套件需要读取对象存储 OSS 和 Rocket MQ 的列表信息,如果子账户没有相应权限,控制台会直接报权限不足。
由主账号在 RAM 控制台的「权限管理 > 权限策略」中创建一条自定义权限策略,内容如下:
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": "oss:ListBuckets",
"Resource": "acs:oss:*:*:*"
},
{
"Effect": "Allow",
"Action": "mq:QueryInstanceBaseInfo",
"Resource": "acs:mq:*:*:*"
}
]
}
然后在 RAM 控制台的「身份管理 > 用户」中找到该子账户,点击操作列的「添加权限」,同时授予两项:上一步创建的自定义策略,以及系统策略中的「AliyunTingwuFullAccess」(管理通义听悟服务的权限)。两项都授予后,子账户才能正常使用开发套件。
第四步:创建项目
在通义听悟控制台左侧导航栏点击「我的项目」,再点击「创建项目」(首次创建时按钮可能显示为「立即创建」)。创建过程有几个关键动作:
- 授权服务角色。账号首次创建项目时,需要授权通义听悟开发套件服务获取对象存储 OSS 和 Rocket MQ 的关键角色。这个授权允许服务通过阿里云访问控制服务,向你的 OSS 写入智能纪要、并发送音视频文件记录任务处理完成等通知。必须授权后才能继续创建项目。该角色只用于通知任务状态和写入处理结果,不会读取或查询你的数据。
- 输入项目名称。
- 选择对象存储 Bucket。下拉列表里没有合适的 Bucket 时,可以点击右侧「创建对象存储 bucket」现场创建。选定后,通义听悟会向该 Bucket 写入一个测试文件
tingwu/initfile.txt,写入成功才算检查通过。之后每次请求的处理结果都会以tingwu开头的 object 写入这个 Bucket。 - 选择回调方式。三种选择,按你的系统形态决定:
- HTTP post:填入接收回调的 URL。通义听悟会向该地址发送 POST 请求,返回 HTTP status 200 即检查通过。
- Rocket MQ 的 HTTP:需要先创建一个 Rocket MQ 4.0 实例,并创建以
TOPIC_TINGWU_开头的 topic。通义听悟通过 HTTP 协议向 RocketMQ 发送消息,写入成功即检查通过。注意仅支持 Rocket MQ 4.0 实例,topic 前缀必须符合要求。 - 不设置回调、主动轮询:实时记录轮询
GetMeetingTrans接口,音视频文件记录轮询GetFileTrans接口。每个账户轮询的 QPS 为 100。
选择 HTTP post 或 Rocket MQ 回调时,通义听悟会向配置的地址发送一条连通性检查消息,形如:
{"Code":"0","Data":{"Test":"checkSyncConf+时间戳"},"Message":"success.","RequestId":"xxxxxx"}
收到这条消息并能正确返回,说明回调链路是通的。最后可以填写项目描述(可选),完成创建。
第五步:在控制台测试识别效果
项目建好后,不必急着写代码。在「我的项目」列表页,点击项目右侧操作列的「详情及语音服务效果测试」,可以直接验证中文、英文、粤语的识别准确率。两种测试方式:
- 麦克风输入:选择测试语言(中文/英文/粤语)与测试方式为麦克风输入,点击「开始录音」,即可看到实时识别的转写结果,60 秒后自动停止识别。点击「确认」返回项目列表。
- 音频文件:选择测试语言与测试方式为音频文件,点击「上传本地文件」,上传成功后查看识别后的转写结果,音频可以在线播放。点击「确认」返回项目列表。
这一步能提前暴露采样率、口音、专业术语等问题,比在代码里调试回调格式要快得多。
第六步:开发接入
控制台验证通过后,按开发参考文档接入接口。接入前需要确认三件事已经就绪:项目已绑定可写的 OSS Bucket、回调地址或轮询方案已确定、RAM 子账户(如使用)已拿到两项权限。服务用量与账单可以分别在控制台的服务用量页面和账单明细页面查询,联调阶段建议定期看一眼,避免试用额度耗尽后请求失败。
一个完整示例
下面把上面的步骤串成一个最小可跑通的场景:用试用版跑通一次音频文件转写,结果写入 OSS,通过 HTTP 回调接收完成通知。
- 注册并登录阿里云账号。
- 进入通义听悟控制台,概览页点击「立即开通」,服务类型选「试用」,勾选协议后点击「立即开通」。此时音视频文件记录每天有 2 小时(音频时长)的免费额度,并发 1 路。
- 如果使用 RAM 子账户:主账号在 RAM 控制台创建自定义策略(内容见第三步),并在「身份管理 > 用户」中给子账户同时授予该自定义策略与
AliyunTingwuFullAccess。 - 在「我的项目」中点击「创建项目」,完成首次服务角色授权,填写项目名称,选择一个与项目同 Region 的 OSS Bucket,回调方式选 HTTP post 并填入你的接收地址。
- 确认回调地址收到连通性检查消息
{"Code":"0","Data":{"Test":"checkSyncConf+时间戳"},"Message":"success.","RequestId":"xxxxxx"}并返回 200。 - 在项目列表点击「详情及语音服务效果测试」,选音频文件方式上传一段本地录音,确认转写结果符合预期。
- 按开发参考接入音视频文件记录接口,提交任务;任务完成后,回调会通知你,处理结果以
tingwu开头的 object 形式出现在项目绑定的 Bucket 中。
如果不想配回调,把第 4 步改为「不设置回调主动轮询」,第 7 步改为轮询 GetFileTrans 接口获取结果,账户级轮询 QPS 为 100。
注意事项
- 试用额度按天重置,不是按总量。实时记录每天 48 小时、音视频文件记录每天 2 小时(音频时长),当日用完后要等 24 小时才能重新使用。联调时如果突然全部请求失败,先检查是不是当天额度已经耗尽。
- 并发是硬上限。试用期实时记录并发 2 路、音视频文件记录并发 1 路,超出并发会失败,压测前务必确认当前处于哪种服务类型。
- 麦克风无使用限制,但实时记录与文件记录的服务额度是分开计算的,不要混为一谈。
- Bucket 与项目 Region 不一致会降低数据存储成功率,创建项目时优先选同 Region 的 Bucket。
- Rocket MQ 只支持 4.0 实例,且 topic 必须以
TOPIC_TINGWU_开头,这两条不满足时回调检查不会通过。 - 首次创建项目必须完成服务角色授权,跳过这一步无法继续创建。该授权只用于任务状态通知与结果写入,不涉及读取你的数据。
- RAM 子账户需要两项权限同时具备:自定义策略(
oss:ListBuckets与mq:QueryInstanceBaseInfo)和系统策略AliyunTingwuFullAccess,缺一项都会在控制台报权限错误。 - 商用版按接口请求时长后付费,从账户余额扣费;试用与商用的具体额度、价格、计费细则可能调整,一律以官网与控制台当前展示的信息为准。