Files
CyberGril/docs/voice-custom-contract-HEL899.md
T

12 KiB
Raw Blame History

自定义音色契约与部署说明(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 "她的声音服务这会儿不在,稍后再试试。";缺 voice 422。
  • 试听不写聊天/记忆/生活/回执(测试断言四表零变化),只记一条资源流水(§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 顺序)

  1. 前置与 HEL-877 相同:统一实例 8360/8361、TTS 9880(GPU≥6GB)、专属 worker 8082。
  2. 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 可覆盖。
  3. 依赖关系:音色登记/列表依赖 8090 面板进程在运行(.12 现状 pid 常驻); 面板不在时相关端点诚实 503,语音会话不受影响(其健康检查仍只看 9880)。 API → 面板走本机回环 https(自签证书,服务端 verify=False,仅回环)。
  4. 零新增 Python 依赖(登记端点用原始字节体 + 查询串,特意不引 multipart 库); 对 8090 的 multipart 代理由已有 httpx 客户端构造。
  5. 回滚:不部署即无痕;已部署时移除 voice.yaml 增补项即回到 HEL-877 行为, 资料空间三个文件留存无害。

5. 自测与证据(全部零真实请求)

  • tests/test_voice_custom.py 18 项:正常登记/列表/选择全链、显式 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 最终音色决定:仍归白栖知/总管(本轮测试音色已授权总管自定)。