语音消息一夜之间全转不出来:PyAV 19 撞上 faster-whisper 1.2.1 的那一行参数


早上七点半,你在通勤路上往 Telegram 的 Hermes 机器人发了三条语音:一条说今天的三个待办,一条转发会议里的一句结论,一条只是试试网络通不通。到公司打开电脑,三条全部回你同一句话——无法转写。

你没升级过任何东西,没改过配置,昨天还好好的。更让人困惑的是:文字消息一切正常,只有语音这一条路断了。

这种“什么都没动却坏了”的故障,八成不是应用代码改了,而是依赖在你不注意的时候自己动了。这次就是一个教科书级的例子。

现象与真凶

本地语音转写这条链路是这样的:平台发来一条语音文件,Hermes 把它交给本地 STT 引擎(faster-whisper,跑在 ctranslate2 上),音频解码则交给 PyAV——Python 版的 FFmpeg 绑定。转写失败时,网关会把这条消息标成 [voice message could not be transcribed],如果音频被落盘了,还会附上路径,方便你事后自己转。

真正抛错的地方在解码这一层。faster-whisper 1.2.1 打开音频时,会这样调用:

av.open(path, metadata_errors="ignore")

metadata_errors 是“遇到坏元数据时怎么办”的开关。PyAV 19 把这个参数删掉了。于是同一行代码在 PyAV 19 上直接抛:

TypeError: open() got an unexpected keyword argument 'metadata_errors'

异常一路冒上去,转写工具判定失败,网关就把消息写成“无法转写”。你看到的是三个字的结果,背后是一次 TypeError。

为什么它突然就坏了

因为 faster-whisper 对 PyAV 的版本要求写得很松:av>=11。这条约束的意思是“11 以上都行”,所以 PyAV 19 发布之后,任何一次重新解析依赖的安装都会心甘情愿地把 19 拉进来——今天的解锁解析拿到的是 av==19.0.2。

于是同一台机器上会出现两种截然不同的命运:

  • 锁定安装:uv.lock 里写死的是 av==18.1.0,装出来的组合是好的,一切正常。
  • 解锁安装(比如你装 hermes-agent[stt-whisper] 这个 extra,或者重建了虚拟环境):解析器拉到 19,语音就全挂。

这也解释了“昨天还好好的”:出问题的不是你的操作,而是某次依赖重装。容器镜像重建、pip install -U、换个 Python 版本、甚至 CI 缓存失效,都可能触发。

为什么不能靠升级解决

正常的思路是“把这个库升到修好的版本”。这次行不通,原因很实在:

  • PyPI 上 faster-whisper 的最新版仍然是 1.2.1,没有更新的版本可装。
  • 上游其实已经修了这个问题(SYSTRAN/faster-whisper#1495),但这个修复还没有进入任何 release。

也就是说,在“等上游发版”和“现在就要能用”之间,只剩一条路:把 PyAV 钉在 19 以下。

修复:把 av 钉在 18.1.0

11 月 8 日合入的 PR #150984 做的就是这件事,改法很朴素但每一步都有理由:

  • av>=11,<19 改成 av==18.1.0。这个仓库的直接依赖本来就是精确钉版本的(pyproject.toml 开头就写了这条约定),所以用 == 而不是加个上限。
  • 为什么是 18.1.0:它 2026 年 8 月 12 日就发布了,远超仓库“至少两周”的年龄规则,而且它本来就是 lock 文件里的版本——换句话说,这不是新引入一个陌生版本,而是把已经验证过能用的那个版本写进约束。
  • 平台标记跟 faster-whisper 完全对齐:win32-arm64(ctranslate2 没有 wheel)和 darwin-x64(onnxruntime 没有 wheel)本来就不走本地 STT 这条路,另外加上 sys_platform != 'android'。
  • uv.lock 重新生成,diff 只有记录新约束的四行,解析出来的版本没有任何变化——这一点很重要:修复不应该顺带升级别的东西。

两个 extra 都要钉:[voice](语音输入/唤醒词那一套)和 [stt-whisper](单独的本地转写)引用的是同一组包,漏一个就还会有人中招。

你自己机器上怎么确认、怎么救

先确认症状对不对得上。最直接的一步是看 PyAV 的版本:

python -c "import av; print(av.__version__)"

如果是 19.x,那你很可能就是这个坑。想看得更细,直接复现那一行调用:

python -c "import av; av.open('/path/to/any.wav', metadata_errors='ignore')"

在 19 上它会立刻抛 TypeError,一字不差。

如果你管着自己的虚拟环境(不是靠 Hermes 的锁定安装),最省事的止血办法就是把它降回来:

pip install 'av==18.1.0'

然后重启网关(或者重启那个跑着 STT 的进程),再发一条语音试试。若你用的是官方安装方式,升级到包含这个 pin 的版本即可,不需要手动干预。

如果你根本不想在本地跑模型——那也有一条完全不碰 PyAV 的路:把转写交给云端。站内那篇 DashScope 语音转写插件 讲的就是这个方案,适合机器性能一般、或者不想维护本地模型的场景。

三个可以带走的经验

一、“锁文件是好的”不等于“装出来是好的”。 这次锁定安装一直没坏,坏的是解锁安装。如果你的部署里有任何一处会重新解析依赖(Docker 构建、CI、pip install 一个新包),你就同时拥有两种环境,而它们的行为不一样。

二、传递依赖的上限,只能由直接依赖来兜。 faster-whisper 声明 av>=11 时并不会预料到 19 会删参数;语义化版本对这种“参数被移除”的破坏性改动保护有限。当上游不打算马上发版时,把版本钉死是最诚实的选择——它承认“我们知道哪个组合能用”。

三、错误信息在终点被磨平了。 你看到的是“无法转写”,真正的 TypeError 埋在日志里。排查这类“功能整体失效”的问题,第一站永远是日志里那行异常,而不是界面上的那句话。如果你还没养成翻日志的习惯,站内的 hermes doctor 命令参考 可以先做一次环境体检。

顺带一提:如果你正在搭语音入口(比如接家里的音箱),这套本地转写链路的完整配置可以看 把 Hermes 接进 Home Assistant,那里的语音链路跟这里讲的是同一套依赖。

状态

这个 pin(PR #150984)在 main 上,2026 年 11 月 8 日合入;v0.23.0 的 pyproject.toml 里根本没有 av 这行直接依赖,它当时完全由 faster-whisper 传递拉进来。所以:老版本 + 锁定安装 = 没事;老版本 + 解锁安装 = 可能中招。

要么升级到带这个 pin 的版本,要么先手动把 av 钉回 18.1.0。别用 av>=11 这种松约束去装本地 STT——那不是配置自由度,那是一个定时炸弹。