voicex —— 语音克隆与合成(百炼 CosyVoice + Edge 朗读)
两件事:音色克隆(把一段参考音频注册成可复用音色,百炼 CosyVoice) 和 文本合成(文字 → 音频,整段 / 流式两套形态)。 合成有两条通道:百炼(走可配置的合成端点)与 Edge 朗读(微软,免凭据)。 语音识别(ASR)是姊妹包 asrx,与它共用凭据与配置中心覆盖。
功能
- DashScope 音色克隆客户端:单端点 + action 切换
(
POST https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/services/audio/tts/customization), 覆盖 create / list / query / update / delete 全套动作。 ⚠️ 只接 CosyVoice(voice-enrollment)—— Qwen-TTS / Qwen-Audio 的 action / model / 字段形态都不一样,且产品上不用,刻意没移植 - 文本合成 · 百炼通道:POST JSON
{text, voice, tts, volume, rate, format}到voice.synth_url指向的 TTS 网关,不用 WebSocket —— 单个 HTTP 请求, 两套响应形态按需挑:- 整段(
Once):合成完一次性回完整 wav/mp3 字节 —— 下载 / 存档用 - 流式(
OnceStream):chunked 逐块读 —— 边合成边转发, 前端fetch+ReadableStream边收边播,首包即首音频帧
- 整段(
- 文本合成 · Edge 通道(
EdgeClient):微软 Edge 朗读,免凭据。 协议本身只有 WebSocket 一条通道,那是对接上游的实现细节 —— 对外暴露的仍是Once/OnceStream,与百炼通道同构,前端不感知 WS:- 主握手
api.msedgeservices.com(配voice.edge.token)+ 备用握手 Bing 公共 TrustedClientToken,主备自动切换 - Sec-MS-GEC 风控参数本地计算,403 时按响应 Date 头自动校时
- 两层超时防 hang:单次 read 30s + 整次任务 180s 兜底强拆
- 输出固定 mp3(24kHz 48kbit mono),
format=wav显式拒绝
- 主握手
- 内置音色目录:百炼 CosyVoice 官方音色(v2 / v3-flash 全量)+ Edge 常用
Neural 音色,seed 首启批量登记进
sys_tts_voice(只补缺不覆盖, 运营改过名/排序的行不会被重跑 migrate 打回去) - "响应是 JSON"= 失败 的嗅探(百炼通道):部分网关失败时回 200 +
{"code","msg"}, 客户端按 Content-Type + 首字节两级嗅探,不让一段 JSON 冒充 mp3 存下去 - 业务层配套(
internal/service/voice.go,不在本包):sys_voice_clone克隆台账 +sys_tts_voice音色登记册 +/biz/voice-clones、/biz/tts/*路由(权限码voice_clone:*/tts:*/tts_voice:*)
不解决什么:
- 不做 ASR(语音识别)—— 那是姊妹包 asrx 的事(百炼 Paraformer), 本包只管克隆与合成,两者共用凭据;
- 百炼不内置合成后端 ——
synth_url为空 = 百炼合成不装配,调用拿到显式报错 (Edge 通道无凭据依赖,不受此限); - 不管凭据轮转 —— api_key 就在 yaml 里,和 OSS / SMTP 同一套纪律。
配置
yaml 侧(voice: 块)
voice:
api_key: ${VOICE_BAILIAN_API_KEY}
workspace_id: "" # 百炼业务空间 ID(拼进端点域名)
region: cn-beijing # 端点地域
default_model: voice-enrollment # CosyVoice 音色注册(仅此一种)
default_target_model: cosyvoice-v3-plus
timeout_seconds: 120 # 克隆接口单次 HTTP 超时(审核链路偏慢)
synth_url: "" # 百炼文本合成端点,如 https://tts.example.com/ai/tts/once
synth_timeout_seconds: 60
edge: # Edge 朗读(免凭据,全可空)
token: "" # 主握手 Ocp-Apim-Subscription-Key(空则走 Bing 公共通道)
wss_url: "" # 备用握手端点(空 = 内置 Bing 默认;自建代理时指过来)
read_timeout_seconds: 30
total_timeout_seconds: 180
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
voice.api_key |
string | 空 | 百炼 API Key。为空 = 克隆接口调用时显式报错(花钱的外呼,失败必须可见) |
voice.workspace_id |
string | 空 | 业务空间 ID,拼进端点域名,必填(缺了 New() 直接报错) |
voice.region |
string | cn-beijing |
端点地域 |
voice.default_model |
string | voice-enrollment |
克隆 model(CosyVoice 专用) |
voice.default_target_model |
string | cosyvoice-v3-plus |
克隆目标音色模型 |
voice.timeout_seconds |
int(秒) | 120 |
克隆接口 HTTP 超时(远端审核链路偏慢,别配太小) |
voice.synth_url |
string | 空 | 百炼 TTS 网关端点。空 = 百炼合成不装配(调用显式报错,与 email.provider 空串同一纪律) |
voice.synth_timeout_seconds |
int(秒) | 60 |
百炼合成单次 HTTP 超时 |
voice.edge.token |
string | 空 | Azure 语音订阅密钥(主握手)。不填 = 走 Bing 公共通道,零凭据可用;填了先走微软官方主端点,握手失败自动落回公共通道 |
voice.edge.wss_url |
string | 空 | 备用/代理握手端点。空 = 内置 Bing 默认;公共通道被风控或出网不稳时,指到自建 edge-tts 代理 |
voice.edge.read_timeout_seconds |
int(秒) | 30 |
单次 read 超时(卡死检测),默认即可 |
voice.edge.total_timeout_seconds |
int(秒) | 180 |
整次合成兜底超时,默认即可 |
edge 怎么配,一句话:什么都不填就能用。 日常留空走 Bing 公共通道 (Edge 浏览器内置的公共 TrustedClientToken,免凭据);公共通道被微软风控 (403 / 空音频)时,要么填
token换官方主端点,要么填wss_url过自建代理, 二者都不用动超时参数。
配置中心(系统配置面板)
百炼相关的 5 个键(voice.api_key / workspace_id / region /
default_target_model / synth_url)已 seed 进系统配置面板
(sys_config,voice 分组):配置文件打底,面板覆盖,改完即生效,不用重启
—— 克隆 / 合成每次调用时都重新解析生效配置(service.ResolveVoiceConfig,
消费方 voiceCloneService / ttsVoiceService)。
合并规则与 aliyun.sms.* 完全一致:面板值生效 ⇔ 该行非停用 且 值非空
且 值 ≠ 该行自带的默认值(即"运营改过的才算数");清空某一格 = 退回
配置文件。edge 通道免凭据,不进面板;超时参数是运维调优项,也留在配置文件。
业务路由(移植后自带)
| 路由 | 权限码 | 说明 |
|---|---|---|
POST /biz/voice-clones |
voice_clone:create |
multipart 上传参考音频 → 克隆(失败也落一条 FAILED 台账) |
GET /biz/voice-clones |
voice_clone:list |
台账分页(keyword/status/tts_type) |
GET /biz/voice-clones/:id |
voice_clone:read |
单条 |
PATCH /biz/voice-clones/:id |
voice_clone:update |
只改展示信息,不重新训练 |
DELETE /biz/voice-clones/:id |
voice_clone:delete |
远端音色 + 参考音频尽力删,失败不阻断 |
POST /biz/voice-clones/batch-delete |
voice_clone:delete |
批量({"ids":["1","2"]}) |
POST /biz/voice-clones/:id/refresh |
voice_clone:refresh |
拉 query_voice 同步状态;终态的 error_msg 不被网络错误覆盖 |
GET /biz/voice-clones/remote |
voice_clone:remote_list |
远端音色列表(不写库,对账用) |
POST /biz/tts/convert |
tts:convert |
文本合成:stream=false 整段 / stream=true 流式;dir 非空落 OSS;provider 选 bailian(默认)/ edge |
GET /biz/tts/voices · POST · PATCH/:id · DELETE/:id · POST batch-delete |
tts_voice:* |
音色登记册 CRUD(创建/更新后异步合成试听音频;tts_type=edge 的行走 Edge 通道合成试听) |
数据范围接线
voice_clone / tts_voice / tts 登记在 bizScopeUnwired(平台级资产,
按 API 码 all-or-nothing 管,同 wxtemplate,不做行级范围)。
使用方法
代码侧直接用客户端
client, err := voicex.New(voicex.Config{
APIKey: cfg.Voice.APIKey,
WorkspaceID: cfg.Voice.WorkspaceID,
Region: cfg.Voice.Region,
})
// 克隆:参考音频必须是 https:// 公网可访问 URL(DashScope 服务端会回头 GET)
voiceID, err := client.CreateVoiceFromURL("cosyvoice-v3-plus", "voice", audioURL, []string{"zh"})
// 查状态:DEPLOYING → OK / UNDEPLOYED
info, err := client.QueryVoice(voiceID)
// 整段合成(百炼通道)
synth, _ := voicex.NewSynthesizer(voicex.SynthConfig{Endpoint: cfg.Voice.SynthURL})
audio, err := synth.Once(voicex.SynthParams{Text: "你好", Voice: voiceID, Format: "wav"})
// 流式合成(边合成边转发)
stream, err := synth.OnceStream(voicex.SynthParams{Text: "你好", Voice: voiceID})
defer stream.Body.Close()
io.Copy(w, stream.Body)
// Edge 通道(免凭据,同一套 Once / OnceStream 形态)
edge := voicex.NewEdgeClient(voicex.EdgeConfig{})
audio, err = edge.Once(voicex.EdgeSynthParams{Text: "你好", Voice: "zh-CN-XiaoxiaoNeural"})
内置音色从哪来
go run ./cmd/migrate 时 seed 自动把内置音色登记进 sys_tts_voice:
- bailian:CosyVoice 官方内置(v2 / v3-flash 全量,
voice_id即官方 voiceId, model 记在 description);Name 用 voiceId 占位,运营可改 - edge:常用 Neural 音色(晓晓/云希/方言/粤语/英语/日语/韩语等),
voice_id是短名(zh-CN-XiaoxiaoNeural),合成时NormalizeEdgeVoice自动展开成协议全名
幂等纪律:按 (tts_type, voice_id) 判存在(Unscoped,软删行也算),
只补缺不覆盖 —— 运营的改名/排序不会被重跑 migrate 打回去。
参考音频的公网 URL 从哪来
克隆要求 https:// 公网可访问 的音频 URL。业务层的做法:参考音频先经
oss.Provider.Put 进对象存储,再 SignDownloadURL 签直链 ——
key 第一段必须是静态挂载点(file.path_root,装配时拼
pathRoot + "/voice" 传入 service),否则 local provider 的直链 404。
local / 无 https 部署下克隆会在 DashScope 侧失败,错误落进台账的 error_msg。
关键纪律
- 凭据缺一不可(克隆):
voicex.New对 api_key / workspace_id 逐个显式报错 —— 半可用的客户端会把"没配"拖到第一次调用才炸; - https 闸门在客户端这边:
http://或相对路径的参考音频不发请求直接拒, 不用等远端 403 再猜; - 合成端点失败必须可见(百炼通道):200 + JSON 的"假成功"被两级嗅探拦下 (Content-Type → 首字节),否则一段 JSON 存成 .mp3,播放器只会报"文件损坏";
- Edge 空 audio 也是失败:握手被风控但连接没断时,WS 会"正常"收 0 字节 ——
Once对 0 字节显式报错,不把空 mp3 当成功交出去; - 只接 CosyVoice:Qwen-TTS / Qwen-Audio 相关的 action / model / 字段 刻意没移植,别因为" DashScope 有的都接"而加回来。