中文 | English | 日本語 | Korean | Français | Español | Italiano | Deutsch | Русский | Português
本项目是 Qwen3-TTS 的极致性能实现，核心突破在于 “指令驱动 (Instruction-Driven)” 与 “零样本自定义音色 (Custom Speakers)” 的深度集成。通过 Rust 的内存安全特性与 llama.cpp/ONNX 的高效推理，为您提供工业级的文本转语音解决方案。
- 并发流式解码：采用 4 帧 (64 codes) 粒度的并发解码策略，首字延迟低至 300ms，实现“边想边说”的流畅体验。
- 硬件加速：默认启用 Vulkan (Windows/Linux) 和 Metal (macOS) 加速，显著提升推理速度。
- 自动运行时管理：零配置环境，自动下载并配置
llama.cpp(b7885) 和onnxruntime，开箱即用。
- 自动扫描与缓存：启动时自动加载
speakers/目录下的音色文件。 - 多种选择方式：支持通过 CLI 参数
--speaker <name>或--voice-file <path>灵活选择说话人。 - 智能回退：若指定说话人不存在，自动回退至默认音色 (vivian)，确保系统稳定性。
- 指令驱动：支持在文本中嵌入
[高兴]、[悲伤]等情感指令，实时调整演绎风格。 - EOS 对齐：完美对齐 Qwen3 的停止逻辑，支持多种 EOS token 检测，杜绝生成末尾的静音或乱码。
| Backend | Model (GGUF) | RTF (Real-Time Factor) | Avg Time (ms) | Avg Audio (s) | Status |
|---|---|---|---|---|---|
| CUDA | Q5_K_M | 0.553 | 1162.6 | 2.19 | OK |
| Vulkan | Q5_K_M | 0.598 | 1285.4 | 2.19 | OK |
| CUDA | Q8_0 | 0.640 | 1523.4 | 2.44 | OK |
| Vulkan | Q8_0 | 0.638 | 1502.0 | 2.44 | OK |
| CPU | Q5_K_M | 1.677 | 2823.4 | 1.96 | OK |
| CPU | Q8_0 | 1.866 | 4160.1 | 2.51 | OK |
- 测试环境: Intel Core i9-13980HX, NVIDIA RTX 2080 Ti. 显存占用约 0.7-1.5GB.
- 数据来源: Windows 平台 10 轮生成平均值。
- 最佳性能: RTF 0.553 (CUDA + Q5KM)，即生成 1 秒音频仅需 0.553 秒。
使用默认说话人生成语音：
cargo run --bin qwen3_tts -- --text "你好，欢迎使用 Qwen3-TTS Rust！"使用预设或自定义说话人：
# 使用名称 (需在 speakers/ 目录下存在对应的 .json 文件)
cargo run --bin qwen3_tts -- --text "今天天气不错。" --speaker dylan
# 使用指定文件路径
cargo run --bin qwen3_tts -- --text "我是自定义音色。" --voice-file "path/to/my_voice.json"只需 3-10 秒的参考音频即可克隆音色：
cargo run --bin qwen3_tts -- `
--ref-audio "ref.wav" `
--ref-text "参考音频对应的文本内容" `
--save-voice "speakers/my_voice.json" `
--text "新音色已保存，现在可以直接使用了！"通过 --instruction 参数实时改变说话语气：
# 悲伤语气
cargo run --bin qwen3_tts -- --text "对不起，我不是故意的..." --instruction "悲伤啜泣，非常难过"
# 开心语气
cargo run --bin qwen3_tts -- --text "太棒了！我们成功了！" --instruction "开心激动，语速稍快"cargo run --bin qwen3_tts -- `
--text "长文本生成测试。" `
--max-steps 1024 ` # 调整最大生成长度
--output "output.wav" # 指定输出文件名通过采样参数控制生成的随机性和多样性：
# 调整温度 (更高 = 更随机，0.0 = 贪婪)
cargo run --bin qwen3_tts -- --text "测试文本" --temperature 0.8
# 使用固定种子复现结果
cargo run --bin qwen3_tts -- --text "测试文本" --seed 12345
# 完整参数示例
cargo run --bin qwen3_tts -- `
--text "测试采样参数。" `
--temperature 0.7 ` # 温度 (默认 0.7)
--top-k 40 ` # Top-K 采样 (默认 40)
--top-p 0.9 ` # Top-P 核采样 (默认 0.9)
--seed 42 # 随机种子 (可选)在 Cargo.toml 中添加依赖：
[dependencies]
# 本地引用
qwen3-tts = { path = "." }
# 或从 Git 引用
# qwen3-tts = { git = "https://github.com/cgisky1980/Qwen3-TTS-Rust" }use qwen3_tts::{TtsEngine, VoiceFile, SamplerConfig};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// 1. 初始化引擎
let mut engine = TtsEngine::new("models", "none").await?;
// 2. 配置采样参数 (可选)
let sampler_config = SamplerConfig::new(0.7, 40, 0.9, None);
engine.set_sampler_config(sampler_config);
// 3. 加载音色
let voice = VoiceFile::load("speakers/sohee.json")?;
// 4. 生成语音
let audio = engine.generate_with_voice(
"你好，欢迎使用 Qwen3-TTS！",
&voice,
None, // instruction
)?;
// 5. 保存音频
audio.save_wav("output.wav")?;
Ok(())
}use qwen3_tts::TtsEngine;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut engine = TtsEngine::new("models", "none").await?;
// 从参考音频提取音色
let voice = engine.create_voice_file(
"reference.wav",
"参考音频对应的文本".to_string(),
)?;
// 保存音色文件
voice.save("speakers/my_voice.json")?;
// 使用新音色生成
let audio = engine.generate_with_voice("测试新音色", &voice, None)?;
audio.save_wav("output.wav")?;
Ok(())
}系统首次运行会自动构建如下结构：
.
├── models/ # 模型文件 (GGUF, ONNX, Tokenizer)
├── runtime/ # 自动下载的依赖库 (dll, so, dylib)
└── speakers/ # 用户自定义音色
- 基于 MIT / Apache 2.0 许可证。
- 感谢 Qwen3-TTS 官方仓库提供的模型与技术基座。
- 感谢 Qwen3-TTS-GGUF 提供的推理流程启发。