k-menu-qwen3-tts-lora

K-Menu Voice Guide - Qwen3-TTS 1.7B LoRA Adapter

K-Menu Voice Guide 프로젝트 최종 TTS 어댑터. 영어 문장 속 한국 음식명 발음 개선(리스펠링) + GUIDE(안내)/CAUTION(경고) 스타일 톤 구분(instruct)까지 반영됨.

이 리포는 어댑터 가중치만 포함합니다. 베이스 모델(Qwen/Qwen3-TTS-12Hz-1.7B-Base)과 함께 로드해야 하며, 화자 등록(speaker config/embedding)까지 필요합니다 — 아래 inference.py가 이 과정을 전부 처리합니다.

사용법 (권장) — inference.py 그대로 사용

pip install qwen-tts peft soundfile huggingface_hub torch

이 리포에서 inference.py를 내려받아 같은 폴더에 두고:

from inference import generate_narration_audio

generate_narration_audio(
    narration_text="Careful, this one's spicy! Tteokbokki is chewy rice cakes simmered in a thick, spicy chili sauce.",
    style="CAUTION",  # 또는 "GUIDE"
    output_wav="output.wav",
)

narration_text는 화면에 표시할 원문 그대로 넘기면 됩니다 — 음식명 리스펠링과 스타일별 톤 지시(instruct)는 내부에서 자동으로 처리됩니다.

직접 로드하는 경우 (커스텀 통합 시 참고)

inference.py 없이 직접 통합하려면, 아래 3가지를 반드시 순서대로 적용해야 합니다. LoRA 가중치만 병합하고 이 단계를 생략하면 화자 목소리가 등록되지 않아 오류가 나거나 의도한 화자로 생성되지 않습니다.

import json
import torch
from huggingface_hub import snapshot_download
from peft import PeftModel
from peft.tuners.lora import LoraLayer
from safetensors.torch import load_file
from qwen_tts import Qwen3TTSModel

BASE_MODEL = "Qwen/Qwen3-TTS-12Hz-1.7B-Base"
ADAPTER_REPO = "k-bite-team/k-menu-qwen3-tts-lora"
SPEAKER_NAME = "speaker"
LORA_SCALE = 0.3  # 1.0은 거의 항상 깨진 결과가 나옵니다 (0.2~0.5 권장 범위)

adapter_dir = snapshot_download(repo_id=ADAPTER_REPO)

tts = Qwen3TTSModel.from_pretrained(
    BASE_MODEL, device_map="cuda:0", torch_dtype=torch.bfloat16, attn_implementation="sdpa",
)

# 1) LoRA를 scale 적용 후 병합
peft_model = PeftModel.from_pretrained(tts.model, adapter_dir)
for module in peft_model.modules():
    if isinstance(module, LoraLayer):
        module.set_scale(peft_model.active_adapter, LORA_SCALE)
tts.model = peft_model.merge_and_unload()

# 2) 화자 config 등록 (adapter_dir의 config.json에 저장된 talker_config를 병합)
core = tts.model
with open(f"{adapter_dir}/config.json", encoding="utf-8") as f:
    talker_config = json.load(f)["talker_config"]
core.config.talker_config.spk_id.update(talker_config.get("spk_id", {}))
core.config.talker_config.spk_is_dialect.update(talker_config.get("spk_is_dialect", {}))
core.config.tts_model_type = core.tts_model_type = "custom_voice"

# 3) 화자 임베딩 주입 (adapter_dir의 speaker_embedding.safetensors)
payload = load_file(f"{adapter_dir}/speaker_embedding.safetensors")
spk_id = core.config.talker_config.spk_id[SPEAKER_NAME]
w = core.talker.model.codec_embedding.weight
w.data[spk_id] = payload["target_speaker_embedding"].to(device=w.device, dtype=w.dtype)
core.eval()

wavs, sr = tts.generate_custom_voice(
    text="Careful, this one's spicy! Duck-bok-kee is chewy rice cakes simmered in a thick, spicy chili sauce.",
    speaker=SPEAKER_NAME,
    language="auto",
    instruct="Say it in an urgent, warning tone, as if cautioning someone.",
)

위 텍스트에 "Duck-bok-kee"처럼 이미 리스펠링된 표기를 직접 쓴 것에 주의하세요 — 직접 로드하는 경우, 리스펠링 자동 치환(아래 표 참고)은 inference.py의 apply_respelling()을 그대로 가져다 써야 적용됩니다.

리스펠링 표 (21개 음식, 발음 문제로 확인된 것만)

(위 표에 없는 나머지 29개 음식은 원본 표기 그대로 사용 — 청취 테스트로 이미 확인됨)

화면에 표시되는 텍스트(narration_text)는 원본 로마자 표기를 그대로 유지하고, TTS 입력 시에만 이 표로 치환합니다. 최종 학습 데이터에도 이 치환된 텍스트가 반영되어 있습니다.

instruct 문구 (스타일별 톤 제어)

강도 단계별(약함→중간→강함→극단) 및 언어(영어 vs 중국어) 비교 청취로 확정:

이 파라미터는 재학습 없이 임의의 체크포인트에서 즉시 적용됩니다.

학습 정보

• 베이스 모델: Qwen/Qwen3-TTS-12Hz-1.7B-Base
• 방식: LoRA (community patch, rank=16, alpha=32, target=q/k/v/o_proj + gate/up/down_proj)
• 하이퍼파라미터: LR 5e-6, 40 epoch(체크포인트: epoch 39), batch_size 4, bf16, lora_scale 0.3
• 데이터: 나레이션 50개 + 발음 캐리어 250개(실제 녹음), CAUTION 클래스 3배 오버샘플링, 리스펠링 21개 반영
• 하이퍼파라미터 탐색: LR(5e-6/1e-5/2e-5) × rank(16/32) 5개 조합 + 100epoch 연장 실험까지 총 8차, Val Loss 8.86~8.89대 수렴 확인(데이터 규모 한계로 판단)

알려진 한계

• 한국어 된소리(ㄸ,ㅃ,ㄲ,ㅆ,ㅉ)는 영어 알파벳 표기로 완벽히 재현 불가 (근사치로 타협)
• CAUTION 스타일 학습 데이터가 전체의 8%로 적어, instruct 없이는 GUIDE와의 톤 구분이 약함 (반드시 instruct 파라미터와 함께 사용 권장)
• 자동 평가(UTMOS)에서 리스펠링이 일부 음식(5개)의 발화 자연스러움을 오히려 낮추는 트레이드오프 확인 — 발음 정확성과 유창함은 서로 다른 축이며, 정식 사람 평가(MOS)로 최종 검증 중