開発と AI · Clash 技術ブログ

Hugging Face のモデルダウンロードが遅い、または中断する場合は？Clash、Git LFS、キャッシュの設定ガイド

Web ページを開けても、モデルファイルのダウンロード経路が正常とは限りません。Hub のメタデータ、Xet または Git LFS の大容量ファイル、ローカルキャッシュを分けて確認し、その後タイムアウト、中断、ディスク容量の問題へ対処します。

本文を読むブログへ戻る
  • Hugging Face
  • モデルのダウンロード
  • Git LFS
  • キャッシュ
目次
公開日
更新日時
読了時間の目安
約 9 分

まず、遅いのが Hub ページ、Xet のチャンク、以前の Git LFS ダウンロードのどれかを確認する

Hugging Face のモデルダウンロードが遅い、または中断する場合も、すぐにキャッシュを消去しないでください。モデルカードと config.json は通常の Hub リクエストですが、大きな重みファイルは一般に Xet のチャンクとしてダウンロードされ、以前のリポジトリでは Git LFS が使われることもあります。この三つでは使用するツール、ログ、再開方法が異なります。まず小さなファイルでアカウントとネットワークを確認し、その後で Clash のプロキシ、タイムアウト、キャッシュディレクトリを設定します。

現在のダウンロード方法

利用方法実際に大容量ファイルを扱うバックエンド適した用途
huggingface_hub / hf CLIhuggingface_hub 0.32+ では hf_xet が自動でインストールされ、Xet のチャンクダウンロードを使用するモデルとデータセットのダウンロードに推奨
git clone + git-xetXet を使用しながら 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 をインポートする前に設定する必要がある

macOS / Linux の現在のターミナルでの例。CLASH_PORT は実際の mixed-port に合わせて変更する
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 で大容量ファイルをダウンロードすると、コンテンツアドレスストレージと署名済みストレージのアドレスにもアクセスします。Web ページが正常でも、huggingface.co に到達できると分かるだけです。チャンクの開始後に再試行を繰り返す場合は、一つのノードに固定し、失敗したドメイン、ステータスコード、キャッシュへの書き込みエラーを確認してください。

自動選択ポリシーがダウンロード中に出口を切り替えると、署名済み URL と並行接続が同時に無効になることがあります。関連する Hub/Xet リクエストを一つの固定ポリシーグループへ入れ、ダウンロードがすべて完了してから自動選択へ戻してください。一時ストレージのドメインを、範囲が広すぎる DOMAIN-KEYWORD ルールとして恒久的に記述しないでください。

401 / 403

リポジトリのライセンスと token を確認し、タイムアウト値は増やさない。

httpx.TimeoutException / Read timed out

ノードを固定し、Xet リクエストが一致することを確認してから、HF_HUB_DOWNLOAD_TIMEOUT を適度に増やす。

No space left on device

HF_HOME/HF_HUB_CACHE を移動し、完了済みのキャッシュは残して、ノードを切り替えない。

キャッシュへの書き込みで Permission denied が発生する

ディレクトリの所有者とマウント権限を修正し、root でモデル全体をダウンロードし直さない。

数 KB のポインターファイルしか取得できない

Git ワークフローに git-xet/git-lfs がないか、大容量ファイルのチェックアウトが完了していない。

同じ revision で再実行し、まず Hub のキャッシュを再利用してから、Xet のチャンクキャッシュを有効にするか判断する

既定の Hub キャッシュは ~/.cache/huggingface/hub にあり、Xet 関連のファイルは ~/.cache/huggingface/xet にあります。HF_HOME を設定すると両方がまとめて移動します。

Hub の refs、blobs、snapshots は、完了済みのファイルを再利用します。ダウンロードが中断した場合は、同じ repo_id、revision、ユーザー、キャッシュディレクトリを使って再実行してください。

現在の公式ドキュメントでは、Xet chunk cache の既定サイズは 0、つまり既定では無効です。同じ範囲の内容を頻繁にダウンロードし、十分なディスク容量がある場合に限り、HF_XET_CHUNK_CACHE_SIZE_BYTES の設定を検討してください。一度のダウンロードが遅い場合は、まずノードを固定してダウンロードのタイムアウトを増やし、キャッシュを試すために完了済みの blobs を削除しないでください。

Python で revision を固定する。CACHE_DIR は自分が書き込めるディレクトリへ変更できる
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 を優先すると、再開状況とキャッシュを確認しやすくなります。

Hugging Face 公式の Git ワークフローに従い、先に HF_REPO を置き換える
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 status

git xet コマンドがない場合は、まず公式のプラットフォーム別手順に従って git-xet をインストールします。macOS では Homebrew を利用でき、Windows 向けの公式ドキュメントには winget によるインストール方法があります。以前のクライアントも LFS bridge 経由でダウンロードできますが、速度や大容量ファイルに問題がある場合は、Hugging Face のツールチェーンを優先して更新してください。

Git は git config と環境変数を使用するため、Python SDK とは別の設定です。hf CLI は正常でも git clone が止まる場合は、Git/Xet/LFS と Git のプロキシだけを確認し、HF_HOME は変更しません。

ダウンロード完了後にネットワークを切断し、モデルが実際にローカルへ保存されていることを確認する

進捗バーが完了しても、プロジェクトが tokenizer、設定、カスタムコードを読み込む際に Hub へアクセスすることがあります。最後に実際のプロジェクトをオフラインで一度テストし、必要なファイルがすべてローカルキャッシュへ入っていることを確認してください。

成果物の検証

  1. 同じダウンロードコマンドをもう一度実行する

    すべてのチャンクを再転送せず、同じ snapshot がすぐ使われる必要がある。

  2. モデルを一度読み込む

    実際の transformers またはプロジェクトコードで重みと tokenizer を読み込む。

  3. オフラインモードを有効にしてテストする

    キャッシュ済みの内容を利用できる場合、HF_HUB_OFFLINE=1 を設定するか local_files_only を使用すれば、Hub へ再びアクセスすることはありません。

  4. 認証情報と空き容量を確認する

    Notebook、ログ、Git 履歴に token がなく、キャッシュ用ドライブにも更新に必要な余裕がある。

  5. revision と snapshot のパスを記録する

    次回のモデル更新時に、新しいバージョンのダウンロードと以前のキャッシュ破損を区別できる。

参考資料