跳到主要内容

Kokoro Web：轻量 TTS 集成

注意

本教程是社区贡献内容，不属于 OPL 数据空间官方支持范围。

什么是 Kokoro Web​

Kokoro Web 为 Kokoro-82M 提供了一个轻量级、OpenAI 兼容的 API，适合与 OPL 数据空间直接集成，为聊天体验增加自然语音输出。

两步完成集成​

1. 部署 Kokoro Web API​

services:
  kokoro-web:
    image: ghcr.io/eduardolat/kokoro-web:latest
    ports:
      - "3000:3000"
    environment:
      - KW_SECRET_API_KEY=your-api-key
    volumes:
      - ./kokoro-cache:/kokoro/cache
    restart: unless-stopped

然后运行：

docker compose up -d

2. 在 OPL 数据空间中接入​

进入 管理员面板 → 设置 → Audio，设置：

  • Text-to-Speech Engine：OpenAI
  • API Base URL：http://localhost:3000/api/v1
    • Docker 场景下可改为 host.docker.internal
  • API Key：your-api-key
  • TTS Model：model_q8f16
  • TTS Voice：af_heart

支持语言​

Kokoro Web 支持多种语言，包括：

  • 英语（美式 / 英式）
  • 日语
  • 中文
  • 西班牙语
  • 印地语
  • 意大利语
  • 巴西葡萄牙语

完整声音和语言列表可在项目仓库或在线 Demo 中查看。

模型选择​

Model ID优化方式适合场景
model_q8f16混合精度推荐默认
model_quantized8-bit更适合 CPU
model_uint8f16混合精度中档 CPU
model_q4f164-bit + fp16更高音质
model_fp16fp16高质量
modelfp32最高质量，但更慢

安装前试听​

你可以先访问 Kokoro Web Demo：

  • 直接在浏览器里运行
  • 不需要注册
  • 不需要安装
  • 可以试听各种声音和语言

故障排查​

连接失败​

  • Docker Desktop：使用 host.docker.internal
  • 同一 Compose 网络：使用 http://kokoro-web:3000/api/v1
  • Linux Docker：改用宿主机 IP

声音无法工作​

  1. 确认 OPL 数据空间和 Kokoro Web 中使用的是同一个 API Key
  2. 直接调用 /api/v1/audio/speech 测试
  3. 检查所填 voice 名称是否存在

更多问题见 音频排障指南。