HuggingFace 모델 업로드 및 모델 로드

모델을 파인튜닝한 이후 GitHub에 업로드하여 버전 관리와 공유를 진행하려 했으나, 모델 파일의 용량이 커 GitHub의 업로드 제한을 초과하는 문제가 발생했다.
Git LFS를 사용하는 방법도 있었지만, 모델 자체를 배포하고 재사용하기에는 다소 번거롭다고 판단했다.

 

그래서 대안으로 Hugging Face Hub를 사용해 모델을 배포하기로 했다.
Hugging Face는 대규모 모델 파일을 관리하기에 적합하고, 모델의 목적과 사용법을 함께 정리할 수 있어 ㅍ관리 측면에도 장점이 있었다.

 

모델 업로드를 위해 가장 먼저 해야 할 일은 Hugging Face Access Token 발급이다.
이 토큰을 통해 로컬 환경에서 Hugging Face Hub에 인증하고, 학습한 모델을 직접 업로드할 수 있다.

 

Access Tokens

 

먼저 Hugging Face 계정의 Settings 메뉴로 이동한 뒤,
좌측 메뉴에서 Access Tokens 항목을 선택한다.
이후 `+ Create new token` 버튼을 클릭하여 새로운 토큰을 생성한다.

 

`Create new token`에서는 다음 세 가지 유형의 토큰을 생성할 수 있다.

• `Fine-grained`: 특정 저장소 단위로 세밀한 권한 설정이 가능한 토큰
• `Read`: 모델 및 데이터셋을 조회할 수 있는 읽기 전용 토큰
• `Write`: 모델과 데이터셋을 업로드 및 수정할 수 있는 토큰

현재 프로젝트에서는 모델 업로드가 필요했기 때문에 Write 토큰을 선택했다.

 

이후 `+ New Model` 메뉴를 통해 모델 저장소를 생성했다.
Private 저장소는 접근 권한이 제한되어 공유에 불편함이 있어, 파인튜닝한 모델을 Public 저장소로 설정했다.

라이선스는 상업적 사용을 제한하기 위해 CC BY-NC 4.0을 지정했다.(그냥 있어보이니까!)

새로운 모델 만들기

 

이렇게 설정을 하고 저장소에 들어가면 다음과 같은 화면이 뜬다.

`Push your model files`를 따라가면 모델을 이제 Hugging Face에 올릴 수 있다.

 

1. Hugging Face CLI 설치

공식 문서에서는 Hugging Face CLI 설치 방법으로 다음과 같은 PowerShell 명령을 안내하고 있다.

# Install the Hugging Face CLI
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

하지만 Hugging Face CLI는 pip을 통해서도 설치할 수 있으며, Python 개발 환경을 이미 사용하고 있다면 이 방법이 더 간편하다.

pip install -U huggingface_hub

2. Hugging Face 로그인

이제 여기서 아까 발급 받은 `Write` 토큰을 입력해주면 된다.

# (optional) Login with your Hugging Face credentials
hf auth login

3. 모델 업로드

모델이 있는 폴더 안에서 해당 명령어를 실행하면 된다.

# Push your model files
hf upload [username]/[repository-name] .

4. Hugging Face에 저장한 모델 로드

Hugging Face에 업로드된 모델은 보통 `AutoModel` 계열을 사용해 불러올 수 있다.
이 방식은 모델 종류에 상관없이 공통 인터페이스로 로드할 수 있어 가장 범용적이다.

from transformers import AutoProcessor, AutoModel

processor = AutoProcessor.from_pretrained(model_id)
model = AutoModel.from_pretrained(model_id)

여기서 `model_id`에는 Hugging Face Hub에 업로드한 모델의 저장소 ID(`username/ repository-name `)를 입력하면 된다.

 

 

이번에 프로젝트를 하면서 파인튜닝한 모델은 Wav2Vec2 기반의 음성 인식 모델로, 입력 전처리를 담당하는 Processor와 CTC 기반 추론을 수행하는 Model이 명확히 구분되어 있었다. 이러한 경우에는 AutoModel 대신 아래와 같이 구체적인 클래스를 사용해 모델을 로드하는 것이 일반적이다.

from transformers import Wav2Vec2Processor, Wav2Vec2ForCTC

processor = Wav2Vec2Processor.from_pretrained(model_id)
model = Wav2Vec2ForCTC.from_pretrained(model_id)

 

• Wav2Vec2Processor
  : 음성 입력을 모델이 처리할 수 있는 형태로 변환하는 전처리 객체
• Wav2Vec2ForCTC
  : 기반으로 음성을 텍스트(또는 음소)로 변환하는 모델

이 방식을 사용하면 모델 파일을 Github에 별도로 올리지 않아도(로컬에 저장하지 않아도), Hugging Face Hub에 업로드된 모델을 필요할 때마다 불러와 사용할 수 있다!