Windows環境でHuggingFaceのモデルダウンロードが途中で停止する問題の対処【備忘録】

Python 機械学習 備忘録

お疲れ様です。 ライブラリを介してモデルをダウンロードする際、ダウンロード処理が途中で停止する現象が発生することがあります。 今回は、この問題の現象と、OSの設定を変更せずに回避するための手動ダウンロード手順についてまとめます。

発生した問題

Windows環境でhuggingface_hubライブラリを使ってモデルをダウンロードすると、途中で停止する現象が起こります。 特にエラー等が出るわけではなく、またフリーズするというわけでもなく、下図のような途中の状態で止まります。 Ctrl+Cで停止することはできます。

Linux（WSL）環境では問題が無かったのでWindows特有の問題のようです。

download

# Target Model
processor = AutoProcessor.from_pretrained(TARGET_MODEL_ID)
target_model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-4-E2B-it",
    dtype="auto",
    device_map="auto",

)

# Assistant Model (the drafter)
assistant_model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-4-E2B-it-assistant",
    dtype="auto",
    device_map="auto",
)

対処方法

Windows側のシステム設定やネットワークプロキシ、シンボリックリンクの設定などを変更することでライブラリを使ってのダウンロードができるようにすることも可能なようです。 ですが、あまり設定はいじりたくない場合あると思います。（業務PCとかなら尚更）

そんなときの簡単な対処方法として、ライブラリを介さずHuggingFaceから直接モデルをダウンロード（clone）する方法があります。 ダウンロードしたフォルダをコード側で指定すれば、モデルをそこから読み込み使用することができます。

HuggingFaceのモデルページ自体がGitリポジトリになっているのでgit cloneでダウンロードすることができます。 Gemma4 MTP Draftersなので、assistant modelも同じ方法でcloneしておきます。

huggingface.co

git clone https://huggingface.co/google/gemma-4-E2B-it

target_model

assistant_model

あとはプログラム側のモデル指定の部分でcloneしたフォルダを指定すればOKです。

# Target Model
processor = AutoProcessor.from_pretrained("./gemma-4-E2B-it")
target_model = AutoModelForCausalLM.from_pretrained(
    "./gemma-4-E2B-it",　# cloneしたフォルダを指定
    dtype="auto",
    device_map="auto",

)

# Assistant Model (the drafter)
assistant_model = AutoModelForCausalLM.from_pretrained(
    "./gemma-4-E2B-it-assistant", # cloneしたフォルダを指定
    dtype="auto",
    device_map="auto",
)

出力もこのように問題なくできました。（簡易出力ですが。）

output

※注意: Git LFSの事前準備が必要です

大容量の重みファイルなどを正しくダウンロードするには、ローカル環境にGit LFSがインストールされている必要があります。 インストールされていない状態でgit cloneを行うと、大容量ファイルのポインタファイル（数KBのテキスト）のみがダウンロードされます。 これはモデルファイルとは別物なので読み込み時にエラーが発生します。

Windowsの場合は、Git for Windowsでインストールをしているとデフォルトでインストールされます。 今回はWindows環境を想定しているので問題にはならないはずです。
下記のコマンドでインストールされているか確認できます。

  • インストール確認のコマンド

git lfs version

git_lfs