Hub documentation
Xet Storage 사용
Xet Storage 사용
Python
Xet을 지원하는 huggingface_hub 버전에 액세스하려면 최신 버전을 설치하면 됩니다:
pip install -U huggingface_hub
huggingface_hub 0.32.0부터 이 패키지는 hf_xet도 함께 설치합니다. hf_xet 패키지는 Xet 백엔드의 Rust 클라이언트인 xet-core와 huggingface_hub를 통합합니다.
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 --versionWindows (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 --versionGit 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 스토리지에 직접 업로드되며, 청크 수준 중복 제거의 힘으로 업로드 속도가 향상됩니다.
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 스토리지의 이점을 최대한 활용하려면 몇 가지 단계를 고려해 보시기 바랍니다.
Python으로 업로드 또는 다운로드할 때:
hf_xet이 설치되어 있는지 확인합니다: Xet는 Git LFS에 최적화된 레거시 클라이언트와 하위 호환성을 유지하지만,hf_xet의huggingface_hub통합은 최적의 청크 기반 성능과 대용량 파일에 대한 더 빠른 반복을 제공합니다.- 적응형 동시성은 기본적으로 활성화되어 있습니다:
hf_xet은 실시간 네트워크 조건에 따라 병렬 전송 스트림의 수를 자동으로 조정합니다 — 설정이 필요하지 않습니다. 기본 설정은 조정 없이 대부분의 네트워크 경로를 포화 상태로 만듭니다. - 다운로드 버퍼는 시스템 메모리에 따라 확장됩니다:
hf_xet1.7.0부터, 다운로드 버퍼 크기는 컨테이너 메모리 한도를 포함하여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를 기반으로 작동하며, 환경 변수를 통해 설정할 수 있습니다. 아래 표에는 세밀한 제어를 위한 개별 변수가 나열되어 있습니다. 대부분의 사용자는 이 변수를 변경할 필요가 없습니다. 기본값은 대부분의 네트워크 경로를 자동으로 포화 상태로 유지하도록 조정되어 있습니다.
HF_XET_HIGH_PERFORMANCE=1은 여러 설정을 한 번에 조정하는 편의 플래그입니다(동시성 한계, 버퍼 크기, 병렬 파일 제한). 이 플래그는 대역폭이 높고 디스크 속도가 빠른 머신을 위해 설계되었습니다.hf_xet1.7.0부터 이 플래그가 설정하는 버퍼 크기는hf_xet에 사용 가능한 메모리를 기준으로 결정됩니다(다운로드 버퍼 참조). 따라서 더 이상 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). |
동시성을 고정된 값으로 고정하려면(적응형 컨트롤러를 우회하려면) 편의 별칭
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 로그 파일에 기록됩니다(로깅 참조).
| 환경 변수 | 기본값 | 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
chunk cache는 다운로드된 바이트 범위(청크)를 디스크에 저장하여 중복되는 데이터를 스토리지에서 다시 가져오지 않도록 합니다. 관련 모델 또는 데이터셋을 반복적으로 다운로드하거나, 새로운 리비전을 생성할 때 가장 유용합니다.
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
HF_XET_CHUNK_CACHE_SIZE_BYTES | 0 (비활성화됨) | 로컬 청크 캐시의 크기입니다. hf_xet Python 패키지는 기본적으로 캐시가 비활성화되어 있습니다. 활성화하려면 바이트 수를 설정하세요(예: 10 GB의 경우 10000000000), 비활성화하려면 0을 설정하세요. 이 변수는 Git Xet v0에서는 효과가 없습니다. |
로깅
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
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를 참고하세요. 비활성화하려면 HF_HUB_DISABLE_TELEMETRY=1을 설정하세요.
현재 한계
Xet은 Git 기반 저장소에 세밀한 중복 제거와 향상된 성능을 제공하지만, 일부 기능 및 플랫폼 호환성은 아직 개발 중입니다. 따라서 Xet가 활성화된 저장소를 사용할 때 다음 제약 사항을 고려하세요.
- 64-bit 시스템만 지원:
hf_xet과 Git Xet 모두 현재 64-bit 아키텍처가 필요합니다. 32-bit 시스템은 지원하지 않습니다.