目次
モデルのページは開くのに、大きなファイルの転送が始まると再試行を繰り返すことがあります。タイムアウトを延ばしたりキャッシュを消したりしても直るとは限りません。小さなファイルと重みでは取得方法が異なる場合があり、アカウントの許可、プロキシ経路、空き容量も別に確認します。完了済みのファイルを残し、使用中のツールに合わせて調べれば、最初からのダウンロードを減らせます。
Hub の小さなファイル、Xet の分割取得、従来の Git LFS はどう違う？
モデルカードまたは config.json で通常の Hub リクエストを確認します。大きな重みは通常 Xet のチャンクでダウンロードされ、大きなファイルを小さく分けて転送します。下の表で使用中のツールを確認してください。旧 Git LFS には別の互換方式があります。調査中も完了済みのキャッシュは残し、小さなファイルでアカウントと通信を確認します。
現在のダウンロード方法
| 利用方法 | 実際に大容量ファイルを扱うバックエンド | 適した用途 |
|---|---|---|
| huggingface_hub / hf CLI | huggingface_hub 0.32+ では hf_xet が自動でインストールされ、Xet のチャンクダウンロードを使用する | モデルとデータセットのダウンロードに推奨 |
| git clone + git-xet | Xet を使用しながら Git ワークフローも維持する | リポジトリ全体とコミット履歴が必要な場合 |
| 従来の Git LFS クライアント | 互換ブリッジ経由で引き続き動作する | 以前のワークフロー向けであり、現在の性能面での第一候補ではない |
| ブラウザーからの単一ファイル取得 | Hub が生成するダウンロードアドレス | 小さなファイルの確認または一時的なダウンロード |
Hugging Face の公式ドキュメントによると、Hub はすでに Xet を採用しています。Git LFS との互換性は維持されていますが、hf_transfer は廃止されており、hf_xet へ移行する必要があります。Git LFS だけをインストールして HF_HUB_ENABLE_HF_TRANSFER を有効にする以前のチュートリアルは、2026 年の標準的な手順には適しません。
config.json の取得可否で、許可の問題と基本的な通信障害を区別する
python -m pip install -U huggingface_hub
hf auth login
hf download gpt2 config.json
# 查看版本
python -c "import huggingface_hub; print(huggingface_hub.__version__)"公開モデルの小さなファイルを取得できれば、Hub のメタデータ、基本的な HTTPS 接続、ローカルキャッシュディレクトリが使用可能だと確認できます。制限付きモデルで 401/403 が返る場合は、ブラウザーから同じアカウントでライセンスに同意し、token に read 権限があるか確認してください。ノードを切り替えても、アカウントが自動的に承認されることはありません。
token は hf auth login で保存し、Clash YAML、Notebook のセル、公開スクリプトには書き込みません。チームのサーバーでは専用の secrets 管理を使用し、個人の token をコピーしないでください。
環境変数は huggingface_hub をインポートする前に設定する必要がある
以下の例では HF_HOME を変更します。前の節でログインした後も、同じ token の取得元を使っているか確認してください。認証では HF_TOKEN の値が優先され、HF_TOKEN_PATH で別のファイルの場所を指定できます。既定の token ファイルの場所は HF_HOME に従います。
制限付きモデルをダウンロードする前に、プロキシとキャッシュディレクトリを決めてください。ディレクトリを変更したらhf auth whoamiで現在のアカウントを確認し、必要ならその環境でログインし直します。公開モデルの例はログイン不要で、成功しても制限付きモデルの利用許可が有効とは証明できません。
CLASH_PORT=7890
export HTTPS_PROXY="http://127.0.0.1:$CLASH_PORT"
export HTTP_PROXY="http://127.0.0.1:$CLASH_PORT"
export HF_HOME="$HOME/hf-cache"
export HF_HUB_DOWNLOAD_TIMEOUT=30
mkdir -p "$HF_HOME"
hf download openai-community/gpt2 --include '*.json'
hf download openai-community/gpt2 --cache-dir "$HF_HOME/hub"公式ドキュメントには、huggingface_hub が import 時に環境変数を読み込むと記載されています。Notebook ですでにライブラリをインポートした後に変数を変更しても、現在の kernel は以前の値を使い続ける場合があります。kernel を再起動するか、起動前に設定してください。HF_HUB_DOWNLOAD_TIMEOUT の既定値は 10 秒です。接続は確立できるものの読み込みが遅い場合に限り、値を増やします。
HF_HOME は token とキャッシュのルートディレクトリの両方に影響します。リポジトリキャッシュだけを移動する場合は、HF_HUB_CACHE またはコマンドの --cache-dir を使用できます。ディレクトリは現在のユーザーが書き込める必要があり、一時チャンク、モデルの revision、展開用の空き容量も確保してください。
Web ページは開けるがモデルのチャンクがタイムアウトする場合、接続画面で Xet のリクエストを探す
モデルカードや README の取得は短いリクエストで済みますが、Xet での大容量ファイルのダウンロードでは、ファイルの内容をもとにデータを特定するアドレスや、一時的なアクセス許可付きの保存先にもアクセスします。ページが開くことから分かるのは huggingface.co に接続できることだけです。分割データのダウンロード開始後に再試行が続く場合は、ノードを固定し、失敗したドメイン、ステータスコード、キャッシュの書き込みエラーを確認してください。
関連する Hub/Xet のリクエストを同じ固定ノードで比較し、出口ごとの到達性の差を確認します。取得後に自動選択へ戻してください。出口の変更だけで署名付き URL が無効になったとは判断できず、ステータスコードと認可情報も確認します。一時的な保存先ドメインを広すぎる DOMAIN-KEYWORD ルールで恒久的に扱わないでください。
401 / 403
リポジトリのライセンスと token を確認し、タイムアウト値は増やさない。
httpx.TimeoutException / Read timed out
ノードを固定し、失敗したリクエストの経路を確認します。Hub のファイル読み込みが遅い場合は HF_HUB_DOWNLOAD_TIMEOUT を調整できますが、Xet の分割取得のエラーは hf_xet のログで別に調べます。一つの変数がすべての取得を制御すると考えないでください。
No space left on device
HF_HOME/HF_HUB_CACHE を移動し、完了済みのキャッシュは残して、ノードを切り替えない。
キャッシュへの書き込みで Permission denied が発生する
ディレクトリの所有者とマウント権限を修正し、root でモデル全体をダウンロードし直さない。
数 KB のポインターファイルしか取得できない
Git ワークフローに git-xet/git-lfs がないか、大容量ファイルのチェックアウトが完了していない。
完了済みの Hub ファイルを再利用する。チャンクキャッシュの変数は無効
既定のHubキャッシュは~/.cache/huggingface/hubで、Xet関連のディレクトリは~/.cache/huggingface/xetです。HF_HOMEを変更すると以後使うパスが変わりますが、既存ファイルは自動で移動しません。元のディレクトリにあるダウンロード済みファイルを残したうえで、移行するか、どのキャッシュを使い続けるかを決めてください。
Hub の refs、blobs、snapshots は、完了済みのファイルを再利用します。ダウンロードが中断した場合は、同じ repo_id、revision、ユーザー、キャッシュディレクトリを使って再実行してください。
現在の公式説明では HF_XET_CHUNK_CACHE_SIZE_BYTES は無効です。hf_xet はダウンロード用のローカルチャンクキャッシュを使わず、この変数を設定しても有効になりません。完了済みの Hub ファイルを再利用し、実際のリクエストと空き容量を確認してください。「分割キャッシュを有効にする」ために blobs を消したり、モデル全体を取得し直したりする必要はありません。
from pathlib import Path
from huggingface_hub import snapshot_download
cache_dir = Path.home() / "hf-cache" / "hub"
path = snapshot_download(
repo_id="openai-community/gpt2",
revision="main",
cache_dir=cache_dir,
)
print(path)Git を使用する必要がある場合は git-xet をインストールし、LFS との互換性も維持する
プロジェクトが Git の履歴またはブランチ操作に実際に依存する場合に限り、この経路を使用します。通常のモデルダウンロードには hf download を優先すると、再開状況とキャッシュを確認しやすくなります。
git xetコマンドがない場合は、公式のプラットフォーム別手順に従ってgit-xetをインストールします。macOSではHomebrewを使用でき、Windowsの公式ドキュメントにはwingetでのインストール方法があります。古いクライアントもLFS bridge経由でダウンロードできますが、速度や大容量ファイルの問題がある場合は、Hugging Faceの関連ダウンロードツールを優先して更新してください。
HF_REPO='OWNER/MODEL'
# 例如 HF_REPO='openai-community/gpt2'
git lfs install
git xet install
git clone "https://huggingface.co/$HF_REPO"
cd "${HF_REPO##*/}"
git xet --version
git lfs version
git statusGit は git config と環境変数を使用するため、Python SDK とは別の設定です。hf CLI は正常でも git clone が止まる場合は、Git/Xet/LFS と Git のプロキシだけを確認し、HF_HOME は変更しません。
オフラインモードを有効にし、モデルの重みとtokenizerをローカルから読み込めることを確認する
ダウンロード結果とオフライン利用を確認する
同じダウンロードコマンドをもう一度実行する
すべてのチャンクを再転送せず、同じ snapshot がすぐ使われる必要がある。
モデルを一度読み込む
実際の transformers またはプロジェクトコードで重みと tokenizer を読み込む。
オフラインモードを有効にしてテストする
キャッシュ済みの内容を利用できる場合、HF_HUB_OFFLINE=1 を設定するか local_files_only を使用すれば、Hub へ再びアクセスすることはありません。
認証情報と空き容量を確認する
Notebook、ログ、Git 履歴に token がなく、キャッシュ用ドライブにも更新に必要な余裕がある。
revision と snapshot のパスを記録する
次回のモデル更新時に、新しいバージョンのダウンロードと以前のキャッシュ破損を区別できる。