音频排障指南
本页覆盖 OPL 数据空间 中语音转文本（STT）和文本转语音（TTS）的常见问题，以及对应的排查思路。
去哪里找音频设置
管理员设置（全站）
管理员可以配置全实例默认音频行为：
- 点击左下角头像
- 打开 管理面板
- 顶部切到 设置
- 进入 音频
这里可以配置：
- 语音转文本引擎：本地 Whisper、OpenAI、Azure、Deepgram、Mistral
- Whisper Model：本地 STT 的模型大小
- 文本转语音引擎：OpenAI 兼容、Mistral、ElevenLabs、Azure、本地 Transformers，或关闭后端 TTS
- TTS 语音：默认语音
- API 密钥 / Base URL：外部服务连接信息
用户设置（每个用户）
单个用户也可以覆盖自己的音频体验：
- 点击左下角头像
- 打开 设置
- 进入 音频
用户级常见选项包括：
- STT 引擎覆盖：例如改用浏览器 Web API
- STT 语言：指定转写语言
- TTS 引擎：例如改用浏览器端语音
- TTS 语音：选择可用音色
- 自动播放：AI 回复后自动播放
- 播放速度：播放速度
- 对话模式：免手动语音交互
提示
用户设置会覆盖管理员默认值。遇到音频问题时，要同时检查管理员和用户两侧，避免被局部覆盖误导。
组织感知排障
如果你启用了组织，管理员音频配置可能来自当前选中的组织作用域。某个组织自己的 STT / TTS 覆盖设置，可能导致“全局看起来正常，但只有这个组织坏了”。排查前先确认当前 admin scope。
快速可用配置
最快上手：OpenAI
在 管理面板 → 设置 → 音频 中：
- STT Engine:
OpenAI - Model:
whisper-1 - TTS Engine:
OpenAI - Model:
tts-1 - Voice:
alloy
也可以直接用环境变量：
environment:
- AUDIO_STT_ENGINE=openai
- AUDIO_STT_OPENAI_API_KEY=sk-...
- AUDIO_TTS_ENGINE=openai
- AUDIO_TTS_OPENAI_API_KEY=sk-...
- AUDIO_TTS_MODEL=tts-1
- AUDIO_TTS_VOICE=alloy完整说明见：
Mistral STT + TTS
如果你使用 Mistral 音频栈：
- STT Engine:
MistralAI - Model:
voxtral-mini-latest - TTS Engine:
MistralAI - Model:
mistral-tts-latest - Voice: 选择可用音色
常见问题
STT 无法转写
检查项：
- 确认当前 STT 引擎与 API key 配置正确
- 如果是本地 Whisper，确认模型已下载完成
- 如果是浏览器 Web API，确认浏览器已授予麦克风权限
- 检查用户级设置是否把 STT 引擎覆盖成了别的选项
本地 Transformers TTS 崩溃或依赖冲突
如果你用的是本地 Transformers TTS，常见问题是依赖版本冲突，尤其是 datasets。
可尝试：
environment:
- EXTRA_PIP_PACKAGES=datasets==3.6.0然后重启容器，并确认安装结果：
docker exec open-webui bash -lc "pip show datasets"提示
如果你不想被本地 TTS 依赖问题拖住，通常更推荐接外部 TTS，例如 OpenAI Edge TTS 或 Kokoro。
TTS 没声音 / Voice 不存在
检查项：
- 管理员侧 Audio 设置里的引擎是否正确
- 语音名称是否真的存在于该引擎
- 如果是外部服务，API Base URL 是否能从 OPL 数据空间 容器访问
- 查看容器日志里是否有 401、404、连接失败等报错
Docker 网络问题
如果 OPL 数据空间 在 Docker 里，而你的 TTS 服务在宿主机上，localhost 往往不可用。
可改成：
host.docker.internal（Docker Desktop on macOS / Windows）- 同一网络下的容器服务名，例如
http://openai-edge-tts:5050/v1