# 빠른 시작

[Hugging Face Hub](https://huggingface.co/)은 머신러닝 모델, 데모, 데이터셋, 메트릭을 공유하는 데 가장 많이 사용되는 플랫폼입니다. `huggingface_hub` 라이브러리를 사용하면 개발 환경을 벗어나지 않고도 Hub와 상호작용할 수 있습니다. 저장소를 쉽게 생성하고 관리하고, 파일을 다운로드 및 업로드하고, Hub에서 유용한 모델 및 데이터셋 메타데이터를 가져올 수 있습니다.

## 설치

시작하려면 `huggingface_hub` 라이브러리를 설치하세요:

```bash
pip install --upgrade huggingface_hub
```

자세한 내용은 [설치](installation) 가이드를 확인하세요.

> [!TIP]
> `huggingface_hub`에는 터미널에서 Hub와 직접 상호작용할 수 있는 [`hf` CLI](./guides/cli)도 함께 제공됩니다. AI 에이전트(Claude Code, Codex, Cursor, ...)를 사용 중이라면 Skill을 설치하여 에이전트가 CLI를 사용할 수 있도록 하세요:
> ```bash
> # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
> hf skills add
> ```
> 자세한 내용은 [AI 에이전트를 위한 Hugging Face CLI](https://huggingface.co/docs/hub/agents-cli) 가이드를 참고하세요.

## 파일 다운로드

Hub의 저장소는 git 버전 관리되며, 사용자는 단일 파일 또는 전체 저장소를 다운로드할 수 있습니다. [hf_hub_download()](/docs/huggingface_hub/v2.4.0/ko/package_reference/file_download#huggingface_hub.hf_hub_download) 함수를 사용하여 파일을 다운로드할 수 있습니다. 이 함수는 파일을 로컬 디스크에 다운로드하고 캐시합니다. 해당 파일이 다시 필요할 때 캐시에서 로드되므로 다시 다운로드할 필요가 없습니다.

다운로드하려는 파일의 저장소 ID와 파일명이 필요합니다. 예를 들어, [Pegasus](https://huggingface.co/google/pegasus-xsum) 모델 구성 파일을 다운로드하려면:

```py
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")
```

특정 버전의 파일을 다운로드하려면 `revision` 매개변수를 사용하여 브랜치 이름, 태그 또는 커밋 해시를 지정하세요. 커밋 해시를 사용하는 경우, 짧은 7자 커밋 해시가 아닌 전체 길이의 해시를 사용해야 합니다:

```py
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )
```

자세한 내용과 옵션은 [hf_hub_download()](/docs/huggingface_hub/v2.4.0/ko/package_reference/file_download#huggingface_hub.hf_hub_download)의 API 참조를 확인하세요.

 

## 인증

많은 경우, Hub에서 작업하려면 Hugging Face 계정으로 인증해야 합니다. 예를 들어, 비공개 저장소를 다운로드하거나 파일을 업로드하거나 PR을 생성하는 경우입니다. 아직 계정이 없다면 [계정을 생성](https://huggingface.co/join)하세요.

### 로그인 명령

가장 쉬운 인증 방법은 [login()](/docs/huggingface_hub/v2.4.0/ko/package_reference/authentication#huggingface_hub.login) 명령을 사용하는 것입니다:

```bash
hf auth login
```

이미 로그인되어 있으면 해당 명령은 즉시 반환됩니다. 재로그인을 강제하려면 `hf auth login --force`를 사용하세요. 로그인되어 있지 않으면 브라우저로 로그인하도록 프롬프트가 표시됩니다: 출력된 URL을 열고, 짧은 코드를 입력하고, 요청을 승인하면 액세스 토큰이 검색되어 `HF_HOME` 디렉터리(기본값은 `~/.cache/huggingface/token`)에 저장됩니다. 토큰은 일정 시간 후 만료되지만 계속 사용하는 동안 자동으로 갱신됩니다. Hub와 상호작용하는 모든 스크립트 또는 라이브러리는 요청을 보낼 때 이 토큰을 사용합니다. 또는 [Settings page](https://huggingface.co/settings/tokens)에서 생성한 [User Access Token](https://huggingface.co/docs/hub/security-tokens)을 붙여넣을 수도 있습니다.

> [!TIP]
> User Access Tokens에는 `read` 또는 `write` 권한이 있습니다. 저장소를 생성하거나 편집하려면 `write` 액세스 토큰을 보유해야 합니다. 그렇지 않은 경우, 토큰이 실수로 유출되었을 때 위험을 줄이기 위해 `read` 토큰을 생성하는 것이 좋습니다.

대신, 노트북이나 스크립트에서 [login()](/docs/huggingface_hub/v2.4.0/ko/package_reference/authentication#huggingface_hub.login)을 사용하여 프로그래밍 방식으로 로그인할 수 있습니다:

```py
>>> from huggingface_hub import login
>>> login()
```

한 번에 하나의 계정으로만 로그인할 수 있습니다. 새 계정으로 로그인하면 이전 계정은 자동으로 로그아웃됩니다. 현재 활성 계정을 확인하려면 `hf auth whoami` 명령을 실행하면 됩니다.

> [!WARNING]
> 로그인 후 Hub에 대한 모든 요청은 인증이 반드시 필요한 메서드가 아니더라도 기본적으로 액세스 토큰을 사용합니다. 토큰의 암시적 사용을 비활성화하려면 `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`을 환경 변수로 설정해야 합니다([참고](../package_reference/environment_variables#hfhubdisableimplicittoken)).

### 로컬에서 여러 토큰 관리

각 토큰으로 [login()](/docs/huggingface_hub/v2.4.0/ko/package_reference/authentication#huggingface_hub.login) 명령을 실행하여 로컬 머신에 여러 토큰을 저장할 수 있습니다. 로컬에서 이 토큰들 사이를 전환해야 하는 경우 `auth switch` 명령을 사용할 수 있습니다:

```bash
hf auth switch
```

이 명령은 저장된 토큰 목록에서 이름을 기준으로 토큰을 선택하도록 프롬프트를 표시합니다. 선택이 완료되면 해당 토큰이 _활성_ 토큰이 되며, Hub와의 모든 상호작용에 사용됩니다.

`hf auth list`를 사용하여 머신에서 사용 가능한 모든 액세스 토큰을 나열할 수 있습니다.

### 환경 변수

환경 변수 `HF_TOKEN`도 인증에 사용할 수 있습니다. 이는 `HF_TOKEN`을 [Space secret](https://huggingface.co/docs/hub/spaces-overview#managing-secrets)으로 설정할 수 있는 Space에서 특히 유용합니다.

> [!TIP]
> **신규:** Google Colaboratory에서 노트북에 [개인 키](https://twitter.com/GoogleColab/status/1719798406195867814)를 정의할 수 있습니다. `HF_TOKEN` 시크릿을 정의하면 자동으로 인증됩니다!

환경 변수 또는 시크릿을 통한 인증은 머신에 저장된 토큰보다 우선합니다.

### 메서드 매개변수

마지막으로, `token`을 매개변수로 받는 모든 메서드에 토큰을 전달하여 인증하는 것도 가능합니다.

```
from huggingface_hub import whoami

user = whoami(token=...)
```

토큰을 영구적으로 저장하지 않거나 여러 토큰을 동시에 처리해야 하는 환경이 아닌 한, 이 방법은 일반적으로 권장되지 않습니다.

> [!WARNING]
> 토큰을 매개변수로 전달할 때는 주의가 필요합니다. 토큰은 코드베이스나 노트북에 하드코딩하는 대신 항상 보안 저장소에서 로드하는 것이 최선의 관행입니다. 코드를 실수로 공유할 경우, 하드코딩된 토큰은 심각한 유출 위험을 초래할 수 있습니다.

## 리포지토리 생성

등록 및 로그인 후 [create_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_repo) 함수를 사용하여 저장소를 생성합니다:

```py
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")
```

리포지토리를 비공개로 설정하려면:

```py
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)
```

Private repositories는 본인만 볼 수 있습니다.

> [!TIP]
> `write` 권한이 있는 User Access Token을 제공해야 Hub에 리포지토리를 생성하거나 콘텐츠를 push할 수 있습니다. [Settings page](https://huggingface.co/settings/tokens)에서 토큰을 생성할 때 권한을 선택할 수 있습니다.

## 파일 업로드

새로 생성한 저장소에 파일을 추가하려면 [upload_file()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.upload_file) 함수를 사용하세요. 다음을 지정해야 합니다:

1. 업로드할 파일의 경로입니다.
2. 저장소 내 파일의 경로입니다.
3. 파일을 추가하려는 저장소 ID

```py
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )
```

한 번에 여러 파일을 업로드하려면, git 사용 여부와 관계없이 파일을 업로드하는 여러 방법을 소개하는 [Upload](./guides/upload) 가이드를 참고하세요.

## 다음 단계

`huggingface_hub` 라이브러리를 사용하면 Python으로 Hub와 쉽게 상호작용할 수 있습니다. Hub에서 파일과 저장소를 관리하는 방법에 대해 자세히 알아보려면 다음을 위한 [가이드](./guides/overview)를 읽어보시는 것을 권장합니다:

- [리포지토리 관리](./guides/repository).
- Hub에서 [다운로드](./guides/download) 파일을 가져옵니다.
- [Upload](./guides/upload) 파일을 Hub에 업로드합니다.
- [Hub 검색](./guides/search)에서 원하는 모델 또는 데이터셋을 검색하세요.
- Hugging Face Hub에 호스팅된 모델에 대해 여러 서비스에서 [추론 실행](./guides/inference)