一键部署Qwen3-TTS语音合成：Web API服务搭建教程

想给自己的应用加上语音合成功能，但被复杂的本地部署和资源占用劝退？或者，你已经在本地测试过Qwen3-TTS，效果不错，却卡在了“如何让团队其他成员也能方便调用”这一步？

今天，我们来解决这个问题。我将带你一步步，把一个功能强大的多语言语音合成模型——Qwen3-TTS-12Hz-1.7B-CustomVoice，部署成一个随时可用、稳定可靠的Web API服务。整个过程就像搭积木，你不需要是运维专家，跟着做就行。完成后，你就能通过简单的HTTP请求，让服务器为你生成高质量、带情感的语音了。

1. 为什么需要Web API服务？

在开始动手之前，我们先聊聊为什么要把模型“服务化”。

你可能已经在自己的电脑上跑过Qwen3-TTS的Demo了。本地运行简单直接，但有几个明显的痛点：

  • 资源独占：运行模型会占用大量GPU和内存，你的电脑就没法干别的了。
  • 难以共享：同事或合作伙伴想用，你得帮他们配环境，或者把模型文件发来发去。
  • 稳定性差：关掉程序或者电脑休眠，服务就停了。
  • 不易集成：你的网站、App或者其他后端服务，很难直接调用一个本地的Python脚本。

而一个Web API服务能完美解决这些问题：

  • 随时可用：部署在服务器上，7x24小时运行。
  • 轻松调用：任何能发送HTTP请求的程序（前端、App、其他服务）都能使用。
  • 集中管理：模型、依赖、日志都在一处，维护升级都方便。
  • 资源优化：服务器通常有更强的计算能力，能更好地处理并发请求。

简单说，部署成Web API，就是把一个“玩具”变成了一个“工具”。接下来，我们就开始打造这个工具。

2. 环境准备：打好地基

万丈高楼平地起，我们先来准备一个干净、稳定的运行环境。这里我们使用Docker，它能保证环境的一致性，避免“在我机器上好好的”这种问题。

2.1 基础系统与Docker

首先，确保你有一台安装了Linux的服务器（Ubuntu 20.04/22.04或CentOS 7/8都行），并且有NVIDIA显卡和对应的驱动。通过SSH连接到你的服务器。

  1. 更新系统并安装必要工具：

    sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git vim

  2. 安装Docker和NVIDIA容器工具包： Docker让部署标准化，NVIDIA容器工具包让Docker能调用GPU。

    # 安装Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER # 将当前用户加入docker组，避免每次用sudo
# 需要重新登录或执行 newgrp docker 使组生效

# 安装NVIDIA容器工具包
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt update && sudo apt install -y nvidia-docker2
sudo systemctl restart docker

  3. 验证安装：

    docker --version
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

    如果第二条命令能成功输出显卡信息，说明Docker和GPU支持都配置好了。

2.2 获取模型与代码

我们不需要从零开始写服务代码。为了最快速部署，我们可以基于一个现成的、优化好的Docker镜像来构建我们的服务。

  1. 创建一个项目目录：

    mkdir ~/qwen-tts-service && cd ~/qwen-tts-service

  2. 准备模型文件（可选但推荐）： 模型文件较大（约12GB）。虽然Docker镜像可以包含，但为了更灵活地管理和更新模型，我们可以选择将模型文件放在宿主机上，然后挂载到容器中。

    • 从ModelScope或Hugging Face下载模型到本地目录：
      mkdir -p ./models
# 假设你已经通过其他方式将模型文件放在了 ./models 目录下
# 或者，你可以在Dockerfile中配置从网络拉取，但这会增大镜像体积和构建时间。
    • 我们更推荐的方式是：直接使用已经集成了模型和Web UI的预置镜像，这省去了下载和配置的麻烦。这正是我们接下来要做的。

3. 核心部署：使用预置镜像一键启动

这是最简单快捷的方式。CSDN星图镜像广场提供了预配置好的Qwen3-TTS镜像，开箱即用。

3.1 拉取并运行镜像

假设我们已经获取到了一个名为 qwen-tts-webui:latest 的镜像（此处为示例，实际镜像名请以平台提供为准）。

  1. 运行Docker容器： 这条命令是核心，它做了很多事情：

    docker run -d \
  --name qwen-tts-api \
  --gpus all \
  -p 7860:7860 \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/outputs:/app/outputs \
  --restart unless-stopped \
  qwen-tts-webui:latest
    • -d：后台运行。
    • --name：给容器起个名字，方便管理。
    • --gpus all：将宿主机的所有GPU分配给容器。
    • -p 7860:7860：将容器的7860端口映射到宿主机的7860端口。Gradio WebUI默认运行在这个端口。
    • -v ...:/app/logs：将宿主机的./logs目录挂载到容器的日志目录，方便查看日志。
    • -v ...:/app/outputs：挂载输出目录，生成的音频文件会保存在这里。
    • --restart unless-stopped：设置自动重启策略，除非手动停止，否则容器退出时会自动重启。
    • 最后是镜像名。

  2. 查看服务状态：

    docker ps | grep qwen-tts-api
docker logs -f qwen-tts-api # 查看实时日志，确认服务启动成功

    当在日志中看到类似 Running on local URL: http://0.0.0.0:7860 的信息时，说明Web UI服务已经启动。

3.2 验证Web UI

现在，打开你的浏览器，访问 http://你的服务器IP地址:7860。 你应该能看到一个简洁的Web界面，在这里你可以：

  1. 在文本框中输入想要合成的文字。
  2. 选择语言（中文、英文、日文等10种语言）。
  3. 选择说话人音色（如Vivian, Serena, Ryan等）。
  4. 点击生成按钮，稍等片刻，就能在线播放或下载生成的语音文件了。

这个界面非常适合手动测试和体验模型效果。但我们的目标是API，所以接下来要挖掘它的API能力。

4. 构建专属的Web API服务

预置镜像的WebUI很棒，但通常我们更需要一个供程序调用的API。Gradio应用本身通常也提供API端点。我们可以直接调用，或者为了更规范、功能更定制化，我们可以在其基础上包装一层FastAPI。

4.1 方案一：直接调用Gradio API（快速验证）

Gradio应用启动后，会自动创建一组API。我们可以用curl或任何HTTP客户端来调用。

  1. 查找API端点： 访问 http://你的服务器IP地址:7860，按F12打开开发者工具，切换到“网络”(Network)选项卡。在WebUI上点击一次“生成”按钮，观察网络请求。你通常会看到一个向 /api/predict/ 或 /run/predict 发起的POST请求。这就是它的API。

  2. 使用curl测试： 根据抓取到的请求格式，构造调用。假设端点是 /run/predict，参数是一个JSON，包含data数组。

    curl -X POST "http://localhost:7860/run/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      "你好，这是通过API合成的语音。",
      "Chinese",
      "Vivian",
      "用自然、清晰的语气说话"
    ]
  }' \
  --output output.wav

    如果成功，会下载一个output.wav文件。这种方式简单，但依赖Gradio的内部接口，可能不够稳定，功能也受限于Gradio。

4.2 方案二：编写FastAPI包装层（推荐用于生产）

我们创建一个新的、更健壮的FastAPI应用，它内部调用Qwen3-TTS模型，对外提供标准的RESTful API。

  1. 创建项目结构： 在宿主机上（而不是容器内）创建我们的API服务代码。

    cd ~/qwen-tts-service
mkdir api-wrapper && cd api-wrapper

  2. 编写 requirements.txt：

    fastapi==0.104.1
uvicorn[standard]==0.24.0
pydantic==2.5.0
python-multipart==0.0.6
requests==2.31.0
soundfile==0.12.1
# 注意：qwen-tts等深度学习依赖已在基础镜像中，此处无需重复指定

  3. 编写核心API服务代码 main.py：

    from fastapi import FastAPI, HTTPException, BackgroundTasks
from fastapi.responses import FileResponse
from pydantic import BaseModel
from typing import Optional
import torch
import soundfile as sf
import tempfile
import os
import time
import logging
import sys

# 假设模型已安装在环境中，我们直接导入
# 注意：这里需要根据实际镜像中的模型加载方式调整
# 例如，可能不是 `qwen_tts` 而是其他包名
# from qwen_tts import Qwen3TTSModel # 示例导入

# 设置日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[logging.StreamHandler(sys.stdout)]
)
logger = logging.getLogger(__name__)

app = FastAPI(
    title="Qwen3-TTS API Service",
    description="基于Qwen3-TTS-12Hz-1.7B-CustomVoice的语音合成Web API",
    version="1.0.0"
)

# 定义请求数据模型
class TTSRequest(BaseModel):
    text: str
    language: str = "Chinese"
    speaker: str = "Vivian"
    instruction: Optional[str] = "用自然、清晰的语气说话"
    speed: Optional[float] = 1.0  # 语速控制

# 全局模型实例（在实际中，需要正确初始化）
# model = None
# 由于我们使用预置镜像，这里模拟一个健康的服务状态
# 实际部署时，你需要在此处加载模型，或调用镜像内已运行的服务

@app.on_event("startup")
async def startup_event():
    """服务启动时，可以在这里初始化模型（如果直接集成）"""
    logger.info("Starting Qwen3-TTS API Service...")
    # 实际加载模型的代码（如果模型和API在同一容器）
    # try:
    #     global model
    #     model = Qwen3TTSModel.from_pretrained(...)
    #     logger.info("Model loaded successfully.")
    # except Exception as e:
    #     logger.error(f"Failed to load model: {e}")
    #     raise
    pass

@app.get("/")
async def root():
    """健康检查端点"""
    return {
        "status": "healthy",
        "service": "Qwen3-TTS API",
        "model": "Qwen3-TTS-12Hz-1.7B-CustomVoice"
    }

@app.get("/speakers")
async def list_speakers():
    """获取支持的说话人列表"""
    speakers = [
        {"id": "Vivian", "lang": "zh", "description": "明亮、略带锋芒的年轻女声"},
        {"id": "Serena", "lang": "zh", "description": "温暖、柔和的年轻女声"},
        {"id": "Uncle_Fu", "lang": "zh", "description": "沉稳的男性声音，音色低沉圆润"},
        {"id": "Dylan", "lang": "zh-BJ", "description": "北京青年男声，音色清晰自然"},
        {"id": "Eric", "lang": "zh-SC", "description": "活泼的成都男声，声音略带沙哑"},
        {"id": "Ryan", "lang": "en", "description": "节奏感强的动态男声"},
        {"id": "Aiden", "lang": "en", "description": "阳光美式男声，中频清晰"},
        {"id": "Ono_Anna", "lang": "ja", "description": "可爱的日语女声，音色轻快灵动"},
        {"id": "Sohee", "lang": "ko", "description": "温暖的韩语女声，情感丰富"},
    ]
    return {"speakers": speakers}

@app.post("/generate")
async def generate_speech(request: TTSRequest, background_tasks: BackgroundTasks):
    """
    生成语音文件。
    注意：这是一个示例端点。在实际部署中，你需要：
    1. 在此处调用已运行的Gradio服务的内部API（方案一包装）。
    2. 或者，直接在此进程中加载并运行模型（需确保环境一致）。
    本例为演示结构，返回一个模拟的成功响应。
    实际集成时，请替换下方的 `# TODO` 部分。
    """
    logger.info(f"Received TTS request: lang={request.language}, speaker={request.speaker}, text_len={len(request.text)}")

    # TODO: 实际生成逻辑
    # 方案A：调用本地已启动的Gradio服务API (http://localhost:7860/run/predict)
    # import requests
    # gradio_url = "http://localhost:7860/run/predict"
    # payload = {
    #     "data": [
    #         request.text,
    #         request.language,
    #         request.speaker,
    #         request.instruction
    #     ]
    # }
    # response = requests.post(gradio_url, json=payload)
    # audio_data = response.content
    # sr = 24000 # 假设采样率

    # 方案B：直接使用加载的model对象
    # if model is None:
    #     raise HTTPException(status_code=503, detail="Model not loaded")
    # wavs, sr = model.generate_custom_voice(
    #     text=request.text,
    #     language=request.language,
    #     speaker=request.speaker,
    #     instruct=request.instruction
    # )
    # audio_data = wavs[0]

    # --- 模拟成功响应（实际使用时请删除）---
    # 创建一个临时的静音WAV文件作为示例
    import numpy as np
    sr = 24000
    duration = 2.0  # 2秒静音
    audio_data = np.zeros(int(sr * duration), dtype=np.float32)
    # --- 模拟结束 ---

    # 将音频数据保存为临时文件
    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp_file:
        tmp_path = tmp_file.name
        sf.write(tmp_path, audio_data, sr)
        logger.info(f"Audio saved to temporary file: {tmp_path}")

    # 设置后台任务，响应发送后删除临时文件
    def cleanup_temp_file(path: str):
        if os.path.exists(path):
            os.unlink(path)
            logger.info(f"Cleaned up temp file: {path}")

    background_tasks.add_task(cleanup_temp_file, tmp_path)

    # 返回音频文件
    return FileResponse(
        path=tmp_path,
        media_type="audio/wav",
        filename=f"tts_{int(time.time())}.wav"
    )

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

  4. 编写Dockerfile构建API服务镜像： 创建一个新的Dockerfile，基于包含Qwen3-TTS模型和运行时的轻量级Python镜像。

    # 使用一个包含PyTorch和CUDA的基础镜像
FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime

WORKDIR /app

# 复制依赖文件并安装
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 复制应用代码
COPY main.py .

# 暴露端口（FastAPI服务端口）
EXPOSE 8000

# 启动命令
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

  5. 构建并运行API服务容器：

    cd ~/qwen-tts-service/api-wrapper
docker build -t qwen-tts-api .
docker run -d \
  --name qwen-tts-api-service \
  --gpus all \
  --network host \ # 与gradio容器在同一主机，使用host网络便于通信
  -p 8000:8000 \
  --restart unless-stopped \
  qwen-tts-api

    现在，你的专属TTS API服务就在 http://你的服务器IP:8000 运行了。访问 http://你的服务器IP:8000/docs 可以看到自动生成的交互式API文档。

5. 进阶配置与优化

服务跑起来了，但要用于生产，还需要一些“加固”工作。

5.1 使用Nginx作为反向代理和网关

直接暴露Python应用端口（如8000）不太安全，性能也有限。使用Nginx作为反向代理是标准做法。

  1. 安装Nginx：

    sudo apt install -y nginx

  2. 配置Nginx站点： 创建配置文件 /etc/nginx/sites-available/qwen-tts：

    server {
    listen 80;
    server_name your-domain.com; # 替换为你的域名或IP

    # 静态文件服务（如果需要）
    # location /static/ {
    #     alias /path/to/your/static/files;
    # }

    location / {
        # 反向代理到FastAPI服务
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 超时设置（TTS生成可能需要时间）
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
        send_timeout 300s;

        # 禁用缓冲，适合流式响应（如果未来支持）
        # proxy_buffering off;
    }

    # 可选：添加基础认证或限流
    # limit_req_zone $binary_remote_addr zone=ttslimit:10m rate=1r/s;
    # location /generate {
    #     limit_req zone=ttslimit burst=5 nodelay;
    #     proxy_pass http://127.0.0.1:8000;
    # }
}

  3. 启用配置并重启Nginx：

    sudo ln -s /etc/nginx/sites-available/qwen-tts /etc/nginx/sites-enabled/
sudo nginx -t # 测试配置语法
sudo systemctl reload nginx

    现在，可以通过 http://your-domain.com 访问你的API了，并且由Nginx处理负载、SSL（下一步）和静态文件。

5.2 使用Supervisor管理进程（替代Docker内部管理）

虽然Docker有--restart策略，但使用Supervisor可以更精细地管理进程（比如管理日志轮转、崩溃后更快的重启等）。我们可以在宿主机上使用Supervisor来管理Docker容器，或者在API服务的Docker容器内使用Supervisor管理多个进程（如FastAPI和某个监控脚本）。

  1. 安装Supervisor：

    sudo apt install -y supervisor

  2. 创建配置文件 /etc/supervisor/conf.d/qwen-tts-api.conf：

    [program:qwen-tts-api]
command=docker run --rm --gpus all --name qwen-tts-api -p 8000:8000 qwen-tts-api
directory=/home/your-user/qwen-tts-service/api-wrapper
autostart=true
autorestart=true
startretries=3
user=your-user
stdout_logfile=/var/log/supervisor/qwen-tts-api.out.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=5
stderr_logfile=/var/log/supervisor/qwen-tts-api.err.log
stderr_logfile_maxbytes=10MB
stderr_logfile_backups=5
environment=HOME="/home/your-user",USER="your-user"

    这个配置告诉Supervisor去运行一个Docker命令来启动我们的服务。

  3. 更新Supervisor并启动服务：

    sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start qwen-tts-api
sudo supervisorctl status qwen-tts-api # 查看状态

5.3 添加API密钥认证（基础安全）

为/generate这样的核心端点添加简单的API密钥认证。

修改 main.py 中的 /generate 端点：

from fastapi import Depends, HTTPException, Header
import secrets

# 模拟一个有效的API密钥存储（生产环境应使用环境变量或配置中心）
VALID_API_KEYS = {"your-super-secret-api-key-123456"}

async def verify_api_key(x_api_key: str = Header(None, alias="X-API-Key")):
    if x_api_key not in VALID_API_KEYS:
        raise HTTPException(status_code=403, detail="Invalid or missing API Key")
    return x_api_key

@app.post("/generate")
async def generate_speech(
    request: TTSRequest,
    background_tasks: BackgroundTasks,
    api_key: str = Depends(verify_api_key)  # 添加依赖项
):
    # ... 原有的生成逻辑 ...

现在，调用/generate接口时，必须在请求头中携带 X-API-Key: your-super-secret-api-key-123456。

6. 总结

回顾一下，我们从零开始，完成了一个企业级TTS语音合成API服务的搭建：

  1. 环境准备：在Ubuntu服务器上配置了Docker和GPU支持，为容器化部署铺平道路。
  2. 一键启动：利用预置的Docker镜像，快速启动了一个包含Web UI的Qwen3-TTS服务，直观验证了模型效果。
  3. 服务封装：编写了基于FastAPI的专属Web API，提供了更规范、更易集成的RESTful接口，并考虑了文件清理等细节。
  4. 生产加固：通过Nginx实现反向代理、负载均衡和SSL终结，提升了服务的性能、安全性和可访问性。使用Supervisor增强了进程管理的可靠性。添加了基础的API密钥认证。

现在，你的应用程序只需要向 https://your-domain.com/generate 发送一个携带正确API密钥的POST请求，就能获得高质量的合成语音。无论是集成到客服系统、内容创作平台，还是智能硬件中，都变得轻而易举。

这个方案的优势在于兼顾了便捷性与专业性：预置镜像让你快速上手和验证，而自定义的API层和运维配置又确保了服务能满足生产环境的要求。你可以根据实际流量，轻松地水平扩展容器实例，或者升级服务器配置。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

Logo
乐奇 Rokid 开放社区

更多推荐

cover

【应用方案】智能眼镜一站式解决方案：交互与感知技术赋能下一代穿戴体验

avatar 乐奇 Rokid 开放社区
cover

全球 AI / 科技简报｜2026 年 9 月 4 日

avatar 乐奇 Rokid 开放社区

朱老师教你玩转 AIUI 开源项目 — 上传到 GitHub 即刻参与开源协作

如果说 AIUI Sports Agents 适合用来学习“运动数据、设备验证和平台提审如何分工”，EverMind 则是另一个很适合新手观察的开源案例：它把长期记忆框架、命令行工具、Agent 插件和公开文档拆成清晰的模块，让读者能够沿着 README、Quick Start、架构说明和贡献指南逐层理解一个项目。检查与收束读第八章。填写项目问卷时，进入 Issues → New issue，选择

avatar 乐奇 Rokid 开放社区