セットアップガイド

【Docker/環境】Hugging Face Hub CLI完全ガイド：モデルダウンロードとDocker内管理のトラブルシューティング

· 15分で読めます · 2 閲覧

問題の概要：Docker環境でのHugging Face Hub CLIの一般的な課題

Hugging Face Hubは、事前学習済みモデルやデータセットを共有・利用するためのプラットフォームとして、AI開発者にとって必須のツールとなっています。特にDockerコンテナ内で機械学習パイプラインを構築する際、Hugging Face Hub CLI（コマンドラインインターフェース）を用いてモデルやデータを効率的に管理することが一般的です。しかし、Docker環境特有の制約により、以下のようなエラーに直面することが頻繁にあります。

  • OSError: We couldn't connect to 'https://huggingface.co' to load this file, couldn't find it in the cached files and it looks like hf.co is not accessible from the network.
  • PermissionError: [Errno 13] Permission denied: '/.cache/huggingface'
  • ValueError: Offline mode is enabled and model 'bert-base-uncased' is not cached locally.
  • Dockerビルド時の認証トークン漏洩リスク
  • コンテナ再起動時のキャッシュ消失による再ダウンロード

これらの問題は、ネットワーク設定、キャッシュパスの権限、認証情報の管理、Dockerレイヤーの特性が原因で発生します。本記事では、これらの課題を体系的に解決し、安定してHugging Face Hubを利用できるDocker環境の構築方法を解説します。

原因の解説：なぜDocker環境で問題が起こるのか？

Dockerコンテナは、軽量で再現性の高い環境を提供しますが、その隔離性と一時的なストレージの性質が、Hugging Face Hub CLIの標準的な使い方と衝突します。主な原因は以下の4点です。

1. ネットワークの隔離とプロキシ設定

企業内の開発環境や特定のクラウド環境では、Dockerコンテナが外部ネットワーク（特にhuggingface.co）に直接アクセスできない場合があります。デフォルトのtransformersライブラリやhuggingface-hubクライアントは、この制約を考慮していないため、接続エラーが発生します。

2. キャッシュディレクトリの権限と永続性

Hugging Face Hubはダウンロードしたモデルをローカルにキャッシュします（デフォルトでは~/.cache/huggingface）。しかし、Dockerコンテナ内では：

  • ルートユーザーで実行されない場合、ホームディレクトリへの書き込み権限がない。
  • コンテナが削除されると、キャッシュも一緒に消えてしまう。

これにより、毎回のビルドや実行で巨大なモデルファイルを再ダウンロードする非効率が生じます。

3. 認証トークンの安全な管理

プライベートリポジトリのモデルをダウンロードするには、Hugging Faceのアクセストークンが必要です。このトークンをDockerfile内に平文で記述したり、環境変数として不適切に扱うと、セキュリティ上の重大なリスクとなります。

4. Dockerレイヤーキャッシュとモデルキャッシュの不一致

Dockerはレイヤーキャッシュを用いてビルドを高速化しますが、RUNコマンド内でダウンロードしたモデルキャッシュは、そのコマンドが変更されると無効化され、再ダウンロードが強制されます。効率的なキャッシュ戦略が必要です。

解決方法：ステップバイステップガイド

以下に、上記の問題をすべて解決する、実践的なDocker環境構築手順を示します。

ステップ1：ベースとなるDockerfileの作成とHF CLIのインストール

まず、必要なツールをインストールする最小限のDockerfileを作成します。Pythonの公式イメージをベースに、huggingface-hub CLIとその依存関係をインストールします。

# Dockerfile
FROM python:3.10-slim

WORKDIR /app

# システム依存関係のインストール（必要に応じて）
RUN apt-get update && apt-get install -y 
    git 
    && rm -rf /var/lib/apt/lists/*

# huggingface-hub CLIとtransformersライブラリのインストール
RUN pip install --no-cache-dir huggingface-hub transformers

# キャッシュ用のディレクトリを作成（適切な権限で）
RUN mkdir -p /hf_cache && chmod 777 /hf_cache

# 環境変数でキャッシュパスを設定
ENV HF_HOME=/hf_cache

# コンテナ起動時のデフォルトコマンド
CMD ["bash"]

ステップ2：安全な認証トークンの受け渡し

アクセストークンは、ビルド時ではなく実行時に渡すことで安全性を高めます。Dockerのシークレット機能（BuildKit）または実行時環境変数を使用します。

方法A：docker run 時の環境変数

# ビルド
docker build -t my-hf-app .

# 実行（トークンを環境変数で渡す）
docker run -it --rm 
  -e HF_TOKEN=your_huggingface_token_here 
  my-hf-app 
  python -c "from huggingface_hub import login; login()"

方法B：Docker BuildKitのシークレットを使用（より安全）

# トークンをファイルに保存（.gitignoreに追加すること！）
echo "your_huggingface_token_here" > .hf_token

# BuildKitを使ってシークレットを渡してビルド
DOCKER_BUILDKIT=1 docker build --secret id=hf_token,src=.hf_token -t my-hf-app .

# ビルド中のRUNコマンドでシークレットにアクセスするには、Dockerfileを修正する必要があります。

ステップ3：永続的なキャッシュボリュームのマウント

モデルキャッシュをホストマシンのディレクトリに永続化することで、コンテナ再起動後もダウンロード済みモデルを利用できます。

# ホスト側にキャッシュディレクトリを作成
mkdir -p ~/huggingface_cache

# ボリュームをマウントしてコンテナを実行
docker run -it --rm 
  -e HF_HOME=/hf_cache 
  -v ~/huggingface_cache:/hf_cache 
  -e HF_TOKEN=${HF_TOKEN}  # シェル変数から取得
  my-hf-app

# コンテナ内でモデルをダウンロード（キャッシュに保存される）
# docker exec -it [container_id] bash などで入って実行
huggingface-cli download bert-base-uncased --local-dir /hf_cache/models/bert-base-uncased

ステップ4：オフライン利用とキャッシュ事前構築の戦略

ネットワークが不安定な環境や、本番デプロイ時には、オフラインで動作するようにキャッシュを事前に構築します。

# 1. 専用の「キャッシュ構築用」Dockerfileステージを用意
# Dockerfile
FROM python:3.10-slim as cache-builder
WORKDIR /app
RUN pip install huggingface-hub
ENV HF_HOME=/hf_cache
RUN mkdir -p ${HF_HOME}
# 必要なモデルをリスト化してダウンロード
RUN python -c "
from huggingface_hub import snapshot_download
snapshot_download('bert-base-uncased', cache_dir='${HF_HOME}')
snapshot_download('gpt2', cache_dir='${HF_HOME}')
"

# 2. 本番用イメージでは、構築済みキャッシュをコピー
FROM python:3.10-slim
WORKDIR /app
COPY --from=cache-builder /hf_cache /hf_cache
ENV HF_HOME=/hf_cache
ENV TRANSFORMERS_OFFLINE=1 # オフラインモードを有効化
RUN pip install transformers
COPY . .
CMD ["python", "your_app.py"]

コード例・コマンド例

Docker内での典型的なHugging Face Hub CLI使用例

# コンテナ内でモデルをダウンロード（キャッシュに保存）
huggingface-cli download meta-llama/Llama-2-7b --local-dir /hf_cache/llama2-7b --token ${HF_TOKEN}

# キャッシュされているモデル一覧を確認（Pythonスクリプト内）
from huggingface_hub import scan_cache_dir
cache_info = scan_cache_dir()
for repo in cache_info.repos:
    print(f"Repo: {repo.repo_id}, Size: {repo.size_on_disk}")

# 特定のモデルをキャッシュからロード（オフライン時）
from transformers import AutoModel, AutoTokenizer
model = AutoModel.from_pretrained("bert-base-uncased", cache_dir="/hf_cache", local_files_only=True)
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased", cache_dir="/hf_cache", local_files_only=True)

トラブルシューティング用コマンド

# 1. ネットワーク接続テスト
docker run --rm my-hf-app curl -I https://huggingface.co

# 2. キャッシュディレクトリの権限確認
docker run --rm my-hf-app ls -la /hf_cache

# 3. 環境変数が正しく設定されているか確認
docker run --rm -e HF_HOME=/test my-hf-app env | grep HF

# 4. キャッシュからモデルを強制削除（問題のあるキャッシュをクリア）
docker run --rm -v ~/huggingface_cache:/cache my-hf-app 
  python -c "from huggingface_hub import delete_from_cache; delete_from_cache('bert-base-uncased')"

まとめ・補足情報

Docker環境でHugging Face Hub CLIを効果的かつ安全に使用するには、「キャッシュの永続化」「認証情報の安全な管理」「オフライン動作の考慮」の3点が重要です。本記事で紹介した方法を実践することで、以下のメリットが得られます。

  • ビルド時間の短縮: モデルキャッシュをボリュームやマルチステージビルドで共有することで、不要な再ダウンロードを防ぎます。
  • セキュリティの向上: アクセストークンをDockerfileにハードコードせず、実行時やシークレットで安全に渡せます。
  • 環境の再現性と移植性: 依存モデルをキャッシュと共にパッケージ化することで、どの環境でも同じモデルで動作を保証できます。
  • オフライン開発の可能化: 事前にキャッシュを構築しておくことで、インターネットに接続していない本番環境でもモデルをロードできます。

最後の注意点: キャッシュ用ボリュームのディスク容量には注意してください。大規模言語モデル(LLM)など、サイズの大きなモデルを多数キャッシュすると、あっという間に数十GBを消費します。定期的なキャッシュの掃除（huggingface-cli delete-cache）や、必要なモデルのみをピンポイントでダウンロードする習慣をつけることをお勧めします。

このガイドが、Dockerを用いた再現性の高いAI開発環境の構築に役立つことを願っています。Hugging Face Hubは日々進化しているため、最新のベストプラクティスについては公式ドキュメント（日本語）も併せて参照してください。

この記事は役に立ちましたか？