[faster-qwen3-tts] 로컬 모델 경로를 HuggingFace Hub ID로 전환하여 배포 간소화

PR 링크: andimarafioti/faster-qwen3-tts#5 상태: Merged | 변경: +20 / -42

들어가며

ML 프로젝트에서 모델 경로를 로컬 파일 시스템에 하드코딩하면, 다른 환경에서 재현이 어려워지고 setup 스크립트가 복잡해집니다. 이 PR은 faster-qwen3-tts 프로젝트 전반에서 로컬 models/ 디렉토리 경로를 HuggingFace Hub ID(Qwen/Qwen3-TTS-12Hz-0.6B-Base)로 교체하고, 불필요한 config 파싱 로직을 제거하여 코드를 20줄 이상 줄인 사례입니다.

핵심 코드 분석

1. 모델 로딩 경로 전환 (benchmarks 전체)

모든 벤치마크 파일에서 동일한 패턴으로 변경이 이루어졌습니다.

Before:

MODEL_PATH = os.path.join(PROJECT_DIR, 'models', f'Qwen3-TTS-12Hz-{MODEL_SIZE}-Base')
model = Qwen3TTSModel.from_pretrained(
    MODEL_PATH, device_map='cuda:0', dtype=torch.bfloat16, local_files_only=True
)

After:

MODEL_ID = f'Qwen/Qwen3-TTS-12Hz-{MODEL_SIZE}-Base'
model = Qwen3TTSModel.from_pretrained(
    MODEL_ID, device_map='cuda:0', dtype=torch.bfloat16
)

os.path.join으로 로컬 경로를 조합하는 대신 HuggingFace Hub의 repo_id 형식을 사용합니다. local_files_only=True 플래그도 함께 제거되어, 캐시에 모델이 없으면 자동으로 다운로드됩니다.

2. config 파싱 로직 제거 (model.py)

from_pretrained 메서드에서 로컬 config.json 파일을 직접 읽어 파싱하던 복잡한 로직이 제거되었습니다.

Before:

from transformers import PretrainedConfig
import json

model_path = Path(model_name)
config_path = model_path / "config.json" if model_path.exists() else None
if config_path and config_path.exists():
    with open(config_path) as f:
        fc = json.load(f)
    pred_config = PretrainedConfig(**fc['talker_config']['code_predictor_config'])
    talker_hidden = fc['talker_config']['hidden_size']
else:
    pred_config = predictor.model.config
    talker_hidden = talker_config.hidden_size

After:

predictor = talker.code_predictor
pred_config = predictor.model.config
talker_hidden = talker_config.hidden_size

이미 로드된 모델 객체에서 config를 직접 추출하므로, json, PretrainedConfig import와 파일 I/O가 모두 불필요해졌습니다.

3. setup.sh 간소화

Before:

models_dir = os.path.join('$DIR', 'models')
os.makedirs(models_dir, exist_ok=True)
for model in ['Qwen3-TTS-12Hz-0.6B-Base', 'Qwen3-TTS-12Hz-1.7B-Base']:
    dest = os.path.join(models_dir, model)
    has_weights = os.path.exists(dest) and any(...)
    if has_weights:
        print(f'  {model}: already downloaded')
    else:
        snapshot_download(f'Qwen/{model}', local_dir=dest)

After:

for model in ['Qwen3-TTS-12Hz-0.6B-Base', 'Qwen3-TTS-12Hz-1.7B-Base']:
    repo_id = f'Qwen/{model}'
    snapshot_download(repo_id)

local_dir 지정을 제거하여 HuggingFace의 기본 캐시 디렉토리(~/.cache/huggingface)를 사용하도록 변경했습니다. 중복 다운로드 체크 로직도 huggingface_hub가 내부적으로 처리하므로 제거되었습니다.

왜 이게 좋은가

이 변경의 핵심 가치는 **"프레임워크가 이미 해결한 문제를 다시 풀지 않는다"**는 원칙에 있습니다. HuggingFace Hub은 모델 캐싱, 버전 관리, 다운로드 재개 등을 내부적으로 처리합니다. 로컬 경로를 직접 관리하면 이런 기능을 수동으로 구현해야 하고, 환경 간 이식성도 떨어집니다. Hub ID 방식으로 전환하면 pip install과 한 줄의 from_pretrained 호출만으로 어떤 환경에서든 동일하게 동작합니다.

정리

항목	Before	After
모델 경로	로컬 models/ 디렉토리	HuggingFace Hub ID
config 로딩	JSON 파일 직접 파싱	모델 객체에서 추출
캐시 관리	수동 체크	Hub 자동 캐싱
코드량	42줄 삭제	20줄 추가 (순감 22줄)

참고 자료

• HuggingFace Hub 문서
• PR #5

⚠️ 알림: 이 분석은 AI가 실제 코드 diff를 기반으로 작성했습니다.