跳到主要内容

使用 Docker 部署 Openedai-speech

注意

本教程为社区贡献，不属于 Open WebUI 官方支持内容。它仅作为如何针对特定用例定制 Open WebUI 的演示。想要参与贡献？请查看贡献教程。

使用 Docker 将 openedai-speech 集成到 Open WebUI 中​

什么是 openedai-speech？​

信息

openedai-speech 是一个兼容 OpenAI Audio/Speech API 规范的文本转语音 (TTS) 服务器。

它提供了 /v1/audio/speech 端点，旨在为用户提供免费、私密的文本转语音体验，并具备自定义声音克隆能力。此服务与 OpenAI 没有任何关联，亦无需 OpenAI API Key。

要求​

  • 系统中已安装 Docker
  • Open WebUI 正在 Docker 容器中运行
  • 对 Docker 和 Docker Compose 有基础了解

选项 1：使用 Docker Compose​

步骤 1：为 openedai-speech 服务创建新文件夹​

创建一个新文件夹（例如 openedai-speech-service），用于存储 docker-compose.yml 和 speech.env 文件。

步骤 2：从 GitHub 克隆 openedai-speech 仓库​

git clone https://github.com/matatonic/openedai-speech.git

这会将 openedai-speech 仓库下载到您的本地机器，其中包括 Docker Compose 配置文件（docker-compose.yml、docker-compose.min.yml 和 docker-compose.rocm.yml）及其他必要文件。

步骤 3：将 sample.env 文件重命名为 speech.env（根据需要自定义）​

在 openedai-speech 仓库文件夹中，新建一个名为 speech.env 的文件，内容如下：

TTS_HOME=voices
HF_HOME=voices

#PRELOAD_MODEL=xtts

#PRELOAD_MODEL=xtts_v2.0.2

#PRELOAD_MODEL=parler-tts/parler_tts_mini_v0.1

#EXTRA_ARGS=--log-level DEBUG --unload-timer 300

#USE_ROCM=1

步骤 4：选择 Docker Compose 文件​

您可以使用以下任意一个 Docker Compose 配置文件：

步骤 5：构建选定的 Docker 镜像​

在运行 Docker Compose 之前，您需要构建相应的 Docker 镜像：

  • Nvidia GPU（CUDA 支持）：
docker build -t ghcr.io/matatonic/openedai-speech .
  • AMD GPU（ROCm 支持）：
docker build -f Dockerfile --build-arg USE_ROCM=1 -t ghcr.io/matatonic/openedai-speech-rocm .
  • 纯 CPU，无 GPU（仅 Piper）：
docker build -f Dockerfile.min -t ghcr.io/matatonic/openedai-speech-min .

步骤 5：运行正确的 docker compose up -d 命令​

  • Nvidia GPU（CUDA 支持）：运行以下命令，在后台模式下启动 openedai-speech 服务：
docker compose up -d
  • AMD GPU（ROCm 支持）：运行以下命令，在后台模式下启动 openedai-speech 服务：
docker compose -f docker-compose.rocm.yml up -d
  • ARM64（Apple M 系列、树莓派）：XTTS 在该架构下仅支持 CPU 运行，速度会非常慢。您可以使用 Nvidia 镜像在 CPU 上运行 XTTS（速度慢），或者使用仅 Piper 的精简版镜像（推荐）：
docker compose -f docker-compose.min.yml up -d
  • 纯 CPU，无 GPU（仅 Piper）：针对仅需要 Piper 支持的极简 Docker 镜像（文件体积小于 1GB，而标准版约为 8GB）：
docker compose -f docker-compose.min.yml up -d

这将在后台模式下启动 openedai-speech 服务。

选项 2：使用 Docker Run 命令​

您也可以直接使用以下 Docker run 命令在后台模式下启动 openedai-speech 服务：

  • Nvidia GPU (CUDA)：运行以下命令以构建并启动 openedai-speech 服务：
docker build -t ghcr.io/matatonic/openedai-speech .
docker run -d --gpus=all -p 8000:8000 -v voices:/app/voices -v config:/app/config --name openedai-speech ghcr.io/matatonic/openedai-speech
  • ROCm (AMD GPU)：运行以下命令以构建并启动 openedai-speech 服务：

若要启用 ROCm 支持，请取消 speech.env 文件中 #USE_ROCM=1 行的注释。

docker build -f Dockerfile --build-arg USE_ROCM=1 -t ghcr.io/matatonic/openedai-speech-rocm .
docker run -d --privileged --init --name openedai-speech -p 8000:8000 -v voices:/app/voices -v config:/app/config ghcr.io/matatonic/openedai-speech-rocm
  • 纯 CPU，无 GPU（仅 Piper）：运行以下命令以构建并启动 openedai-speech 服务：
docker build -f Dockerfile.min -t ghcr.io/matatonic/openedai-speech-min .
docker run -d -p 8000:8000 -v voices:/app/voices -v config:/app/config --name openedai-speech ghcr.io/matatonic/openedai-speech-min

步骤 6：配置 Open WebUI 使用 openedai-speech 进行 TTS​

openedai-tts

打开 Open WebUI 设置，导航到 管理员面板 > 设置 > 音频 (Admin Panel > Settings > Audio) 下的 TTS 设置，添加以下配置：

  • API Base URL：http://host.docker.internal:8000/v1
  • API Key：sk-111111111（请注意，这是一个虚拟 API Key。因为 openedai-speech 不需要 API Key，只要此字段不为空，您可以输入任何内容。）

步骤 7：选择音色​

在管理员面板中相同的音频设置菜单下的 TTS 音色 (TTS Voice) 选项中，您可以从 openedai-speech 支持的以下模型中选择要使用的 TTS 模型。这些模型的音色针对英语进行了优化。

  • tts-1 或 tts-1-hd：alloy、echo、echo-alt、fable、onyx、nova 和 shimmer（tts-1-hd 是可配置的，默认使用 OpenAI 样本）

步骤 8：点击“保存”以应用更改并开始体验自然的声音​

点击 保存 (Save) 按钮以将更改应用到您的 Open WebUI 设置中。刷新页面使更改完全生效，您就可以在 Open WebUI 中尽情体验 openedai-speech 集成带来的自然流畅的文本转语音语音朗读体验了。

模型详情​

openedai-speech 支持多种文本转语音模型，每种模型都有自己的优势和硬性硬件要求。目前提供以下模型：

  • Piper TTS（速度极快，可在 CPU 上运行）：通过 voice_to_speaker.yaml 配置文件使用您自己的 Piper 语音音色。该模型非常适合需要超低延迟和高性能的场景。Piper TTS 还支持 多语言 音色。
  • Coqui AI/TTS XTTS v2（速度快，但需要大约 4GB 的 GPU 显存以及支持 CUDA 的 Nvidia GPU）：该模型使用 Coqui AI 的 XTTS v2 声音克隆技术来生成高质量的语音。虽然它需要更强大的 GPU 支持，但能提供出色的推理性能和极佳的音频质量。Coqui 同样支持 多语言 音色。
  • Beta 阶段的 Parler-TTS 支持（实验性，速度较慢）：该模型使用 Parler-TTS 框架来生成语音。虽然目前仍处于 Beta 阶段，但它允许您描述说话者声音的基础特征。每次生成的具体声音会略有不同，但应与提供的说话人描述相似。如需了解如何描述声音的灵感，请参阅 文本描述转语音 (Text Description to Speech)。

故障排除​

如果您在将 openedai-speech 集成到 Open WebUI 时遇到任何问题，请按照以下故障排除步骤进行排查：

  • 验证 openedai-speech 服务：确保 openedai-speech 服务处于运行状态，且 docker-compose.yml 文件中指定的端口已对外暴露。
  • 检查对 host.docker.internal 的访问：验证域名 host.docker.internal 能在 Open WebUI 容器内部被正确解析。这是必须的，因为 openedai-speech 在您 PC 的 localhost 上暴露，但 open-webui 默认无法从其容器内部直接访问它。您可以在 docker-compose.yml 文件中添加一个挂载卷，将主机的文件挂载到容器中（例如，挂载到由 openedai-speech 服务的目录中）。
  • 核对 API Key 配置：确保 API Key 设置为一个虚拟值。因为 openedai-speech 不需要真实的 API Key，所以该字段只需填写任意内容即可。
  • 检查音色配置：验证您想要用于 TTS 的音色是否存在于您的 voice_to_speaker.yaml 文件中，且对应的文件（如 voice XML 文件）确实存在于正确的目录中。
  • 核实声音模型路径：如果您在加载声音模型时遇到问题，请仔细核对 voice_to_speaker.yaml 文件中的路径是否与声音模型的实际存放位置相匹配。

其他故障排除技巧​

  • 检查 openedai-speech 日志中的错误或警告，这通常能指出问题所在。
  • 确认您的 docker-compose.yml 文件已针对您的本地环境进行了正确配置。
  • 如果仍有连接问题，请尝试重启 openedai-speech 服务或整个 Docker 环境。
  • 如果问题仍未解决，请访问 openedai-speech 的 GitHub 仓库或在相关的社区论坛中寻求帮助。

GPU 显存问题 (XTTS)​

如果 XTTS 无法加载或导致显存溢出 (OOM) 错误：

  • XTTS 需要大约 4GB 的 GPU 显存支持。
  • 考虑使用仅支持 Piper 的精简版镜像 (docker-compose.min.yml)，该版本可在 CPU 上流畅运行。
  • 在启动容器前，减少其他占用 GPU 显存的进程。

AMD GPU (ROCm) 注意事项​

使用 AMD GPU 时：

  1. 取消 speech.env 文件中 USE_ROCM=1 的注释。
  2. 使用 docker-compose.rocm.yml 配置文件。
  3. 确保主机上已正确安装 ROCm 驱动程序。

ARM64 / Apple 芯片​

  • XTTS 在 ARM64 下仅支持 CPU，运行起来会非常缓慢。
  • 请使用 Piper 精简版镜像 (docker-compose.min.yml)，以便在 ARM 设备上获得可接受的性能。
  • Apple M 系列芯片可以工作，但使用精简版镜像能获得更好的性能表现。

容器网络配置​

如果您使用自定义 Docker 网络：

# 添加到您的 Docker Compose 中
networks:
  webui-network:
    driver: bridge

然后，直接使用 http://openedai-speech:8000/v1 代替 localhost 进行引用。

有关更多故障排除技巧，请参阅 音频故障排除指南。

常见问题 (FAQ)​

如何控制所生成音频的情感起伏？

目前没有直接的机制能控制生成音频的情感输出。某些因素（如大写字母或标点语法）可能会影响生成的音频效果，但内部测试显示其结果并不稳定。

声音文件存储在什么位置？配置文件又在哪里？

定义可用音色及其属性的配置文件存储在 config 卷中。具体来说，默认音色是在 voice_to_speaker.default.yaml 中定义的。

额外资源​

有关配置 Open WebUI 使用 openedai-speech（包括设置环境变量）的更多信息，请参阅 Open WebUI 官方配置文档。

有关 openedai-speech 的更多详细信息，请访问其 GitHub 仓库。

如何向 openedai-speech 添加更多自定义音色： 自定义音色指南 (Custom-Voices-HowTo)

备注

您可以在 docker-compose.yml 文件中将端口号更改为任何空闲且可用的端口，但请务必相应地更新 Open WebUI 管理员音频设置中的 API Base URL。

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.