音频故障排除指南

本页面介绍了 Open WebUI 中语音转文字 (STT) 和文字转语音 (TTS) 功能的常见问题及其解决方案。

如何找到音频设置

管理员设置（全站）

管理员可以配置全站的默认音频设置：

点击您的头像/个人信息图标（左下角）
选择 Admin Panel（管理员面板）
在顶部导航栏中点击 Settings（设置）
选择 Audio（音频）标签页

您可以在此处配置：

Speech-to-Text Engine（语音转文字引擎） — 在本地 Whisper、OpenAI、Azure、Deepgram 或 Mistral 之间进行选择
Whisper Model — 选择本地 STT 的模型大小（tiny、base、small、medium、large）
Text-to-Speech Engine（文字转语音引擎） — 选择兼容 OpenAI 的接口、Mistral、ElevenLabs、Azure、本地 Transformers，或者禁用后端 TTS（仅使用浏览器）
TTS Voice — 选择默认语音
API Keys and Base URLs（API 密钥和基础 URL） — 配置外部服务的连接

用户设置（单用户）

个人用户可以自定义其音频体验：

点击您的头像/个人信息图标（左下角）
选择 Settings（设置）
点击 Audio（音频）标签页

用户级选项包括：

STT Engine Override（重写 STT 引擎） — 使用 "Web API" 进行基于浏览器的语音识别
STT Language — 设置首选的转录语言
TTS Engine — 选择 "Browser Kokoro" 进行本地浏览器内 TTS
TTS Voice — 从可用语音中进行选择
Auto-playback（自动播放） — 自动播放 AI 的回复
Playback Speed（播放速度） — 调节音频速度
Conversation Mode（通话模式） — 启用免提语音交互

提示

用户设置会覆盖管理员的默认设置。如果您遇到问题，请同时检查这两个位置，以确保设置之间没有冲突。

快速设置指南

最快设置：OpenAI（付费）

如果您有 OpenAI API 密钥，这是最简单的设置方式：

在 Admin Panel（管理员面板） → Settings（设置） → Audio（音频）中：

STT Engine: OpenAI | Model: whisper-1
TTS Engine: OpenAI | Model: tts-1 | Voice: alloy
在这两个部分中输入您的 OpenAI API 密钥

或者通过环境变量进行配置：

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

→ 参见完整指南：Speech-to-Text | Text-to-Speech

快速设置：Mistral STT + TTS（付费）

如果您更喜欢使用 Mistral 的音频技术栈：

在 Admin Panel（管理员面板） → Settings（设置） → Audio（音频）中：

STT Engine: MistralAI | Model: voxtral-mini-latest（或留空）
TTS Engine: MistralAI | Model: mistral-tts-latest（或留空） | Voice: 从列表中选择
在这两个部分中输入您的 Mistral API 密钥

或者通过环境变量进行配置：

environment:
  - AUDIO_STT_ENGINE=mistral
  - AUDIO_STT_MISTRAL_API_KEY=...
  - AUDIO_TTS_ENGINE=mistral
  - AUDIO_TTS_MISTRAL_API_KEY=...
  - AUDIO_TTS_MODEL=mistral-tts-latest

→ 参见指南：Mistral Voxtral STT | Mistral TTS

免费设置：本地 Whisper + Edge TTS

如果您想要完全免费的设置：

STT： 将引擎留空（使用在后端运行的内置 Whisper）

environment:
  - WHISPER_MODEL=base  # 选项有：tiny, base, small, medium, large

TTS： 使用 OpenAI Edge TTS（免费的微软语音）

services:
  openai-edge-tts:
    image: travisvn/openai-edge-tts:latest
    ports:
      - "5050:5050"

  open-webui:
    environment:
      - AUDIO_TTS_ENGINE=openai
      - AUDIO_TTS_OPENAI_API_BASE_URL=http://openai-edge-tts:5050/v1
      - AUDIO_TTS_OPENAI_API_KEY=not-needed

→ 参见完整指南：OpenAI Edge TTS

仅限浏览器设置（无需后端配置）

如需在不进行任何服务器端音频处理的情况下使用基本功能：

在 User Settings（用户设置） → Audio（音频）中：

STT Engine: Web API（使用浏览器内置的语音识别；不会调用后端的 STT 接口）
TTS Engine: Web API 或 Browser Kokoro（使用浏览器内置的文本转语音或客户端的 Kokoro；不会调用后端的 TTS 接口）

备注

当管理员将 AUDIO_TTS_ENGINE 留空（默认值）时，表示后端没有可用的 TTS 服务。所有的 TTS 均在客户端处理。同样地，如果用户在用户设置中为 STT选择 "Web API"，则不会使用后端的本地 Whisper。

麦克风访问问题

理解安全上下文

出于安全原因，对麦克风的访问权限被限制在通过 HTTPS 或本地 localhost 提供服务的页面上。这一要求的目的是通过确保您的数据在安全通道上传输，来保障您的数据安全。

常见权限问题 🚫

诸如 Chrome、Brave、Microsoft Edge、Opera、Vivaldi 以及 Firefox 等浏览器，都会限制非 HTTPS 链接的麦克风访问。这在从同一网络内的另一台设备访问网站时通常会成为问题（例如，使用手机访问运行在台式机上的服务器）。

非 HTTPS 连接的解决方案

设置 HTTPS（推荐）：
- 将您的服务器配置为支持 HTTPS。这不仅可以解决权限问题，还能提高数据传输的安全性。
- 您可以使用 Nginx 或 Caddy 等反向代理，配合 Let's Encrypt 证书来实现。
临时浏览器 Flag（谨慎使用）：
- 这些设置强迫您的浏览器将某些非安全 URL 视为安全 URL。这在开发阶段很有用，但会带来严重的安全风险。
基于 Chromium 的浏览器（例如 Chrome、Brave）：
- 打开 chrome://flags/#unsafely-treat-insecure-origin-as-secure
- 输入您的非 HTTPS 地址（例如：http://192.168.1.35:3000）
- 重启浏览器以应用更改
基于 Firefox 的浏览器：
- 打开 about:config
- 搜索并修改（或创建）字符串值 dom.securecontext.allowlist
- 添加您的 IP 地址，用英文逗号分隔（例如：http://127.0.0.1:8080）

注意

虽然浏览器 Flag 提供了快速修复方法，但它们绕过了重要的安全检查，这可能会使您的设备和数据面临漏洞风险。请始终优先考虑妥善的安全措施，特别是在规划生产环境时。

麦克风无法工作

如果即使在 HTTPS 下麦克风图标也没有反应：

检查浏览器权限： 确保您的浏览器已允许该网站访问麦克风
检查系统权限： 在 Windows/Mac 上，确保在系统设置中允许浏览器访问麦克风
检查浏览器兼容性： 某些浏览器对 STT 的支持有限
尝试使用不同的浏览器： Chrome 通常对 Web Audio API 具有最佳的支持

Text-to-Speech (TTS) 问题

TTS 无限加载 / 无法工作

如果点击对话回复中的播放按钮导致无限加载，请尝试以下解决方案：

1. Hugging Face Dataset 库冲突（本地 Transformers TTS）

症状：

TTS 一直处于加载状态，无法播放
容器日志显示：RuntimeError: Dataset scripts are no longer supported, but found cmu-arctic-xvectors.py

原因： 这在使用本地 Transformers TTS (AUDIO_TTS_ENGINE=transformers) 时会发生。datasets 库是作为 transformers 包的间接依赖项引入的，并没有在 Open WebUI 的 requirements 中锁定特定版本。新版本的 datasets 移除了对数据集加载脚本的支持，从而在加载说话人嵌入（speaker embeddings）时引发了此错误。

解决方案：

临时修复方法（容器重启后会失效，需要重新配置）：

docker exec open-webui bash -lc "pip install datasets==3.6.0" && docker restart open-webui

使用环境变量进行永久修复： 在您的 docker-compose.yml 中添加以下内容：

environment:
  - EXTRA_PIP_PACKAGES=datasets==3.6.0

验证已安装的版本：

docker exec open-webui bash -lc "pip show datasets"

提示

建议考虑使用外部 TTS 服务，例如 OpenAI Edge TTS 或 Kokoro，以代替本地 Transformers TTS，从而避免这些依赖冲突。

2. 使用外部 TTS 代替本地 TTS

如果您在本地 TTS 上仍然遇到问题，配置外部 TTS 服务通常更为可靠。请参考下面使用 openai-edge-tts 的 Docker Compose 示例配置：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - AUDIO_TTS_ENGINE=openai
      - AUDIO_TTS_OPENAI_API_KEY=your-api-key-here
      - AUDIO_TTS_OPENAI_API_BASE_URL=http://openai-edge-tts:5050/v1
    depends_on:
      - openai-edge-tts
    # ... 其他配置

  openai-edge-tts:
    image: travisvn/openai-edge-tts:latest
    ports:
      - "5050:5050"
    environment:
      - API_KEY=your-api-key-here
    restart: unless-stopped

TTS 语音未找到 / 无音频输出

核对清单：

验证在 **Admin Panel（管理员面板） → Settings（设置） → Audio（音频）**中是否正确配置了 TTS 引擎
检查语音名称是否与您选择的引擎的可用语音相匹配
对于外部 TTS 服务，验证从 Open WebUI 容器是否可以访问 API Base URL
检查容器日志是否有任何错误信息

Docker 网络与 TTS 间的问题

如果 Open WebUI 无法连接到您的 TTS 服务：

问题： 在 API Base URL 中使用 localhost 在 Docker 容器内部是无法访问的。

解决方案：

使用 host.docker.internal 代替 localhost（适用于 Windows/Mac 的 Docker Desktop）
如果两个服务在同一个 Docker 网络上，请使用容器名称（例如 http://openai-edge-tts:5050/v1）
使用宿主机的实际 IP 地址

Speech-to-Text (STT) 问题

Whisper STT 无法工作 / 计算类型错误

症状：

错误信息：Error transcribing chunk: Requested int8 compute type, but the target device or backend do not support efficient int8 computation
STT 无法处理音频，通常会显示持续的加载图标或弹窗显示红色的错误提示。

原因： 这通常发生在配合 NVIDIA GPU 使用 :cuda Docker 镜像，而该 GPU 不支持所需的 int8 计算操作时（在较旧的 Maxwell 或 Pascal 架构 GPU 上很常见）。在 v0.6.43 版本中，由于一个回归（regression），导致计算类型在某些场景下被错误地默认或硬编码为 int8。

解决方案：

1. 升级到最新版本（推荐）

最可靠的修复方法是升级到最新版本的 Open WebUI。最近的更新已确保能正确遵循 WHISPER_COMPUTE_TYPE，并为 CUDA 环境提供了优化后的默认设置。

2. 手动设置计算类型

如果您目前使用的是受影响的版本，或者在 GPU 上依然遇到此问题，可以显式地将计算类型设置为 float16：

environment:
  - WHISPER_COMPUTE_TYPE=float16

3. 切换到标准镜像

如果您的 GPU 非常老旧或者兼容性问题依然存在，请切换到标准的（基于 CPU 的）镜像。对于像 Whisper 这样较小的模型，CPU 模式通常可以提供不错的性能，且不会产生兼容性问题：

# 替代以下镜像：
# ghcr.io/open-webui/open-webui:cuda

# 使用此镜像：
ghcr.io/open-webui/open-webui:main

信息

CUDA 镜像主要加速了 RAG 嵌入/重排（embedding/reranking）模型和 Whisper STT。对于像 Whisper 这样较小的模型，CPU 模式通常能提供相近的性能，且完全没有兼容性方面的困扰。

调整 Whisper 计算类型

如果您希望保留 GPU 加速，请尝试更改计算类型：

environment:
  - WHISPER_COMPUTE_TYPE=float16  # GPU 推荐设置

可用的计算类型（源自 faster-whisper）：

计算类型	最佳适用场景	备注
`int8`	CPU（默认）	速度最快，但在老旧的 GPU 上无法工作
`float16`	CUDA/GPU（推荐）	对 GPU 而言在速度和兼容性上达到了最佳平衡
`int8_float16`	混合精度的 GPU	对权重使用 int8，对计算使用 float16
`float32`	最大兼容性	速度最慢，但能在所有硬件上正常工作

默认行为

CPU 模式： 默认为 int8 以获得最佳性能
CUDA 模式： :cuda 镜像可能默认使用 int8，这可能会在较旧的 GPU 上引发错误。对于 GPU，请显式设置为 float16。

STT 无法正确识别语音

获得更佳识别效果的技巧：

设置正确的语言：

environment:
  - WHISPER_LANGUAGE=zh  # 使用 ISO 639-1 语言代码（例如 zh 表示中文，en 表示英文）

尝试使用更大的 Whisper 模型以提高准确性（代价是识别速度会变慢）：
```
environment:
  - WHISPER_MODEL=medium  # 选项有：tiny, base, small, medium, large
```
检查浏览器麦克风权限（参考上文）
使用 Web API 引擎作为替代方案：
- 前往用户设置（非管理员面板）
- 在 STT Settings（STT 设置）下，尝试将 Speech-to-Text Engine（语音转文字引擎）切换为 "Web API"
- 这将直接使用浏览器内置的语音识别功能

ElevenLabs 集成

Open WebUI 原生支持 ElevenLabs。配置步骤如下：

前往 Admin Panel（管理员面板） → Settings（设置） → Audio（音频）
选择 ElevenLabs 作为 TTS 引擎
输入您的 ElevenLabs API 密钥
选择语音和模型
保存设置

使用环境变量：

environment:
  - AUDIO_TTS_ENGINE=elevenlabs
  - AUDIO_TTS_API_KEY=sk_...  # 您的 ElevenLabs API 密钥
  - AUDIO_TTS_VOICE=EXAVITQu4vr4xnSDxMaL  # 来自 ElevenLabs 后台的语音 ID
  - AUDIO_TTS_MODEL=eleven_multilingual_v2

备注

您可以在 ElevenLabs 控制台的语音设置中找到您的 Voice ID。常见的模型选项包括 eleven_multilingual_v2 或 eleven_monolingual_v1。

通用调试提示

检查容器日志

# 查看 Open WebUI 日志
docker logs open-webui -f

# 查看外部 TTS 服务的日志（如果适用）
docker logs openai-edge-tts -f

检查浏览器控制台

打开浏览器开发者工具（F12 或右键点击 → 检查）
切换到控制台 (Console) 标签页
在尝试使用音频功能时，寻找相关的错误日志

验证服务健康状况

对于外部 TTS 服务，可以直接进行测试：

# 测试 OpenAI Edge TTS
curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{"input": "Hello, this is a test.", "voice": "alloy"}' \
  --output test.mp3

网络连通性

验证 Open WebUI 容器能否访问外部服务：

# 进入容器
docker exec -it open-webui bash

# 测试连通性（如果容器内有 curl 可用）
curl http://your-tts-service:port/health

快速参考：环境变量

TTS 环境变量

变量	描述
`AUDIO_TTS_ENGINE`	TTS 引擎：`""`（留空，禁用后端 TTS - 使用浏览器）、`openai`、`mistral`、`elevenlabs`、`azure`、`transformers`
`AUDIO_TTS_MODEL`	要使用的 TTS 模型（默认：`tts-1`）
`AUDIO_TTS_VOICE`	TTS 默认语音（默认：`alloy`）
`AUDIO_TTS_API_KEY`	ElevenLabs 或 Azure TTS 的 API 密钥
`AUDIO_TTS_OPENAI_API_BASE_URL`	兼容 OpenAI 的 TTS 的基础 URL
`AUDIO_TTS_OPENAI_API_KEY`	兼容 OpenAI 的 TTS 的 API 密钥
`AUDIO_TTS_MISTRAL_API_KEY`	Mistral TTS 的 API 密钥
`AUDIO_TTS_MISTRAL_API_BASE_URL`	Mistral TTS 的基础 URL

STT 环境变量

变量	描述
`WHISPER_MODEL`	Whisper 模型：`tiny`、`base`、`small`、`medium`、`large`（默认：`base`）
`WHISPER_COMPUTE_TYPE`	计算类型：`int8`、`float16`、`int8_float16`、`float32`（默认：`int8`）
`WHISPER_LANGUAGE`	ISO 639-1 语言代码（留空 = 自动检测）
`WHISPER_VAD_FILTER`	是否启用语音活动检测（VAD）过滤器（默认：`False`）
`AUDIO_STT_ENGINE`	STT 引擎：`""`（留空，使用本地 Whisper）、`openai`、`azure`、`deepgram`、`mistral`
`AUDIO_STT_OPENAI_API_BASE_URL`	兼容 OpenAI 的 STT 的基础 URL
`AUDIO_STT_OPENAI_API_KEY`	兼容 OpenAI 的 STT 的 API 密钥
`DEEPGRAM_API_KEY`	Deepgram API 密钥

完整的音频环境变量列表，请参见环境变量配置。

仍然有问题？

如果您尝试了上述解决方案后仍有问题：

在 GitHub 上搜索现有 Issue 以查看是否有类似的问题
查看 Discussions 获取社区提供的解决方案
创建一个新的 Issue，并提供以下信息：
- Open WebUI 版本
- 正在使用的 Docker 镜像
- 完整的错误日志
- 非常详尽的复现步骤
- 您的环境详情（操作系统、如果适用的话还包括 GPU 信息）

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

如何找到音频设置​

管理员设置（全站）​

用户设置（单用户）​

快速设置指南​

最快设置：OpenAI（付费）​

快速设置：Mistral STT + TTS（付费）​

免费设置：本地 Whisper + Edge TTS​

仅限浏览器设置（无需后端配置）​

麦克风访问问题​

理解安全上下文​

常见权限问题 🚫​

非 HTTPS 连接的解决方案​

麦克风无法工作​

Text-to-Speech (TTS) 问题​

TTS 无限加载 / 无法工作​

1. Hugging Face Dataset 库冲突（本地 Transformers TTS）​

2. 使用外部 TTS 代替本地 TTS​

TTS 语音未找到 / 无音频输出​

Docker 网络与 TTS 间的问题​

Speech-to-Text (STT) 问题​

Whisper STT 无法工作 / 计算类型错误​

1. 升级到最新版本（推荐）​

2. 手动设置计算类型​

3. 切换到标准镜像​

调整 Whisper 计算类型​

STT 无法正确识别语音​

ElevenLabs 集成​

通用调试提示​

检查容器日志​

检查浏览器控制台​

验证服务健康状况​

网络连通性​

快速参考：环境变量​

TTS 环境变量​

STT 环境变量​

仍然有问题？​

如何找到音频设置

管理员设置（全站）

用户设置（单用户）

快速设置指南

最快设置：OpenAI（付费）

快速设置：Mistral STT + TTS（付费）

免费设置：本地 Whisper + Edge TTS

仅限浏览器设置（无需后端配置）

麦克风访问问题

理解安全上下文

常见权限问题 🚫

非 HTTPS 连接的解决方案

麦克风无法工作

Text-to-Speech (TTS) 问题

TTS 无限加载 / 无法工作

1. Hugging Face Dataset 库冲突（本地 Transformers TTS）

2. 使用外部 TTS 代替本地 TTS

TTS 语音未找到 / 无音频输出

Docker 网络与 TTS 间的问题

Speech-to-Text (STT) 问题

Whisper STT 无法工作 / 计算类型错误

1. 升级到最新版本（推荐）

2. 手动设置计算类型

3. 切换到标准镜像

调整 Whisper 计算类型

STT 无法正确识别语音

ElevenLabs 集成

通用调试提示

检查容器日志

检查浏览器控制台

验证服务健康状况

网络连通性

快速参考：环境变量

TTS 环境变量

STT 环境变量

仍然有问题？