Qwen3-TTS 통합

고품질 다국어 음성 합성을 위해 Alibaba의 Qwen3-TTS를 로컬에서 실행하세요. 이 가이드는 Libre WebUI에 포함된 OpenAI 호환 TTS 서버 설정을 다룹니다.

개요

Qwen3-TTS는 다음 기능을 갖춘 고급 음성 합성 시스템입니다.

영어, 중국어, 일본어, 한국어를 아우르는 9가지 기본 음성
독일어, 프랑스어, 스페인어, 이탈리아어, 포르투갈어, 러시아어를 포함한 10개 언어 지원
3초 오디오 샘플을 사용한 음성 복제
자연어 설명을 사용한 음성 디자인
감정과 운율을 위한 지시 제어

포함된 서버는 Qwen3-TTS를 OpenAI 호환 API로 감싸므로 Libre WebUI에서 표준 플러그인 시스템을 통해 사용할 수 있습니다.

요구 사항

구성 요소	최소	권장
Python	3.12+	3.12(3.14 제외)
GPU VRAM	4GB(0.6B 모델)	8GB+(1.7B 모델)
RAM	8GB	16GB+
디스크	5GB	10GB

플랫폼 지원

플랫폼	백엔드	참고
NVIDIA GPU	CUDA	최고 성능, bfloat16 지원
Apple Silicon	MPS	메모리 효율을 위해 0.6B 모델 사용
CPU	PyTorch	더 느리므로 0.6B 모델 사용

Apple Silicon 사용자

Mac에서는 메모리 압력을 피하도록 customvoice-0.6b 모델 변형을 사용하세요. 1.7B 모델은 통합 메모리 16GB 컴퓨터에서 시스템 불안정을 일으킬 수 있습니다.

빠른 시작

1. 서버 설치

cd examples/qwen-tts-server

# Create virtual environment (Python 3.12 required)
python3.12 -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

2. 서버 시작

# NVIDIA GPU (recommended)
python server.py --model customvoice-1.7b

# Apple Silicon
python server.py --model customvoice-0.6b

# CPU (slower)
python server.py --model customvoice-0.6b

서버는 기본적으로 http://localhost:8100에서 실행됩니다.

3. Libre WebUI 설정

플러그인은 plugins/qwen-tts.json에 미리 설정되어 있습니다. 설정 → 플러그인 → Qwen3 TTS에서 활성화하세요.

4. 테스트

curl http://localhost:8100/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-tts", "input": "Hello, welcome to Libre WebUI!", "voice": "Ryan"}' \
  --output speech.wav

사용 가능한 모델

모델	크기	용도
`customvoice-1.7b`	~3.5GB	지시 제어를 지원하는 기본 음성
`customvoice-0.6b`	~1.5GB	VRAM이 제한된 환경용 경량 변형
`voicedesign-1.7b`	~3.5GB	텍스트 설명에서 음성 생성
`base-1.7b`	~3.5GB	3초 샘플에서 음성 복제
`base-0.6b`	~1.5GB	경량 음성 복제

음성

기본 음성(CustomVoice 모델)

음성	언어	설명
Ryan	영어	남성, 또렷하고 자연스러움
Aiden	영어	남성, 따뜻한 어조
Vivian	중국어	여성, 전문적
Serena	중국어	여성, 친근함
Uncle_Fu	중국어	남성, 성숙함
Dylan	중국어	남성, 베이징 방언
Eric	중국어	남성, 쓰촨 방언
Ono_Anna	일본어	여성
Sohee	한국어	여성

OpenAI 음성 별칭

OpenAI TTS 클라이언트와의 호환성을 위해 서버는 OpenAI 음성 이름을 다음과 같이 매핑합니다.

OpenAI 음성	매핑 대상
`alloy`	Ryan
`echo`	Aiden
`fable`	Vivian
`onyx`	Uncle_Fu
`nova`	Serena
`shimmer`	Ono_Anna

API 참조

음성 생성

엔드포인트: POST /v1/audio/speech

{
  "model": "qwen3-tts",
  "input": "Text to convert to speech",
  "voice": "Ryan",
  "response_format": "wav",
  "instruct": "Speak with enthusiasm",
  "language": "English"
}

매개변수	유형	기본값	설명
`model`	string	`qwen3-tts`	모델 식별자
`input`	string	필수	합성할 텍스트(최대 10,000자)
`voice`	string	`ryan`	음성 이름(위 표 참조)
`response_format`	string	`wav`	오디오 형식(`wav`만 지원)
`instruct`	string	`""`	감정/운율 지시
`language`	string	자동 감지	언어 감지 재정의

응답: 오디오 파일(audio/wav)

음성 디자인

엔드포인트: POST /v1/audio/voice-design

자연어 설명에서 사용자 지정 음성을 만듭니다.

{
  "model": "qwen3-tts-voicedesign",
  "input": "Welcome to our service.",
  "voice_description": "A warm, friendly female voice with a slight British accent",
  "language": "English"
}

노트

voicedesign-1.7b 모델을 로드해야 합니다.

음성 복제

엔드포인트: POST /v1/audio/voice-clone

3초 이상의 오디오 샘플에서 음성을 복제합니다.

curl -X POST http://localhost:8100/v1/audio/voice-clone \
  -F "input=Hello, this is my cloned voice." \
  -F "reference_audio=@reference.wav" \
  -F "reference_text=This is what was said in the reference." \
  --output cloned.wav

매개변수	유형	설명
`input`	string	합성할 텍스트
`reference_audio`	file	3초 이상의 오디오 샘플
`reference_text`	string	참조 오디오의 텍스트 기록

노트

base-1.7b 또는 base-0.6b 모델을 로드해야 합니다.

음성 목록

엔드포인트: GET /v1/voices

{
  "voices": [
    {"id": "ryan", "name": "Ryan", "language": "English"},
    {"id": "aiden", "name": "Aiden", "language": "English"},
    ...
  ]
}

상태 확인

엔드포인트: GET /health

{ "status": "healthy", "model_loaded": true }

서버 설정

python server.py [OPTIONS]

옵션	기본값	설명
`--host`	`0.0.0.0`	바인딩할 호스트
`--port`	`8100`	바인딩할 포트
`--model`	`customvoice-1.7b`	로드할 모델 변형

네트워크 접근

네트워크의 다른 컴퓨터에서 서버에 접근하려면 다음을 실행합니다.

# Start server on all interfaces
python server.py --host 0.0.0.0 --port 8100

# Access from another machine
curl http://192.168.1.100:8100/v1/audio/speech ...

plugins/qwen-tts.json의 플러그인 엔드포인트를 업데이트합니다.

{
  "endpoint": "http://192.168.1.100:8100/v1/audio/speech",
  "capabilities": {
    "tts": {
      "endpoint": "http://192.168.1.100:8100/v1/audio/speech"
    }
  }
}

프로덕션 기능

텍스트 정리

서버는 모델이 멈추는 것을 방지하기 위해 입력 텍스트를 자동으로 정리합니다.

이모지와 기호 제거
Markdown 서식 제거(*bold*, _italic_ 등)
반복 문자 축약(FUUUUU → FUU)
무대 지시 제거(*(action)*, (whispers))
공백 정규화

텍스트 청크 분할

긴 텍스트는 문장 경계에서 자동으로 나뉩니다.

청크당 최대 500자
청크당 제한 시간 30초
실패한 청크는 건너뛰고 나머지 청크는 계속 처리
청크를 하나의 오디오 응답으로 연결

이를 통해 자연스러운 음성 흐름을 유지하면서 긴 AI 응답의 시간 초과를 방지합니다.

다중 GPU 설정

GPU가 여러 개인 시스템에서는 텐서 장치 불일치를 방지하기 위해 서버가 단일 GPU 실행을 강제합니다.

device_map = {"": "cuda:0"}  # Uses first GPU only

특정 GPU를 사용하려면 다음을 실행합니다.

CUDA_VISIBLE_DEVICES=1 python server.py --model customvoice-1.7b

문제 해결

모델 다운로드 실패

모델은 처음 실행할 때 Hugging Face에서 다운로드됩니다. 실패하면 다음을 실행하세요.

# Set Hugging Face token for gated models
export HF_TOKEN=hf_...

# Or download manually
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice

메모리 부족(Apple Silicon)

RuntimeError: MPS backend out of memory

더 작은 모델 변형을 사용하세요.

python server.py --model customvoice-0.6b

CUDA 메모리 부족

torch.cuda.OutOfMemoryError: CUDA out of memory

다른 GPU 애플리케이션을 닫습니다.
0.6B 모델 변형을 사용합니다.
server.py에서 청크 크기를 줄입니다(max_chunk_size=300).

서버 시간 초과

긴 텍스트 생성에서 시간이 초과된다면 다음을 확인하세요.

서버가 텍스트를 자동으로 청크로 나누고 나머지 청크를 계속 처리합니다.
서버 로그에서 시간 초과된 청크를 확인합니다.
입력 텍스트를 줄이는 것을 고려합니다.

오디오가 이상하게 들림

음절 반복: 일반적으로 이모지나 특수 문자 때문에 발생합니다. 정리기가 자동으로 처리해야 합니다.
잘못된 언어: 요청에 language 매개변수를 명시적으로 설정하세요.
부자연스러운 멈춤: 텍스트가 잘못된 경계에서 나뉠 수 있습니다. 특이한 문장 부호를 확인하세요.

플러그인 설정

포함된 플러그인(plugins/qwen-tts.json):

{
  "id": "qwen-tts",
  "name": "Qwen3 TTS",
  "type": "tts",
  "endpoint": "http://localhost:8100/v1/audio/speech",
  "auth": {
    "header": "",
    "key_env": ""
  },
  "model_map": [
    "qwen3-tts",
    "qwen3-tts-customvoice",
    "qwen3-tts-voicedesign",
    "qwen3-tts-clone"
  ],
  "capabilities": {
    "tts": {
      "endpoint": "http://localhost:8100/v1/audio/speech",
      "model_map": [
        "qwen3-tts",
        "qwen3-tts-customvoice",
        "qwen3-tts-voicedesign",
        "qwen3-tts-clone"
      ],
      "config": {
        "voices": [
          "Ryan",
          "Aiden",
          "Vivian",
          "Serena",
          "Uncle_Fu",
          "Dylan",
          "Eric",
          "Ono_Anna",
          "Sohee"
        ],
        "default_voice": "Ryan",
        "formats": ["wav"],
        "default_format": "wav",
        "max_characters": 10000,
        "supports_streaming": false,
        "no_auth_required": true
      }
    }
  },
  "description": "Qwen3-TTS local TTS server (NVIDIA CUDA, Apple MPS, or CPU)",
  "documentation_url": "https://github.com/QwenLM/Qwen3-TTS"
}

리소스

Qwen3-TTS GitHub - 공식 저장소
Qwen3-TTS 데모 - 온라인에서 사용해 보기
Alibaba Cloud TTS 문서 - Cloud API 문서

개요​

요구 사항​

플랫폼 지원​

빠른 시작​

1. 서버 설치​

2. 서버 시작​

3. Libre WebUI 설정​

4. 테스트​

사용 가능한 모델​

음성​

기본 음성(CustomVoice 모델)​

OpenAI 음성 별칭​

API 참조​

음성 생성​

음성 디자인​

음성 복제​

음성 목록​

상태 확인​

서버 설정​

네트워크 접근​

프로덕션 기능​

텍스트 정리​

텍스트 청크 분할​

다중 GPU 설정​

문제 해결​

모델 다운로드 실패​

메모리 부족(Apple Silicon)​

CUDA 메모리 부족​

서버 시간 초과​

오디오가 이상하게 들림​

플러그인 설정​

리소스​

개요