이 리포는 어댑터 가중치만 포함합니다. 베이스 모델(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를 내려받아 같은 폴더에 두고:

python

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 가중치만 병합하고 이 단계를 생략하면 화자 목소리가 등록되지 않아 오류가 나거나 의도한 화자로 생성되지 않습니다.

python

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개 음식, 발음 문제로 확인된 것만)

원본 표기	TTS 입력용 리스펠링
Tteokbokki	Duck-bok-kee
Bibimbap	Bee-bim-bahp
Nakji Bokkeum	Nahk-jee Boh-kum
Agujjim	Ah-goo-jim
Maeuntang	May-oon-tang
Bibim Naengmyeon	Bee-bim Nang-myun
Cheonggukjang	Chung-gook-jang
Doenjang Jjigae	Dwen-jang Jee-geh
Dongtae Jjigae	Dong-teh Jee-geh
Dubu Kimchi	Doo-boo Kim-chee
Jeyuk Bokkeum	Jeh-yook Bok-kum
Kimchi Bokkeumbap	Kim-chee Bok-kum-bap
Kimchi Jjigae	Kim-chee Jee-geh
Kongguksu	Kong-gook-soo
Mulhoe	Mul-hweh
Ojingeo Bokkeum	Oh-jing-uh Bok-kum
Sundae	Soon-deh
Sundubu Jjigae	Soon-doo-boo Jee-geh
Tteokgalbi	Duck-gal-bee
Tteokguk	Duck-gook
Yukhoe	Yook-hweh

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

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

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

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

style	instruct
GUIDE	`Speak in a calm, informative tone, like a knowledgeable guide explaining something interesting. Keep a natural, steady pace, not slow.`
CAUTION	`Say it in an urgent, warning tone, as if cautioning someone.`

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

학습 정보

베이스 모델: 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)로 최종 검증 중

k-bite-team/k-menu-qwen3-tts-lora

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

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