개요

이 문서는 리눅스 시스템에서 고성능 음성 합성 모델인 Qwen3-TTS-12Hz-1.7B-Base를 빠르게 설치하고 실행하는 방법을 안내합니다. 이 모델은 단 3초의 샘플 음성을 기반으로 목소리를 복제할 수 있으며, 다양한 텍스트 입력에 대해 자연스러운 음성을 생성해줍니다.

특히 Ubuntu 기반의 리눅스 사용자를 중심으로 설명하며, 시스템 준비부터 의존성 설치, 모델 다운로드 및 서비스 구동까지 전 과정을 단계별로 소개합니다. GPU 메모리 부족 시 대처 방법도 함께 제공합니다.

시스템 요구사항

• 운영체제: Ubuntu 18.04 이상 (또는 다른 Linux 배포판)
• GPU: 최소 8GB VRAM 권장 (RTX 3070 이상 추천)
• RAM: 최소 16GB 이상
• 저장 공간: 최소 20GB 이상 여유 공간 필요

먼저 시스템 패키지를 업데이트합니다:

sudo apt update && sudo apt upgrade -y

필수 도구 설치:

sudo apt install -y wget curl git python3 python3-pip python3-venv

파이썬 가상환경 설정 및 의존성 설치

프로젝트용 가상 환경을 생성하고 활성화합니다:

python3 -m venv tts-env
source tts-env/bin/activate

CUDA 버전에 맞는 PyTorch 설치:

# CUDA 11.8용
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# 또는 CUDA 12.1용
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

필요한 라이브러리 설치:

pip install qwen3-tts transformers accelerate soundfile

(선택 사항) 더 빠른 처리를 위한 FlashAttention 설치:

pip install -U flash-attn --no-build-isolation

모델 파일 다운로드

Hugging Face CLI를 통해 모델 다운로드:

pip install huggingface_hub
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base --local-dir ./tts_model

혹은 Git LFS 사용:

sudo apt install -y git-lfs
git lfs install
git clone https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-Base ./tts_model

완료 후 다음 파일들이 포함되어 있는지 확인하세요:

• config.json
• pytorch_model.bin 혹은 .safetensors
• tokenizer 관련 설정 파일들

서비스 시작 및 테스트

웹 인터페이스 실행:

qwen-tts-demo ./tts_model --ip 0.0.0.0 --port 8000

브라우저에서 http://localhost:8000 으로 접속하면 UI를 사용할 수 있습니다.

직접 코드로 테스트하려면 아래 스크립트를 참고하세요:

import torch
from qwen_tts import Qwen3TTSModel
import soundfile as sf

# 모델 로드
model = Qwen3TTSModel.from_pretrained(
    "./tts_model",
    device_map="auto",
    torch_dtype=torch.float16,
)

# 샘플 오디오 경로와 텍스트 지정
ref_audio_path = "your_sample_audio.wav"
reference_text = "샘플 오디오의 원본 텍스트입니다."

# 음성 생성
input_text = "안녕하세요! 이것은 테스트 음성입니다."
audio_data, sr = model.generate_voice_clone(
    text=input_text,
    language="Korean",
    ref_audio=ref_audio_path,
    ref_text=reference_text,
)

# 결과 저장
sf.write("generated_output.wav", audio_data[0], sr)
print("음성이 성공적으로 생성되었습니다.")

VRAM 부족 문제 해결

VRAM이 충분하지 않은 경우 아래와 같은 방법들을 적용할 수 있습니다.

1. FP16 정밀도 사용

model = Qwen3TTSModel.from_pretrained(
    "./tts_model",
    device_map="auto",
    torch_dtype=torch.float16,
)

2. CPU 오프로딩 설정

model = Qwen3TTSModel.from_pretrained(
    "./tts_model",
    device_map="auto",
    offload_folder="./cpu_offload_cache",
)

3. 배치 크기 조절

audio_data, sr = model.generate_voice_clone(
    text=input_text,
    language="Korean",
    ref_audio=ref_audio_path,
    ref_text=reference_text,
    batch_size=1,
)

4. CPU 전용 실행

model = Qwen3TTSModel.from_pretrained(
    "./tts_model",
    device_map="cpu",
)

자주 발생하는 문제 및 해결법