【Hugging Face】大規模モデルのダウンロードが途中で止まる問題の完全解決法

Hugging Faceからの大規模モデルダウンロードが停止する問題

問題の概要

Hugging Faceから数GB〜数十GBの大規模言語モデル（LLM）やStable Diffusionモデルをダウンロードする際、途中でプログレスバーが止まったり、タイムアウトエラーが発生することがあります。特に70Bパラメータ以上のモデルや、ネットワーク環境が不安定な場合に頻発します。

主な原因

この問題は主に以下の原因で発生します。

1. ネットワークタイムアウト設定が短い

デフォルトのHTTPタイムアウト設定では、大容量ファイルのダウンロード中に接続が切断されることがあります。特にVPN経由やプロキシ環境下で顕著です。

2. ディスク容量不足

huggingface_hubはダウンロード時にキャッシュディレクトリ（~/.cache/huggingface/）に一時ファイルを作成します。モデル本体のサイズに加え、一時ファイル分の空き容量が必要です。

3. huggingface_hubのバージョンが古い

古いバージョンのhuggingface_hubライブラリにはレジューム（再開）機能が十分に実装されていない場合があります。

解決法1: 環境変数でタイムアウトを延長する

ダウンロード前に以下の環境変数を設定してタイムアウトを延長します。

# Linux/Mac
export HF_HUB_DOWNLOAD_TIMEOUT=3600
export HUGGINGFACE_HUB_CACHE="/path/to/large/disk/hf_cache"

# Windows (PowerShell)
$env:HF_HUB_DOWNLOAD_TIMEOUT = "3600"

解決法2: huggingface-cliでレジュームダウンロード

Pythonスクリプトではなく、huggingface-cliコマンドを使用すると、中断時の自動レジュームが可能です。

# huggingface_hubを最新に更新
pip install --upgrade huggingface_hub

# CLIでダウンロード（自動レジューム対応）
huggingface-cli download meta-llama/Llama-3.1-70B-Instruct --local-dir ./models/llama-3.1-70b

ネットワークが切断されても、同じコマンドを再実行すれば途中から再開されます。

解決法3: hf_transferで高速ダウンロード

Hugging Face公式の高速ダウンローダー「hf_transfer」を利用すると、マルチスレッド並列ダウンロードにより大幅に速度が向上します。

# インストール
pip install hf_transfer

# 有効化してダウンロード
HF_HUB_ENABLE_HF_TRANSFER=1 huggingface-cli download bigscience/bloom --local-dir ./models/bloom

hf_transferは特に100GB超のモデルで効果的で、通常の3〜5倍の速度が期待できます。

解決法4: Git LFSで直接クローン

上記でも問題が解決しない場合、Git LFSを使った直接クローンが最も確実です。

# Git LFSをインストール
sudo apt install git-lfs
git lfs install

# リポジトリをクローン
GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/meta-llama/Llama-3.1-70B-Instruct
cd Llama-3.1-70B-Instruct
git lfs pull

GIT_LFS_SKIP_SMUDGE=1を指定することで、まずメタデータのみをクローンし、その後git lfs pullで大きなファイルを個別にダウンロードできます。

解決法5: プロキシ・VPN環境での対処

企業ネットワークやVPN環境では、追加の設定が必要な場合があります。

# プロキシ設定
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# SSL証明書の検証を一時的にスキップ（セキュリティ上、本番では非推奨）
export HF_HUB_DISABLE_TELEMETRY=1
export CURL_CA_BUNDLE=""

まとめ

大規模モデルのダウンロード停止は、タイムアウト延長、最新のhuggingface-cliの利用、hf_transferによる高速化、Git LFSでの直接クローンの順で対処するのが効果的です。特にhf_transferとhuggingface-cliの組み合わせが現在最も推奨される方法です。

この記事はAIトラブル解決に特化した技術メディア「EffiAI」が提供しています。