本教程系统讲解文本转语音(TTS)技术,详细介绍两款主流 TTS 方案:免费在线的 edge-tts 与开源本地的 Qwen3-TTS。通过完整示例项目 a4voice,你将学会用 Python 调用两种 TTS 引擎,将两者封装为 OpenAI 兼容的 /v1/audio/speech 接口,并构建一个输入文字、点击按钮即可生成并播放语音的前端页面。

前置教程

如想快速开始学习本教程,你可能需要先完成以下前置教程:

资源下载

1. TTS 技术概览

1.1 什么是 TTS

TTS(Text-to-Speech,文本转语音) 是指将文字内容自动转换为自然流畅的人声语音的技术,是人工智能语音领域最基础也最成熟的应用之一。

TTS 的应用场景非常广泛:

  • 语音助手:智能音箱、手机助手的播报能力
  • 有声内容:有声书、播客、新闻朗读的批量合成
  • 视频配音:短视频、自媒体配音,降低配音成本
  • 教育场景:外语学习、课文朗读、无障碍阅读
  • 客服系统:呼叫中心自动应答、车载语音播报

现代 TTS 系统的核心处理流程如下:

graph LR A[输入文本] --> B[文本前端分析] B --> C[声学模型生成特征] C --> D[声码器合成波形] D --> E[输出音频] classDef input fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px classDef process fill:#d5f5e3,stroke:#27ae60,stroke-width:2px classDef model fill:#ffecd6,stroke:#e67e22,stroke-width:2px classDef output fill:#ebdef0,stroke:#8e44ad,stroke-width:2px class A input class B process class C,D model class E output
阶段 作用 说明
文本前端分析 分词、注音、标点停顿处理 决定发音是否正确
声学模型 将文本特征映射为声学特征 决定音质与自然度
声码器 将声学特征还原为音频波形 决定听感是否细腻

TTS 的本质是"文本到语音"的映射,其效果取决于声学模型与声码器的质量,而工程上的重点是选择合适的技术方案并把它封装成易于调用的服务。

1.2 在线 TTS 与本地部署 TTS 的对比

调用 TTS 有两种主流方式:调用在线 TTS 服务 与 本地部署 TTS 模型。两者的对比如下:

对比项 在线 TTS 本地部署 TTS(Qwen3-TTS)
联网要求 需要联网调用服务 无需联网,完全离线可用
调用成本 大部分收费 模型开源免费,需自备硬件
音色定制 服务商定制,音色丰富 9 个预置精品音色,支持自然语言指令控制语气与情感
部署门槛 极低,根据服务商提供的接口接入即可 较高,需要 GPU 与较多依赖
稳定可控 依赖第三方服务稳定性 完全自主可控,数据不出本地
合成延迟 受网络环境影响 取决于本机硬件性能

1.3 本教程的选型

  • edge-tts:用来演示"零成本快速接入在线 TTS",安装一条命令、调用几行代码,适合对音质要求不高、需要快速上手的场景。
  • Qwen3-TTS:用来演示"本地部署高质量 TTS",阿里通义千问团队开源的语音生成大模型,提供 9 个预置精品音色、10 种语言合成,并支持用自然语言指令控制语气、语速与情感,适合对隐私、可控性和表现力有要求的场景。

选择建议:原型验证、轻量应用选 edge-tts;生产级语音合成、强表现力需求选本地部署 Qwen3-TTS。两者能力可以互补,本教程的示例项目将它们统一封装为同一套接口,切换引擎只需改一个参数。

2. 在线 TTS:edge-tts

2.1 edge-tts 简介

edge-tts 是一个非官方 Python 库,封装了微软 Edge 浏览器内置的神经网络语音合成引擎。它免费、无需 API Key,即可调用微软的高质量中文语音,支持 40 多种语言、300 多种音色,是快速体验 TTS 最轻量的方案。

主要特点:

  • 免费无密钥:直接调用微软 Edge 在线接口,无需注册与付费
  • 中文自然:内置多款针对中文优化的人声,发音清晰自然
  • 使用简单:异步 API,几行代码即可生成 MP3 音频
  • 参数灵活:支持语速、音量、音调等参数调节

2.2 安装 edge-tts

uv pip install edge-tts

安装后可以查看全部可用音色:

# 查看所有可用音色
edge-tts --list-voices

# 过滤出中文音色(Windows PowerShell 使用 Select-String)
edge-tts --list-voices | Select-String zh-CN

# 或者使用 grep 命令过滤中文音色(Linux/Mac)
edge-tts --list-voices | grep zh-CN

2.3 常用中文音色

查询结果中的 Name 是音色名称,格式为 语言-国家/地区-名字Neural,如 zh-CN-XiaoxiaoNeural 表示简体中文、晓晓音色。常用中文音色如下:

音色名称 性别/风格 特点
zh-CN-XiaoxiaoNeural 女 自然温暖,最常用
zh-CN-XiaoyiNeural 女 温柔可爱
zh-CN-XiaohanNeural 女 抒情柔和
zh-CN-XiaomoNeural 女 情感丰富,支持多种风格
zh-CN-XiaoruiNeural 女 成熟专业
zh-CN-YunxiNeural 男 年轻活泼
zh-CN-YunjianNeural 男 沉稳叙事
zh-CN-YunyangNeural 男 新闻播报风格
zh-CN-YunxiaNeural 男 童声

音色列表会随微软服务更新而扩充,以 edge-tts --list-voices 实时查询结果为准。

2.4 Python 调用示例

edge-tts 基于 asyncio 异步模型,生成音频的核心代码如下:

# 基础调用示例
import asyncio
import edge_tts

TEXT = "你好,欢迎使用 edge-tts 文本转语音服务。"
VOICE = "zh-CN-XiaoxiaoNeural"  # 中文女声

async def main():
    communicate = edge_tts.Communicate(TEXT, VOICE)
    await communicate.save("output.mp3")

if __name__ == "__main__":
    asyncio.run(main())

运行后目录下会生成 output.mp3 文件,使用播放器即可试听。

也可以使用命令行快速合成:

edge-tts --voice zh-CN-YunxiNeural --text "你好,世界" --write-media hello.mp3

2.5 语速与音量调节

Communicate 支持通过 rate、volume、pitch 参数调节语速、音量与音调:

async def main():
    # rate 语速(范围约 -50% 到 +200%),volume 音量(范围 -100% 到 +100%)
    communicate = edge_tts.Communicate(
        TEXT, VOICE,
        rate="+20%",     # 语速加快 20%
        volume="+0%",    # 音量保持不变
    )
    await communicate.save("output.mp3")

3. 本地 TTS:Qwen3-TTS

3.1 Qwen3-TTS 简介

Qwen3-TTS 是阿里通义千问团队开源的语音生成大模型,它将大语言模型的语义理解能力引入语音合成,可根据文本语义与指令自适应控制语气、语速与情感表达。本教程使用其中的 Qwen3-TTS-12Hz-1.7B-CustomVoice 版本:约 17 亿参数,提供 9 个预置精品音色,支持中、英、日、韩、德、法、俄、葡、西、意 10 种语言合成,并支持通过自然语言指令精细控制说话风格。

CustomVoice 版本的合成流程如下:

graph LR A[输入文本] --> D[Qwen3-TTS
语音大模型] B[预置音色] --> D C[风格指令] --> D D --> E[音频解码] E --> F[WAV 语音] classDef input fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px classDef process fill:#d5f5e3,stroke:#27ae60,stroke-width:2px classDef model fill:#ffecd6,stroke:#e67e22,stroke-width:2px classDef output fill:#ebdef0,stroke:#8e44ad,stroke-width:2px class A,B,C input class D model class E process class F output

预置音色:9 个音色覆盖不同性别、年龄、语言与方言。建议优先让音色说其母语(如 Ryan、Aiden 说英语,Ono_Anna 说日语),各音色也可以说任意受支持的语言:

音色 声线描述 母语
Vivian 明亮利落的年轻女声 中文
Serena 温暖柔和的年轻女声 中文
Uncle_Fu 低沉醇厚的成熟男声 中文
Dylan 清晰自然的北京口音男声 中文(北京话)
Eric 活泼略带沙哑的成都口音男声 中文(四川话)
Ryan 节奏感强的活力男声 英语
Aiden 阳光清爽的美式男声 英语
Ono_Anna 俏皮轻快的日语女声 日语
Sohee 情感丰富的温暖韩语女声 韩语

自然语言风格控制:不需要记参数,直接用一句话描述想要的效果即可,如"用特别愤怒的语气说""语速稍微放慢,带点笑意"。模型会结合文本语义自适应调整语气、语速与情感,这是 Qwen3-TTS 相对传统 TTS 的核心优势。

本地模型目录:本教程假设模型已放置在 C:\models\Qwen3-TTS-12Hz-1.7B-CustomVoice,目录中包含 model.safetensors 等权重文件与 config.json 等配置文件,以 ModelScope 仓库实际文件为准。

3.2 部署环境准备

Qwen3-TTS 需要 GPU 推理环境。1.7B 模型 BF16 权重约 3.5 GB,建议使用显存 8GB 以上的 NVIDIA GPU;无 GPU 时也可用 CPU 推理但速度较慢。Python 依赖统一使用 uv 安装,比 pip 快一个数量级。

提示:本教程第 3、4 章共用同一个 conda 环境 a4voice,第 4 章的 a4voice 项目直接复用本环境,无需再单独创建环境。

# 创建并激活本教程统一使用的 conda 环境
conda create -n a4voice python=3.10 -y
conda activate a4voice

# 安装 uv(Python 包管理工具)
pip install uv

用 uv 安装 GPU 版 PyTorch。国内推荐从阿里云镜像直链下载 cu128 的 wheel,速度远快于官方源;网络好的读者也可改用官方源命令:

# 方法一:阿里云镜像直链(国内推荐,速度快)
uv pip install \
  "https://mirrors.aliyun.com/pytorch-wheels/cu128/torch-2.8.0%2Bcu128-cp310-cp310-win_amd64.whl" \
  "https://mirrors.aliyun.com/pytorch-wheels/cu128/torchvision-0.23.0%2Bcu128-cp310-cp310-win_amd64.whl" \
  "https://mirrors.aliyun.com/pytorch-wheels/cu128/torchaudio-2.8.0%2Bcu128-cp310-cp310-win_amd64.whl"

# 方法二:PyTorch 官方源(需能访问 download.pytorch.org)
uv pip install torch==2.8.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

3.3 安装 qwen-tts

Qwen 官方提供了开箱即用的 qwen-tts Python 包,一条命令安装即可(自动补齐 transformers 等依赖,已安装的 cu128 torch 会被保留):

# 请确保仍然在 a4voice 环境下
uv pip install -U qwen-tts soundfile --index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后,即可在任意 Python 代码中通过 from qwen_tts import Qwen3TTSModel 调用模型。

提示:追求更低显存占用与更快推理的读者,可另行安装 FlashAttention 2(pip install -U flash-attn --no-build-isolation),并在 a4voice 的 config.py 中将 QWEN_TTS_USE_FLASH_ATTN 改为 True。Windows 下编译 flash-attn 较繁琐,默认不安装不影响使用。

3.4 下载模型权重

Qwen3-TTS-12Hz-1.7B-CustomVoice 模型可通过 ModelScope 或 HuggingFace 下载。国内用户推荐使用 ModelScope:

# 使用 ModelScope 下载(推荐国内用户)
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir C:/models/Qwen3-TTS-12Hz-1.7B-CustomVoice

下载完成后文件即位于 C:\models\Qwen3-TTS-12Hz-1.7B-CustomVoice 目录,无需解压。

3.5 交互体验方式

Qwen 官方 qwen-tts 包自带一个可视化 Demo 脚本,无需写代码即可体验模型效果:

# 请确保仍然在 a4voice 环境下
qwen-tts-demo C:/models/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 127.0.0.1 --port 8001

启动后访问 http://127.0.0.1:8001,即可在网页中选择音色、输入文本、填写风格指令并试听。注意端口不要与第 4 章 a4voice 服务的 8000 端口冲突。

3.6 使用 Python 调用本地模型

在 Python 中调用 Qwen3-TTS-12Hz-1.7B-CustomVoice 的核心代码如下:

import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

# 加载本地模型
model = Qwen3TTSModel.from_pretrained(
    "C:/models/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    device_map="cuda",        # 无 GPU 时改为 cpu
    dtype=torch.bfloat16,     # BF16 半精度推理,降低显存占用
)

# 文本 + 音色 + 风格指令 -> 输出语音
wavs, sr = model.generate_custom_voice(
    text="你好,欢迎使用 Qwen3-TTS 文本转语音。",
    language="Chinese",       # 语言,10 种可选;传 Auto 或省略则自动识别
    speaker="Vivian",         # 预置音色,共 9 个
    instruct="用轻松愉快的语气说",  # 自然语言风格指令,不需要可省略
)
sf.write("output.wav", wavs[0], sr)   # 以模型返回的采样率保存 WAV

核心要点:generate_custom_voice() 的关键字参数为待合成文本 text、预置音色 speaker、语言 language 与自然语言风格指令 instruct,返回音频数组与采样率。instruct 是 Qwen3-TTS 的精髓,语气、语速、情感都用一句话控制,如"用特别愤怒的语气说""语速稍微放慢"。模型在首次调用时加载权重,需要一定时间。

4. 综合示例:a4voice 文本转语音服务

4.1 项目目标与架构

示例项目 a4voice 将前面介绍的两款 TTS 引擎整合为一个完整服务,实现以下目标:

  • 用 Python(FastAPI)实现后端服务
  • 调用 edge-tts 在线服务合成语音
  • 调用本地 Qwen3-TTS-12Hz-1.7B-CustomVoice 模型合成语音(模型地址 C:\models\Qwen3-TTS-12Hz-1.7B-CustomVoice)
  • 对外暴露 OpenAI 兼容 API(POST /v1/audio/speech)
  • 构建前端界面:用户输入文字,点击按钮,调用 TTS 服务生成音频文件并播放

整体架构如下:

graph LR U[前端页面
static/index.html] -->|POST /v1/audio/speech| A[FastAPI 后端
main.py] A --> E[edge-tts 在线引擎] A --> Q[Qwen3-TTS 本地引擎] E -->|MP3| U Q -->|WAV| U E --> S[微软 Edge 语音服务] Q --> M[Qwen3-TTS 模型
C:/models/Qwen3-TTS-12Hz-1.7B-CustomVoice] classDef frontend fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px classDef backend fill:#d5f5e3,stroke:#27ae60,stroke-width:2px classDef engine fill:#ebdef0,stroke:#8e44ad,stroke-width:2px classDef model fill:#ffecd6,stroke:#e67e22,stroke-width:2px classDef external fill:#fadbd8,stroke:#c0392b,stroke-width:2px class U frontend class A backend class E,Q engine class M model class S external

4.2 项目结构

a4voice/
├── config.py                  # 服务配置(端口、音色、模型路径)
├── main.py                    # FastAPI 后端,暴露 OpenAI 兼容接口
├── requirements.txt           # 依赖管理
├── services/
│   ├── __init__.py
│   ├── edge_tts_service.py    # 在线引擎:调用 edge-tts 服务
│   └── qwen_tts_service.py    # 本地引擎:调用 Qwen3-TTS 模型
└── static/
    └── index.html             # 前端页面

4.3 配置文件 config.py

所有配置统一在 config.py 中修改,包括监听端口、edge-tts 音色列表、Qwen3-TTS 模型路径与注册的预置音色:

# config.py(核心片段,完整代码请查看 a4voice/config.py)
PORT = 8000

# 在线 TTS(edge-tts)配置
EDGE_TTS_DEFAULT_VOICE = "zh-CN-XiaoxiaoNeural"

# 本地 TTS(Qwen3-TTS)配置
QWEN_TTS_MODEL_DIR = "C:/models/Qwen3-TTS-12Hz-1.7B-CustomVoice"  # 模型目录
QWEN_TTS_DEVICE = "cuda"           # 推理设备:cuda / cpu
QWEN_TTS_DTYPE = "bfloat16"        # 推理精度:bfloat16 / float32
QWEN_TTS_USE_FLASH_ATTN = False    # 是否启用 FlashAttention 2

# 注册的预置音色(CustomVoice 模型内置 9 个音色)
QWEN_TTS_SPEAKERS = [
    {"name": "Vivian", "label": "Vivian(女,明亮利落)"},
    {"name": "Serena", "label": "Serena(女,温暖柔和)"},
    {"name": "Uncle_Fu", "label": "付叔(男,低沉醇厚)"},
    # ... 其余音色见完整代码
]

4.4 在线引擎:调用 edge-tts 服务

services/edge_tts_service.py 封装了 edge-tts 的调用逻辑,将 OpenAI 的 speed 语速参数转换为 edge-tts 的 rate 参数,并把流式音频块写入内存缓冲区:

# services/edge_tts_service.py(核心片段,完整代码请查看 a4voice/services/edge_tts_service.py)
import edge_tts

async def synthesize(text, voice=None, speed=1.0):
    """将文本合成为 MP3 音频,返回 (音频字节流, 音频格式)"""
    voice = voice or EDGE_TTS_DEFAULT_VOICE
    rate = speed_to_rate(speed)      # 将 1.0 映射为 +0%,1.2 映射为 +20%

    communicate = edge_tts.Communicate(text, voice, rate=rate)
    buffer = io.BytesIO()
    async for chunk in communicate.stream():
        if chunk["type"] == "audio":
            buffer.write(chunk["data"])
    return buffer, "mp3"

4.5 本地引擎:调用 Qwen3-TTS 服务

services/qwen_tts_service.py 封装了 Qwen3-TTS 的调用逻辑。考虑到模型加载耗时,采用懒加载方式在首次请求时才加载权重;同时模型推理非线程安全,使用全局锁串行化推理请求:

# services/qwen_tts_service.py(核心片段,完整代码请查看 a4voice/services/qwen_tts_service.py)
from qwen_tts import Qwen3TTSModel
import soundfile as sf

def synthesize(text, speaker="Vivian", language=None, speed=1.0, instruct=None):
    """将文本合成为 WAV 音频,返回输出文件路径"""
    output_path = os.path.join(OUTPUT_DIR, f"{uuid.uuid4().hex}.wav")

    # Qwen3-TTS 用自然语言指令控制语气、语速与情感,
    # 语速系数转换为指令后与风格指令合并为一条 instruct
    hints = [h for h in (instruct, speed_instruct(speed)) if h]
    final_instruct = ",".join(hints) or None

    kwargs = {"text": text, "speaker": speaker}
    if language:                 # 语言代码映射为模型语言名,缺省由模型自动识别
        kwargs["language"] = LANGUAGE_MAP[language]
    if final_instruct:
        kwargs["instruct"] = final_instruct

    tts = _get_tts()             # 懒加载模型
    with _infer_lock:            # 串行化推理
        wavs, sr = tts.generate_custom_voice(**kwargs)
    sf.write(output_path, wavs[0], sr)   # 以模型返回的采样率保存
    return output_path

其中 speed_instruct() 将语速系数转换为"语速稍微放慢""语速稍微加快"等指令,LANGUAGE_MAP 把 ZH、EN 等语言代码映射为 Chinese、English 等模型语言名。

4.6 对外暴露 OpenAI 兼容接口

main.py 是服务的核心入口,对外暴露 OpenAI 兼容的 POST /v1/audio/speech 接口。该接口根据请求中的 model 参数自动路由到对应的 TTS 引擎:

# main.py(核心片段,完整代码请查看 a4voice/main.py)
class SpeechRequest(BaseModel):
    model: str = "edge-tts"       # 引擎:edge-tts(在线)/ qwen-tts(本地)
    input: str                    # 待合成的文本
    voice: str | None = None      # 音色
    speed: float = 1.0            # 语速,范围 0.25~4.0
    lang: str | None = None       # 合成语言,仅 qwen-tts 支持,缺省自动识别
    instruct: str | None = None   # 风格指令,仅 qwen-tts 支持
    response_format: str = "mp3"  # 输出格式

@app.post("/v1/audio/speech")
async def text_to_speech(req: SpeechRequest):
    """OpenAI 兼容的文本转语音接口"""
    if req.model == "edge-tts":
        audio, fmt = await edge_tts_service.synthesize(req.input, req.voice, req.speed)
        return Response(content=audio.read(), media_type="audio/mpeg")
    if req.model == "qwen-tts":
        output_path = qwen_tts_service.synthesize(
            req.input, req.voice or "Vivian", req.lang, req.speed, req.instruct
        )
        return FileResponse(output_path, media_type="audio/wav")
    raise HTTPException(status_code=400, detail=f"不支持的模型: {req.model}")

代码要点说明:

功能模块 实现方式 说明
接口路径 POST /v1/audio/speech 与 OpenAI 官方规范一致
参数格式 model + input + voice 请求体使用 OpenAI 标准字段
引擎路由 按 model 字段分发 edge-tts 走在线,qwen-tts 走本地
返回格式 音频字节流 edge-tts 返回 MP3,Qwen3-TTS 返回 WAV

4.7 前端界面

前端为单页 HTML 应用,位于 static/index.html。你可以前往 a4voice/static/index.html 查看完整的示例代码。页面主要功能:

  1. 引擎切换:在"edge-tts 在线"与"Qwen3-TTS 本地"之间切换
  2. 音色选择:根据所选引擎加载对应音色列表
  3. 语速调节:两种引擎均支持滑动调节语速(Qwen3-TTS 在服务层转换为自然语言指令)
  4. 语言选择:Qwen3-TTS 引擎可选合成语言(自动识别 / 10 种语言)
  5. 风格指令:Qwen3-TTS 引擎支持输入自然语言指令,控制语气与情感
  6. 文本输入:输入待合成的文字内容
  7. 生成播放:点击"生成语音"按钮,通过 fetch 调用 /v1/audio/speech 接口,将返回的音频流以 Blob 方式加载到播放器并自动播放

要点:前端本身就是一个 OpenAI 兼容 API 客户端,它直接调用 /v1/audio/speech 而非自定义接口,验证了该接口的通用兼容性。

4.8 运行与测试

第一步:创建环境并安装依赖

本教程全篇共用一个 conda 环境 a4voice。若已按第 3 章完成环境准备,直接激活即可:

conda activate a4voice

若未按第 3 章创建过该环境(例如仅使用 edge-tts 引擎),则新建:

conda create -n a4voice python=3.10
conda activate a4voice

然后进入项目目录用 uv 安装核心依赖:

cd a4voice

# 安装核心依赖(fastapi、uvicorn、edge-tts),国内可加清华镜像加速
uv pip install -r requirements.txt --index-url https://pypi.tuna.tsinghua.edu.cn/simple

第二步:启用本地 Qwen3-TTS 引擎(可选)

若已按第 3 章完成 qwen-tts 安装与模型下载,此步可跳过。否则执行:

uv pip install -U qwen-tts soundfile --index-url https://pypi.tuna.tsinghua.edu.cn/simple
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir C:/models/Qwen3-TTS-12Hz-1.7B-CustomVoice

确保模型位于 C:\models\Qwen3-TTS-12Hz-1.7B-CustomVoice(并已在 config.py 中配置对应路径)。仅使用 edge-tts 引擎可跳过此步。

第三步:启动服务

python main.py

启动后访问 http://localhost:8000,即可看到语音合成界面。

第四步:验证功能

在界面中输入文字、选择引擎与音色,点击"生成语音",确认能正常生成并播放音频。

安装核心依赖(fastapi、uvicorn、edge-tts),国内可加清华镜像加速示意图

也可使用 curl 直接验证接口:

# edge-tts 引擎
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "edge-tts", "input": "你好,世界", "voice": "zh-CN-XiaoxiaoNeural", "speed": 1.0}' \
  --output test.mp3

# Qwen3-TTS 引擎(风格指令控制语气)
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-tts", "input": "你好,世界", "voice": "Vivian", "instruct": "用开心的语气说"}' \
  --output test.wav

4.9 使用 OpenAI SDK 验证接口兼容性

由于服务暴露的是 OpenAI 兼容接口,可以直接使用 openai 官方 Python SDK 调用,无需关心底层引擎细节:

# 使用 openai SDK 调用本地 a4voice 服务
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",  # 本地服务地址
    api_key="not-needed",                 # 本地服务不校验 Key
)

resp = client.audio.speech.create(
    model="edge-tts",
    input="你好,欢迎使用 a4voice 文本转语音服务。",
    voice="zh-CN-XiaoxiaoNeural",
)
resp.stream_to_file("test.mp3")

只要服务实现 OpenAI 兼容接口,任何基于 OpenAI SDK 开发的应用都可以无缝切换到底层 TTS 引擎,这正是兼容接口的价值所在。

5. 总结

5.1 核心内容回顾

  • TTS 技术:文本转语音,核心流程为文本前端分析、声学模型生成特征、声码器合成波形
  • 在线方案 edge-tts:免费、无密钥、使用简单,适合快速接入
  • 本地方案 Qwen3-TTS:开源、离线可用,9 个预置精品音色、10 种语言合成,支持自然语言指令控制语气、语速与情感,适合生产级应用
  • 服务封装:FastAPI 实现 /v1/audio/speech OpenAI 兼容接口,按 model 参数路由到不同引擎
  • 前端应用:输入文字、点击按钮、生成并播放音频,前端本身即兼容 API 客户端

5.2 常见问题与解答

问:edge-tts 需要注册或 API Key 吗?

答:不需要。edge-tts 直接调用微软 Edge 在线语音接口,免费使用,但需要联网。

问:Qwen3-TTS 提示"模型目录不存在"怎么办?

答:先下载 Qwen3-TTS-12Hz-1.7B-CustomVoice 模型权重,并确认 config.py 中 QWEN_TTS_MODEL_DIR 指向的目录与实际下载位置一致。

问:Qwen3-TTS 的语速、语气如何控制?

答:Qwen3-TTS 没有独立的语速参数,而是通过自然语言指令 instruct 统一控制语气、语速与情感。前端语速滑块在服务层被转换为"语速稍微放慢""语速稍微加快"等指令,也可以在"风格指令"输入框中直接描述,如"用沉稳的语气慢慢说"。

问:Qwen3-TTS 朗读英文发音不准怎么办?

答:先确认"合成语言"选择了英语或保持自动识别;其次建议让音色说其母语,如英语文本选 Ryan 或 Aiden,日语文本选 Ono_Anna。Qwen3-TTS 对文本噪声的鲁棒性较强,一般无需手动标注发音。

问:Qwen3-TTS 合成报 CUDA out of memory?

答:1.7B 模型 BF16 推理建议 8GB 以上显存。显存不足时,确认 config.py 中 QWEN_TTS_DTYPE 为 bfloat16,或缩短输入文本;无 GPU 时将 QWEN_TTS_DEVICE 改为 cpu。

问:Qwen3-TTS 引擎加载很慢?

答:模型权重较大,首次请求加载需要一定时间属正常现象。加载完成后缓存于内存,后续请求速度会明显提升。

问:edge-tts 引擎为什么不支持 wav 输出?

答:edge-tts 原生输出 MP3 格式,本示例直接返回其原生格式。如需 wav 需额外使用 ffmpeg 等工具转码。