Question 1

使用小数据集微调 PocketTTS 时出现错误 "no readable samples ... (0 failures)"，该如何修复？

Accepted Answer

清单文件路径通常没有问题。按长度分桶的加载器在每个加载器分片包含至少 `num_bucket_batches × batch_size` 个样本之前不会输出批次。使用旧的默认值时，这要求每个 GPU 有 `20 × 64 × 6 = 7,680` 条语音。较小的分片会产生误导性的 `0 failures` 错误。

请升级到包含 PR #342 的版本，该版本将默认值降低为 `num_bucket_batches: 5` 和 `loader_procs: 3`，并在启动时验证训练/验证清单文件。

对于非常小的微调数据集，请在 `finetune.yaml` 中禁用分桶并减少加载器进程数：

```yaml
data:
  num_bucket_batches: 1  # 1 表示禁用长度分桶
  loader_procs: 1
  batch_size: 8          # 不得大于最小的训练/验证分片
```

每个 GPU 的要求为：

```text
num_bucket_batches × batch_size × loader_procs
```

当 `num_bucket_batches: 1` 且 `loader_procs: 1` 时，每个数据拆分只需要至少 `batch_size` 条可读条目。请确保验证清单也满足此大小要求，因为验证使用训练的批次大小；否则运行将在第一个验证步骤失败。或者，添加更多验证样本或增大数据集规模。

Question 2

如何修复法语 Pocket TTS 语音混乱或截断一两个单词发音的问题？

Accepted Answer

这是由 EOS 过早终止引起的：对于某些法语语音，EOS logit 在前导停顿期间可能达到约 `-3`，在语音生成之前就越过了默认的 `-4` 阈值，因此短文本会过早结束。

修复方法：更新到包含 PR **"Ignore EOS on the first 6 generated frames"** 以及新法语模型的发布版本。然后使用以下任一选项：

- `--language french` — 加载新的 6 层法语模型
- `french_24l` — 加载新的 24 层法语模型

如果无法更新，可立即采用的变通方法：切勿合成少于三个单词的文本。在流式模式下，将过短的文本块与下一个文本块拼接后再进行合成。这将报告的失败率从 1–2 个单词时的约 40% 降至 3 个及以上单词时的约 2%。

添加前导填充词并无帮助，而且在 Apple Silicon 上使用 `quantize=True` 会使该问题更加严重。

Question 3

为什么西班牙语、法语或 english_2026-01 TTS 模型使用 temperature 0.7 并产生不稳定的韵律？

Accepted Answer

那些随附的 YAML 配置省略了 `default_temperature`，因此 `TTSModel.load_model()` 会回退到 schema 默认值 `0.7`，而不是经过调优的英语值 `0.3`。该修复将 schema 默认值更改为 `0.3`，使所有随附模型都以 `0.3` 进行采样，同时仍允许按配置进行覆盖。升级到包含 #322 修复的版本后，可通过以下方式验证：
```python
m = TTSModel.load_model(language="spanish")
print(m.temp)  # 应为 0.3
```
作为旧版本上的临时解决方案，请将以下内容添加到受影响的配置中（例如 `spanish.yaml`、`french.yaml` 或 `english_2026-01.yaml`）：
```yaml
default_temperature: 0.3
```

Question 4

当客户端在流式传输中途断开与 /tts 的连接时，我该如何停止 Pocket TTS 的生成？

Accepted Answer

升级到包含 PR #228 的 Pocket TTS 版本。该修复为每个请求创建一个 threading.Event，将其传入 generate_audio_stream()，并在客户端断开连接时设置它。generate_data_with_state 中的生成循环会检查该事件，并通过其正常终止路径退出，而不是解码剩余文本。如果手动应用此修复：1) 为每个请求创建 stop_event = threading.Event()；2) 将其传递给 generate_audio_stream(..., stop_event=stop_event)；3) 在断开连接/取消处理程序中调用 stop_event.set()；4) 在生成循环内检查该事件，并在运行另一个 tts_model 请求之前停止。这可以防止 CPU 浪费，并避免对非线程安全模型的并发使用；据报告，中断到下一条回复的延迟从约 7.9 s 降至 0.27 s。

Question 5

如何修复因 Hugging Face token 无效导致 pocket-tts export-voice 失败的问题？

Accepted Answer

该故障可能是由过期的 `HF_TOKEN` 环境变量引起的。请将其删除，然后重新运行导出。

PowerShell（当前终端）：
```powershell
Remove-Item Env:HF_TOKEN
```

要从 Windows 用户环境中永久删除它：
```powershell
[Environment]::SetEnvironmentVariable("HF_TOKEN", $null, "User")
```

重启终端，使用 `echo $env:HF_TOKEN` 验证它为空，然后重新运行：
```powershell
pocket-tts export-voice .	urtle_sample.wav turtle.safetensors
```

如果语音克隆需要身份验证，请改用来自 Hugging Face 的有效令牌替换过期的令牌：
```powershell
$env:HF_TOKEN = "hf_your_valid_token"
```
或者使用 `[Environment]::SetEnvironmentVariable("HF_TOKEN", "hf_your_valid_token", "User")` 永久设置它，然后重启终端。

pocket-tts

项目简介

README 预览

常见问题 (5)

同类型项目

browser-use

puppeteer

manim

PaddleOCR