OpenWebUI 接入 Kokoro-FastAPI:OpenAI 兼容 TTS 的 Base URL 与声音映射配置实战
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 的「设置 / 配置」区域完成两件事:
- 设置模型:将 TTS 模型设为
kokoro - 设置 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 一节)。
八、延伸阅读
- OpenAI 官方客户端集成指南:同一套
/v1接口的 Python 调用示例,含流式直出扬声器的 PCM 写法,可用于验证与 OpenWebUI 相同的请求形态。 - SillyTavern 集成指南:另一个同构的 OpenAI 兼容前端,Base URL 与端口约定一致,可对照理解
host.docker.internal的用法。 - 配置参考:
PORT、DEFAULT_VOICE、ENABLE_VOICE_TAGS等全部环境变量说明,调整端口或默认声音时查阅。 - 集成总览:所有兼容 OpenAI TTS 端点的客户端清单,以及新增集成的贡献规范。
- 服务端实现细节:OpenAI 兼容路由器、请求/响应 Schema、声音映射数据、OpenAI 端点测试。
按上述步骤配置后,OpenWebUI 即可调用本地 Kokoro 合成语音:既可以使用 OpenAI 风格的声音名(alloy/echo/nova/shimmer 等)快速上手,也可以直接选用全部几十个 Kokoro 原生声音包,甚至借助组合语法调配出混合音色。