本地TTS服务器：兼容OpenAI与ElevenLabs API的私有化语音合成方案

1. 项目概述一个兼容两大主流API的本地TTS服务器如果你正在折腾一个需要语音交互的AI项目比如一个本地的聊天机器人那么“让AI开口说话”这个环节大概率会让你头疼。要么依赖OpenAI、ElevenLabs这些云端服务不仅产生费用延迟和隐私也是问题要么去研究各种本地TTS模型发现配置复杂、API不通用很难和你现有的项目无缝集成。今天要聊的这个项目ndrco/silero_openai_tts就是为了解决这个痛点而生的。它是一个本地自托管的文本转语音服务器核心卖点就一个同时实现了OpenAI TTS API和ElevenLabs兼容API。这意味着任何原本设计用来调用OpenAI或ElevenLabs语音服务的客户端几乎不用修改只需要把请求地址指向你这个本地服务器就能获得高质量的本地语音合成能力。这个项目最初是为 OpenClaw 这个开源聊天机器人项目量身打造的目的是让OpenClaw能“开口说话”且完全脱离对任何云服务的依赖。但它的设计非常通用只要你手头有任何期望调用POST /v1/audio/speech(OpenAI风格) 或POST /v1/text-to-speech/{voice_id}(ElevenLabs风格) 接口的应用它都能充当一个完美的“替身”后端。它的技术底子是Silero TTS这是一个在俄语和英语上表现非常出色的开源语音合成模型通过PyTorch的torch.hub加载第一次运行时会自动下载。项目在此基础上包装了一层完整的、符合行业标准的HTTP API并加入了针对俄语和英语的文本预处理比如智能读数字、处理货币符号让你用起来的感觉和付费的云服务几乎无差但所有数据都在你自己的机器上处理。1.1 核心优势与适用场景为什么你需要关注这个项目我总结了几点它在实际应用中的独特价值第一资源分离物尽其用。很多朋友在本地部署AI应用时GPU资源是非常宝贵的通常要优先留给大语言模型推理。这个TTS服务器默认运行在CPU上而且经过优化合成速度很快。这样你就可以把计算密集型的LLM放在GPU上把TTS任务卸载到CPU实现硬件资源的最优分配。实测下来在普通的CPU上合成一句中等长度的句子延迟通常在几百毫秒到一秒左右对于对话交互来说完全可接受。第二开箱即用的API兼容性。这是它最大的便利之处。你不用去学习Silero模型那套原始的、较为底层的调用方式。如果你有一个现成的项目里面写死了调用api.openai.com/v1/audio/speech你只需要在配置里把base_url改成http://localhost:8000它就能立刻工作。这种“即插即用”的特性极大地降低了集成成本。第三内置的服务器端自动播放。这个功能对于像OpenClaw这样的桌面应用尤其有用。项目作者提到OpenClaw内置的浏览器端自动播放不稳定。而这个TTS服务器可以配置为合成语音后直接在服务器所在的电脑上通过扬声器播放出来。这对于打造一个能和你“对话”的桌面助手来说体验非常直接和稳定。第四对俄语和英语的深度优化。不仅仅是简单的语音合成它内置的文本规范化管道能智能处理数字。比如输入“我有21块钱”它会正确地合成为“我有二十一块钱”而不是“二一”。对于俄语它还能根据数字调整后面名词的格让语音听起来更自然。这种细节处理是一般TTS系统所欠缺的。适合谁来用我认为这几类开发者会特别受益OpenClaw用户这是最直接的受益者完美解决其语音输出问题。任何使用OpenAI API兼容框架的开发者比如在使用openaiPython库、langchain等框架时想本地化TTS功能。需要私有化部署的AI应用开发者对数据隐私有要求所有语音数据不能出本地。多语言俄/英内容创作者或开发者需要高质量的本地语音合成来生成视频配音、有声内容等。2. 核心功能与架构设计解析这个项目虽然核心是调用Silero模型但其工程化设计思路非常清晰值得拆开细说。它不是一个简单的模型调用脚本而是一个具备生产级应用雏形的服务。2.1 双API兼容层如何做到“鱼与熊掌兼得”项目最巧妙的设计在于其API路由层。它使用FastAPI从uvicorn的启动命令可以看出构建了Web服务并同时挂载了两套路由OpenAI兼容路由核心端点是POST /v1/audio/speech。它严格遵循了OpenAI官方TTS API的请求和响应格式。你发送一个JSON包含model,input,voice,response_format,speed字段它就会返回一个音频文件。尽管model字段在这里被忽略因为底层只用Silero但保留它确保了最大程度的兼容性。任何按照OpenAI文档编写的客户端代码都能直接运行。ElevenLabs兼容路由可选通过环境变量ENABLE_ELEVENLABS_COMPATtrue开启。它会额外暴露几个端点GET /v1/voices获取可用声音列表、GET /v1/models获取模型列表、POST /v1/text-to-speech/{voice_id}及其流式版本。这对于那些使用了ElevenLabs SDK或类似接口的应用来说迁移成本几乎为零。实现原理这两套API在底层共享同一个合成引擎。当请求进来时路由层会解析参数进行统一的标准化处理比如将ElevenLabs的voice_id映射到内部的Silero speaker ID将output_format映射到response_format然后交给核心的Silero合成模块。合成完成后再根据请求的格式通过FFmpeg编码成对应的音频格式MP3、WAV等返回。这种设计避免了代码重复也保证了无论从哪个接口调用最终的语音质量都是一致的。注意ElevenLabs的API设计更复杂支持更多参数如稳定性、相似度增强等。本项目目前实现的是一个“最小兼容子集”主要目的是让客户端能连上并工作。如果你需要ElevenLabs的全部高级功能可能需要在此基础上进行扩展。2.2 文本预处理管道让数字和符号“会说话”一个成熟的TTS系统绝不能直接把用户输入的文本扔给模型。原始文本中的数字、符号、缩写等如果直接读出来会非常生硬比如“2024年”读成“二零二四年”而不是“两千零二十四年”“21%”读成“二一百分号”。这个项目内置了一个针对俄语和英语的文本规范化管道主要做了以下几件事数字转写自动识别文本中的整数并将其扩展为对应的单词。例如“I have 3 apples” 中的 “3” 会被预处理为 “three”。货币与百分比处理识别 “$”, “€”, “₽”, “%” 等符号并将其转换为可读的单词如 “percent”, “ruble”。俄语语法协调这是针对俄语的特有优化。俄语中名词的格需要根据前面的数字发生变化。例如“1 рубль”, “2 рубля”, “5 рублей”。这个预处理模块会尝试分析数字后的名词并对其进行正确的变格使得合成出的语音符合俄语语法习惯听起来非常自然。实操心得这个预处理模块是基于规则和正则表达式的虽然对于常见情况处理得很好但面对复杂的日期、时间、分数或专业缩写时可能力有不逮。如果你的应用场景涉及大量特殊格式文本可能需要扩展这个normalizer.py模块。一个简单的思路是引入更强大的文本规范化库或者针对你的领域添加自定义规则。2.3 语音映射与多格式输出语音映射OpenAI TTS API预定义了如alloy,echo,nova等几种声音。本项目内部维护了一个映射表将这些名字对应到Silero模型的不同说话人ID上例如alloy-baya(一个俄语女声)。你也可以绕过映射直接在voice字段传入Silero原生的说话人ID如aidar(俄语男声)、kseniya(俄语女声) 等。这给了用户更大的灵活性。多格式输出得益于FFmpeg的强大能力服务器支持输出wav、mp3、opus、aac、flac等多种音频格式。这在集成时非常方便你可以根据客户端的需求或存储空间的考虑来选择格式。例如网络传输可能选择更小的opus而本地存档可能选择无损的wav或flac。语速控制通过speed参数范围0.25到4.0你可以调整语音的播放速度。这个功能同样是借助FFmpeg的atempo音频过滤器实现的。服务器在生成原始WAV音频后会调用FFmpeg进行变速处理然后编码成目标格式。这比在模型层面调整语速要简单和稳定得多。3. 从零开始的完整部署与配置指南纸上得来终觉浅绝知此事要躬行。下面我将带你一步步把这个TTS服务器跑起来并集成到一个示例应用中。我会以LinuxUbuntu环境为主进行说明Windows下的关键差异也会指出。3.1 系统环境与依赖准备首先确保你的系统已经安装了Python 3.10或更高版本。这个项目强依赖两个系统工具FFmpeg和libsndfile。FFmpeg负责音频格式转码和语速控制。没有它除了WAV以外的格式和变速功能都无法使用。libsndfile一个用于读写音频文件尤其是WAV格式的C库PyTorch的某些音频后端或Silero模型本身可能会用到它来加载/保存WAV文件。在Ubuntu/Debian系统上安装依赖sudo apt update sudo apt install -y ffmpeg libsndfile1安装完成后运行ffmpeg -version确认安装成功。在Windows系统上安装依赖Python从官网下载安装Python 3.10安装时务必勾选 “Add Python to PATH”。FFmpeg推荐使用winget安装这是Windows自带的包管理器。winget install Gyan.FFmpeg安装后重启终端或新开一个PowerShell窗口运行ffmpeg -version检查。libsndfile对于Windows通常通过Python包soundfile的安装会自动处理。如果后续运行出错提示缺少libsndfile可以手动从 官方页面 下载DLL并放置到系统路径或Python的DLL搜索目录下。3.2 获取项目与创建Python虚拟环境使用Git克隆项目代码并创建一个独立的Python虚拟环境这是管理项目依赖的最佳实践可以避免污染系统级的Python包。# 克隆代码仓库 git clone https://github.com/ndrco/silero_openai_tts.git cd silero_openai_tts # 创建虚拟环境Linux/macOS python -m venv .venv # 激活虚拟环境 source .venv/bin/activate # 升级pip并安装项目依赖-e 表示以可编辑模式安装方便开发 pip install -U pip pip install -e .Windows PowerShell下的操作# 克隆代码仓库 git clone https://github.com/ndrco/silero_openai_tts.git cd silero_openai_tts # 创建虚拟环境 python -m venv .venv # 激活虚拟环境 .\.venv\Scripts\Activate.ps1 # 如果提示脚本执行策略禁止先运行一次仅需一次 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser # 安装依赖 python -m pip install -U pip python -m pip install -e .3.3 配置文件与环境变量详解项目使用.env文件来管理配置。首先复制示例文件cp .env.example .env然后用文本编辑器打开.env文件。下面我挑几个关键配置项详细解释# .env 文件示例 HOST0.0.0.0 PORT8000 # Silero 模型配置 SILERO_LANGUAGEru SILERO_MODEL_IDv5_1_ru SILERO_SAMPLE_RATE48000 SILERO_DEVICEcpu SILERO_NUM_THREADS0 SILERO_DEFAULT_SPEAKERkseniya # 认证 REQUIRE_AUTHfalse API_KEYdummy-local-key # 缓存 CACHE_DIR.cache_tts CACHE_MAX_FILES2000 # 音频播放 AUTO_PLAYfalse FFPLAY_BINffplay AUTO_PLAY_SHOW_SKIP_WINDOWtrue # ElevenLabs 兼容模式 ENABLE_ELEVENLABS_COMPATfalse ELEVENLABS_REQUIRE_XI_API_KEYtrueSILERO_LANGUAGE和SILERO_MODEL_ID这决定了你使用哪种语言的语音模型。ru对应俄语en对应英语。v5_1_ru是俄语的最新V5.1版本模型效果和稳定性最好。如果你是英语用户可以设置为SILERO_LANGUAGEen和SILERO_MODEL_IDv4_en。SILERO_DEVICE默认为cpu。如果你有NVIDIA GPU并安装了CUDA版本的PyTorch可以设置为cuda以加速推理。但根据项目初衷CPU通常已足够快且能节省GPU资源给LLM。SILERO_NUM_THREADSPyTorch的推理线程数。0表示自动选择。如果你的CPU核心多可以尝试设置为物理核心数可能有助于提升性能。REQUIRE_AUTH如果设置为true那么所有API请求都必须携带Authorization: Bearer API_KEY头。这对于将服务暴露在局域网或公网非常不推荐公网直接暴露时增加一层简单的安全防护很有用。API_KEY就是你自己设定的密钥。AUTO_PLAY这是服务器端自动播放功能。设置为true后每次成功合成语音服务器会调用ffplay在本地声卡上直接播放出来。这对于桌面助手场景非常方便。ENABLE_ELEVENLABS_COMPAT按需开启。如果你有需要调用ElevenLabs API的客户端就把它打开。3.4 启动服务器与基础测试配置好.env后就可以启动服务器了。你有几种启动方式方式一使用uvicorn直接启动推荐便于调试uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload--reload参数使得在修改代码后服务器会自动重启适合开发阶段。方式二使用安装后生成的命令行工具由于我们用了pip install -e .项目安装了一个叫silero-tts的命令行工具。# 直接运行使用 .env 中的配置 silero-tts # 带参数运行覆盖部分配置 silero-tts --host 127.0.0.1 --port 8080 --force-play--force-play参数会强制开启服务器端播放并同时在控制台打印合成的文本。首次运行启动后你会看到控制台开始下载Silero模型文件几百MB大小。下载完成后服务就就绪了。基础功能测试打开另一个终端用curl测试一下核心的OpenAI兼容API。curl http://localhost:8000/v1/audio/speech \ -H Content-Type: application/json \ -d { model: tts-1, input: Привет, мир! Это тест русского синтеза речи., voice: alloy, response_format: mp3, speed: 1.0 } \ --output test.mp3如果一切正常当前目录下会生成一个test.mp3文件播放它就能听到合成的俄语语音。把input换成英文句子同样可以测试。4. 高级集成与实战应用服务器跑起来只是第一步如何把它用起来才是关键。下面我将以两个典型场景为例展示如何将其集成到现有项目中。4.1 场景一为OpenClaw聊天机器人注入语音这是本项目诞生的初衷集成也最为简单。OpenClaw的配置文件中需要指定TTS服务的地址。启动TTS服务器确保silero_openai_tts服务在本地运行例如在http://127.0.0.1:8000。配置OpenClaw找到OpenClaw的配置文件通常是~/.openclaw/openclaw.json在env和messages.tts部分进行如下配置{ env: { // 关键将OpenAI TTS的基础URL指向你的本地服务器 OPENAI_TTS_BASE_URL: http://127.0.0.1:8000/v1, // 如果TTS服务器开启了认证这里填你的API_KEY否则填任意值如dummy-local-key OPENAI_API_KEY: dummy-local-key }, messages: { ackReactionScope: group-mentions, tts: { // 指定使用openai作为TTS提供商 provider: openai, // 自动播放模式always总是、never从不、mention被提及时 auto: always, // 语音模式final最终回复时、streaming流式回复时 mode: final, openai: { // 选择默认语音对应silero的映射 voice: alloy }, // 禁用其他TTS提供商如Edge TTS edge: { enabled: false } } } }重启OpenClaw保存配置后重启OpenClaw应用。现在每当OpenClaw生成一条文本回复它就会向你的本地TTS服务器发送请求获取语音音频并在客户端播放。由于网络是本地回路延迟极低体验会非常流畅。实操心得在配置OPENAI_TTS_BASE_URL时结尾的/v1非常重要因为OpenAI的客户端库通常会在你设置的base_url后面拼接具体的端点路径如/audio/speech。所以完整的请求URL应该是base_url /audio/speech。如果你设置成http://127.0.0.1:8000客户端可能会请求http://127.0.0.1:8000/audio/speech这就会404错误。正确的设置是http://127.0.0.1:8000/v1这样客户端会请求http://127.0.0.1:8000/v1/audio/speech正好匹配我们服务器的路由。4.2 场景二在自定义Python应用中使用假设你有一个自己的Python脚本或应用原本使用OpenAI的官方库来合成语音现在想切换到本地服务。原版使用OpenAI的代码from openai import OpenAI client OpenAI(api_keyyour-openai-key) response client.audio.speech.create( modeltts-1, voicealloy, inputHello, this is a test of local TTS. ) response.stream_to_file(output_openai.mp3)切换到本地Silero TTS服务器的代码只需要修改base_url和api_key如果服务器未开启认证api_key可填任意非空字符串。from openai import OpenAI # 将客户端指向本地服务器 client OpenAI( base_urlhttp://localhost:8000/v1, # 注意 /v1 后缀 api_keydummy-local-key # 如果服务器 REQUIRE_AUTHtrue则需填写正确的API_KEY ) try: response client.audio.speech.create( modeltts-1, # 此字段被本地服务器忽略但需保留以符合API格式 voicealloy, # 可以是 alloy, echo, nova 等或 silero 的 aidar, baya 等 inputHello, this is a test of local TTS. The number is 123., response_formatmp3, speed1.2 ) # 将音频流保存到文件 response.stream_to_file(output_local.mp3) print(语音合成成功已保存至 output_local.mp3) except Exception as e: print(f请求失败: {e})代码解析与注意事项base_url必须包含/v1路径原因同上。api_key如果本地服务器配置了REQUIRE_AUTHtrue则必须提供与.env中API_KEY一致的值。否则可以传任意字符串但不能是None因为openai库会检查这个字段是否存在。错误处理本地服务可能因模型未下载、FFmpeg缺失等问题启动失败或者合成过程中出现异常。良好的错误处理如检查服务是否可达、捕获合成异常能提升应用健壮性。性能考虑对于需要频繁、实时合成语音的应用如实时对话建议启用服务器的磁盘缓存功能默认已开启。相同的文本请求第二次会直接返回缓存文件极大减少延迟和CPU占用。缓存目录和大小可以通过.env中的CACHE_DIR和CACHE_MAX_FILES配置。4.3 服务器端自动播放与交互这是一个很有用的特性尤其当你把TTS服务器运行在一台有扬声器的设备上比如树莓派做的智能音箱主机。启用自动播放在.env中设置AUTO_PLAYtrue并确保FFPLAY_BIN指向正确的ffplay路径通常安装FFmpeg后会自动包含。启动服务器使用silero-tts命令或uvicorn启动。发送合成请求无论是通过curl还是你的应用程序向服务器发送一个TTS请求。观察效果服务器在合成音频后不会仅仅返回文件还会自动调用ffplay在后台播放该音频。同时如果AUTO_PLAY_SHOW_SKIP_WINDOWtrue默认屏幕上会弹出一个简单的Tkinter窗口带有一个“Skip”按钮。这在调试或演示时非常直观你可以随时中断当前播放的语音。跳过当前播放如果自动播放开启你可以通过一个专门的API端点来跳过当前正在播放的音频curl -X DELETE http://localhost:8000/v1/audio/speech/skip这在实现语音交互时很有用比如用户打断了AI的说话你可以立即发送一个“skip”请求。5. 常见问题排查与性能优化在实际部署和使用过程中你可能会遇到一些问题。下面我整理了一些常见的情况和解决方法。5.1 安装与启动问题问题现象可能原因解决方案ModuleNotFoundError: No module named torch或fastapiPython依赖未正确安装。确保在虚拟环境激活状态下重新运行pip install -e .。检查requirements.txt是否包含所有依赖。ERROR: Could not find a version that satisfies the requirement torchPyTorch安装失败可能由于网络或平台兼容性。尝试从PyTorch官网获取适合你系统和Python版本的安装命令。例如CPU版本pip install torch --index-url https://download.pytorch.org/whl/cpu。启动时卡在Downloading model...或下载失败网络连接问题无法从torch.hub下载Silero模型。1. 检查网络尝试科学上网。2. 手动下载模型根据Silero官方仓库指引手动下载模型文件.pt或.pth并放置到~/.cache/torch/hub/snakers4_silero-models_master/目录下对应的位置。启动后访问API返回500 Internal Server Error日志显示FFmpeg错误FFmpeg未安装或不在系统PATH中。1. 运行ffmpeg -version确认安装。2. 在.env中显式设置FFMPEG_BIN为完整路径如FFMPEG_BIN/usr/bin/ffmpeg。请求返回音频文件但播放时没有声音或杂音1. 采样率不匹配。2. 音频编码问题。3. 自动播放时ffplay找不到音频设备。1. 尝试指定response_format: wav这是最原始的格式排除编码问题。2. 检查.env中的SILERO_SAMPLE_RATE常见的有24000和48000尝试切换。3. 对于自动播放无声检查ffplay是否能单独播放一个MP3文件。在Linux上可能需要配置音频服务器如PulseAudio权限。5.2 合成效果与性能问题问题现象可能原因解决方案与优化建议合成速度慢首次请求尤其慢。1. 模型首次加载需要时间。2. CPU性能不足。3. 文本过长。1.缓存预热服务启动后先发送几个简短的测试请求让模型完全加载到内存。2.调整线程数在.env中设置SILERO_NUM_THREADS为你的CPU物理核心数可通过lscpu或sysctl -n hw.ncpu查看。3.文本分句如果输入文本很长考虑在客户端将其分成句子再分别请求合成并行处理。语音听起来不自然特别是数字读得奇怪。文本预处理未生效或对某些格式支持不好。1. 确认输入文本是纯字符串没有奇怪的编码或HTML标签。2. 查看服务器日志看预处理后的文本是什么样子。可以在请求时添加一个调试头或者修改代码打印预处理结果。3. 对于特定领域术语如产品型号、特殊缩写可能需要扩展项目的normalizer.py文件添加自定义规则。内存占用逐渐升高。可能是缓存文件过多或者PyTorch内存未释放。1. 检查CACHE_DIR目录大小通过CACHE_MAX_FILES限制缓存数量。2. 定期重启服务。对于长期运行的服务可以设置一个定时任务或使用进程管理器如systemd, supervisord在内存达到阈值时自动重启。3. 考虑使用SILERO_DEVICEcpu而非cuda因为CUDA上下文有时会持有内存。想使用GPU加速但设置SILERO_DEVICEcuda无效。1. 安装的PyTorch不是CUDA版本。2. 没有可用的CUDA设备或驱动不正确。1. 运行python -c import torch; print(torch.cuda.is_available())检查CUDA是否可用。2. 如果返回False需要卸载当前PyTorch重新安装CUDA版本。参考 PyTorch官网 的命令行安装指令。5.3 安全与部署建议不要直接暴露到公网这个项目本身没有设计强大的安全防护。如果需要在公网访问务必在前面部署反向代理如Nginx并启用HTTPS。同时强烈建议设置REQUIRE_AUTHtrue并使用一个强密码作为API_KEY。使用进程管理器在生产环境不要直接用uvicorn app.main:app在前台运行。使用systemd(Linux)、supervisord或PM2等工具来管理进程实现开机自启、崩溃重启、日志收集等功能。监控与日志确保服务日志通常输出到控制台被重定向到文件如/var/log/silero-tts.log便于问题排查。可以监控服务的CPU、内存占用以及API的响应时间。多语言支持目前项目主要优化了俄语和英语。如果你需要合成其他语言如中文、德语Silero模型本身支持多种语言但项目的文本预处理管道可能需要大幅修改或关闭。一个折中方案是在客户端先将文本处理成符合TTS模型输入的格式再发送给服务器。这个silero_openai_tts项目是一个将强大开源模型与易用API结合的优秀范例。它解决了本地AI应用生态中“语音输出”这个关键环节的集成难题。通过它你可以快速为你的智能助手、内容创作工具或任何需要语音交互的应用添加一个免费、私有、低延迟的语音合成能力。