多语言零样本 TTS、声音克隆或按属性设计音色时，用…

适用于用 OmniVoice 从参考音频克隆音色、用文本属性设计说话人，或批量合成 600+ 语言语音。

适用场景

解决思路

1. 环境要求：Python 3.9+、PyTorch 2.8+，使用 CUDA（推荐）或 Apple Silicon（MPS）或 CPU。
2. 安装 PyTorch：NVIDIA GPU（CUDA 12.8）执行 `pip install torch==2.8.0+cu128 torchaudio==2.8.0+cu128 --extra-index-url https://download.pytorch.org/whl/cu128`。
3. 安装 PyTorch：Apple Silicon 执行 `pip install torch==2.8.0 torchaudio==2.8.0`。
4. 安装 OmniVoice：执行 `pip install omnivoice`。
5. 或从源码安装最新版：执行 `pip install git+https://github.com/k2-fsa/OmniVoice.git`。
6. 或可编辑开发安装：执行 `git clone https://github.com/k2-fsa/OmniVoice.git`，进入目录后执行 `pip install -e .`。
7. 使用 uv 安装：执行 `git clone https://github.com/k2-fsa/OmniVoice.git`，进入目录后执行 `uv sync`；需要镜像时执行 `uv sync --default-index "https://mirrors.aliyun.com/pypi/simple"`。
8. 若 HuggingFace 被阻断，执行 `export HF_ENDPOINT="https://hf-mirror.com"`。
9. 理解三种模式：Voice Cloning 提供 `ref_audio` + `ref_text`；Voice Design 提供 `instruct` 字符串；Auto Voice 不提供额外内容。
10. 加载模型 NVIDIA GPU：`model = OmniVoice.from_pretrained("k2-fsa/OmniVoice", device_map="cuda:0", dtype=torch.float16)`。
11. 加载模型 Apple Silicon：`model = OmniVoice.from_pretrained("k2-fsa/OmniVoice", device_map="mps", dtype=torch.float16)`。
12. 加载模型 CPU：`model = OmniVoice.from_pretrained("k2-fsa/OmniVoice", device_map="cpu", dtype=torch.float32)`，速度较慢。
13. 声音克隆（手动参考转写，更快更准确）：`audio = model.generate(text="Hello, this is a test of zero-shot voice cloning.", ref_audio="ref.wav", ref_text="Transcription of the reference audio.")`。
14. 声音克隆（省略 `ref_text`）：`audio = model.generate(text="Hello, this is a test of zero-shot voice cloning.", ref_audio="ref.wav")`，由 Whisper 自动转录 `ref_audio`。
15. 保存输出：`audio` 是 `list[torch.Tensor]`，每个形状 `(1, T)`，采样率 24kHz；执行 `torchaudio.save("out.wav", audio[0], 24000)`。
16. 声音设计：`audio = model.generate(text="Hello, this is a test of zero-shot voice design.", instruct="female, low pitch, british accent")`，用逗号分隔属性。
17. 声音设计支持属性：Gender `male`/`female`；Age `child`/`young`/`middle-aged`/`elderly`；Pitch `very low pitch`/`low pitch`/`high pitch`/`very high pitch`；Style `whisper`；English accents `american accent`/`british accent`/`australian accent` 等；中文方言 `四川话`/`陕西话` 等。
18. Auto Voice：`audio = model.generate(text="This is a sentence without any voice prompt.")`，模型随机选择声音，然后 `torchaudio.save("out.wav", audio[0], 24000)`。
19. 生成参数：`num_step=32` 为默认扩散步数；`num_step=16` 更快（约 2 倍）但质量略低；`speed=1.2` 语速 >1 更快、<1 更慢；`duration=8.0` 固定输出秒数并覆盖 `speed`。
20. 非语言符号：在文本中内联 `[laughter]`、`[sigh]`、`[confirmation-en]`、`[question-en]`、`[question-ah]`、`[question-oh]`、`[question-ei]`、`[question-yi]`、`[surprise-ah]`、`[surprise-oh]`、`[surprise-wa]`、`[surprise-yo]`、`[dissatisfaction-hnn]`。
21. 中文发音控制：在句子中内联带声调数字的大写拼音，如 `这批货物打ZHE2出售后他严重SHE2本了，再也经不起ZHE1腾了。`。
22. 英文发音控制：在方括号中使用大写 CMU dict 音素，如 `You could probably still make [IH1 T] look good.`。
23. 启动 Web Demo：`omnivoice-demo --ip 0.0.0.0 --port 8001`；查看全部选项：`omnivoice-demo --help`。
24. 单条推理声音克隆 CLI：`omnivoice-infer --model k2-fsa/OmniVoice --text "This is a test for text to speech." --ref_audio ref.wav --ref_text "Transcription of the reference audio." --output hello.wav`；省略 `ref_text` 可让 Whisper 自动转录。
25. 单条推理声音设计 CLI：`omnivoice-infer --model k2-fsa/OmniVoice --text "This is a test for text to speech." --instruct "male, British accent" --output hello.wav`。
26. 单条推理 Auto Voice CLI：`omnivoice-infer --model k2-fsa/OmniVoice --text "This is a test for text to speech." --output hello.wav`。
27. 批量推理多 GPU CLI：`omnivoice-infer-batch --model k2-fsa/OmniVoice --test_list test.jsonl --res_dir results/`。
28. 准备 JSONL：每行至少写 `id` 和 `text`；可选 `ref_audio`、`ref_text`、`instruct`、`language_id`、`language_name`、`duration`、`speed`。
29. JSONL 字段说明：`id` 必填且唯一；`text` 必填；`ref_audio` 可选参考音频路径；`ref_text` 可选参考音频转写；`instruct` 可选说话人属性；`language_id` 可选语言代码如 `"en"`；`language_name` 可选语言名如 `"English"`；`duration` 可选固定输出秒数；`speed` 可选语速，若设置 `duration` 则忽略。
30. JSONL 示例：`{"id": "sample_001", "text": "Hello world", "ref_audio": "/path/to/ref.wav", "ref_text": "Reference transcript"}`；`{"id": "sample_002", "text": "Voice design example", "instruct": "female, british accent"}`；`{"id": "sample_003", "text": "Auto voice example"}`；`{"id": "sample_004", "text": "Speed controlled", "ref_audio": "/path/to/ref.wav", "speed": 1.2}`；`{"id": "sample_005", "text": "Duration fixed", "ref_audio": "/path/to/ref.wav", "duration": 10.0}`；`{"id": "sample_006", "text": "With language hint", "ref_audio": "/path/to/ref.wav", "language_id": "en", "language_name": "English"}`。
31. 完整声音克隆流水线：定义 `clone_voice(ref_audio_path, texts, output_dir)`，加载 `OmniVoice.from_pretrained("k2-fsa/OmniVoice", device_map="cuda:0", dtype=torch.float16)`，用 `Path(output_dir).mkdir(parents=True, exist_ok=True)` 创建目录，循环 texts 调用 `model.generate(text=text, ref_audio=ref_audio_path, num_step=32, speed=1.0)`，保存为 `f"{output_dir}/output_{i:04d}.wav"`。
32. 从列表批量处理：准备 items（如 `{"id": "s1", "text": "English sentence.", "instruct": "female, american accent"}`、`{"id": "s2", "text": "Another sentence.", "ref_audio": "ref.wav"}`、`{"id": "s3", "text": "Auto voice."}`），根据 item 构造 kwargs 并调用 `model.generate(**kwargs)`，保存为 `f"{item['id']}.wav"`。
33. 声音设计组合：循环 designs 如 `"male, elderly, low pitch"`、`"female, child, high pitch"`、`"male, whisper"`、`"female, british accent, high pitch"`、`"male, american accent, middle-aged"`，调用 `model.generate(text="The quick brown fox jumps over the lazy dog.", instruct=design)`，把文件名安全化后保存。
34. 快速推理：将 `num_step` 从默认 32 改为 16，可约 2 倍速度，质量略低。
35. 输出格式：采样率 24,000 Hz；类型 `list[torch.Tensor]`，每个张量形状 `(1, T)`；用 `torchaudio.save(path, audio[0], 24000)` 保存。
36. HuggingFace 下载失败：`export HF_ENDPOINT="https://hf-mirror.com"`。
37. CUDA 显存不足：使用 `dtype=torch.float16` 而不是 float32；或在批量推理中减小 batch size/文本长度。
38. Whisper ASR 不可用导致 `ref_text` 自动转录失败：执行 `pip install openai-whisper`。
39. 中文发音错误：直接在文本字符串中使用带声调数字的内联拼音。
40. 音频质量问题：把 `num_step` 提高到 32 或 64；手动提供 `ref_text` 而不依赖自动转录；使用干净无噪、3–15 秒的参考音频。
41. Apple Silicon（MPS）问题：显式使用 `device_map="mps"` 和 `dtype=torch.float16`。
42. 模型与资源：HuggingFace 模型 `k2-fsa/OmniVoice`；HuggingFace Space `https://huggingface.co/spaces/k2-fsa/OmniVoice`；论文 `https://arxiv.org/abs/2604.00688`；Demo `https://zhu-han.github.io/omnivoice`；支持语言 `docs/languages.md`；声音设计属性 `docs/voice-design.md`；生成参数 `docs/generation-parameters.md`；训练/评估示例 `examples/`。

适用边界 · 注意事项

• 未安装 Python 3.9+、PyTorch 2.8+、omnivoice，或无法访问 HuggingFace 模型权重时不要用。
• 需要在无 GPU/Apple Silicon 的 CPU 上做极低延迟实时流式 TTS 时慎用，CPU 可能较慢。
• 目标语言/方言或商业 SLA 超出 OmniVoice 600+ 语言支持范围时，需先验证。