# 모델 업로드

Hub에 모델을 업로드하려면 [Hugging Face](https://huggingface.co/join)에서 계정을 생성해야 합니다. Hub의 모델은 [Git 기반 저장소](./repositories)로, 버전 관리, 브랜치, 검색 및 공유 기능, 수십 개의 라이브러리와의 통합 등을 제공합니다. 저장소에 업로드할 내용은 사용자가 직접 제어할 수 있으며, 체크포인트, 설정 파일, 기타 파일 등을 포함할 수 있습니다.

개별 사용자, 예: [osanseviero/fashion_brands_patterns](https://huggingface.co/osanseviero/fashion_brands_patterns), 또는 조직, 예: [facebook/bart-large-xsum](https://huggingface.co/facebook/bart-large-xsum)과 리포지토리를 연결할 수 있습니다. 조직은 회사, 커뮤니티 또는 라이브러리와 관련된 모델을 모을 수 있습니다! 조직을 선택하면 해당 모델은 조직 페이지에 소개되며, 조직의 모든 구성원은 리포지토리에 기여할 수 있습니다. 새 조직을 [여기](https://huggingface.co/organizations/new)에서 만들 수 있습니다.

> **_참고:_** 다운로드 메트릭을 얻으려면 Transformers/Diffusers 라이브러리와 호환될 필요가 없습니다. 모든 커스텀 모델이 지원됩니다. 아래에서 자세히 알아보세요!

모델을 업로드하여 Hub에 잘 통합되고 [다운로드 지표](models-download-stats)를 받을 수 있는 여러 가지 방법이 있으며, 아래에 설명되어 있습니다.

- 모델이 [내장 지원](#upload-from-a-library-with-built-in-support)이 있는 라이브러리를 위해 설계된 경우, 해당 라이브러리가 제공하는 메서드를 사용할 수 있습니다. `trust_remote_code=True`를 사용하는 커스텀 모델도 이러한 메서드를 활용할 수 있습니다.
- 모델이 커스텀 PyTorch 모델인 경우, Transformers, Diffusers, Timm 라이브러리의 모델처럼 `nn.Module` 클래스에 `from_pretrained`, `push_to_hub`를 추가할 수 있으므로 [`PyTorchModelHubMixin` 클래스](#upload-a-pytorch-model-using-huggingfacehub)를 활용할 수 있습니다.
- 프로그램을 통한 업로드 외에도 [웹 인터페이스](#using-the-web-interface) 또는 [git 명령줄](#using-git)을 항상 사용할 수 있습니다.

모델이 업로드되면, 모델에 대한 문서를 작성하고 검색 가능성을 높이기 위해 리포지토리에 [Model Card](./model-cards)를 추가하는 것을 권장합니다.

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/example_repository.png"
alt="drawing" width="600"/>

 [PyTorchModelHubMixin](#upload-a-pytorch-model-using-huggingfacehub)을 활용하는 [저장소](https://huggingface.co/LiheYoung/depth_anything_vitl14)의 예시입니다. 다운로드 횟수는 오른쪽에 표시됩니다.

## 웹 인터페이스 사용

새로운 모델 저장소를 만들려면 [huggingface.co/new](http://huggingface.co/new)으로 이동하세요. 다음 단계를 따르세요:

1. "Files and versions" 탭에서 "Add File"를 선택하고 "Upload File"을 지정합니다:

2. 그 후, 업로드할 파일을 컴퓨터에서 선택하고 업로드하는 내용을 알 수 있도록 유용한 커밋 메시지를 남겨야 합니다:

3. 이후 **Commit changes**를 클릭하여 모델을 Hub에 업로드하세요!

4. 파일 및 히스토리 검사

최근 추가된 모든 파일과 함께 저장소를 확인할 수 있습니다!

UI를 통해 모델 파일과 커밋을 탐색하고 각 커밋에서 도입된 diff를 확인할 수 있습니다:

5. 메타데이터 추가

모델 카드에 메타데이터를 추가할 수 있습니다. 다음을 지정할 수 있습니다:
* 이 모델이 수행하는 작업의 유형으로, 위젯과 Inference Providers를 활성화합니다.
* 사용된 라이브러리(`transformers`, `spaCy` 등)
* 언어
* 데이터셋
* metrics
* 라이선스
* 훨씬 더 많은 것들이 있습니다!

모델 태그에 대해 자세히 알아보려면 [여기](./model-cards#model-card-metadata)를 참조하세요.

6. TensorBoard 트레이스 추가

`tfevents`가 포함된 파일명이 있는 모든 저장소는 [`TensorBoard` 태그](https://huggingface.co/models?filter=tensorboard)로 분류됩니다. 관례적으로 트레이스를 `runs/` 하위 폴더에 저장하는 것을 권장합니다. 그러면 "Training metrics" 탭에서 loss나 accuracy와 같이 기록된 변수의 차트를 쉽게 검토할 수 있습니다.

🤗 Transformers로 학습된 모델은 [`tensorboard`](https://pypi.org/project/tensorboard/)가 설치되어 있으면 기본적으로 [TensorBoard traces](https://huggingface.co/docs/transformers/main_classes/callback#transformers.integrations.TensorBoardCallback)를 생성합니다.

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

모델이 Transformers, Diffusers, Timm, Asteroid 등 Hub에 push/load하는 기능을 내장 지원하는 라이브러리에서 온지 먼저 확인하세요: https://huggingface.co/docs/hub/models-libraries. 아래에서는 Transformers와 같은 라이브러리에서 이 작업이 얼마나 쉬운지 보여줍니다:

```python
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와 같은 일부 라이브러리는 [Hub에서 코드를 로드](https://huggingface.co/docs/transformers/custom_models)하는 기능을 지원합니다. 이는 `trust_remote_code=True` 플래그를 사용하여 Transformers와 함께 모델을 작동시키는 방법입니다. 완전한 라이브러리 통합 대신 이 옵션을 고려해 볼 수 있습니다.

## huggingface_hub를 사용하여 PyTorch 모델을 업로드

모델이 (사용자 정의) PyTorch 모델인 경우, [huggingface_hub](https://github.com/huggingface/huggingface_hub) Python 라이브러리에서 사용할 수 있는 `PyTorchModelHubMixin` [클래스](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin)를 활용할 수 있습니다. 이 클래스는 `nn.Module`에 `from_pretrained` 및 `push_to_hub` 기능과 다운로드 메트릭을 추가하는 최소한의 클래스입니다.

`pip install huggingface_hub`을 실행했다고 가정할 때, 사용 방법은 다음과 같습니다:

```python
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 dataclasses는 지원됩니다.

이 기능에는 자동화된 다운로드 지표가 포함되어 있어, Transformers, Diffusers 또는 Timm 라이브러리에 네이티브로 통합된 모델과 동일한 방식으로 모델이 몇 번 다운로드되었는지 확인할 수 있습니다. 이 mixin 클래스를 사용하면 각 개별 체크포인트는 2개의 파일로 구성된 단일 저장소로 Hub에 저장됩니다:

- 가중치를 포함하는 `pytorch_model.bin` 또는 `model.safetensors` 파일
- 모델 구성의 직렬화 버전인 `config.json` 파일입니다. 이 클래스는 다운로드 메트릭을 집계하는 데 사용됩니다. 사용자가 `config.json`을 로드하기 위해 `from_pretrained`를 호출할 때마다 카운트가 1 증가합니다. 자동화된 다운로드 메트릭에 대해서는 [이 가이드](https://huggingface.co/docs/hub/models-download-stats)를 참조하세요.

각 체크포인트에 모델 카드를 추가하여 모델에 대한 설명, 관련 논문 링크 등을 확인할 수 있도록 하는 것이 권장됩니다.

자세한 내용은 [huggingface_hub 문서](https://huggingface.co/docs/huggingface_hub/guides/integrations)를 참조하세요.

Alternatively, one can also simply programmatically upload files or folders to the hub: https://huggingface.co/docs/huggingface_hub/guides/upload.

## Git 사용

마지막으로, 모델 저장소는 Git 저장소이므로 Git을 사용하여 모델 파일을 Hub에 push할 수도 있습니다. [저장소 시작하기](repositories-getting-started#terminal) 가이드를 참고하여 `git` CLI를 사용해 모델을 commit하고 push하는 방법을 알아보세요.