5.13开发博客

开发日志（2026年5月13日）

今日主题：语音识别功能调试

今天主要搞 AI 智能问答模块里的语音输入，踩了几个坑，记录一下。

问题一：0.0.0.0 访问不了

启动服务后习惯性地在浏览器敲 http://0.0.0.0:8000，结果打不开，有点懵。查了一下才反应过来，0.0.0.0 是告诉服务器“监听所有网卡”，但作为访问地址是没有意义的，得老老实实写 127.0.0.1 或者 localhost。

问题二：Whisper 模型下载失败

点击麦克风按钮，后端直接甩回来一段报错：

{"detail":"无法下载 Whisper 模型，请检查网络连接或使用代理"}

看一眼就大概猜到了，faster-whisper 默认去 Hugging Face Hub 拉模型（tiny 版大概 75MB），国内网络直连基本没戏。解决方案就是在启动脚本里加上 Hugging Face 镜像的环境变量：

import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

这样模型会走国内的 HF Mirror，下载很快。

问题三：前端判断条件写错了，数据都返回了还提示失败

这是最让人无语的一个。后端日志已经显示语音识别成功，返回的 JSON 也是正常的：

{"code": 0, "message": "success", "data": {"text": "没法就喇叭", ...}}

结果前端页面上弹出来的却是“⚠ 未识别到语音内容，请重试”。对着前端代码找了半天，发现是状态码判断写成了 code === 200，而我们后端的统一响应里成功是 code: 0。改成 code === 0 就立刻好了。

小结

今天这三个问题，一个比一个低级，但都挺典型的：

• 网络基础不扎实，0.0.0.0 和 127.0.0.1 的区别偶尔会忘。
• 第三方库依赖外部网络时，国内开发环境最好第一时间配好镜像。
• 前后端约定好的状态码一定要对齐，不然就会出现这种“后端明明返回了数据，前端却当失败处理”的尴尬。

语音输入功能总算能用了，Whisper tiny 模型识别准确度一般般，不过离线跑能有这个效果已经可以接受了，后面有需要再考虑换大模型或者加端点检测。