简介:本文面向无独立显卡或显存不足的环境,介绍在CPU上部署轻量语音合成服务的完整方法。内容涵盖版本选型、INT8量化、HTTP接口与流式返回、十秒样本零样本克隆,并给出接口示例、错误码、基线测试和故障排查方法。读者可以用较低成本搭建可被业务系统调用的本地语音服务。
读完本文,你可以在一台4核CPU、8GB内存的机器上运行一个语音合成服务,通过HTTP接口生成WAV或流式PCM音频,并用约10秒的干净样本完成声音克隆。本文的服务代码与接口定义是完整可用的,模型推理部分需要按你选定的模型实现,具体模型名称与版本以所选项目的仓库说明为准。
适用人群包括开发者、运维人员和技术负责人。本文假设你熟悉Linux命令行、Python虚拟环境和HTTP请求。
选型应先看业务需求,再看机器条件。下表中的内存和磁盘数值是估算值,实际占用需在目标机器上复测。
| 维度 | 轻量版(约0.1B参数,INT8) | 质量版(约0.6B参数,FP16或FP32) |
|---|---|---|
| 典型场景 | 内部工具、批量短视频配音、交互式低延迟播报 | 数字人、宣传片、多语言长文本配音 |
| 权重体积估算 | 约0.1GB | 约1.2GB(FP16)至2.4GB(FP32) |
| 推理内存估算 | 不低于2GB | 不低于6GB,建议16GB |
| 磁盘占用 | 不低于2GB | 不低于5GB |
| CPU指令集 | 建议支持AVX2 | 建议支持AVX2,AVX-512更佳 |
| 语言覆盖 | 中英文 | 以所选仓库声明为准 |
| 许可证 | 下载前逐项核对 | 下载前逐项核对 |
判断标准很简单。若单机并发较低且首包延迟敏感,选轻量版。若音质权重高于延迟,并且内存足够,选质量版。
先确认机器满足条件:
lscpu | grep -i avx2 # 应有输出free -h # 可用内存建议不低于8GBdf -h /opt # 剩余空间建议不低于10GBpython3 --version # 建议3.10至3.12
创建运行账号和目录。服务以非特权账号运行,模型、样本、输出、日志和缓存分开存放:
sudo useradd --system --home /opt/tts --shell /usr/sbin/nologin ttsrunnersudo mkdir -p /opt/tts/{app,models,config,voices,output,logs,cache}sudo chown -R ttsrunner:ttsrunner /opt/ttssudo chmod 750 /opt/tts/config /opt/tts/voices
创建虚拟环境并安装固定版本依赖:
sudo -u ttsrunner python3 -m venv /opt/tts/venvsudo -u ttsrunner /opt/tts/venv/bin/pip install \onnxruntime==1.19.2 fastapi==0.115.0 uvicorn==0.30.6 \soundfile==0.12.1 numpy==1.26.4 pydantic==2.9.2
从模型官方仓库下载权重和配置。仓库地址和文件名以项目README为准。下载后保存校验文件并核对哈希:
sudo -u ttsrunner /opt/tts/venv/bin/pip install -U "huggingface_hub[cli]==0.25.2"sudo -u ttsrunner huggingface-cli download <组织名>/<模型仓库名> \--local-dir /opt/tts/models/tts-light-int8cd /opt/tts/models/tts-light-int8sha256sum -c SHA256SUMS
SHA256SUMS 应来自官方仓库。若仓库未提供校验文件,请自行计算哈希并保存在变更记录中。同时把许可证文件复制到 /opt/tts/models/tts-light-int8/LICENSE_COPY,便于审计。
服务使用一个JSON配置文件,路径为 /opt/tts/config/server.json:
{"model_dir": "/opt/tts/models/tts-light-int8","precision": "int8","threads": 3,"sample_rate": 24000,"max_chars_per_request": 300,"max_concurrency": 1,"queue_size": 8,"request_timeout_s": 30,"max_upload_mb": 5,"voice_dir": "/opt/tts/voices","output_dir": "/opt/tts/output","cache_dir": "/opt/tts/cache","cache_max_mb": 512,"log_path": "/opt/tts/logs/tts.log","token_env": "TTS_API_TOKEN","bind_host": "127.0.0.1","bind_port": 8080}
字段说明如下:
threads:推理线程数。4核机器设为3,为HTTP层和系统进程留出一个核心。max_chars_per_request:单次文本上限。超过后返回400,调用方需要按句切分。max_concurrency:同时执行推理的任务数。CPU推理通常设为1,避免线程争抢。queue_size:排队等待的请求数。超过后返回429。request_timeout_s:等待执行槽位的最长时间。超过后返回504。max_upload_mb:克隆样本的大小上限。token_env:保存访问令牌的环境变量名,令牌不写入配置文件。令牌文件 /opt/tts/config/env 只允许服务账号读取:
python3 -c "import secrets;print(secrets.token_urlsafe(32))"# 将输出写入 /opt/tts/config/env,格式为 TTS_API_TOKEN=<输出值>sudo chown ttsrunner:ttsrunner /opt/tts/config/envsudo chmod 600 /opt/tts/config/env
服务代码放在 /opt/tts/app/。app/__init__.py 保持为空文件即可。app/engine.py 负责封装所选模型,需要实现以下接口:
Engine(model_dir, precision, threads):加载权重。synthesize(text, voice, speed) -> np.ndarray:返回单声道float32数组,采样率为24000Hz。stream(text, voice, speed):逐段生成,每次产出一段float32数组。clone(wav_path, speaker_id):从样本提取音色并保存。forget(speaker_id):删除该音色的缓存特征。主入口 app/main.py 如下:
import asyncio, hmac, io, json, os, re, uuidimport numpy as npimport soundfile as sffrom fastapi import FastAPI, File, Form, Header, UploadFilefrom fastapi.responses import JSONResponse, Response, StreamingResponsefrom pydantic import BaseModel, Fieldfrom app.engine import Enginecfg = json.load(open(os.environ.get("TTS_CONFIG", "/opt/tts/config/server.json"), encoding="utf-8"))TOKEN = os.environ[cfg["token_env"]]NAME_RE = re.compile(r"^[a-z0-9_]{3,32}$")app = FastAPI()engine = Noneslots = asyncio.Semaphore(cfg["max_concurrency"])waiting = 0class ApiError(Exception):def __init__(self, status, code, message):self.status, self.code, self.message = status, code, message@app.exception_handler(ApiError)async def api_error(request, exc: ApiError):return JSONResponse(status_code=exc.status, content={"error": {"code": exc.code, "message": exc.message, "request_id": uuid.uuid4().hex}})def check_auth(authorization):if not hmac.compare_digest(authorization or "", f"Bearer {TOKEN}"):raise ApiError(401, "UNAUTHORIZED", "missing or invalid bearer token")def voice_path(name):if not NAME_RE.match(name):raise ApiError(400, "INVALID_VOICE_NAME", "voice name must match [a-z0-9_]{3,32}")path = os.path.join(cfg["voice_dir"], f"{name}.wav")if not os.path.exists(path):raise ApiError(404, "VOICE_NOT_FOUND", f"voice {name} does not exist")return path@app.on_event("startup")def load_model():global engineengine = Engine(cfg["model_dir"], cfg["precision"], cfg["threads"])engine.synthesize("预热", "default", 1.0) # warm-up to avoid cold-start latency@app.get("/v1/health")def health():return {"status": "ok", "model": os.path.basename(cfg["model_dir"]),"precision": cfg["precision"], "queue_depth": waiting}class TtsReq(BaseModel):text: str = Field(min_length=1)voice: str = "default"speed: float = Field(1.0, ge=0.5, le=2.0)stream: bool = False@app.post("/v1/tts")async def tts(req: TtsReq, authorization: str | None = Header(None)):global waitingcheck_auth(authorization)if len(req.text) > cfg["max_chars_per_request"]:raise ApiError(400, "TEXT_TOO_LONG", f"text exceeds {cfg['max_chars_per_request']} chars")if req.voice != "default":voice_path(req.voice)if waiting >= cfg["queue_size"]:raise ApiError(429, "QUEUE_FULL", "too many queued requests, retry later")waiting += 1try:await asyncio.wait_for(slots.acquire(), timeout=cfg["request_timeout_s"])except asyncio.TimeoutError:raise ApiError(504, "TIMEOUT", "waited too long for a worker slot")finally:waiting -= 1if req.stream:async def gen():it = engine.stream(req.text, req.voice, req.speed)try:while True:chunk = await asyncio.to_thread(next, it, None)if chunk is None:breakyield (np.clip(chunk, -1, 1) * 32767).astype("<i2").tobytes()finally:slots.release()return StreamingResponse(gen(), media_type="application/octet-stream", headers={"X-Audio-Format": f"pcm_s16le; rate={cfg['sample_rate']}; channels=1"})try:wav = await asyncio.to_thread(engine.synthesize, req.text, req.voice, req.speed)except Exception:raise ApiError(500, "INFERENCE_FAILED", "synthesis failed, check server log")finally:slots.release()buf = io.BytesIO()sf.write(buf, wav, cfg["sample_rate"], format="WAV", subtype="PCM_16")return Response(buf.getvalue(), media_type="audio/wav")@app.post("/v1/clone")async def clone(speaker_id: str = Form(...), consent_ref: str = Form(...),file: UploadFile = File(...), authorization: str | None = Header(None)):check_auth(authorization)if not NAME_RE.match(speaker_id):raise ApiError(400, "INVALID_VOICE_NAME", "speaker_id must match [a-z0-9_]{3,32}")if file.content_type not in ("audio/wav", "audio/x-wav"):raise ApiError(415, "UNSUPPORTED_MEDIA_TYPE", "upload a WAV file")data = await file.read()if len(data) > cfg["max_upload_mb"] * 1024 * 1024:raise ApiError(413, "SAMPLE_TOO_LARGE", f"sample exceeds {cfg['max_upload_mb']} MB")path = os.path.join(cfg["voice_dir"], f"{speaker_id}.wav")with open(path, "wb") as f:f.write(data)try:await asyncio.to_thread(engine.clone, path, speaker_id)except Exception:os.remove(path)raise ApiError(500, "CLONE_FAILED", "clone failed, check sample and server log")return {"speaker_id": speaker_id, "consent_ref": consent_ref, "status": "created"}@app.delete("/v1/voices/{speaker_id}")def delete_voice(speaker_id: str, authorization: str | None = Header(None)):check_auth(authorization)path = voice_path(speaker_id)os.remove(path)engine.forget(speaker_id)return {"speaker_id": speaker_id, "status": "deleted"}
几个实现要点需要说明:
../ 之类的输入可能读写目录外的文件。hmac.compare_digest,避免字符串比较泄露时序信息。用systemd管理服务。创建 /etc/systemd/system/tts.service:
[Unit]Description=CPU TTS serviceAfter=network.target[Service]User=ttsrunnerWorkingDirectory=/opt/ttsEnvironmentFile=/opt/tts/config/envEnvironment=TTS_CONFIG=/opt/tts/config/server.jsonExecStart=/opt/tts/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8080 --workers 1Restart=on-failureNoNewPrivileges=yesProtectSystem=strictReadWritePaths=/opt/tts/output /opt/tts/voices /opt/tts/cache /opt/tts/logs[Install]WantedBy=multi-user.target
启动并查看日志:
sudo systemctl daemon-reloadsudo systemctl enable --now ttsjournalctl -u tts -n 50 --no-pager
调用示例。将令牌读入环境变量后执行:
```bash
export TTS_API_TOKEN=$(sudo grep TTS_API_TOKEN /opt/tts/config/env | cut -d= -f2)
curl -sS http://127.0.0.1:8080/v1/health
curl -sS -X POST http://127.0.0.1:8080/v1/tts \
-H “Authorization: Bearer $TTS_API_TOKEN” -H “Content-Type: