모델 업로드 (Uploading Models)

모델을 허브에 업로드하려면 Hugging Face 계정을 만들어야 해요. 허브의 모델은 Git 기반 저장소로, 버전 관리, 브랜치, 발견성, 공유 기능과 수십 개 라이브러리와의 통합을 제공해요. 저장소에 체크포인트, 설정, 그 밖의 파일 등 원하는 것을 무엇이든 업로드할 수 있어요.

저장소는 osanseviero/fashion_brands_patterns처럼 개인 사용자와 연결하거나, facebook/bart-large-xsum처럼 조직과 연결할 수 있어요. 조직은 회사·커뮤니티·라이브러리와 관련된 모델을 모을 수 있어요. 조직을 선택하면 모델이 조직 페이지에 노출되고, 조직의 모든 멤버가 저장소에 기여할 수 있어요. 새 조직은 여기에서 만들 수 있어요.

참고: 다운로드 지표를 얻기 위해 모델이 Transformers/Diffusers 라이브러리와 호환될 필요는 없어요. 모든 커스텀 모델이 지원돼요. 아래에서 자세히 다룰게요.

모델을 허브에 잘 통합하고 다운로드 지표를 받는 데는 여러 방법이 있어요.

모델이 내장 지원이 있는 라이브러리를 위해 설계된 경우, 해당 라이브러리가 제공하는 메서드를 쓸 수 있어요. trust_remote_code=True를 쓰는 커스텀 모델도 이 메서드를 활용할 수 있어요.
모델이 커스텀 PyTorch 모델이라면 PyTorchModelHubMixin 클래스를 활용할 수 있어요. Transformers, Diffusers, Timm 라이브러리의 모델처럼 어떤 nn.Module 클래스에도 from_pretrained, push_to_hub를 추가해 주죠.
프로그래밍 방식 업로드 외에도, 웹 인터페이스나 git 명령줄을 항상 쓸 수 있어요.

모델을 업로드한 뒤에는 저장소에 Model Card를 추가해 모델을 문서화하고 발견성을 높이는 걸 권장해요.

웹 인터페이스 사용

새 모델 저장소를 만들려면 huggingface.co/new를 방문하고 다음 단계를 따르세요.

"Files and versions" 탭에서 "Add File"을 선택하고 "Upload File"을 지정해요.
컴퓨터에서 업로드할 파일을 선택하고, 무엇을 올리는지 알 수 있게 도움이 되는 커밋 메시지를 남겨요.
그런 다음 Commit changes를 클릭해 모델을 허브에 업로드해요!
파일과 히스토리를 검사해요. 최근에 추가된 모든 파일과 함께 저장소를 확인할 수 있어요.
모델 카드에 메타데이터를 추가할 수 있어요. 지정할 수 있는 것들:
- 이 모델이 처리하는 작업 유형(위젯과 Inference Providers 활성화)
- 사용된 라이브러리(transformers, spaCy 등)
- 언어
- 데이터셋
- 지표
- 라이선스
- 그 외 여러 가지 모델 태그에 대한 자세한 내용은 여기를 참고하세요.
TensorBoard 추적을 추가해요. TensorBoard 추적(tfevents가 포함된 파일명)을 담고 있는 저장소는 TensorBoard 태그로 분류돼요. 관례상 추적은 runs/ 하위 폴더에 저장하는 걸 권장해요. 그러면 "Training metrics" 탭에서 손실이나 정확도 같은 로깅된 변수의 차트를 쉽게 볼 수 있어요.

🤗 Transformers로 훈련한 모델은 tensorboard가 설치되어 있으면 기본적으로 TensorBoard 추적을 생성해요.

내장 지원이 있는 라이브러리에서 업로드

먼저 모델이 허브에 푸시/로드할 수 있는 내장 지원이 있는 라이브러리(Transformers, Diffusers, Timm, Asteroid 등)에서 온 것인지 확인하세요: https://huggingface.co/docs/hub/models-libraries. Transformers 같은 라이브러리에선 얼마나 쉬운지 아래에서 보여드릴게요.

from transformers import BertConfig, BertModel

config = BertConfig()
model = BertModel(config)

model.push_to_hub("nielsr/my-awesome-bert-model")

# reload
model = BertModel.from_pretrained("nielsr/my-awesome-bert-model")

Transformers 같은 일부 라이브러리는 허브에서 코드를 로드하는 것을 지원해요. trust_remote_code=True 플래그로 모델을 Transformers에서 작동하게 만드는 방법이에요. 완전한 라이브러리 통합 대신 이 옵션을 고려해 볼 만해요.

huggingface_hub로 PyTorch 모델 업로드

모델이 (커스텀) PyTorch 모델이라면 huggingface_hub Python 라이브러리의 PyTorchModelHubMixin 클래스를 활용할 수 있어요. 어떤 nn.Module에도 from_pretrained와 push_to_hub 능력(다운로드 지표 포함)을 추가해 주는 최소한의 클래스예요.

사용법은 다음과 같아요(pip install huggingface_hub를 실행했다고 가정).

import torch
import torch.nn as nn
from huggingface_hub import PyTorchModelHubMixin


class MyModel(
    nn.Module,
    PyTorchModelHubMixin,
    # optionally, you can add metadata which gets pushed to the model card
    repo_url="your-repo-url",
    pipeline_tag="text-to-image",
    license="mit",
):
    def __init__(self, num_channels: int, hidden_size: int, num_classes: int):
        super().__init__()
        self.param = nn.Parameter(torch.rand(num_channels, hidden_size))
        self.linear = nn.Linear(hidden_size, num_classes)

    def forward(self, x):
        return self.linear(x + self.param)

# create model
config = {"num_channels": 3, "hidden_size": 32, "num_classes": 10}
model = MyModel(**config)

# save locally
model.save_pretrained("my-awesome-model")

# push to the hub
model.push_to_hub("your-hf-username/my-awesome-model")

# reload
model = MyModel.from_pretrained("your-hf-username/my-awesome-model")

보시다시피 유일한 요구사항은 모델이 PyTorchModelHubMixin을 상속받는 것이에요. 모든 인스턴스 속성은 config.json 파일로 자동 직렬화돼요. init 메서드의 인자는 JSON 직렬화가 가능한 것만 받을 수 있다는 점에 주의하세요. Python dataclass는 지원돼요.

자동 다운로드 지표도 함께 제공돼서, Transformers·Diffusers·Timm 라이브러리에 네이티브로 통합된 모델처럼 다운로드 횟수를 볼 수 있어요. 이 믹스인 클래스를 쓰면 각 체크포인트가 허브에 2개 파일로 구성된 단일 저장소로 저장돼요.

가중치를 담고 있는 pytorch_model.bin 또는 model.safetensors 파일
모델 설정의 직렬화 버전인 config.json 파일. 이 클래스는 다운로드 지표 계산에 사용돼요. 사용자가 config.json을 로드하려고 from_pretrained를 호출할 때마다 카운트가 하나씩 올라가요. 자동 다운로드 지표에 대한 이 가이드를 참고하세요.

각 체크포인트에 모델 카드를 추가해 사람들이 모델이 무엇인지, 논문 링크 등을 읽을 수 있게 하는 걸 권장해요. huggingface_hub의 통합에 대해 더 자세히 배우려면 문서를 방문하세요.

또는 파일이나 폴더를 허브에 프로그래밍 방식으로 단순히 업로드할 수도 있어요: https://huggingface.co/docs/huggingface_hub/guides/upload.

Git 사용

마지막으로, 모델 저장소는 그냥 Git 저장소이므로 Git으로 모델 파일을 허브에 푸시할 수도 있어요. git CLI로 커밋하고 푸시하는 법은 Repositories 시작하기 가이드를 따라 하세요.