Xet Storage 사용하기
Xet Storage 사용하기
Xet은 허깅페이스 Hub가 AI/ML 대용량 파일을 위해 도입한 스토리지 시스템이에요. Python(hf_xet 통합)이나 Git(Git Xet 확장)에서 간단히 설정하면 업로드·다운로드에 청크 수준 중복 제거와 더 빠른 전송 성능을 얻을 수 있답니다.
출처: 문서
본문
Python
Xet 인식 버전의 huggingface_hub에 접근하려면 최신 버전을 설치하기만 하면 돼요:
pip install -U huggingface_hub
huggingface_hub 0.32.0부터는 hf_xet도 함께 설치돼요. hf_xet 패키지는 huggingface_hub를 Xet 백엔드의 Rust 클라이언트인 xet-core와 통합해요.
transformers나 datasets 라이브러리를 사용한다면, 이미 huggingface_hub를 쓰고 있어요. huggingface_hub 버전이 >= 0.32.0인 한 추가 조치는 필요 없어요.
huggingface_hub 버전 >= 0.30.0이고 < 0.32.0이 설치된 경우 hf_xet를 명시적으로 설치해야 해요:
pip install -U hf-xet
그게 전부예요! 이제 업로드와 다운로드 모두에서 Xet 중복 제거의 혜택을 누릴 수 있어요. huggingface_hub < 0.30.0 버전을 쓰는 팀 멤버는 여전히 LFS 브리지가 제공하는 역호환성을 통해 저장소를 업로드·다운로드할 수 있어요.
더 자세한 사용 문서는 huggingface_hub 문서의:
Git
Git 사용자는 Git Xet 확장을 다운로드·설치하면 Xet의 혜택에 접근할 수 있어요. 설치 후에는 Git으로 Hub 저장소를 관리하는 표준 워크플로를 사용하면 돼요 — 추가 변경 필요 없어요.
사전 요구 사항
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로 설치:
brew install git-xet
git xet install
설치를 확인하려면:
git xet --version
Windows (amd64)
winget 사용:
winget install git-xet
인스톨러 사용:
git-xet-windows-installer-x86_64.zip(여기에서 받기)을 다운로드하고 압축을 풀어요.msi인스톨러 파일을 실행하고 프롬프트를 따라요.
수동 설치:
git-xet-windows-x86_64.zip(여기에서 받기)을 다운로드하고 압축을 풀어요.- 추출된
git-xet.exe를PATH디렉토리에 놓아요. - 터미널에서
git xet install을 실행해요.
설치를 확인하려면:
git xet --version
Git Xet 사용하기
플랫폼에 설치하면 Git Xet 사용은 Hub의 표준 Git 워크플로를 따르기만 하면 돼요.
모든 사전 요구 사항이 설치·구성돼 있는지 확인하고, Hub의 저장소 작업 설정 지침을 따라간 뒤, 변경 사항을 커밋하고 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 프로토콜이 호출되어 대용량 파일을 Xet storage로 직접 업로드해, 청크 수준 중복 제거의 힘으로 업로드 속도를 높여요.
macOS 또는 Linux에서 제거하기
Homebrew 사용:
git xet uninstall
brew uninstall git-xet
설치 스크립트를 사용했다면(MacOS 또는 Linux) 터미널에서 다음을 실행해요:
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 storage의 혜택을 최대한 얻으려면 고려할 만한 몇 가지 단계가 있어요.
Python으로 업로드·다운로드할 때:
hf_xet이 설치됐는지 확인해요: Xet은 Git LFS에 최적화된 레거시 클라이언트와 역호환을 유지하지만,huggingface_hub와의hf_xet통합이 최적의 청크 기반 성능과 대용량 파일에서의 더 빠른 반복을 제공해요.- 적응형 동시성(adaptive concurrency)이 기본적으로 켜져 있어요:
hf_xet이 실시간 네트워크 상태에 따라 병렬 전송 스트림 수를 자동 조정해요 — 구성이 필요 없어요. 기본 설정은 조정 없이 대부분의 네트워크 경로를 포화시킬 거예요. - 고급 튜닝: 세밀한 제어를 위해
HF_XET_FIXED_DOWNLOAD_CONCURRENCY와HF_XET_FIXED_UPLOAD_CONCURRENCY로 동시성을 적응형 컨트롤러를 우회해 고정값으로 지정할 수 있어요. 전체 옵션 목록은hf_xet의 환경 변수를 참고해요.
Git이나 Python으로 업로드·다운로드할 때:
- 빈번한 증분 커밋 활용하기: Xet의 청크 수준 중복 제거는 모델이나 데이터셋에 안전하게 증분 업데이트할 수 있게 해줘요. 변경된 청크만 업로드되므로, 빈번한 커밋은 빠르고 스토리지 효율적이에요.
.gitattributes에서 구체적으로 지정하기: Xet이나 LFS 패턴을 정의할 때 정확한 파일 확장자(예:*.safetensors,*.bin)를 사용해 작은 파일이 큰 파일 스토리지를 불필요하게 거치지 않게 해요.- 커뮤니티 접근성 우선하기: Xet은 대용량 파일 전송의 효율과 규모를 크게 높여요. 저장소를 총 크기(또는 개별 파일 크기)를 줄이도록 구성하는 대신, 협력자와 커뮤니티 사용자가 쉽게 탐색·검색할 수 있도록 정리해요.
환경 변수
hf_xet과 Git Xet 모두 xet-core로 구동되며, 환경 변수로 구성할 수 있어요. 아래 표는 세밀한 제어를 위한 개별 변수를 나열해요. 대부분의 사용자는 이것들을 바꿀 필요가 없어요 — 기본값은 대부분의 네트워크 경로를 자동으로 포화시키도록 튜닝돼 있어요.
[!NOTE]
HF_XET_HIGH_PERFORMANCE=1은 여러 설정(동시성 한계, 버퍼 크기, 병렬 파일 한도)을 한 번에 조정하는 편의 플래그예요. 대역폭이 높고 버퍼링용 RAM이 최소 64GB 이상인 머신을 위한 거예요. 메모리가 적은 머신에서는 성능이 떨어질 수 있어요.
일반 (General)
대부분의 사용자가 가장 먼저 손대는 고수준 플래그예요.
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
HF_XET_HIGH_PERFORMANCE (별칭 HF_XET_HP) |
off | 동시성, 버퍼 크기, 병렬 파일 한도를 한 번에 높여 네트워크·CPU 사용을 극대화하는 편의 플래그. 위 메모 참고 — 대역폭이 높고 RAM이 64GB 이상인 머신에 가장 좋아요. |
HF_XET_CACHE |
$HF_HOME/xet |
Xet이 데이터를 로컬에 캐시하는 디렉토리(다운로드된 청크와 중복 제거 샤드). HF_HOME보다 우선해요. |
적응형 동시성 (Adaptive Concurrency)
기본적으로 xet-core는 적응형 동시성을 사용해요 — 실시간 네트워크 상태에 따라 병렬성을 동적으로 조정하죠. 대부분의 경우 필요하지 않은 고급 설정이에요. 아래 변수는 적응형 컨트롤러의 동작을 제어해요:
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
HF_XET_CLIENT_ENABLE_ADAPTIVE_CONCURRENCY |
true |
적응형 동시성 제어 활성화/비활성화. 비활성화하면 동시성은 초기값으로 유지돼요. |
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 |
목표 왕복 시간. 전체 전송의 예측 왕복 시간이 이 값보다 낮은 한 동시성이 증가해요. |
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를 사용해요. 이들은 초기·최소·최대 동시성을 같은 값으로 설정해요.
네트워크 및 재시도 (Network and Retry)
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
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 |
풀에 있는 최대 유휴 연결 수. |
데이터 전송 (Data Transfer)
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
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 |
파일 인제션 중 읽는 블록 크기. |
HF_XET_DATA_PROGRESS_UPDATE_INTERVAL |
200ms |
진행 바가 갱신되는 주기. |
HF_XET_DATA_PROGRESS_UPDATE_SPEED_SAMPLING_WINDOW |
10s |
진행 보고에서 전송 속도 측정을 집계하는 데 쓰는 시간 창. |
다운로드 버퍼 (Download Buffers)
이들은 다운로드 중 메모리 사용을 제어해요. HF_XET_HIGH_PERFORMANCE=1이 이들을 크게 높여요.
| 환경 변수 | 기본값 | HP 모드 | 설명 |
|---|---|---|---|
HF_XET_RECONSTRUCTION_MIN_RECONSTRUCTION_FETCH_SIZE |
256mb |
1gb |
재구성 요청의 최소 fetch 크기. |
HF_XET_RECONSTRUCTION_MAX_RECONSTRUCTION_FETCH_SIZE |
8gb |
16gb |
재구성 요청의 최대 fetch 크기. |
HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_SIZE |
2gb |
16gb |
총 다운로드 버퍼 크기. |
HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_PERFILE_SIZE |
512mb |
2gb |
파일별 다운로드 버퍼 크기. |
HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_LIMIT |
8gb |
64gb |
총 다운로드 버퍼 메모리 하드 한도. |
HF_XET_RECONSTRUCTION_TARGET_BLOCK_COMPLETION_TIME |
15m |
— | 프리페치 블록 완료 목표 시간. 다운로드 중 얼마나 앞서 프리페치할지 결정하는 데 사용. |
HF_XET_RECONSTRUCTION_MIN_PREFETCH_BUFFER |
1gb |
— | 추정 완료 시간과 무관하게 다운로드 중 프리페치로 유지할 최소 데이터 양. |
샤드 캐시 (Shard Cache)
샤드 캐시는 중복 제거 인덱스(이미 업로드된 청크를 설명하는 "샤드")를 Xet 캐시 디렉토리 아래 디스크에 보관해요. 캐시가 클수록 클라이언트가 이전에 본 데이터에 대해 중복 제거할 수 있어서, 재업로드되는 바이트가 줄어요.
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
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_CHUNK_CACHE_SIZE_BYTES |
0 (비활성화) |
로컬 청크 캐시 크기. hf_xet Python 패키지는 캐시가 기본적으로 비활성화된 채 배포돼요; 바이트 수(예: 10 GB는 10000000000)를 설정해 활성화하거나 0으로 비활성화해요. 이 변수는 Git Xet v0에서는 효과가 없어요. |
로깅 (Logging)
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
HF_XET_LOG_DEST |
(없음) | 로그 대상. 파일 경로나 디렉토리 경로(/로 끝나는)를 받아요. 디렉토리로 설정하면 타임스탬프 이름의 로그 파일이 생성돼요. 빈 문자열로 설정하면 콘솔로 나가요. 설정하지 않으면 Hugging Face Xet 캐시 디렉토리의 logs/ 하위 디렉토리로 나가요. |
HF_XET_LOG_FORMAT |
(없음) | 로그 형식. 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 |
로그 파일 최대 수명. 이보다 오래된 파일은 정리 중 항상 삭제돼요. |
현재 제한 사항
Xet이 Git 기반 스토리지에 세밀한 중복 제거와 향상된 성능을 가져오지만, 일부 기능과 플랫폼 호환성은 아직 개발 중이에요. 그 결과 Xet 지원 저장소로 작업할 때 다음 제약을 염두에 두세요:
- 64비트 시스템 전용:
hf_xet과 Git Xet 모두 현재 64비트 아키텍처가 필요해요; 32비트 시스템은 지원되지 않아요.
더 알아보기 (Learn more)
huggingface_hub>= 0.32.0은hf_xet을 자동 포함해 청크 수준 중복 제거를 제공해요.- Git 사용자는 Git Xet 확장을 설치하면 표준 Git 워크플로로 Xet의 혜택을 누릴 수 있어요.