GPT-Academic 语音合成实战：EDGE-TTS 与 SoVITS 两种 TTS 方案配置与实现原理

GPT-Academic 语音合成实战：EDGE-TTS 与 SoVITS 两种 TTS 方案配置与实现原理

【免费下载链接】gpt_academic为GPT/GLM等LLM大语言模型提供实用化交互接口，特别优化论文阅读/润色/写作体验，模块化设计，支持自定义快捷按钮&函数插件，支持Python和C++等项目剖析&自译解功能，PDF/LaTex论文翻译&总结功能，支持并行问询多种LLM模型，支持chatglm3等本地模型。接入通义千问, deepseekcoder, 讯飞星火, 文心一言, llama2, rwkv, claude2, moss等。项目地址: https://gitcode.com/GitHub_Trending/gp/gpt_academic

GPT-Academic 内置了文字转语音（TTS，Text-to-Speech）能力，可以把模型在对话界面中流式输出的文本逐句朗读出来，为论文朗读、听稿等场景提供语音交互。本文基于仓库文档 使用TTS文字转语音 展开，先完整给出 EDGE-TTS（云端、免部署）与 SoVITS（本地克隆音色、需显卡）两套方案的配置步骤，再结合 FastAPI 服务端 与 前端播放脚本 的源码，剖析/vits接口的请求链路、音频切分与排队播放机制，帮助你既能快速启用 TTS，也能理解并排查底层问题。

一、TTS 相关配置项总览

项目所有 TTS 配置集中在 config.py 中，共三个参数：

# GPT-SOVITS 文本转语音服务的运行地址（将语言模型的生成文本朗读出来） TTS_TYPE = "EDGE_TTS" # EDGE_TTS / LOCAL_SOVITS_API / DISABLE GPT_SOVITS_URL = "" EDGE_TTS_VOICE = "zh-CN-XiaoxiaoNeural"

各配置项含义如下：

需要说明的是，TTS_TYPE会在启动时被读取并注入到前端初始化脚本中：main.py 通过get_conf取出该值，并在 main.py 中以_js=f"""()=>GptAcademicJavaScriptInit("{DARK_MODE}","{INIT_SYS_PROMPT}","{ADD_WAIFU}","{LAYOUT}","{TTS_TYPE}")"""的形式传给浏览器端，用于决定页面是否启用自动朗读入口。

另外，EDGE-TTS 方案的依赖已在 requirements.txt 中声明（edge-tts>=7.0.0），安装项目依赖后即可使用；而 mp3 转 wav 的环节依赖 ffmpeg（见后文原理部分）。

二、方案一：使用 EDGE-TTS（简单，无需显卡）

这是文档推荐的入门方案，无需本地部署任何语音服务，直接复用微软 Edge 的在线语音合成能力。只需将 config.py 修改为：

TTS_TYPE = "EDGE_TTS" EDGE_TTS_VOICE = "zh-CN-XiaoxiaoNeural"

修改配置后重启项目即可。EDGE_TTS_VOICE决定了朗读音色，默认值zh-CN-XiaoxiaoNeural是晓晓女声，也可以换成其他音色名称以改变听感。

该方案的前提是服务能够访问 Edge TTS 的在线接口（属于网络可达性问题），因此在内网或受限网络环境下需要自备代理。

三、方案二：使用 SoVITS（本地部署，支持克隆音色，需要显卡）

SoVITS（GPT-SoVITS）支持用少量参考音频克隆角色音色，适合想让模型用"指定角色声音"朗读的场景。由于推理需要显卡，文档建议通过 Docker 部署。操作步骤与文档 使用TTS文字转语音 完全一致：

1. 创建如下文件夹结构（reference目录用于挂载克隆音色的参考素材）：

. ├── docker-compose.yml └── reference ├── clone_target_txt.txt └── clone_target_wave.mp3

2.docker-compose.yml内容（注意其中19880:9880的端口映射，宿主机端口 19880 是后续配置要记住的值）：

version: '3.8' services: gpt-sovits: image: fuqingxu/sovits_gptac_trim:latest container_name: sovits_gptac_container working_dir: /workspace/gpt_sovits_demo environment: - is_half=False - is_share=False volumes: - ./reference:/reference ports: - "19880:9880" # 19880 为 sovits api 的暴露端口，记住它 shm_size: 16G deploy: resources: reservations: devices: - driver: nvidia count: "all" capabilities: [gpu] command: bash -c "python3 api.py"

3. 准备克隆素材：clone_target_wave.mp3是想要克隆的角色音频，clone_target_txt.txt是该音频逐字对应的文本（角色语音素材可参考公开的角色语音合集）。

4. 启动服务：在目录内运行docker-compose up，等待 SoVITS API 容器启动完成。

5. 修改 GPT-Academic 配置（端口必须与 docker-compose 中暴露的端口对应）：

TTS_TYPE = "LOCAL_SOVITS_API" GPT_SOVITS_URL = "http://127.0.0.1:19880"

6. 启动本项目。此后所有朗读请求都会转发到本地 SoVITS 服务，音色由容器内reference挂载的参考音频决定。

四、实现原理：从/vits接口到浏览器播放

理解底层链路，可以在 TTS 不工作时快速定位问题出在哪一环。

4.1 服务端：/vits接口的注册与分发

TTS 接口注册在 FastAPI 封装层 shared_utils/fastapi_server.py 中。关键点：

• 按配置条件注册：只有TTS_TYPE != "DISABLE"时，代码才会执行接口注册逻辑，并挂载POST /vits路由（fastapi_server.py）。因此TTS_TYPE = "DISABLE"时该端点根本不存在。
• EDGE_TTS 分支：收到 JSON 请求体后取出text字段，用edge_tts.Communicate(text=..., voice=EDGE_TTS_VOICE)合成语音，先存为临时 mp3 文件，再通过pydub.AudioSegment转成 wav 后作为二进制响应返回。这里有一个显式的前置依赖：转换失败会抛出RuntimeError("ffmpeg未安装，无法处理EdgeTTS音频。...")（fastapi_server.py）。也就是说EDGE-TTS 方案实际依赖系统安装了 ffmpeg，即使 requirements 里只声明了edge-tts与pydub相关 Python 包。
• LOCAL_SOVITS_API 分支：直接把整个请求体原样POST到GPT_SOVITS_URL，超时设为 60 秒，并把远端响应内容、状态码与响应头原样回传给浏览器（fastapi_server.py）。从源码结构看，GPT-Academic 在这一模式下充当的是 SoVITS 服务的透明代理，音频格式完全由 SoVITS API 决定。
• 错误处理：转发过程中的httpx.RequestError会被包装为 400 状态码返回，前端会收到非 2xx 响应（见下文）。

仓库中还有对应的独立测试脚本 tests/test_tts.py，它复现了 EDGE_TTS 分支的完整流程（合成 → 临时文件 → pydub 转 wav → ffmpeg 缺失时抛出相同报错），可以直接python tests/test_tts.py运行来单独验证本机 Edge-TTS 与 ffmpeg 环境是否正常，与 Web 界面解耦。

4.2 前端：文本切分、并发请求与顺序播放

浏览器侧逻辑位于 themes/tts.js。其工作机制可以概括为三步：

1. 逐句切分与请求：push_text_to_audio函数将待朗读文本按text.split(/[\n。]/)（换行或中文句号）拆成短句，对每个非空句子向${window.location.href}vits发起POST，请求体为{ "text": ..., "text_language": "zh" }，并携带自增序号send_index；句子之间还会await delay(3000)做节流（tts.js）。整个推送过程由自定义的FIFOLock串行锁保护，避免乱序触发。
2. 乱序到达的处理：由于各句的合成耗时不同，返回顺序可能乱序。UpdatePlayQueue会比较返回序号cnt与期望的recv_index：不一致时先缓存到to_be_processed，一致时立即入队播放并顺带把已缓存的前序音频依次取出播放，保证朗读顺序与文本顺序一致（tts.js）。
3. 顺序播放与停止：AudioPlayer类基于 Web Audio API（AudioContext.decodeAudioData+AudioBufferSourceNode）实现播放队列，enqueueAudio只在朗读开关allow_auto_read_tts_flag开启时生效；stop()方法清空队列并停止当前音源，对应界面上的暂停/停止朗读操作（tts.js）。

4.3 端到端调用链小结

综合以上源码，一次"文本被朗读"的完整链路为：

模型流式输出文本 → themes/tts.js 按换行/句号切句，带序号 POST 到 /vits → shared_utils/fastapi_server.py 按 TTS_TYPE 分发： EDGE_TTS：edge_tts 合成 mp3 → pydub 转 wav（需 ffmpeg） LOCAL_SOVITS_API：透传到 GPT_SOVITS_URL（本地 SoVITS API） → 二进制音频返回浏览器，按序号恢复顺序进入 AudioPlayer 队列 → Web Audio API 顺序播放

五、常见问题与排查要点

结合文档与源码，可以归纳出以下排查路径：

• 页面没有朗读按钮 / 点了没反应：确认TTS_TYPE不是DISABLE，且修改配置后重启了服务——/vits路由在启动时按配置决定是否注册（fastapi_server.py）。
• EDGE-TTS 报 ffmpeg 相关错误：服务端日志出现"ffmpeg未安装"提示时，说明 mp3→wav 环节失败，安装 ffmpeg 后重启即可；也可先单独运行 tests/test_tts.py 验证本机环境。
• SoVITS 模式下无声音：依次检查GPT_SOVITS_URL端口与 docker-compose 的19880:9880映射是否一致、docker-compose up容器是否仍在运行、浏览器能否直接访问该 URL；服务端转发超时为 60 秒，长句合成超过该时长会失败。
• 网络受限环境使用 EDGE-TTS：Edge-TTS 走在线接口，无外网连通性时建议改用本地 SoVITS 方案。

六、小结

GPT-Academic 的 TTS 功能通过"一个开关（TTS_TYPE）+ 一个统一入口（POST /vits）"实现了两种引擎的可插拔切换：追求开箱即用选EDGE_TTS（记得系统装有 ffmpeg），追求音色可控选LOCAL_SOVITS_API（需显卡并部署 SoVITS API 容器）。本文介绍的配置步骤均来自 docs/use_tts.md 与 config.py，实现细节可在 shared_utils/fastapi_server.py、themes/tts.js 与 tests/test_tts.py 中继续深入验证。

【免费下载链接】gpt_academic为GPT/GLM等LLM大语言模型提供实用化交互接口，特别优化论文阅读/润色/写作体验，模块化设计，支持自定义快捷按钮&函数插件，支持Python和C++等项目剖析&自译解功能，PDF/LaTex论文翻译&总结功能，支持并行问询多种LLM模型，支持chatglm3等本地模型。接入通义千问, deepseekcoder, 讯飞星火, 文心一言, llama2, rwkv, claude2, moss等。项目地址: https://gitcode.com/GitHub_Trending/gp/gpt_academic