xiaozhi-esp32-server 接入 Fish Speech 语音合成AutoDL 云端部署与本地 TTS 配置实战【免费下载链接】xiaozhi-esp32-server本项目为xiaozhi-esp32提供后端服务帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.项目地址: https://gitcode.com/gh_mirrors/xia/xiaozhi-esp32-server导读本文基于 docs/fish-speech-integration.md 编写完整讲解如何在 AutoDL 云服务器上从零部署 Fish Speech 开源语音合成服务并将其接入 xiaozhi-esp32-server 的 TTS 模块让 ESP32 设备用上自托管、可克隆音色的中文语音合成能力。读完本文你将掌握AutoDL 实例的镜像选择与学术加速设置、Fish Speech 的依赖安装与模型下载、api_server接口的启动与端口转发、以及 xiaozhi-esp32-server 中FishSpeech提供方的完整配置方法与底层调用原理。一、方案总览为什么用 Fish SpeechFish Speech 是 Fish Audio 开源的高质量语音合成TTS模型核心能力是基于参考音频reference audio 参考文本reference text的上下文学习in-context learning进行声音克隆只需一段数秒的音频样本即可合成出相似音色的语音。在 xiaozhi-esp32-server 的 TTS 生态中FishSpeech属于自托管型提供方它不依赖任何商业云厂商的 TTS API而是把推理服务运行在你自己控制的 GPU 机器如 AutoDL上通过标准的 HTTP 接口对外提供/v1/tts服务xiaozhi-esp32-server 侧仅需配置api_url即可调用。相比云端商业 TTS这种方案的优势在于音色完全由你掌控、支持本地参考音频克隆、无按次计费限制非常适合需要定制音色的私有化部署场景。该提供方位于 core/providers/tts/fishspeech.py通过core/utils/tts.py中的工厂函数create_instance按type: fishspeech动态加载与 config.yaml 中预置的配置节一一对应。二、AutoDL 云端部署 Fish Speech 服务2.1 租用实例与镜像选择登录 AutoDL 控制台租用一台 GPU 实例。镜像选择PyTorch / 2.1.0 / 3.10(ubuntu22.04) / cuda 12.1该镜像自带 PyTorch 2.1.0、Python 3.10Ubuntu 22.04与 CUDA 12.1 运行环境与 Fish Speech 官方推荐的依赖版本兼容。2.2 设置学术加速并拉取项目机器开机后首先开启学术加速用于加速访问 GitHub 等外部资源source /etc/network_turbo进入工作目录AutoDL 数据盘cd autodl-tmp/克隆 Fish Speech 官方仓库并进入项目目录git clone https://gitclone.com/github.com/fishaudio/fish-speech.git ; cd fish-speech说明gitclone.com是国内常用的 GitHub 加速镜像地址。如果你所在的网络环境可以直连 GitHub也可以直接使用官方仓库地址https://github.com/fishaudio/fish-speech.git。2.3 安装依赖以可编辑模式安装项目依赖会安装到当前 Python 环境pip install -e.如果安装过程中报错通常是因为缺少portaudio开发库PyAudio 等音频库的编译依赖执行apt-get install portaudio19-dev -y安装完成后重新执行pip install -e.即可。2.4 重装指定版本的 PyTorch为与 CUDA 12.1 及模型运行环境严格匹配官方流程要求显式重装 PyTorch 2.3.1 全家桶注意实例镜像自带的是 2.1.0这里升级到 2.3.1指定 cu121 的 wheel 源pip install torch2.3.1 torchvision0.18.1 torchaudio2.3.1 --index-url https://download.pytorch.org/whl/cu121版本匹配说明torchvision0.18.1与torchaudio2.3.1是 torch 2.3.1 对应的配套版本三者必须一致否则可能出现算子不匹配或运行时崩溃。2.5 下载模型权重进入tools目录并运行官方下载脚本cd tools python download_models.py该脚本会自动下载 Fish Speech 推理所需的模型权重包括 VQGAN、LLAMA 语音语言模型等。下载耗时取决于网络状况请耐心等待其完成。2.6 启动 HTTP 接口服务模型下载完成后启动官方提供的 API 服务监听所有网卡地址的 6006 端口python -m tools.api_server --listen 0.0.0.0:6006启动成功后服务会在0.0.0.0:6006上提供/v1/tts等接口即 xiaozhi-esp32-server 将要调用的 TTS 端点。2.7 配置端口转发自定义服务由于 AutoDL 实例不直接对外暴露端口需要在 AutoDL 控制台开启端口转发打开 AutoDL 实例列表页面https://autodl.com/console/instance/list找到刚才启动的机器点击自定义服务按钮开启端口转发服务将实例内6006端口映射到本地端口转发配置完成后在本地电脑浏览器访问http://localhost:6006/即可看到 Fish Speech 的 API 服务预览页说明服务已可以通过本地端口访问。部署验证提示访问http://localhost:6006/docs若服务启用 Swagger 文档可以直接在页面上发起一次 TTS 请求用于验证模型推理与端口转发是否正常再进行下一步的服务器端配置。三、xiaozhi-esp32-server 端核心配置3.1 最小可用配置单模块部署在 config.yaml 中FishSpeech提供方已经预置了完整配置。单模块部署时核心配置如下selected_module: TTS: FishSpeech TTS: FishSpeech: reference_audio: [config/assets/wakeup_words.wav,] reference_text: [哈啰啊我是小智啦声音好听的台湾女孩一枚超开心认识你耶最近在忙啥别忘了给我来点有趣的料哦我超爱听八卦的啦,] api_key: 123 api_url: http://127.0.0.1:6006/v1/tts配置修改完成后重启 xiaozhi-esp32-server 服务即可生效。逐项说明selected_module.TTS指定全局 TTS 提供方为FishSpeech。初始化时 modules_initialize.py 会根据selected_module[TTS]从config[TTS]取出对应配置节并交给 tts.py 的create_instance动态实例化。reference_audio参考音频路径列表用于声音克隆的样本音频。reference_text与参考音频一一对应的参考文本须是参考音频中真实说出的话。api_key接口鉴权密钥。Fish Speech 的api_server默认对 key 校验较为宽松随意填写一个字符串即可但不能缺失源码会做 key 检查见下文。api_urlFish Speech 服务的 TTS 端点地址。若 xiaozhi-esp32-server 与 Fish Speech 同机运行填http://127.0.0.1:6006/v1/tts若 Fish Speech 部署在其他机器则改为该机器的实际 IP 与端口。3.2 完整配置参数参考默认值一览config.yaml 中预置的完整配置如下各项含义与默认值均可在 fishspeech.py 的TTSProvider.__init__中找到对应实现TTS: FishSpeech: type: fishspeech output_dir: tmp/ response_format: wav reference_id: null reference_audio: [config/assets/wakeup_words.wav,] reference_text: [哈啰啊我是小智啦声音好听的台湾女孩一枚超开心认识你耶最近在忙啥别忘了给我来点有趣的料哦我超爱听八卦的啦,] normalize: true max_new_tokens: 1024 chunk_length: 200 top_p: 0.7 repetition_penalty: 1.2 temperature: 0.7 streaming: false use_memory_cache: on seed: null channels: 1 rate: 44100 api_key: 你的api_key api_url: http://127.0.0.1:8080/v1/tts参数默认值说明typefishspeech提供方类型标识工厂函数据此加载core/providers/tts/fishspeech.pyoutput_dirtmp/TTS 音频文件的输出目录仅非删除模式时生成文件response_formatwav返回音频格式支持wav、pcm、mp3对应服务端ServeTTSRequest.formatreference_idnullFish Audio 云端音色 ID使用本地参考音频时保持null传入官方示例 ID 时可用云端音色reference_audio见上参考音频路径列表支持;分隔字符串或列表见parse_string_to_listreference_text见上参考文本列表与参考音频一一对应normalizetrue是否对文本做归一化对中英文数字等稳定性有帮助max_new_tokens1024单次生成的最大 token 数chunk_length200分块长度服务端约束范围 100–300top_p0.7采样参数服务端约束范围 0.1–1.0repetition_penalty1.2重复惩罚服务端约束范围 0.9–2.0temperature0.7采样温度服务端约束范围 0.1–1.0streamingfalse是否使用流式合成use_memory_cacheon服务端记忆缓存开关on/offseednull随机种子固定后可复现同一次合成结果channels1音频声道数rate44100音频采样率api_key—接口鉴权密钥check_model_key会拦截含你字的未填写占位值api_urlhttp://127.0.0.1:8080/v1/ttsFish Speech 服务 TTS 端点3.3 配置加载与参数解析的底层实现理解这些参数如何生效有助于排查问题工厂加载core/utils/tts.py的create_instance会检查core/providers/tts/下是否存在与class_name同名的.py文件存在则动态importlib.import_module并实例化其中的TTSProvider因此type: fishspeech精确对应 fishspeech.py。键检查check_model_key(FishSpeech TTS, self.api_key)见 util.py会检测 api_key 是否包含你字——即配置模板中的占位符——从而在启动时直接给出API key 未设置的明确报错。列表解析reference_audio/reference_text经parse_string_to_listutil.py处理兼容 YAML 列表与;分隔字符串两种写法。类型兜底channels、rate、max_new_tokens、chunk_length、top_p、temperature、repetition_penalty等均对空字符串做了兜底处理缺省时回落为默认值见 fishspeech.py。四、请求协议与调用链路4.1 客户端请求构造TTSProvider.text_to_speakfishspeech.py是核心调用方法它做了三件事读取参考音频与参考文本audio_to_bytes将参考音频文件读为二进制read_ref_text支持直接传文本字符串或文本文件路径两者按序配对组装成references列表。构造请求体将text、references、reference_id、normalize、format、max_new_tokens、chunk_length、top_p、repetition_penalty、temperature、streaming、use_memory_cache、seed全部打包进ServeTTSRequestPydantic 模型字段约束与服务端一致见 fishspeech.py。发送 HTTP 请求以ormsgpackMessagePack序列化请求体请求头携带Authorization: Bearer {api_key}与Content-Type: application/msgpackPOST 到api_url成功后把返回的音频字节流写入output_file或直接返回。4.2 音频回传链路合成出的音频字节流返回后进入 base.py 基类定义的播放链路to_tts_stream或to_tts会按delete_audio全局配置决定直接转音频流还是落盘后流转随后audio_bytes_to_data_stream/audio_to_opus_data_stream将音频重采样并编码为 Opus经tts_audio_queue交给_audio_play_priority_thread消费线程最终通过sendAudioMessage推送给 ESP32 设备播放见 base.py 与 base.py。因此服务端返回的采样率默认 44100 Hz、单声道与本机conn.sample_rate不一致时也会在数据流转换阶段统一处理。五、常见问题排查启动报错 FishSpeech TTS 的 API key 未设置api_key仍保留着配置模板中的你的api_key占位文本被check_model_key拦截改为任意非占位字符串如123即可。create_instance抛出 不支持的TTS类型说明TTS.FishSpeech.type未设置为fishspeech或core/providers/tts/fishspeech.py文件缺失请核对type: fishspeech。本地无法访问localhost:6006确认 AutoDL 控制台的自定义服务端口转发已开启、实例内api_server监听的是0.0.0.0:6006而非仅回环地址。pip install -e.报编译错误多为缺少portaudio19-dev所致执行apt-get install portaudio19-dev -y后重试。合成失败/返回非 200text_to_speak会打印响应状态码与服务端返回的 JSON 错误信息fishspeech.py据此检查参考音频路径是否有效、参考文本是否与音频内容一致、服务端模型是否已加载完成。声音不像/音质异常优先检查reference_audio与reference_text是否严格对应参考文本必须是参考音频中实际说出的内容并适当增加参考音频的清晰度与时长。六、延伸参考完整集成教程原文档docs/fish-speech-integration.md提供方源码core/providers/tts/fishspeech.py配置预置节config.yamlTTS 工厂加载core/utils/tts.py模块初始化链路core/utils/modules_initialize.pyTTS 基类与音频流转core/providers/tts/base.py若希望在同一实例上同时部署推理服务与使用其他 TTS 提供方可参考 docs/paddlespeech-deploy.md 了解同类自托管 TTS 的部署思路【免费下载链接】xiaozhi-esp32-server本项目为xiaozhi-esp32提供后端服务帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.项目地址: https://gitcode.com/gh_mirrors/xia/xiaozhi-esp32-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
