[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를 기반으로 작성했습니다.