语音消息一夜之间全转不出来: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——那不是配置自由度,那是一个定时炸弹。