【メモ】これだけ覚える！Hugging Faceからモデルのダウンロード方法

LLM AI python 開発 コンピュータ

Hugging Faceは、機械学習・自然言語処理モデルのオープンソースプラットフォームで、「AI界のGitHub」とも呼ばれ、最先端のAIモデルを共有・活用する中心的な場所となっています。Hugging Faceから最新のモデルをダウンロードしてローカルで使用する方法についてここでは説明をしていきます。ブラウザを使うことで手動でダウンロードすることも可能ですが、モデルはかなり大きなファイルになるので、ツールを使用するほうが容易です。

1. モデルダウンロードの手法について

Hugging Faceのモデルを活用するには、まずモデルファイルをローカル環境にダウンロードする必要があります。ここでは、代表的なダウンロード方法について比較します。

wget や curl による方法

Webに公開されているファイルなのでwgetやcurlで取得することは出来ます。

wgetで取得する例

$ wget https://huggingface.co/mmnga/ELYZA-japanese-Llama-2-7b-gguf/resolve/main/ELYZA-japanese-Llama-2-7b-q2_K.gguf

または

curlで取得する例

$ curl -L https://huggingface.co/mmnga/ELYZA-japanese-Llama-2-7b-gguf/resolve/main/ELYZA-japanese-Llama-2-7b-q2_K.gguf -o ELYZA-japanese-Llama-2-7b-q2_K.gguf

非公開または認証が必要なモデルの場合は、Hugging Face のトークンを使用する必要があります。トークンはHugging FaceのWebサイトから取得出来ますがユーザー登録が必須です。わりと認証でエラーになることが多いようです。

git による方法

git cloneでもモデルを取得することは出来ます。ただ、モデルファイルが大きいため、git lftの機能を使用します。

git lfsは Git Large File Storageの略です。これは、バイナリファイルや大容量ファイルを効率的に扱うための Git の拡張機能です。Hugging Faceではgit lfsを使用してモデルリポジトリを管理しています。そのため、リポジトリを git cloneする際には、事前にgit lfs installを実行してセットアップする必要があります。

gitで取得する例

$ git lfs install
$ git clone https://huggingface.co/mmnga/ELYZA-japanese-Llama-2-7b-gguf

認証が必要な場合には以下のように実行します。

$ git clone https://YOUR_USERNAME:YOUR_TOKEN@huggingface.co/mmnga/ELYZA-japanese-Llama-2-7b-gguf

huggingface-cliによる方法

第3の手段としてはhuggingface-cliというツールを使用することも出来ます。この場合には別途ツールのインストールを行う必要があります。

huggingface-cliで取得する例

$ huggingface-cli download mmnga/ELYZA-japanese-Llama-2-7b-gguf --local-dir models --include "ELYZA-japanese-Llama-2-7b-q2_K.gguf"

各方法の比較

方法 長所 短所
wget/curl • 追加ソフトウェアのインストールが不要
• シンプルで直感的
• 単一ファイルの取得に適している 		• 大規模リポジトリの一部のみを取得するのが困難
• 認証が必要なモデルの取得にはヘッダー追加が必要
• スクリプト化が面倒
• 複数ファイルのダウンロードには向かない
git • リポジトリ全体を取得できる
• バージョン管理が可能
• 更新の追跡が容易
• 複数ファイルの同期に適している 		• Git LFS が必要
• リポジトリ全体をダウンロードするため、不要なファイルも取得する
• ディスク容量を多く消費する
• 認証情報がコマンドラインに露出する可能性がある
huggingface-cli • 特定ファイルのみを選択的にダウンロード可能
• キャッシュ機能によるダウンロードの最適化
• 認証が簡単で安全
• スクリプト化に適している
• 再開可能なダウンロード 		• Hugging Face Hub パッケージのインストールが必要
• 他のツールと比較して学習コストがやや高い

これらの比較から複数のモデルを管理する環境では huggingface-cli が最も柔軟で効率的な選択肢になりそうです。

2. Huggingface Hub のインストールと機能

【重要】 huggingface-cli コマンドラインツールはhuggingface_hub パッケージに含まれた機能です。huggingface_hubインストールすると自動的にインストールされます。

インストールの方法は主に2つあります。

2-1. 仮想環境を活用したセットアップ

Hugging Face Hubのツールを導入に仮想環境を使用することシステムのPython環境に依存度を減らしてに使用できます。

venv によるインストール方法

以下は、Python のvenvを使ってHugging Face Hubをインストールする手順となります。

# 必要があればディレクトリを作成移動
$ huggingface-env
$ cd huggingface-env

# 仮想環境の作成
$ python -m venv huggingface-env

# 仮想環境のアクティベート
$ source huggingface-env/bin/activate

# huggingface_hub パッケージのインストール
$ pip install huggingface_hub

# 使用後の仮想環境の非アクティベート
$ deactivate

2-2. apt によるインストール方法

Debian/Ubuntu ベースのシステムでは、aptを使ってインストールすることも可能です。

$ sudo apt update
$ sudo apt install python3-huggingface-hub

2-3. venv による方法と apt による方法の比較

方法 長所 短所
venv + pip • 最新バージョンを入手可能
• 複数バージョンの共存が可能
• プロジェクト単位で分離可能
• root権限不要 		• システム全体で利用する場合は各環境で個別にインストールが必要
apt • システム全体で利用可能
• 依存関係の自動解決
• システムパッケージとの整合性 		• パッケージが古い場合がある
• バージョン指定が難しい
• root権限が必要

3. Huggingface CLI によるモデルダウンロード

huggingface-cliコマンドの説明

huggingface-cliを使用するとモデルを効率的にダウンロードできます。

モデルの取得例

$ huggingface-cli download mmnga/ELYZA-japanese-Llama-2-7b-gguf --local-dir models --include "ELYZA-japanese-Llama-2-7b-q2_K.gguf"

パラメータの意味

  • download　…　 ダウンロード操作を実行することを指定
  • mmnga/ELYZA-japanese-Llama-2-7b-gguf　…　 ダウンロード対象のモデルリポジトリID
  • --local-dir models　…　 ファイルを保存するローカルディレクトリを指定
  • --include "ELYZA-japanese-Llama-2-7b-q2_K.gguf"　…　 ダウンロードするファイルをパターンで指定

おわりに

これでHugging Faceからのモデルのダウンロードが簡単にできるようになりました。Pythonの仮想環境を使用しているので、ダウンロードあたってはシェルスクリプトを使用するのもいいかもしれません。