OpenWebUI 接入 Kokoro-FastAPI:OpenAI 兼容 TTS 的 Base URL 与声音映射配置实战

原创2026-10-11 23:18:411,818 阅读
文章标签:人工智能语音模型推理服务本地部署后端

OpenWebUI 接入 Kokoro-FastAPI:OpenAI 兼容 TTS 的 Base URL 与声音映射配置实战

Kokoro-FastAPI 对外暴露 OpenAI 兼容的 /v1 语音合成接口,而 OpenWebUI 原生支持 OpenAI 兼容 TTS 提供商,二者可以零代码对接。本文以 docs/integrations/openwebui.md 为核心指南,完整覆盖 Base URL 设置、模型与 API Key 配置、OpenAI 声音映射的使用与修改、以及 Kokoro 原生声音名的直接调用,并结合仓库源码解释背后的映射与校验机制,帮助你在一台机器上快速搭建"OpenWebUI + Kokoro 本地语音合成"的完整链路。

一、接入原理:OpenAI 兼容端点与模型映射

OpenWebUI 的 TTS 功能通过标准的 OpenAI Speech 接口(POST /v1/audio/speech)工作。Kokoro-FastAPI 在 api/src/main.py 中将 OpenAI 兼容路由器挂载在 /v1 前缀下,因此 OpenWebUI 只需要把 Base URL 指向 http://<主机>:8880/v1,即可获得与 OpenAI TTS 相同的请求/响应形态。

在模型侧,服务端维护了一张"OpenAI 模型名 → Kokoro 内部模型名"的映射表,位于 api/src/core/openai_mappings.json:

{
    "models": {
        "tts-1": "kokoro-v1_0",
        "tts-1-hd": "kokoro-v1_0",
        "kokoro": "kokoro-v1_0",
        "gpt-4o-mini-tts": "kokoro-v1_0"
    },
    "voices": {
        "alloy": "am_adam",
        "ash": "af_nicole",
        "coral": "bf_emma",
        "echo": "af_bella",
        "fable": "af_sarah",
        "onyx": "bm_george",
        "nova": "bf_isabella",
        "sage": "am_michael",
        "shimmer": "af_sky"
    }
}

也就是说,无论请求里写的是 tts-1、tts-1-hd、kokoro 还是 gpt-4o-mini-tts,底层都会加载同一份 Kokoro v1.0 模型权重(kokoro-v1_0.pth)。/v1/models 端点(见 api/src/routers/openai_compatible.py)会把这四个模型 ID 全部返回给客户端,OpenWebUI 据此渲染模型下拉列表。

二、前置条件:先把 Kokoro-FastAPI 跑起来

OpenWebUI 集成的前提是 Kokoro-FastAPI 已经在本机或同网段可达的位置运行,且默认监听 8880 端口(默认值见 api/src/core/config.py)。

最快捷的启动方式(模型已内置于镜像,首次启动自动预热):

# CPU 环境
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

# NVIDIA GPU 环境
docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

使用 Docker Compose 时,8880:8880 的端口映射已写死在 docker/cpu/docker-compose.yml 与 docker/gpu/docker-compose.yml 中,进入对应目录执行 docker compose up 即可。若想更换端口,需要同时修改 PORT 环境变量和 compose 文件里的宿主机端口映射,并同步更新 OpenWebUI 的 Base URL。

启动成功后可用 curl http://localhost:8880/health 验证服务健康状态,返回 {"status":"healthy"} 即表示就绪。

三、设置 OpenWebUI 的 Base URL

这是整条集成链路最关键的一步,取决于 OpenWebUI 自身以何种方式运行:

OpenWebUI 运行方式 Base URL 填写值 说明
Docker 容器 http://host.docker.internal:8880/v1 容器内通过宿主机特殊域名访问另一个容器
直接运行(本机进程) http://localhost:8880/v1 与 Kokoro-FastAPI 同机直连
  • Docker 容器场景:OpenWebUI 容器与 Kokoro-FastAPI 容器虽然都在 Docker 中,但各自的网络栈相互隔离,localhost 指向的是容器自己。host.docker.internal 是 Docker 提供的宿主机解析域名,配合 8880 端口即可让 OpenWebUI 容器穿透到宿主机上监听的 Kokoro-FastAPI。
  • 直接运行场景:OpenWebUI 以本机进程方式运行时(例如官方安装脚本部署),直接填 http://localhost:8880/v1 即可。

补充提示(适用 Linux 主机):host.docker.internal 在 Docker Desktop(macOS/Windows)上默认可用;在部分 Linux 发行版的 Docker Engine 上,需要为 OpenWebUI 容器显式添加 extra_hosts: <a href="https://link.gitcode.com/i/f88040c3050ebe5a2ac86cc3e15be8ac" target="_blank">"host.docker.internal:host-gateway"] 才能解析,可参考 [docs/deployment/digitalocean.md 中的部署思路排查。

设置完成后,OpenWebUI 就能通过 /v1 前缀访问到 Kokoro-FastAPI 的 OpenAI 兼容接口——这一前缀来源于 api/src/main.py 的路由挂载,也是 OpenAI 生态客户端约定俗成的路径。

四、在 OpenWebUI 中配置 TTS 模型

在 OpenWebUI 的「设置 / 配置」区域完成两件事:

  1. 设置模型:将 TTS 模型设为 kokoro
  2. 设置 API Key:填入 not-needed(任意非空字符串均可,本地服务不做鉴权校验)

API Key 之所以可以随意填,是因为 Kokoro-FastAPI 的 OpenAISpeechRequest 请求模型根本不包含鉴权字段,服务端不校验任何 Key。OpenAI 官方客户端库默认要求携带 api_key,填 not-needed 只是为了让客户端校验通过。

模型名 kokoro 会被 openai_mappings.json 的 models 段解析为 kokoro-v1_0;这一解析逻辑在 api/src/routers/openai_compatible.py 的 get_model_name 中实现,路由入口 create_speech 会先校验模型名是否在映射表内,否则直接返回 400 invalid_model。

配置完成后,可以在浏览器打开 http://localhost:8880/docs(FastAPI 自动生成的 Swagger 文档)对照查看 /v1/audio/speech 的请求参数,确认服务端能力与 OpenWebUI 的预期一致。

五、使用映射的 OpenAI 声音(Mapped OpenAI Voices)

OpenWebUI 支持 OpenAI 官方的声音名称体系,而 Kokoro-FastAPI 已经预先做好了「OpenAI 声音名 → Kokoro 声音包」的映射,因此你可以直接使用 alloy、echo、fable、onyx、nova、shimmer 等名字,无需任何额外配置。

当前映射表(保存在 api/src/core/openai_mappings.json 的 voices 段):

OpenAI 声音名 实际加载的 Kokoro 声音包
alloy am_adam
ash af_nicole
coral bf_emma
echo af_bella
fable af_sarah
onyx bm_george
nova bf_isabella
sage am_michael
shimmer af_sky

映射的底层机制:在 process_and_validate_voices 中,每个声音名会先执行 _openai_mappings["voices"].get(name, name) 做一级替换(第 183 行),即:如果传入的名字命中映射表,就替换为对应的 Kokoro 声音包名;未命中则保持原样。替换后再到已加载的声音包列表里做存在性校验,不存在的名字会返回 400 Voice 'xxx' not found。

对应的行为有测试用例覆盖,见 api/tests/test_openai_endpoints.py:test_openai_voice_mapping 验证了请求 voice="alloy" 时最终以 am_adam 调用生成接口,test_openai_voice_mapping_streaming 验证了流式模式下同样的映射行为。

修改映射的方法:如果你通过 docker compose 或 uv 直接运行(源码目录可见),可以编辑 api/src/core/openai_mappings.json,把某个 OpenAI 声音名指向你更偏好的声音包,例如把 shimmer 改成 af_bella,重启服务即生效。需要说明的是,该 JSON 是服务启动时一次性加载到内存的(见 load_openai_mappings 与模块级缓存 _openai_mappings),因此修改后必须重启服务;如果使用官方预构建镜像且未挂载源码目录,则建议通过重建镜像或挂载方式覆盖该文件。

六、直接使用 Kokoro 原生声音名

如果不想依赖 OpenAI 映射,也可以直接使用 Kokoro 的声音包名称。在 OpenWebUI 的 voice 参数中填写声音名(去掉 .pt 文件扩展名),例如:

af_nicole
am_michael
af_bella

Kokoro 的声音包文件位于 api/src/voices/v1_0 目录(仓库内随附数十个 .pt 声音包)。从命名前缀与 README.md 声明的多语言支持可以推断出语言约定:af_*/am_* 为美式英语女声/男声,bf_*/bm_* 为英式英语,ef_*/em_* 为西班牙语,ff_* 为法语,hf_*/hm_* 为印地语,if_*/im_* 为意大利语,jf_*/jm_* 为日语,pf_*/pm_* 为巴西葡萄牙语,zf_*/zm_* 为普通话中文。当请求未显式指定 lang_code 时,服务端会取声音名的首字母推断语言(见 OpenAISpeechRequest 的字段说明)。

推荐做法:直接使用 /v1/audio/voices 拉取完整声音列表。该端点(api/src/routers/openai_compatible.py)返回 {"voices": <a href="https://link.gitcode.com/i/c74c846778685123f65d4e54ddc1fcc4" target="_blank">{"id": ..., "name": ..., "overall_grade": ...}], "default_voice": ...} 结构,其中 id 与 name 均为声音包名——这一结构正是为兼容 OpenWebUI 设计的(它会直接读取 voice['id'] 来渲染声音下拉框),同时附带 target_quality、training_duration、overall_grade 等质量评分字段(数据源为 [api/src/core/voice_grades.json)。因此,OpenWebUI 用户可以直接在界面上看到并选择全部几十个 Kokoro 声音,而不局限于 OpenAI 映射的 9 个。

进阶:声音组合。voice 参数还支持组合语法,例如 af_bella+af_nicole(多个声音按比例混合),或带权重的 af_bella(2)+af_sky(1)。OpenAI 兼容客户端同样可以通过该语法使用,仓库 README.md 与 docs/integrations/openai.md 中均有示例;服务端会对组合中的每个声音做与单个声音相同的映射与校验。

七、验证与常见问题排查

配置完成后,可以用以下命令从命令行侧验证整条链路是否打通:

# 1. 查看服务端暴露的模型(应包含 kokoro / tts-1 / tts-1-hd / gpt-4o-mini-tts)
curl http://localhost:8880/v1/models

# 2. 查看完整声音列表(OpenWebUI 渲染下拉框的数据源)
curl http://localhost:8880/v1/audio/voices

# 3. 直接请求一次语音合成(OpenWebUI 内部同款接口)
curl -X POST http://localhost:8880/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "kokoro", "voice": "af_bella", "input": "Hello from Kokoro!"}' \
  -o test.mp3

常见问题:

  • Base URL 填了但 OpenWebUI 报连接失败:先确认 Kokoro-FastAPI 容器是否在运行、端口映射是否正确(docker compose ps);Docker 场景检查 host.docker.internal 是否可解析(Linux 需 extra_hosts)。
  • 提示模型不存在:确认 TTS 模型名填的是 kokoro(或 tts-1/tts-1-hd/gpt-4o-mini-tts 之一),服务端对未知模型会返回 400。
  • API Key 校验失败:OpenWebUI 的 Key 填 not-needed 即可,服务端不校验 Key 真实性。
  • 声音列表只有少数几个:旧版 OpenWebUI 客户端会在拿不到 voice['id'] 时回退到硬编码的 6 个声音;请使用当前版本的 api/src/routers/openai_compatible.py 返回的 id/name 结构,即可渲染出完整列表。
  • 听不到声音但接口正常:确认 OpenWebUI 的音频播放设备与浏览器自动播放策略,同时可在服务端日志中确认是否收到 /v1/audio/speech 请求(默认日志级别为 DEBUG,见 docs/configuration.md 的 Logging 一节)。

八、延伸阅读

按上述步骤配置后,OpenWebUI 即可调用本地 Kokoro 合成语音:既可以使用 OpenAI 风格的声音名(alloy/echo/nova/shimmer 等)快速上手,也可以直接选用全部几十个 Kokoro 原生声音包,甚至借助组合语法调配出混合音色。

登录后查看全文
Kokoro-FastAPI