12 KiB
自定义音色契约与部署说明(HEL-899)
性质:产品后端代码 + 前端可直接实现的请求/响应/错误/录音格式契约。本卡零真实 LLM/嵌入/ASR/TTS 调用、零模型下载/安装、零共享音色实写、零部署;全部验证用 fake 面板/TTS 传输完成(见 §5)。基准 v1.11 → 本卡按治理机制升 v1.12 (CG-010 边界更新,来源评论
01a17de1-2892-78be-a422-eb6a11ffebfd)。 读取提交:8dc84f88e9d5e961e17b246f24c23eaf526b012e(hel-879-assembly tip)。
0. 用户原话(需求来源,2026-10-27)
".12已恢复,另外以上一条让我解压附件包试听,我不明白是什么意思,是让我听预设音色吗? 如果是我觉得你的设计不够合理,我想要的是可以自定义音色,我的.12上安装的TTS是支持 自定义音色的。至于最长2小时,3次通话的测试,我同意,音色你自己决定就行"
要点:① 自定义音色(不是仅选预设);② 直接复用 .12 已装 TTS 的克隆能力; ③ 本轮通话测试音色总管自定、最长 2 小时/3 次通话(授权给总管,不在本卡执行)。
1. 能力边界(复用,不自建)
- 登记:复用 .12 语音面板(8090)
POST /api/voices/upload的 zero-shot 注册 (写共享voices.json+ CosyVoice mtime 热加载;参考文本留空时面板用 FunASR 转写)。 CyberGril 统一 API 是它的服务端代理:浏览器不直连 8090,凭据不进浏览器, 共享voices.json只有 8090 一个写者(无跨进程读-改-写竞态)。 - 试听:复用 CosyVoice(9880)
POST /tts({"text","voice"}→ 24k mono int16 PCM 流);API 现场包成 WAV 返回。每次试听都是新合成,无缓存。 - 应用:写 CyberGril 专属 worker 的
voice_state_cybergril.json(原子写); worker 在会话入口读一次(HEL-877 既有行为,未改)。 - 不自建克隆引擎、不训练模型、不改 CosyVoice/8090 任何代码与配置。
共享注册表涉及的操作(全部经 8090,本服务不直接写共享文件)
| 操作 | 途径 | 性质 |
|---|---|---|
| 列表 | GET /api/voices |
只读 |
| 登记 | POST /api/voices/upload(服务端生成 cg- 专属 ID) |
唯一写入,只新增 |
| 参考文本回看 | 只读 voices.json(部署配置路径),补全 ASR 转写文本供备份清单 |
只读 |
通用助手自己的 voice_state.json、persona_state.json、既有 11 支音色条目
(bailu/bajie/default/female_soft/haimianbaobao/jiaojiao/male_warm/nezha/rain/
sunwukong/xiaoyun)从不触碰;也不通过改面板全局默认偷换她的声音。
命名空间
- 新增音色 ID =
cg-+ 8 位十六进制(服务端生成,不收用户起名)→ 结构上不可能撞上/覆盖既有 11 支,也不互相覆盖(撞名重试,见 §4 测试)。 - 显示名
label(可中文,≤20 字)只存 CyberGril 资料空间,不进共享注册表。 - 8090 的名字规则(
[a-zA-Z0-9_\-]{1,24})由 cg- 前缀天然满足。
2. HTTP 契约(前端可直接实现)
全部挂在统一 API(与现有 /api/voice/* 同前缀、同进程、同拒绝风格)。
错误体一律 {"detail": "<中文文案>"}。
2.1 GET /api/voice/voices — 列出可用声音
{
"configured": true,
"voices": [
{"id": "rain", "label": "rain", "source": "builtin", "selected": false,
"previewed": false, "registered_at": null, "prompt_text": null, "prompt_wav": null},
{"id": "cg-9f2c1a77", "label": "她的声音", "source": "custom", "selected": true,
"previewed": true, "registered_at": 1793114934826,
"prompt_text": "这段参考音频念的文字", "prompt_wav": "/opt/voice-agent/cosyvoice/voice_samples/cg-9f2c1a77.wav"}
],
"selection": {"voice": "cg-9f2c1a77", "label": "她的声音", "updated_at": 1793114940000}
}
source:builtin(11 支既有)|custom(cg-前缀)。prompt_text/prompt_wav是备份清单字段(CG-009 承接),前端 UI 可不展示。- 实例未配置语音:
200 {"configured": false, "voices": [], "selection": null}(诚实空态)。 - 面板暂不可用:
503 {"detail": "音色登记服务这会儿不在,稍后再试试。"}。
2.2 POST /api/voice/voices — 登记参考音频
请求体就是参考音频原始 WAV 字节(不引入 multipart 依赖);参数走查询串:
POST /api/voice/voices?label=她的声音&prompt_text=这段音频念的文字&allow_asr=false
Content-Type: audio/wav (或 application/octet-stream)
<body: WAV 字节>
| 参数 | 必填 | 说明 |
|---|---|---|
label |
否 | 显示名,≤20 字,不含控制字符/尖括号;缺省用 ID |
prompt_text |
否 | 参考文字(音频念的内容),≤500 字 |
allow_asr |
否 | true = 参考文字留空时明确允许面板 FunASR 自动转写(显式,不隐形) |
201 响应即登记结果(同列表项结构):
{"id": "cg-9f2c1a77", "label": "她的声音", "prompt_text": "...",
"prompt_text_source": "user" | "asr", "prompt_wav": "...", "registered_at": 1793114934826}
服务端复验(不信任任何客户端声明;用户文件路径不是输入):
| 检查 | 拒绝(422) |
|---|---|
| WAV magic(RIFF/WAVE,fmt/data 可解析) | "只支持 WAV 格式的参考音频。" / "WAV 头不完整。" |
| 大小 ≤ 15MB(同 8090) | "文件过大(>15MB),请录 5–20 秒的一段。" |
| 字节数与真实时长 ≥ 2 秒(同 8090 字节线 + 按头计算时长) | "参考音频太短(至少 2 秒),请录 5–20 秒。" |
| 无参考文字且未明确允许转写 | "请填写这段音频的参考文字,或明确选择让系统转写(会用到语音识别)。" |
其他错误:面板 400 透传原中文 detail(422);面板 5xx/断连 503
"音色登记服务这会儿不在,稍后再试。";登记成功但列表未出现 422
"登记结果没有出现在音色列表里,请重试。"(不留下半条可选项)。
建议录音格式(前端 MediaRecorder 录完后转):WAV(PCM),16k 或 24k 采样, 单声道,16 位,5–20 秒,安静环境念 1–2 句完整的话。API 端校验是 "合法 WAV + ≥2 秒";时长上限由 15MB 大小线自然约束。
2.3 POST /api/voice/preview — 试听(应用前必听)
POST /api/voice/preview
{"voice": "cg-9f2c1a77", "text": "可选:自定义试听文字(≤200 字)"}
- 成功:
200 audio/wav(24k/mono/16bit),现场新合成,绝不缓存旧音频。 - 默认试听句:"你好,这是我的声音,以后就用它陪你说话。"
- 未知音色
404"这个声音现在不在列表里。"(前置拦截:CosyVoice 对未知 音色会静默回落 default,绝不让它"换人"冒充);TTS 不在503"她的声音服务这会儿不在,稍后再试试。";缺voice422。 - 试听不写聊天/记忆/生活/回执(测试断言四表零变化),只记一条资源流水(§4)。
2.4 GET /api/voice/selection — 读取当前选择
{"voice": "cg-9f2c1a77", "label": "她的声音", "updated_at": 1793114940000}
从未选择过:{"voice": null, "label": "", "updated_at": null}。
2.5 POST /api/voice/selection — 应用给她
POST /api/voice/selection {"voice": "cg-9f2c1a77"}
- 成功
200 {"voice","label","updated_at"};未知音色404; 自定义音色未试听过409"这个声音还没有试听过,先试听再给她用。" (内置 11 支是 D1 既有候选,不强制试听);状态写不进503"她的音色状态这会儿写不进,这次没有换成功。"(已整体回滚,无半状态)。 - 语义:换声音只换发声——不重建伴侣、不改出生底色/名字/关系/聊天/记忆 (测试断言 companion/bazi_core/chat_message 逐字节不变)。
- 生效时机:worker 在会话入口读一次音色 → 通话中改选最迟下一通话生效,
绝不半句换人;
POST /api/voice/session的响应新增"voice"字段 = 本次通话捕获的有效音色(选择已失效则诚实回落"default")。
3. 状态与资源(可核算、可恢复)
CyberGril 资料空间(实例数据库旁,与语音清理账同模式,重启读回):
| 文件 | 内容 |
|---|---|
<db>-voice-selection.json |
当前选择(voice/label/updated_at),原子写 |
<db>-voice-custom.json |
自定义音色元数据 + 备份清单(id/label/prompt_text/prompt_wav/registered_at) |
<db>-voice-usage.jsonl |
资源流水:`{"ts","kind":"preview_tts" |
- ASR 只在
allow_asr=true且参考文字为空时发生(面板内 FunASR,非 LLM), 每次记register_asr流水;试听每次记preview_tts。LLM 调用零新增。 - 备份清单:
GET /api/voice/voices的 custom 项即完整清单(参考音频路径 + 参考文本 + 映射);恢复 = 按清单重新登记(面板无导出接口,属 R6 备份卡范围)。 - worker 文件
voice_state_cybergril.json:原子写且保留文件里其他键; 用户从未经 API 选择时,通话开启不代写该文件(部署/D1 域不替用户定)。
4. 部署说明(本卡未执行;总工按 HEL-877 runbook §4 顺序)
- 前置与 HEL-877 相同:统一实例 8360/8361、TTS 9880(GPU≥6GB)、专属 worker 8082。
config/voice.yaml增补(全部可选,缺省即本机默认值):panel_url: https://127.0.0.1:8090、tts_url: http://127.0.0.1:9880、registry_file: /opt/voice-agent/cosyvoice/voices.json、worker_state_file: /opt/voice-agent-cybergril/voice_state_cybergril.json; 环境变量CYBERGRIL_VOICE_PANEL_URL/TTS_URL/REGISTRY_FILE/WORKER_STATE可覆盖。- 依赖关系:音色登记/列表依赖 8090 面板进程在运行(.12 现状 pid 常驻);
面板不在时相关端点诚实 503,语音会话不受影响(其健康检查仍只看 9880)。
API → 面板走本机回环 https(自签证书,服务端
verify=False,仅回环)。 - 零新增 Python 依赖(登记端点用原始字节体 + 查询串,特意不引 multipart 库); 对 8090 的 multipart 代理由已有 httpx 客户端构造。
- 回滚:不部署即无痕;已部署时移除 voice.yaml 增补项即回到 HEL-877 行为, 资料空间三个文件留存无害。
5. 自测与证据(全部零真实请求)
tests/test_voice_custom.py18 项:正常登记/列表/选择全链、显式 ASR 准许、 格式/大小/时长拒绝、cg- 命名空间与撞名重试(含并发 4 路登记各自成立)、 面板拒绝/断连/谎报成功不留半条、未知音色 404 且 TTS 零调用(防静默回落 default)、TTS 停机诚实 503、试听零写聊天/记忆/回执、自定义未试听 409/内置 直选、写失败整体回滚、重启读回(选择/元数据/试听凭据)、通话捕获并定住/ 失效回落 default/未选择不代写、通用助手状态零写入零删除、身份表零改写、 未配置端点诚实拒绝。scripts/verify_hel899_custom_voice.py:12/12(真实 app + fake 面板/TTS/LiveKit: 列表→拒绝无准许 ASR→显式登记→未试听 409→试听→应用→会话捕获→通话中改选 定住本通话→下一通话生效→capabilities.voice=false→重启读回)。- 全量
pytest tests -q:370 通过(基线 352 + 本卡 18)。
6. 未验证 / 承接(如实)
- 真实 CosyVoice 试听、真实 FunASR 转写质量、克隆相似度:留统一审核卡在获批 环境实测(复用合法剩余额度,不另开账绕 HEL-879 上限);本卡零真实调用。
- 前端入口(上传/录音/试听/应用 UI):视觉总监按 §2 契约接线(本卡未动 web/)。
- 自定义音色删除、面板导出/完整备份(CG-009/R6):后续卡(本卡最小合同不含删除, 失败/多余登记不影响使用;8090 面板自己的删除入口不代管)。
- D1 最终音色决定:仍归白栖知/总管(本轮测试音色已授权总管自定)。