nari-qwen3-tts README

The project's README from github.com/nari-labs/nari-qwen3-tts. As one markdown file: README.md.

Nari Qwen3-TTS

TL;DR

Nari Qwen3-TTS is a high-performance, single-H100 serving implementation of Qwen3-TTS 1.7B CustomVoice. It exposes streaming and non-streaming speech generation over HTTP, plus WebSocket-based input streaming for incremental text input.

It achieves 10 requests per second (RPS) and sub-50 ms p95 time-to-first-audio (TTFA) while maintaining real-time playback on a single NVIDIA H100 SXM. Even at 20 RPS, it sustains sub-80 ms p95 TTFA.

Below is a performance comparison with popular serving engines.

p95 TTFA under load comparison

[!NOTE] Methodology

Read our blog post for the full methodology. For details on the benchmark, see the benchmark repository.

Run with Docker

The container requires an NVIDIA H100, the NVIDIA Container Toolkit, and a driver compatible with CUDA 13.0. The published image supports Linux x86_64 (linux/amd64) H100 hosts. The engine has been tested only with English as the primary language.

docker run --rm --gpus all \
  -p 8000:8000 \
  -e HF_TOKEN \
  -e QWEN3_TTS_PROFILE=ttfa \
  -v nari-qwen3-tts-cache:/home/nari/.cache \
  ghcr.io/nari-labs/nari-qwen3-tts:latest

Model files and compiled kernels are cached in the named volume. Once model loading and CUDA Graph capture finish, check readiness with:

curl --fail http://127.0.0.1:8000/ready

To build the image locally instead:

docker build \
  --build-arg VCS_REF="$(git rev-parse HEAD)" \
  -t nari-qwen3-tts:local .

Run with uv

Python and uv versions are pinned in .python-version and pyproject.toml. The checked-in uv.lock defines the complete environment.

Install the required system packages (Debian/Ubuntu):

sudo apt-get install -y build-essential libsndfile1 sox

uv sync --frozen --extra codec --extra cuda --extra serving
uv run --frozen nari-qwen3-tts-server --profile ttfa

Add --local-files-only after the model is cached to prevent downloads at startup. --frozen is intentional: an out-of-date lockfile fails instead of silently resolving a different CUDA or Python environment.

The distribution name uses hyphens, while Python imports use underscores:

from nari_qwen3_tts import ModelAssetConfig, open_model

Profiles

Select a Docker profile with QWEN3_TTS_PROFILE, or pass --profile to nari-qwen3-tts-server. You can also set QWEN3_TTS_MODEL_CACHE_DIR and QWEN3_TTS_LOCAL_FILES_ONLY=1 in Docker.

For advanced tuning, apply a strict partial YAML overlay:

nari-qwen3-tts-server \
  --local-files-only \
  --engine-config /path/to/engine.yaml

The overlay may name its packaged base with extends: ttfa, balanced, or throughput; alternatively, pass --profile and omit extends. Unknown keys, invalid capture lists, and profile/base mismatches fail before model loading. The fully resolved config and its SHA-256 are printed at startup.

API and architecture

The service exposes:

See WebSocket speech API for the live-text protocol and client example.

HTTP client example

POST /v1/audio/speech follows the OpenAI Audio Speech request shape. Nari Qwen3-TTS supports only the model listed above, wav and pcm output, and speed: 1.0. It also accepts Nari-specific controls such as language.

curl http://127.0.0.1:8000/v1/audio/speech \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    "input": "Hello from Nari Labs.",
    "voice": "ryan",
    "language": "english",
    "response_format": "wav",
    "stream": false
  }' \
  --output speech.wav

Readiness remains false until CUDA Graph capture and a warm-up TTS request have both completed.

Thanks and references

Built by Nari Labs. Thanks to the Qwen3-TTS authors for releasing Qwen3-TTS, and to these projects for their work on high-performance multimodal and speech serving:

nari-qwen3-tts (nari-labs/nari-qwen3-tts)

Searching Database…

187 ·GitHub
Nari-qwen3-tts
Что это?Nari Qwen3-TTS — высокопроизводительная реализация обслуживания модели Qwen3-TTS 1.7B CustomVoice, рассчитанная на одну NVIDIA H100 и предоставляемая как API с потоковой и непотоковой генерацией речи.
Это файл модели для скачивания или сервер для запуска?Это сервер/API, а не отдельный файл модели: он открывает генерацию речи из текста через HTTP- и WebSocket-эндпоинты вроде POST /v1/audio/speech и WS /v1/audio/speech/ws.
Как его запустить?Скачайте и запустите опубликованный Docker-образ на хосте с H100 либо установите локально через uv, используя зафиксированные файлы .python-version, pyproject.toml и uv.lock; файлы модели и скомпилированные CUDA-ядра кэшируются в именованном томе.
Нужна ли конкретная видеокарта для запуска?Да, требуется одна NVIDIA H100, NVIDIA Container Toolkit и драйвер, совместимый с CUDA 13.0; опубликованный Docker-образ рассчитан только на Linux-хосты x86-64 с H100.
Поддерживает ли он языки, кроме английского?Он тестировался только с английским как основным языком, поэтому хорошая работа других языков не гарантирована.
Какие профили планирования можно выбрать?Доступны три встроенных профиля: «ttfa» оптимизирует минимальную задержку до первого звука за счёт меньших чанков, «balanced» — вариант по умолчанию, а «throughput» использует более крупные батчи для большей суммарной нагрузки; выбор через QWEN3_TTS_PROFILE или --profile.
Совместим ли API с TTS-эндпоинтом OpenAI?POST /v1/audio/speech повторяет форму запроса OpenAI Audio Speech, но этот сервер поддерживает только единственную встроенную модель, вывод wav/pcm и скорость 1.0, плюс специфичные для Nari параметры вроде языка.
Насколько быстрая генерация речи?На одной H100 SXM он удерживает 10 запросов в секунду с p95 задержкой до первого звука ниже 50 мс, и даже при 20 RPS держит p95 TTFA ниже 80 мс, сохраняя воспроизведение в реальном времени.
Как он сравнивается с другими движками обслуживания TTS?В README приводится сравнение с другими высокопроизводительными движками вроде vLLM-Omni, SGLang-Omni и VoxServe; за полной методологией отсылают к отдельному репозиторию бенчмарков и посту в блоге.
What are similar projects?vllm-omni, HyperQwen, InstinctFlash, TensorFold, text-generation-inference, csm, project-maya, dgx-spark-qwen38
Which topics is it in?streaming-audio, inference-optimization, http-server, inference-engine, model-serving, audio-generation, text-to-speech, websocket, openai-compatible, streaming, inference, nvidia
Creator
nari-labs
Size
0.5 MB
Stars
187
Updated
CommitAug 19
Age
2mo
Commits · 90 Days