SKILL.md
4.7 KB查看排版效果| 1 | --- |
| 2 | name: qq-voice |
| 3 | description: 让 QQ 机器人用 GPT-SoVITS 本地合成的嗓音发语音消息。当用户说「发个语音」「用语音说」「我想听你说话」「读给我听」「voice」时使用；在 QQ 私聊/群里想用语音回一句时也用。 |
| 4 | --- |
| 5 | |
| 6 | # QQ 语音（GPT-SoVITS 本地 TTS） |
| 7 | |
| 8 | 本地部署了 GPT-SoVITS：本地合成 wav → 走 QQ 官方机器人接口以「语音」消息发出（msg_type 7）。 |
| 9 | 有两条路，优先用 A。 |
| 10 | |
| 11 | ## 方式 A：通道级（只在 QQ 会话里有效，最自然） |
| 12 | |
| 13 | 在 QQ 私聊/群的回复里，把**整条回复**写成这样： |
| 14 | |
| 15 | ``` |
| 16 | [[voice]]主人，我在这儿呢，今天累不累呀？ |
| 17 | ``` |
| 18 | |
| 19 | - QQ 通道会把这行识别成「要说的内容」，合成语音后当成语音气泡发出去； |
| 20 | - 合成失败会自动降级成普通文字，不会丢消息； |
| 21 | - 标记只认**开头**；一条回复一个语音，后面的文字仍然走普通消息； |
| 22 | - **不要在 Web/桌面会话里写 `[[voice]]`**，那边没有这个钩子，会原样显示。 |
| 23 | |
| 24 | 适合：闲聊、撒娇、道晚安这类一两句话。写长段落、贴代码、讲正事时用文字。 |
| 25 | |
| 26 | ## 方式 A+：自动语音（默认关闭） |
| 27 | |
| 28 | `QQBot.send()` 还有一层自动语音：打开后，QQ 里的短回复（≤120 字、不含代码块/表格/链接）会按概率自动转成语音气泡，不需要 agent 配合。 |
| 29 | |
| 30 | **默认 `auto_voice: false`——只在别人明确要语音时才发**（用方式 A 的 `[[voice]]` 或方式 B）。 |
| 31 | |
| 32 | 开关都读同一份 `qqvoice\config.json`： |
| 33 | |
| 34 | | 键 | 默认 | 说明 | |
| 35 | | --- | --- | --- | |
| 36 | | `auto_voice` | **false** | 总开关；关着的时候只有显式 `[[voice]]` 才会发语音 | |
| 37 | | `auto_voice_ratio` | 0.5 | 打开后有多大概率把这条回成语音，1 = 每条都语音 | |
| 38 | | `auto_voice_max_chars` | 120 | 超过这个字数的回复仍然用文字 | |
| 39 | |
| 40 | **TTS 服务自愈**：发语音时如果 9880 没在监听，SDK 会自己拉起 TTS 服务（CUDAGraph=0、cwd 指向项目目录），等端口就绪后重试一次；冷启动约 20 秒。可用环境变量 `GPTSOVITS_PYTHON` / `GPTSOVITS_PROJ` / `GPTSOVITS_START_CMD` 覆盖路径。 |
| 41 | |
| 42 | ## 方式 B：命令行（任何会话都能发） |
| 43 | |
| 44 | 当前会话发（自动认人在哪个 QQ 会话，按 DSH_SESSION_ID 反查）： |
| 45 | |
| 46 | ``` |
| 47 | qqvoice\say-here.cmd --text "要说的话" |
| 48 | ``` |
| 49 | |
| 50 | 指定对象发（绕开自动识别）： |
| 51 | |
| 52 | ``` |
| 53 | qqvoice\say.cmd --text "要说的话" # 默认主人私聊 |
| 54 | qqvoice\say.cmd --scope group --target <群openid> --text "要说的话" |
| 55 | ``` |
| 56 | |
| 57 | 只合成不发送：加 `--dry`，音频落在 `qqvoice\out\`。 |
| 58 | |
| 59 | ## 音色：本地微调模型 |
| 60 | |
| 61 | - 用自备音声素材微调出来的专属模型（素材如来自第三方，请自行确认版权）： |
| 62 | - s1（韵律）`<GPT-SoVITS目录>\logs\<模型>\<模型>-e15.ckpt` |
| 63 | - s2（声码器）`<GPT-SoVITS目录>\logs\<模型>\<模型>_e8_s712.pth` |
| 64 | - 写在 `GPT_SoVITS\configs\tts_infer.yaml` 的 `custom` 段（version v2）。 |
| 65 | - 参考音是素材内的真人音频（`prompt_lang: ja`，硬限制 3~10 秒）：默认 `refs\<参考音>\<参考音>.wav`。 |
| 66 | - 音色参数存在 `qqvoice\config.json`：`temperature 0.7` / `sample_steps 32` / `cfg_rate 0.35` / `speed 1.05`；合成后自动过一遍 ffmpeg `loudnorm=I=-16:TP=-1.5:LRA=11` 再上传（否则偏轻发闷）。 |
| 67 | - 换参考音只改 `ref` + `prompt_text`（两者必须严格对应）；换音色模型改 `tts_infer.yaml` 的 custom 段后重启 TTS。 |
| 68 | |
| 69 | ## 参数 |
| 70 | |
| 71 | | 参数 | 说明 | |
| 72 | | --- | --- | |
| 73 | | `--text` | 必填，要合成的话（中文，10~100 字最自然） | |
| 74 | | `--scope` | `c2c` / `group`，不填读 config.json 或按会话自动判断 | |
| 75 | | `--target` | openid，不填读 config.json / 会话映射 | |
| 76 | | `--ref` / `--prompt-text` | 参考音色与对应文本，默认读 `qqvoice\config.json` | |
| 77 | | `--out` | 指定 wav 输出路径 | |
| 78 | | `--dry` | 只合成不发送 | |
| 79 | |
| 80 | ## 依赖与排错 |
| 81 | |
| 82 | - TTS 服务 `http://127.0.0.1:9880`；没起来先跑 `<GPT-SoVITS目录>\gptsovits\start-api.cmd`（可设登录自启）。 |
| 83 | - 首次请求加载模型约 5~15 秒，之后单句 0.5~1.5 秒。 |
| 84 | - `100016 invalid appid or secret`：`qqvoice\.env` 的 AppSecret 过期，从配置中心/凭据管理取当前值更新。 |
| 85 | - TTS 报 `Resource 'averaged_perceptron_tagger_eng' not found`：nltk 数据缺失，跑 `python -c "import nltk; nltk.download('averaged_perceptron_tagger_eng')"`。文本里出现英文单词会触发这个检查。 |
| 86 | - 通道级 `[[voice]]` 依赖 `QQBot.js` 的本机补丁（`@tencent-connect/qqbot-nodejs/dist/QQBot.js`），改完要重启 DSH 才生效；补丁文件注意备份。 |
| 87 | |
| 88 | ## 说话风格 |
| 89 | |
| 90 | - 1~2 句，口语化，带语气词（呀、哦、嘛）更自然。 |
| 91 | - 别念 markdown、表情、网址。 |
| 92 | - 语音发出就无法编辑，发之前想清楚。 |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
