本项目将 hexgrad/Kokoro-82M-v1.1-zh 模型推理包装在一个轻量级的 FastAPI 服务中，提供 /text2audio 接口以供阅读3.0的 TTS 使用。

• Python 3.12+
• 放置在 model/ 目录下的 Kokoro 1.1 中文权重和声音文件
• 通过 KOKORO_API_TOKEN 环境变量配置的访问令牌（调用接口必需）

可选但推荐：

• 运行 device=cuda 时需要支持 CUDA 的 GPU

# 创建虚拟环境并安装依赖
uv lock
uv sync

# 从项目根目录执行
uv run uvicorn tts_service:app --host 0.0.0.0 --port 3236

# 终端输出示例
# INFO kokoro_tts: Kokoro model loaded on cuda
# INFO kokoro_tts.monitor: cpu=5.12% rss=1024.00MB ...

启动成功后可以访问：

• http://127.0.0.1:3236/health —— 查看模型是否已加载以及当前设备
• http://127.0.0.1:3236/text2audio?token=<令牌>&tex=卧槽小米怎么这么坏啊 —— 快速检验语音输出

主要端点：

• GET /text2audio
• POST /text2audio
• GET /health

重要的查询/表单参数：

响应以 audio/wav 流形式返回，包含以下头部信息：

• X-RTF：合成过程的实时因子
• X-Sample-Rate：音频采样率（24 kHz）
• X-Device：实际用于推理的设备
• 调用接口必须携带有效的访问令牌，可通过请求头（默认 X-API-Token） 或在 URL 末尾追加 ?token=<令牌> 的方式提供。

如果请求 CUDA 但不可用，或者推理过程中发生 CUDA 运行时错误，服务会自动重试 CPU。

• 运行时日志写入 logs/tts_service.log。文件在达到 5MB 时轮换，保留三个备份，防止无限增长。可通过环境变量调整（见下文）。
• 轻量级资源监控器每 10 秒记录 CPU 使用情况和（当 CUDA 可用时）GPU 内存。可通过 KOKORO_MONITOR_INTERVAL 更改采样频率。

Invoke-WebRequest -Method POST `
  -Uri "http://127.0.0.1:3236/text2audio" `
  -Headers @{ "X-API-Token" = "<你的令牌>" } `
  -Body "tex=卧槽小米怎么这么坏啊&voice=zf_001&device=cuda" `
  -ContentType "application/x-www-form-urlencoded" `
  -OutFile "demo.wav"

# 使用 curl 通过 HTTP POST 调用 /text2audio 并把输出保存为 demo.wav
curl -X POST 'http://127.0.0.1:3236/text2audio' \
  -H 'X-API-Token: <你的令牌>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'tex=卧槽小米怎么这么坏啊' \
  --data 'voice=zf_001&device=cuda' \
  --output demo.wav

http://127.0.0.1:3236/text2audio?token=<你的令牌>&tex=卧槽小米怎么这么坏啊

检查响应头来查看 X-RTF 和 X-Device 的值。

在阅读 3.0 App 的“朗读引擎”中新增自定义配置，可参考以下 JSON 并粘贴源：

{
  "concurrentRate": "",
  "contentType": "audio/wav",
  "enabledCookieJar": false,
  "header": "Content-Type: application/x-www-form-urlencoded",
  "id": -100,
  "lastUpdateTime": 1762950914174,
  "loginCheckJs": "",
  "loginUi": "",
  "loginUrl": "",
  "name": "Kokoro",
  "url": "http://<服务器IP或域名>:3236/text2audio?token=<你的令牌>,{\"method\":\"POST\",\"body\":\"tex={{java.encodeURI(java.encodeURI(speakText))}}&speakSpeed={{speakSpeed}}&voice=zf_001\"}"
}

说明：

• speakSpeed 对应阅读的“语速”滑条，服务端会自动映射到 5-50 的范围
• voice 参数可以替换为 voices/ 目录下其他可用声线的名称（需要对应语言）