# Xet Storage 사용

## Python

Xet을 지원하는 `huggingface_hub` 버전에 액세스하려면 최신 버전을 설치하면 됩니다:

```bash
pip install -U huggingface_hub
```

`huggingface_hub` 0.32.0부터 이 패키지는 `hf_xet`도 함께 설치합니다. `hf_xet` 패키지는 Xet 백엔드의 Rust 클라이언트인 [`xet-core`](https://github.com/huggingface/xet-core)와 `huggingface_hub`를 통합합니다.

`transformers` 또는 `datasets` 라이브러리를 사용하는 경우 이미 `huggingface_hub`를 사용하고 있습니다. `huggingface_hub` 버전이 >= 0.32.0이면 추가 조치가 필요하지 않습니다.

`huggingface_hub`의 버전이 >= 0.30.0이고 < 0.32.0인 경우, `hf_xet`을 명시적으로 설치해야 합니다:

```bash
pip install -U hf-xet
```

그리고 끝입니다! 이제 업로드와 다운로드 모두에서 Xet 중복 제거의 이점을 누릴 수 있습니다. `huggingface_hub`의 0.30.0 미만 버전을 사용하는 팀 구성원은 여전히 [LFS 브리지에서 제공하는 하위 호환성](legacy-git-lfs#backward-compatibility-with-lfs)을 통해 저장소를 업로드하고 다운로드할 수 있습니다.

자세한 사용법을 보려면 다음 항목의 `huggingface_hub` 문서를 참고하세요:

- [업로드](https://huggingface.co/docs/huggingface_hub/guides/upload#faster-uploads)
- [다운로드](https://huggingface.co/docs/huggingface_hub/guides/download#faster-downloads)
- [Managing the `hf_xet` cache](https://huggingface.co/docs/huggingface_hub/guides/manage-cache#chunk-based-caching-xet)

## Git

Git 사용자는 Git Xet 확장 기능을 다운로드하여 설치함으로써 Xet의 이점을 활용할 수 있습니다. 설치 후 [Git으로 Hub 저장소를 관리하는 표준 워크플로우](../repositories-getting-started)를 그대로 사용하면 되며, 추가적인 변경은 필요하지 않습니다.

### 필수 조건

[Git](https://git-scm.com/)과 [Git LFS](https://git-lfs.com/)를 설치합니다.

### macOS 또는 Linux(amd64 또는 aarch64)에 설치

터미널에서 다음 명령을 사용하여 설치 스크립트로 설치합니다(`curl` 및 `unzip` 필요):
```
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/huggingface/xet-core/refs/heads/main/git_xet/install.sh | sh
```

또는 [Homebrew](https://brew.sh/)를 사용하여 설치할 수 있습니다:
```
brew install git-xet
git xet install
```

설치를 확인하려면 다음을 실행하세요:
```
git xet --version
```

### Windows (amd64)

`winget` 사용:
```
winget install git-xet
```

설치 프로그램 사용:
 - `git-xet-windows-installer-x86_64.zip`를 [여기](https://github.com/huggingface/xet-core/releases/download/git-xet-v0.2.0/git-xet-windows-installer-x86_64.zip)에서 다운로드한 후 압축을 풉니다.
 - `msi` 설치 파일을 실행하고 프롬프트에 따라 진행합니다.

수동 설치:
 - `git-xet-windows-x86_64.zip`를 [여기](https://github.com/huggingface/xet-core/releases/download/git-xet-v0.2.0/git-xet-windows-x86_64.zip)에서 다운로드한 후 압축을 풉니다.
 - `git-xet.exe`를 `PATH` 디렉터리 아래에 배치하세요.
 - 터미널에서 `git xet install`을 실행합니다.

설치를 확인하려면 다음을 실행하세요:
  ```
  git xet --version
  ```

### Git Xet 사용

플랫폼에 설치한 후, Git Xet를 사용하는 것은 Hub의 표준 Git 워크플로우를 따르는 것만큼 간단합니다.

모든 [사전 요구 사항이 설치 및 구성되었는지](https://huggingface.co/docs/hub/repositories-getting-started#requirements) 확인하고, [Hub에서 저장소 작업을 위한 설정 지침](https://huggingface.co/docs/hub/repositories-getting-started#set-up)을 따른 후 변경 사항을 커밋하고 Hub에 `push`합니다:

  ```
  # Create any files you like! Then...
  git add .
  git commit -m "Uploading new models"  # You can choose any descriptive message
  git push
  ```
내부적으로 [Xet 프로토콜](https://huggingface.co/docs/xet/index)이 호출되어 대용량 파일이 Xet 스토리지에 직접 업로드되며, [청크 수준 중복 제거](./deduplication)의 힘으로 업로드 속도가 향상됩니다.

### macOS 또는 Linux에서 설치 해제

Homebrew 사용:
```bash
git xet uninstall
brew uninstall git-xet
```
설치 스크립트(MacOS 또는 Linux용)를 사용했다면 터미널에서 다음을 실행하세요:
```bash
git xet uninstall
sudo rm $(which git-xet)
```
### Windows에서 설치 해제

`winget`을 사용했다면:
```
winget uninstall git-xet
```

설치 프로그램을 사용했다면:
-  Settings -> Apps -> Installed apps로 이동합니다
- "Git-Xet"을 찾습니다.
- 컨텍스트 메뉴에서 사용 가능한 "Uninstall" 옵션을 선택합니다.

수동으로 설치한 경우:
- 터미널에서 `git xet uninstall`를 실행합니다.
- `git-xet.exe` 파일을 원래 설치된 위치에서 삭제합니다.

## 권장 사항

Xet은 Hub의 모든 워크플로와 원활하게 통합됩니다. 그러나 Xet 스토리지의 이점을 최대한 활용하려면 몇 가지 단계를 고려해 보시기 바랍니다.

Python으로 업로드 또는 다운로드할 때:

- **`hf_xet`이 설치되어 있는지 확인**합니다: Xet는 Git LFS에 최적화된 레거시 클라이언트와 하위 호환성을 유지하지만, `hf_xet`의 `huggingface_hub` 통합은 최적의 청크 기반 성능과 대용량 파일에 대한 더 빠른 반복을 제공합니다.
- **적응형 동시성은 기본적으로 활성화되어 있습니다**: `hf_xet`은 실시간 네트워크 조건에 따라 병렬 전송 스트림의 수를 자동으로 조정합니다 — 설정이 필요하지 않습니다. 기본 설정은 조정 없이 대부분의 네트워크 경로를 포화 상태로 만듭니다.
- **다운로드 버퍼는 시스템 메모리에 따라 확장됩니다**: `hf_xet` 1.7.0부터, 다운로드 버퍼 크기는 컨테이너 메모리 한도를 포함하여 `hf_xet`에 사용 가능한 메모리를 기준으로 설정됩니다. 작은 컨테이너는 다운로드에 더 적은 메모리를 사용하고, 큰 머신은 더 많은 메모리를 사용하며, 별도의 설정이 필요하지 않습니다. [다운로드 버퍼](#download-buffers)를 참조하세요.
- **고급 튜닝**: 세밀한 제어를 위해 `HF_XET_FIXED_DOWNLOAD_CONCURRENCY`와 `HF_XET_FIXED_UPLOAD_CONCURRENCY`를 사용하면 적응형 컨트롤러를 우회하여 병렬성을 고정된 값으로 고정할 수 있습니다. 전체 옵션 목록은 `hf_xet`의 [환경 변수](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#xet)를 참조하세요.

Git 또는 Python에서 업로드 또는 다운로드할 때:

- **자주적인 증분 커밋 활용**: Xet의 청크 수준 중복 제거 기능 덕분에 모델이나 데이터셋에 안전하게 증분 업데이트를 수행할 수 있습니다. 변경된 청크만 업로드되므로, 자주 커밋해도 빠르고 저장소 효율적입니다.
- **.gitattributes에서 구체적으로 지정**: Xet 또는 LFS 패턴을 정의할 때는 `*.safetensors`, `*.bin`와 같이 정확한 파일 확장자를 사용하여 작은 파일이 불필요하게 대용량 파일 저장소로 라우팅되는 것을 방지하세요.
- **커뮤니티 접근성 우선**: Xet은 대용량 파일 전송의 효율성과 규모를 크게 향상시킵니다. 저장소의 전체 크기(또는 개별 파일의 크기)를 줄이기 위해 저장소를 구성하는 대신, 협업자와 커뮤니티 사용자가 필요한 콘텐츠를 쉽게 탐색하고 가져갈 수 있도록 구성하세요.

## 환경 변수

`hf_xet`과 Git Xet 모두 `xet-core`를 기반으로 작동하며, 환경 변수를 통해 설정할 수 있습니다. 아래 표에는 세밀한 제어를 위한 개별 변수가 나열되어 있습니다. 대부분의 사용자는 이 변수를 변경할 필요가 없습니다. 기본값은 대부분의 네트워크 경로를 자동으로 포화 상태로 유지하도록 조정되어 있습니다.

> [!NOTE]
> `HF_XET_HIGH_PERFORMANCE=1`은 여러 설정을 한 번에 조정하는 편의 플래그입니다(동시성 한계, 버퍼 크기, 병렬 파일 제한). 이 플래그는 대역폭이 높고 디스크 속도가 빠른 머신을 위해 설계되었습니다. `hf_xet` 1.7.0부터 이 플래그가 설정하는 버퍼 크기는 `hf_xet`에 사용 가능한 메모리를 기준으로 결정됩니다([다운로드 버퍼](#download-buffers) 참조). 따라서 더 이상 64 GB의 RAM이 필요하지 않으며, 사용자가 직접 설정한 변수가 이 플래그보다 우선합니다. 이전 버전에서는 최소 64 GB의 RAM이 있는 머신에서만 이 플래그를 사용해야 합니다.

### 일반

대부분의 사용자가 가장 먼저 사용하는 고급 플래그입니다.

| 환경 변수 | 기본값 | 설명 |
|---|---|---|
| `HF_XET_HIGH_PERFORMANCE` (별칭 `HF_XET_HP`) | off | 동시성, 버퍼 크기, 병렬 파일 한도를 한 번에 높여 네트워크와 CPU 사용률을 최대화하는 편의 플래그입니다. 위의 참고 사항을 확인하세요. |
| `HF_XET_CACHE` | `$HF_HOME/xet` | Xet이 데이터를 로컬에 캐시하는 디렉터리(다운로드된 청크 및 중복 제거 샤드). `HF_HOME`보다 우선합니다. |

### 적응형 동시성

기본적으로 `xet-core`는 적응형 동시성(adaptive concurrency)을 사용합니다. 이는 실시간 네트워크 상태에 따라 병렬성을 동적으로 조정하는 방식입니다. 이러한 설정은 고급 옵션으로, 대부분의 경우 필요하지 않습니다. 아래 변수는 적응형 컨트롤러의 동작을 제어합니다:

| 환경 변수 | 기본값 | 설명 |
|---|---|---|
| `HF_XET_CLIENT_ENABLE_ADAPTIVE_CONCURRENCY` | `true` | 적응형 동시성 제어(adaptive concurrency control)를 활성화하거나 비활성화합니다. 비활성화하면 동시성 값이 초기 값으로 유지됩니다. |
| `HF_XET_CLIENT_AC_INITIAL_UPLOAD_CONCURRENCY` | `1` | 동시 업로드 스트림의 시작 개수. HP 모드: `16`. |
| `HF_XET_CLIENT_AC_INITIAL_DOWNLOAD_CONCURRENCY` | `1` | 동시 다운로드 스트림의 시작 개수. HP 모드: `16`. |
| `HF_XET_CLIENT_AC_MIN_UPLOAD_CONCURRENCY` | `1` | 업로드 동시성 하한. HP 모드: `4`. |
| `HF_XET_CLIENT_AC_MIN_DOWNLOAD_CONCURRENCY` | `1` | 다운로드 동시성 하한. HP 모드: `4`. |
| `HF_XET_CLIENT_AC_MAX_UPLOAD_CONCURRENCY` | `64` | 업로드 동시성 상한. HP 모드: `124`. |
| `HF_XET_CLIENT_AC_MAX_DOWNLOAD_CONCURRENCY` | `64` | 다운로드 동시성 상한. HP 모드: `124`. |
| `HF_XET_CLIENT_AC_TARGET_RTT` | `60s` | Target round-trip time. 전체 전송에 대한 예측 왕복 시간이 이 값보다 낮을 때까지 동시성(concurrency)이 증가합니다. |
| `HF_XET_CLIENT_AC_MAX_HEALTHY_RTT` | `90s` | 허용되는 최대 왕복 시간입니다. 이 시간보다 오래 걸리는 전송은 적응형 컨트롤러에 의해 실패로 집계됩니다. |
| `HF_XET_CLIENT_AC_HEALTHY_SUCCESS_RATIO_THRESHOLD` | `0.8` | 컨트롤러가 동시성을 증가시키는 임계값인 성공률. |
| `HF_XET_CLIENT_AC_UNHEALTHY_SUCCESS_RATIO_THRESHOLD` | `0.5` | 컨트롤러가 동시성을 감소시키는 임계 성공률. |
| `HF_XET_CLIENT_AC_LOGGING_INTERVAL_MS` | `10000` | 동시성 상태가 기록되는 간격(ms). |

> [!TIP]
> 동시성을 고정된 값으로 고정하려면(적응형 컨트롤러를 우회하려면) 편의 별칭 `HF_XET_FIXED_UPLOAD_CONCURRENCY`와 `HF_XET_FIXED_DOWNLOAD_CONCURRENCY`를 사용하세요. 이 별칭들은 초기, 최소, 최대 동시성을 동일한 값으로 설정합니다.

### 네트워크 및 재시도

| 환경 변수 | 기본값 | 설명 |
|---|---|---|
| `HF_XET_CLIENT_RETRY_MAX_ATTEMPTS` | `5` | 요청 실패 시 최대 재시도 횟수. |
| `HF_XET_CLIENT_RETRY_BASE_DELAY` | `3000ms` | 재시도 간 기본 지연 시간(지수적 백오프 사용). |
| `HF_XET_CLIENT_RETRY_MAX_DURATION` | `360s` | 요청을 재시도하는 데 사용할 최대 총 시간. |
| `HF_XET_CLIENT_CONNECT_TIMEOUT` | `60s` | TCP 연결 시간 초과. |
| `HF_XET_CLIENT_READ_TIMEOUT` | `120s` | HTTP 응답에 대한 읽기 시간 초과입니다. |
| `HF_XET_CLIENT_IDLE_CONNECTION_TIMEOUT` | `60s` | 유휴 연결이 닫히기 전까지의 타임아웃입니다. |
| `HF_XET_CLIENT_MAX_IDLE_CONNECTIONS` | `16` | 풀의 유휴 연결 최대 수. |

### 데이터 전송

| 환경 변수 | 기본값 | 설명 |
|---|---|---|
| `HF_XET_DATA_MAX_CONCURRENT_FILE_INGESTION` | `8` | 업로드 중에 동시에 처리되는 파일의 최대 수. HP 모드: `100`. |
| `HF_XET_DATA_MAX_CONCURRENT_FILE_DOWNLOADS` | `8` | 동시에 다운로드할 수 있는 최대 파일 수. |
| `HF_XET_DATA_INGESTION_BLOCK_SIZE` | `8mb` | Size of blocks read during file ingestion. |
| `HF_XET_DATA_PROGRESS_UPDATE_INTERVAL` | `200ms` | 진행 바가 업데이트되는 빈도. |
| `HF_XET_DATA_PROGRESS_UPDATE_SPEED_SAMPLING_WINDOW` | `10s` | 진행 상황 보고에서 전송 속도 측정치를 집계하는 데 사용되는 시간 창입니다. |

### 다운로드 버퍼

이 설정들은 다운로드 중 메모리 사용량을 제어합니다.

`hf_xet` 1.7.0부터 세 개의 `DOWNLOAD_BUFFER` 변수 기본값은 `hf_xet`가 사용할 수 있는 메모리 양을 기준으로 설정됩니다. 이는 머신의 RAM 또는, 그 값이 더 낮은 경우 컨테이너의 메모리 한도입니다. 각 기본값은 해당 메모리의 일부이며, 표에 표시된 최소값과 최대값 사이로 유지됩니다. HP 모드에서는 동일한 최소값과 최대값을 유지하면서 배수를 두 배로 사용합니다. 예를 들어, 4 GB로 제한된 컨테이너는 1 GB 한도로 약 256 MB의 버퍼를, 32 GB 머신은 이전 버전과 마찬가지로 약 2 GB의 버퍼와 8 GB의 한도를 얻습니다.

이전 버전 또는 사용 가능한 메모리 용량을 파악할 수 없는 버전은 `2gb`, `512mb`, `8gb` (HP 모드에서는 `16gb`, `2gb`, `64gb`)의 고정 기본값을 사용합니다. 사용 중인 값은 시작 시 `hf_xet` 로그 파일에 기록됩니다([로깅](#logging) 참조).

| 환경 변수 | 기본값 | HP 모드 | 설명 |
|---|---|---|---|
| `HF_XET_RECONSTRUCTION_MIN_RECONSTRUCTION_FETCH_SIZE` | `256mb` | `1gb` | 재구성 요청의 최소 가져오기 크기. |
| `HF_XET_RECONSTRUCTION_MAX_RECONSTRUCTION_FETCH_SIZE` | `8gb` | `16gb` | 재구성 요청의 최대 가져오기 크기. |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_SIZE` | 메모리의 1/16, `64mb`에서 `16gb` | 메모리의 1/8 | 기본 공유 버퍼 예산. |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_PERFILE_SIZE` | 메모리의 1/64, `16mb`에서 `2gb` | 메모리의 1/32 | 활성 파일당 추가 버퍼 예산. |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_LIMIT` | 메모리의 1/4, `264mb`에서 `64gb` | 메모리의 1/2 | 다운로드 버퍼 메모리의 총량에 대한 하드 제한입니다. `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_SIZE`가 이 값보다 높게 설정된 경우, 제한이 해당 값에 맞춰 상향 조정됩니다. |
| `HF_XET_DISABLE_MEMORY_DERIVED_DOWNLOAD_BUFFERS` | unset | — | 가용 메모리에서 버퍼 크기를 설정하는 대신 고정된 기본값을 사용하려면 `1`로 설정합니다. |
| `HF_XET_RECONSTRUCTION_TARGET_BLOCK_COMPLETION_TIME` | `15m` | — | prefetch 블록을 완료하는 데 걸리는 목표 시간. 다운로드 중에 미리 가져올 데이터의 양을 결정하는 데 사용됩니다. |
| `HF_XET_RECONSTRUCTION_MIN_PREFETCH_BUFFER` | `1gb` | — | 다운로드 중 예상 완료 시간과 관계없이 사전 가져오기를 위해 유지할 최소 데이터량. |

### Shard Cache

**shard cache**는 디스크의 Xet 캐시 디렉터리 아래에 중복 제거 인덱스(이미 업로드된 청크를 설명하는 "shards")를 저장합니다. 캐시가 클수록 클라이언트는 이전에 확인한 더 많은 데이터와 중복을 제거할 수 있어, 다시 업로드되는 바이트 수가 줄어듭니다.

| 환경 변수 | 기본값 | 설명 |
|---|---|---|
| `HF_XET_SHARD_CACHE_SIZE_LIMIT` | `16gb` | 디스크 상의 샤드 캐시에 대한 소프트 캡입니다. 캐시는 실행의 **시작** 시점에 이 크기로 정리되지만, 단일 장시간 실행 세션 내에서 이 크기를 초과하여 증가할 수 있습니다. 대략적인 가이드로, 크기가 *X*인 캐드는 약 1000 × *X* 크기의 데이터에 대해 중복 제거를 수행합니다(16 GB → 약 16 TB). 매우 큰 저장소에서 더 나은 중복 제거를 위해 값을 높이고, 증가하는 캐시가 디스크를 가득 채울 위험이 있다면 값을 낮추세요. 사람이 읽을 수 있는 크기(예: `32gb`) 또는 원시 바이트 수를 허용합니다. |
| `HF_XET_SHARD_CHUNK_INDEX_TABLE_MAX_SIZE` | `64mb` | 메모리 내 청크 인덱스의 최대 크기. 이 크기에 도달하면 중복 제거를 위해 더 이상의 청크는 로드되지 않습니다. |
| `HF_XET_SHARD_CACHE_SUBDIR` | `shard-cache` | Xet 캐시 디렉터리 내 샤드 캐시를 위한 하위 디렉터리. |

### Chunk Cache

`hf_xet`은 더 이상 다운로드에 로컬 청크 캐시를 사용하지 않습니다. 다운로드된 파일은 여전히 `huggingface_hub` 파일 기반 캐시에 저장됩니다.

| 환경 변수 | 기본값 | 설명 |
|---|---|---|
| `HF_XET_CHUNK_CACHE_SIZE_BYTES` | — | `hf_xet`에서 더 이상 사용되지 않습니다. 이 값을 설정해도 다운로드 청크 캐시가 활성화되지 않습니다. |

### 로깅

| 환경 변수 | 기본값 | 설명 |
|---|---|---|
| `HF_XET_LOG_DEST` | (none) | 로그 저장 위치. 파일 경로 또는 디렉터리 경로(`/`로 끝나는)를 허용합니다. 디렉터리로 설정하면 타임스탬프가 포함된 이름으로 로그 파일이 생성됩니다. 빈 문자열로 설정하면 로그가 콘솔로 출력됩니다. 설정되지 않으면 Hugging Face Xet 캐시 디렉터리의 `logs/` 하위 디렉터리로 로그가 저장됩니다. |
| `HF_XET_LOG_FORMAT` | (none) | 로그 형식. JSON 형식의 로그를 사용하려면 `json`으로 설정합니다. 그렇지 않으면 일반 텍스트를 사용합니다. 기본적으로 파일 로그는 JSON, 콘솔 로그는 텍스트를 사용합니다. |
| `HF_XET_LOG_PREFIX` | `xet` | 디렉터리에 로깅할 때 로그 파일 이름에 사용되는 접두사. |
| `HF_XET_LOG_DIR_DISABLE_CLEANUP` | `false` | 로그 디렉터리에서 오래된 로그 파일의 자동 정리 기능을 비활성화합니다. |
| `HF_XET_LOG_DIR_MAX_SIZE` | `250mb` | 로그 디렉터리의 로그 파일 총 최대 크기입니다. 이 한도를 초과하지 않도록 오래된 파일이 정리됩니다. |
| `HF_XET_LOG_DIR_MIN_DELETION_AGE` | `1d` | 정리 과정에서 로그 파일을 삭제할 수 있는 최소 경과 시간. |
| `HF_XET_LOG_DIR_MAX_RETENTION_AGE` | `14d` | 로그 파일의 최대 유지 기간. 이 기간보다 오래된 파일은 정리 시 항상 삭제됩니다. |

### 텔레메트리

`hf_xet`는 각 업로드 및 다운로드 후 짧은 보고서를 전송합니다. 보고서의 내용은 [Telemetry](./telemetry)를 참고하세요. 비활성화하려면 `HF_HUB_DISABLE_TELEMETRY=1`을 설정하세요.

## 현재 한계

Xet은 Git 기반 저장소에 세밀한 중복 제거와 향상된 성능을 제공하지만, 일부 기능 및 플랫폼 호환성은 아직 개발 중입니다. 따라서 Xet가 활성화된 저장소를 사용할 때 다음 제약 사항을 고려하세요.

- **64-bit 시스템만 지원**: `hf_xet`과 Git Xet 모두 현재 64-bit 아키텍처가 필요합니다. 32-bit 시스템은 지원하지 않습니다.