1. 产品概述
Qwen3-TTS-X 是针对智能 AI 助手与机器人交互场景深度优化的高性能本地 Text-to-Speech (TTS) 底座仓库。基于开源模型架构，本项目通过深度解耦内部引擎管线，提供了一套能够实现**“零首字延迟”（极低 TTFB）**特征的本地流式 HTTP 语音 API 与 WebSocket 交互平台。
(注：本项目后续将统一发布于并持续更新在 shumox.com 官方主页。)
2. 核心理念
首播响应最大化 (TTFB-First)：在 AI 对话中，机器响应的起音速度是体验的关键。打破传统“全部生成完再打包下载”的伪流，做到真·原生流式边推理边播。
无感化生态接轨：对于任何支持 OpenAI 生态链的应用，只需要修改 Base URL 就能一键无损享受本地高速发音。
全局严密并发统筹：使用极度克制与严谨的资源独占安全机制，彻底消灭 TTS 并发造成的显存雪崩危机。
3.核心特性与项目特征
极限流式合成：打破传统框架，大幅缩短流式实际首音延迟，起音延迟最低可压降至 200ms 以内。
多后端加速推理：底层兼容度极高。针对 1.7B 规格模型，一块 RTX 2080Ti 即能轻松榨出 RTF 0.21 的卓越成绩；由于使用了兼容性更广的执行后台，AMD 显卡亦可无缝利用 Vulkan 后端开启推算加速。
OpenAI 标准完美模拟：原生支持 POST /v1/audio/speech 及周边状态接口，返回携带音频头或裸流的 Chunked Transfer 数据流。
“动态劫持”推流专利级设计：在运行时（Runtime）热重写或拦截底层模型的内部播放队列机制（Monkey Patching），将本该发往系统外设的声音流平滑劫持到网络队列，不产生冗余本地 I/O 损耗。
抗造鲁棒的异常熔断（保险丝机制）：多重 finally 与指针备份护航，在 Web 端强退、长文本断连场景下，均可保证核心推理链路的稳固与显存释放。
4. 性能指标
以下数据基于硬件环境 (RTX 2080Ti 平台) 测定参考：
实时生成率 (RTF)
RTX 2080Ti (独显)：RTF 0.21 （即：每生成 1 秒的音频实际只需消耗 0.21 秒）
纯 CPU 执行：RTF 1.3
普通集成显卡：RTF 1.3
注：当 RTF < 1 时，意味着引擎内部生成声音片段的速度已经远超实际播放消耗的速度，实现了绝对不会断音卡顿的极致流式体验。
显存性能开销 (VRAM)
使用规模较大的 1.7B 模型参数底座下，全程生成峰值仅需占用约 1.8 GB 显存。
使用更轻量的 0.6B 版虽可再极限压缩节省 500MB 显存，但在此框架下对最终合成速度的绝对提升感知不大。这是因为该架构中的耗时核心瓶颈主要卡在了 Predictor 推理模块上（合成每一秒音频需要经过自回归迭代运算 12.5*15 = 187.5 次），而 0.6B 与 1.7B 模型的算力鸿沟仅只体现在外围的 Talker 映射层，因此一般建议直接锁定音质更加优秀的 1.7B 权重。
5. Clone（音色克隆）原理
声音克隆技术底层的本质实际上是利用大模型的**“接续说话 (In-Context Learning 上下文微调)”**特性。 直观地理解：想象一下，你正在大声通融地读一段话，当你读到一半被强制停下，这时我让你立马“紧接着继续往下读”，你自然而然地就会顺着原先原有的语气、鼻音和声带质感发声。本架构中的语音引擎恰好极尽利用了这一点 —— 通过配置文件（如 test1-voice.json）强行投喂带克隆目标特征音色的锚点素材进提示词前端（Context），模型便会毫不费力地以该角色的声带参数模板平滑地“续写”出完全一致的后续 TTS 语音。
6. 系统架构
底层推算与数据源 (GGUF+ONNX)：模型通过 GPU（CUDA Provider）以细粒度切片（Chunk size=8）全速处理。
并发锁与队列中枢 (Mutex & Queue)：采用异步显存串行锁排队机制，底层产出的所有 np.float32 张量块会推向中央暂存异步队列。
协议暴露层 (FastAPI)：
HTTP 管道负责将内部张量清洗、装头、重采样至 int16 返回给第三方调用端。
WS 管道则将裸数组交由浏览器。
前端消费层 (WebAudio Console)：脱离繁复的 DOM <audio> 播放器，利用 AudioContext 进行硬件级的按时采样率衔接播放。
7. 技术栈
后端框架：FastAPI, Uvicorn, Pydantic
并发与网络底层：Python 原生 asyncio 协程、WebSockets
模型推理载体：onnxruntime-gpu / Vulkan 计算环境, numpy, gguf
前端音频渲染：Vanilla JS, WebAudio API
8. 目录结构
📦 qwen3-tts-x
┣ 📂 log/ # 运行日志归档
┣ 📂 model-base/ # AI 语音相关的基底权重文件及其 config
┣ 📂 output/elaborate/ # 音色配置及输出克隆模板 (如 test1-voice.json)
┣ 📂 qwen3_tts_gguf/ # TTS 底层推理核心代码仓
┣ 📜 qwen3-tts-x-api.py # 兼容 OpenAI 的本地流式 API 网关与主服务程序
┣ 📜 qwen3-tts-x-studio.py # 基于 WebSocket 连接的真流式低延迟极客 Web 端控制台
┣ 📜 requirements.txt # 项目构建的 Python 包依赖名单
┗ 📜 README.md # 当前说明文档
9. 核心功能
纯流式 TTS API (OpenAI /v1/audio/speech)：
包含流式音频生成、流排队解析策略。
自由回退机制（从非常规后缀自动折算成 wav / pcm）。
极客 WebUI 终端控制台：
即刻录入、即刻发声，自带可视化频谱监控。
客户端长短连接自适应，模型自我断点恢复。
10. 安装方式
环境要求：
Windows/Linux 系统，推荐具有 NVIDA 显卡及正确配置了 CUDA 的运行环境。
Python 3.10+
步骤 1: 准备依赖栈 请进入项目根目录并在激活的 Python venv 环境下运行：
pip install -r requirements.txt
步骤 2: 启动标准 API 网关
python qwen3-tts-x-api.py
服务将在 http://0.0.0.0:8100 激活，提供 v1 各类 HTTP 路由。
步骤 3: 启动超低延迟 WebSocket WebUI (可选)
python qwen3-tts-x-studio.py
服务将在 http://0.0.0.0:8000 暴露 Web 交互界面。
