Hugging Face's logo

Hub documentation

Xet Storageの使用

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Xet Storageの使用

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リポジトリの管理に関する標準的なワークフローをそのまま使用すればよく、追加の変更は不要です。

前提条件

GitとGit LFSをインストールしてください。

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上のリポジトリで作業するためのセットアップ手順に従った後、変更をコミットして、pushをHubに実行します:

# 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

インストーラーを使用した場合は:

  • 設定 -> アプリ -> インストールされたアプリに移動します
  • 「Git-Xet」を検索します。
  • コンテキストメニューで利用可能な「Uninstall」オプションを選択します。

手動でインストールした場合は:

  • ターミナルでgit xet uninstallを実行します。
  • 元々配置されていた場所からgit-xet.exeファイルを削除してください。

推奨事項

XetはHubのすべてのワークフローとシームレスに統合されます。ただし、Xetストレージの恩恵を最大限に得るために、いくつかのステップを検討することをお勧めします。

Pythonでアップロードまたはダウンロードを行う場合:

  • hf_xet がインストールされていることを確認してください: Xet は Git LFS 向けに最適化されたレガシークライアントとの後方互換性を保ちつつ、huggingface_hub との hf_xet 統合により、最適なチャンクベースの性能と、大規模ファイルでの高速な反復処理を実現します。
  • 適応的並行処理はデフォルトで有効です: hf_xetはリアルタイムのネットワーク状況に基づいて並列転送ストリームの数を自動的に調整します。設定は不要です。デフォルトの設定により、チューニングなしでほとんどのネットワークパスを飽和させることができます。
  • ダウンロードバッファはシステムメモリに応じてスケーリングされます: hf_xet 1.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 1.8.0 以降、アップロードでは Xet ストレージサービス経由だけでなく、Amazon S3 に直接データを送信できるようになりました。Hub は各アップロードごとに直接アップロードを使用するかどうかを判断し、段階的にこれを有効化しています。ダウンロードは変更ありません。

ネットワークがアウトバウンドトラフィックを制限している場合、プロキシまたはファイアウォールを介したダウンロードに記載されているホスト名に加えて、以下のホスト名（HTTPS、ポート443）を許可してください。

ホスト名目的
s3.us-east-1.amazonaws.com直接アップロード（米国）
s3.eu-west-3.amazonaws.comEUに保存されているリポジトリの直接アップロード

これらのホスト名はhf.coやhuggingface.coの下にないため、これらのサフィックスを許可リストに追加しても対象外となります。

hf_xet が S3 に到達できない場合、直接アップロードをリトライし、その後、そのデータを Xet ストレージサービス経由で送信します。アップロード自体は完了しますが、各ブロックがまずリトライを待機するため、大幅に遅くなる可能性があります。この状況が発生すると、hf_xet の ログ に Upload grant URL unreachable, falling back to legacy xorb upload path (may be slower) と表示されます。S3 のホスト名を許可できない場合は、HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOAD=1 を設定して直接アップロードを無効にしてください。

環境変数

hf_xet と Git Xet はどちらも xet-core によって駆動されており、環境変数で設定できます。以下の表には、細粒度の制御を行うための個別の変数がリストされています。ほとんどのユーザーはこれらを変更する必要はありません。デフォルト値は、ほとんどのネットワークパスを自動的に飽和させるよう調整されています。

HF_XET_HIGH_PERFORMANCE=1 は、複数の設定（並行処理の上限、バッファサイズ、並列ファイルの制限）を一度に調整する便利なフラグです。高帯域幅と高速ディスクを備えたマシンでの使用を想定しています。hf_xet 1.7.0 以降、このフラグが設定するバッファサイズは hf_xet に利用可能なメモリに基づいて決定されるため（ダウンロードバッファ を参照）、64 GB の RAM は不要になりました。また、ユーザーが自分で設定した変数は、このフラグよりも優先されます。以前のバージョンでは、少なくとも 64 GB の RAM を備えたマシンでのみ使用してください。

一般

ほとんどのユーザーが最初に使う高レベルなフラグ。

環境変数デフォルト説明
HF_XET_HIGH_PERFORMANCE（別名 HF_XET_HP）off並行性、バッファサイズ、並列ファイル制限を同時に引き上げることで、ネットワークとCPUの使用率を最大化する便利なフラグです。上記の注記を参照してください。
HF_XET_CACHE$HF_HOME/xetXetがデータをローカルにキャッシュするディレクトリ（ダウンロードされたチャンクと重複排除シャード）。HF_HOMEよりも優先されます。

適応的並行性

デフォルトでは、xet-coreは適応型並行処理を使用します。これはリアルタイムのネットワーク状況に基づいて並列度を動的に調整する機能です。これらの設定は高度な設定であり、ほとんどのケースでは必要ありません。以下の変数は、適応型コントローラーの動作を制御します。

環境変数デフォルト説明
HF_XET_CLIENT_AC_INITIAL_UPLOAD_CONCURRENCY2並列アップロードストリームの初期数。HPモード: 16。
HF_XET_CLIENT_AC_INITIAL_DOWNLOAD_CONCURRENCY4並行ダウンロードストリームの初期数。HPモード: 16。
HF_XET_CLIENT_AC_MIN_UPLOAD_CONCURRENCY1アップロード並行処理の下限値。HPモード: 4。
HF_XET_CLIENT_AC_MIN_DOWNLOAD_CONCURRENCY1ダウンロード並行処理の下限値。HPモード: 4。
HF_XET_CLIENT_AC_MAX_UPLOAD_CONCURRENCY64アップロードの並行処理数の上限。HPモード: 124。
HF_XET_CLIENT_AC_MAX_DOWNLOAD_CONCURRENCY64ダウンロード並行数の上限。HPモード: 124。
HF_XET_CLIENT_AC_TARGET_RTT60s往復時間（ラウンドトリップタイム）の目標値。完全な転送の予測往復時間がこの値を下回る限り、並行性は増加し続けます。
HF_XET_CLIENT_AC_MAX_HEALTHY_RTT90s許容される最大ラウンドトリップ時間。この時間を超える転送は、適応型コントローラーによって失敗としてカウントされます。
HF_XET_CLIENT_AC_HEALTHY_SUCCESS_RATIO_THRESHOLD0.8コントローラーが並行性を増加させる閾値となる成功率。
HF_XET_CLIENT_AC_UNHEALTHY_SUCCESS_RATIO_THRESHOLD0.5コントローラーが並行度を下げる閾値となる成功率。
HF_XET_CLIENT_AC_LOGGING_INTERVAL_MS10000並行処理のステータスがログに記録される間隔（ミリ秒単位）。

並行度を固定値に固定するには（適応型コントローラーをバイパスするには）、HF_XET_FIXED_UPLOAD_CONCURRENCY および HF_XET_FIXED_DOWNLOAD_CONCURRENCY という便利なエイリアスを使用します。これらは、初期値、最小値、最大値の並行度をすべて同じ値に設定します。

ネットワークとリトライ

環境変数デフォルト説明
HF_XET_CLIENT_RETRY_MAX_ATTEMPTS5失敗したリクエストの最大再試行回数。
HF_XET_CLIENT_RETRY_BASE_DELAY3000msリトライ間のベースディレイ（指数バックオフ付き）。
HF_XET_CLIENT_RETRY_MAX_DURATION360s単一のリトライまでの最大待機時間。HF_XET_CLIENT_RETRY_MAX_ATTEMPTS 回でリトライが停止するため、リトライの総時間はこの値を超える可能性があります。
HF_XET_CLIENT_CONNECT_TIMEOUT60sTCP接続のタイムアウト。
HF_XET_CLIENT_READ_TIMEOUT300sHTTPレスポンスの読み取りタイムアウト。
HF_XET_CLIENT_IDLE_CONNECTION_TIMEOUT60sアイドル状態の接続が閉じられるまでのタイムアウト。
HF_XET_CLIENT_MAX_IDLE_CONNECTIONS16プール内のアイドル接続の最大数。
HF_XET_CLIENT_RECONSTRUCTION_API_VERSION(未設定)フォールバックなしで、ダウンロード（再構築）API のバージョンを 1 または 2 に強制指定します。未設定の場合、hf_xet はバージョン 2 を試み、サーバーがサポートしていない場合はバージョン 1 にフォールバックします。
HF_XET_CLIENT_SHARD_API_VERSION(未設定)アップロード（シャード）API のバージョンを 1 または 2 に強制指定し、フォールバックを行いません。未設定の場合、hf_xet はバージョン 2 を試み、サーバーがサポートしていない場合はバージョン 1 にフォールバックします。

データ転送

環境変数デフォルト説明
HF_XET_DATA_MAX_CONCURRENT_FILE_INGESTION8アップロード中に並行して処理されるファイルの最大数。HPモード: 100。
HF_XET_DATA_MAX_CONCURRENT_FILE_DOWNLOADS8同時にダウンロードされるファイルの最大数。
HF_XET_DATA_INGESTION_BLOCK_SIZE8mbファイル取り込み時に読み込まれるブロックのサイズ。
HF_XET_DATA_PROGRESS_UPDATE_INTERVAL200ms進捗バーが更新される頻度。
HF_XET_DATA_PROGRESS_UPDATE_SPEED_SAMPLING_WINDOW10s進行状況のレポートにおいて、転送速度の測定値を集計するために使用される時間ウィンドウ。
HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOADfalseすべてのアップロードデータを S3 に直接送信するのではなく、Xet ストレージサービス経由で送信するには、1 に設定します（hf_xet 1.8.0 以降）。プロキシまたはファイアウォールを介したアップロードを参照してください。

バッファのダウンロード

これらはダウンロード中のメモリ使用量を制御します。

hf_xet 1.7.0 以降、3 つの DOWNLOAD_BUFFER 変数のデフォルト値は、hf_xet が使用できるメモリ量に基づいて決定されます。これは、マシンの RAM、またはそれより低い場合はコンテナのメモリ上限です。各デフォルト値は、そのメモリの一定割合であり、表に示されている最小値と最大値の範囲内に保たれます。HP モードでは、同じ最小値と最大値の範囲内で、割合が 2 倍になります。例えば、メモリ上限が 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_SIZE256mb1gb再構築リクエストの最小フェッチサイズ。
HF_XET_RECONSTRUCTION_MAX_RECONSTRUCTION_FETCH_SIZE8gb16gb再構築リクエストの最大フェッチサイズ。
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_BUFFERSunset—1に設定すると、利用可能なメモリからバッファサイズを決定する代わりに、固定のデフォルト値を使用します。
HF_XET_RECONSTRUCTION_TARGET_BLOCK_COMPLETION_TIME15m—プリフェッチブロックの完了目標時間。ダウンロード中に事前にプリフェッチするデータ量を決定するために使用されます。
HF_XET_RECONSTRUCTION_MIN_PREFETCH_BUFFER1gb—ダウンロード中の推定完了時刻に関わらず、プリフェッチとして保持するデータの最小量。

Shard Cache

shard cacheは、Xetキャッシュディレクトリ配下のディスク上に、重複排除インデックス（すでにアップロードされたチャンクを記述する「shards」）を保持します。キャッシュが大きいほど、クライアントはより多くの過去のデータに対して重複排除を行うことができ、再アップロードされるバイト数が少なくなります。

環境変数デフォルト説明
HF_XET_SHARD_CACHE_SIZE_LIMIT16gbディスク上のシャードキャッシュのソフト上限。実行の開始時にキャッシュはこのサイズまで削減されますが、1回の長時間セッション内でこれを超えて増加する可能性があります。目安として、サイズがXのキャッシュは、おおよそ 1000 × X のデータ量に対する重複排除を行います（16 GB → 約 16 TB）。非常に大きなリポジトリで重複排除の精度を高める場合は値を上げ、キャッシュの増加がディスク容量を逼迫する恐れがある場合は値を下げてください。人間が読みやすいサイズ（例: 32gb）または生のバイト数を指定できます。
HF_XET_SHARD_CHUNK_INDEX_TABLE_MAX_SIZE67108864メモリ内重複排除インデックス内のチャンクエントリの最大数。サイズ（128mb など）ではなく、整数を指定してください。hf_xet 1.7.1 以降では、インデックスが満杯になると、新しいチャンクを追加するために最も古いシャードがインデックスから削除されます。以前のバージョンでは、インデックスが満杯になるとチャンクの追加が停止します。
HF_XET_SHARD_CACHE_SUBDIRshard-cacheXetキャッシュディレクトリ内のシャードキャッシュ用サブディレクトリ。

チャンクキャッシュ

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_PREFIXxetディレクトリにログを出力する場合のログファイル名のプレフィックス。
HF_XET_LOG_DIR_DISABLE_CLEANUPfalseログディレクトリ内の古いログファイルの自動クリーンアップを無効にします。
HF_XET_LOG_DIR_MAX_SIZE250mbログディレクトリ内のログファイルの合計サイズ上限。この上限を超えないように、古いファイルが削除されます。
HF_XET_LOG_DIR_MIN_DELETION_AGE1dクリーンアップ時にログファイルを削除できる最小の経過時間。
HF_XET_LOG_DIR_MAX_RETENTION_AGE14dログファイルの最大経過時間。これより古いファイルは、クリーンアップ時に常に削除されます。

テレメトリ

hf_xet は、各アップロードとダウンロードの後に短いレポートを送信します。その内容については、テレメトリを参照してください。無効にするには、HF_HUB_DISABLE_TELEMETRY=1を設定してください。

現在の制限事項

XetはGitベースのストレージに細粒度の重複排除とパフォーマンスの向上をもたらしますが、一部の機能やプラットフォームの互換性については開発中です。そのため、Xet対応のリポジトリで作業する際は、以下の制約を念頭に置いてください。

  • 64ビットシステムのみ: hf_xetとGit Xetは現在、64ビットアーキテクチャを必要とします。32ビットシステムはサポートされていません。
Update on GitHub

←Xetの履歴と概要 セキュリティ→