火山引擎语音 API 到期断服修复复盘:一个 key 的更换,为什么要动三个地方的配置

背景与目标

晚上用豆包语音输入时发现识别不了,火山引擎发来到期关停通知:账号下 14 个语音类云资源于 2026-10-10 23:59:59 到期关停,涵盖语音识别、语音合成、声音复刻、语音播客等。目标是恢复语音输入工具可用,并把修复同步到所有分发产物。

过程回顾

第一步:从 14 个关停资源里定位真正依赖的那一个

本人把通知全文贴进来问:"这个我要如何使用?我们使用的是哪个模型啊?"

没有猜,直接读代码取证:

• asr_client.py:130 默认 resource_id = "volc.seedasr.sauc.duration" —— 豆包流式语音识别 2.0(SAUC 大模型)的资源 ID,按时长计费;
• asr_client.py:155 连接 wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_nostream,请求体 model_name: "bigmodel"(asr_client.py:55)。

结论:14 个资源里项目只用 1 个——清单第三行「豆包流式语音识别模型2.0 | API调用小时结」。其余 13 个(BigTTS、声音复刻、录音文件识别、语音播客等)与本项目无关,不用管。本人在控制台重新开通的正是这个服务(小时版,20 小时时长包,截图显示"已开通/运行中/剩余 20/20 小时"),一次选对。

第二步:新 key 端到端实测

本人新建 API Key 后指令:"你帮我测试下看看"。

写入 config.json:2 的 api_key 字段后,没有做"改完配置就算完"的假验证,而是造了一段真音频实测:

1. PowerShell 调 System.Speech 合成中文语音(Microsoft Huihui Desktop [zh-CN]),输出 16kHz/16bit/单声道 WAV——与 ASR 协议要求的 PCM 参数一致;
2. Python wave 模块提取 PCM 帧;
3. 调 asr_client.transcribe(pcm, cfg) 走真实 WebSocket 接口。

结果:识别返回"你好,这是火山引擎豆包语音识别测试,一二三四五。"——与合成文本一字不差。服务开通、20 小时计费包、新 key 鉴权三者同时验证通过。

第三步:本人一问,牵出打包版本的配置断层

实测通过后本人追问:"你有没有帮我替换这个桌面上的打包版本啊?还有这个Linux的版本。两个包有没有更新?"

——没有。此前只改了源码目录的 config.json,两个打包产物都还是旧配置。沿配置加载链路排查:

• 桌面快捷方式 → D:\code\kimi_cg\dist\豆包语音输入.exe(9 月 4 日打包);
• main.py:67-77 的加载逻辑:exe 同目录的 config.json 优先,找不到才回退到 PyInstaller 内嵌配置;而 dist/ 下恰恰没有 config.json,exe 一直在用打包时嵌入的旧配置(api_key 为空,走旧版 app_key+access_key 鉴权);
• dist/voice_input.log 给出硬证据:20:47:12 识别失败: server rejected WebSocket connection: HTTP 403 —— 旧凭证已被服务端拒绝。

修复方案因此很简单:把新 config.json 复制到 dist/,免重新打包。重启运行中的两个进程后,日志 20:50:10 已加载 177 个热词 / 已启动:按住【space】说话,当场恢复。

第四步:Linux 包不是改配置,是重建

doubao-voice-linux.zip 逐文件 diff 后发现它是 7 月 21 日的源码快照:11 个文件里 6 个已落后于仓库(main.py/asr_client.py/hotkey.py/injector.py/build_linux.sh/README.md),而且缺 corrector.py——当前 main.py:18 已经 import corrector,旧包在 Linux 上根本跑不起来。

处置:用仓库当前源码重建 zip,共 15 个文件,config.json 与 config.linux.json 都写入新 key,补齐 corrector.py、hotwords.txt、corrections.txt。

关键踩坑

坑 1:Git Bash 内联 PowerShell,$ 变量全军覆没。 第一次生成测试音频用 powershell -Command "...$s.GetInstalledVoices()..." 内联写法,bash 先把 $s、$zh 当自己的变量展开成空串,PowerShell 收到一堆语法错误;中文台词也变成乱码。解法:写成 test_tts.ps1 文件,再用 Python 转成 UTF-16LE 带 BOM 后 powershell -File 执行,一次通过。

坑 2:Windows Python 不认 Git Bash 的 /tmp。 重建 zip 时先在 /tmp/linuxzip 备好文件,zipfile.write('/tmp/linuxzip/...') 直接 FileNotFoundError——Windows 进程看到的是字面路径。改从仓库目录 D:\code\kimi_cg 直接打包。另:Git Bash 无 zip 命令,打包走 Python zipfile。

最终方案

核心机制一条:main.py 的配置加载是"外置优先、内嵌兜底"——这意味着改 key 这类纯配置变更不需要重新打包,往 exe 同目录放一份新 config.json 即可生效;但前提是维护者知道这条链路,否则就会像本次一样,源码修好了、用户手里的 exe 还在用旧凭证报 403。

做得好的地方

1. 诊断靠代码取证不靠猜:14 个资源里定位唯一依赖,依据是 resource_id 和 ws_url 两行代码,结论可直接复核;
2. 验证用端到端实测:合成语音参数(16kHz/16bit/mono)对齐协议要求,识别结果一字不差,比"key 填进去没报错"硬得多;
3. 本人第三问的价值:不满足于"能用了",追问分发产物覆盖面,直接抓出 AI 的漏项——这正是交付面思维。

复盘与改进

1. AI 侧机制缺口:改配置必须沿加载链路追产物。 本次 config.json 改完、实测通过后,军师没有主动想到 dist exe 内嵌旧配置、Linux zip 是旧快照,被本人抓到才补。固化规则:凡修改被分发产物引用的配置,交付前必答"哪些产物内嵌或外置了这份配置",逐个核销。
2. 同类坑重犯。 "内联 PowerShell 经 bash 必翻车"在 10-09 台账已有记录(BOM 被 bash 吞),本次换个形式又踩一次——规则记录了但没映射成肌肉记忆,下次涉及 PowerShell 直接默认写 ps1 文件路线。
3. 资源包余量要有预警。 20 小时时长包用完会再次断服(本次断服的根因就是到期),语音输入是高频工具,值得在控制台配预警或在日志里加失败告警。

成长评估

AI 自评失分点(同场):

1. 配置修复后未主动排查打包产物(dist exe 内嵌旧配置、Linux zip 旧快照),被本人第三条指令抓到补漏——本场最大失分;
2. 内联 PowerShell 生成测试音频翻车一次($ 展开+中文乱码),属台账已录教训的重犯;
3. 重建 zip 时 Windows Python 认 /tmp 路径报错,环境边界意识慢了半拍。

指令实证:

1. "我重新创建了一个api:…,你帮我测试下看看" → AI 行为:不停留在改配置,合成中文语音走真实 WebSocket 接口端到端实测;证据=config.json:2 + 识别输出一字不差 + dist/voice_input.log 20:50 正常启动。
2. "你有没有帮我替换这个桌面上的打包版本啊?还有这个Linux的版本。两个包有没有更新?" → AI 行为:从单点配置修改升级为配置加载链路排查(main.py:67-77 外置优先),落地 dist/config.json + 进程重启 + Linux zip 15 文件重建;证据=dist/config.json、doubao-voice-linux.zip。

素材点

• "14 个资源关停通知 vs 项目只用 1 个模型"的取证式诊断过程,可写 S3 向短文:云服务到期排障第一步是读代码定位真实依赖;
• "改 key 不用重新打包"的外置配置优先机制,对 PyInstaller 分发工具的人有直接抄走价值;
• Git Bash × PowerShell × 中文编码的三重翻车现场,是 Windows 下自动化脚本的经典坑位。