WSL2+Docker+llama.cppによるHuggingFaceモデルのGGUF形式変換

本記事の概要

本記事では、WSL2環境でDockerとllama.cppを使用して、HuggingFace上のモデルをGGUF形式に変換する方法を解説します。
Windowsネイティブ環境でllama.cppを利用しようとすると、C++コンパイラの設定や依存関係の解決など、環境構築に手間がかかります。本記事で紹介するWSL2+Docker+VSCodeの組み合わせにより、コンパイラ設定などの手順を回避し、環境構築から変換作業までをスムーズに行うことができます。

前提とする環境

• OS: Windows 11
  • バージョン: 23H2
  • 64ビットオペレーティングシステム、x64ベースプロセッサ
• WSL2: Ubuntu 24.04.1 LTS
• Visual Studio Code: 1.98.0 + Remote Development拡張機能

プロジェクト構成

次の構成を準備します。

llama-cpp-converter/
├── .devcontainer/
│   └── devcontainer.json
├── models/               # 変換後のモデルを保存するディレクトリ
├── docker-compose.yml
├── Dockerfile
└── download_model.py     # HuggingFaceからモデルをダウンロードするスクリプト

必要なファイルの作成

必要なファイルを作成します。

docker-compose.yml

docker-compose.yml

version: "3.8"

services:
  llama-cpp-converter:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: llama-cpp-converter
    volumes:
      - ./models:/app/models
      - ./download_model.py:/app/download_model.py
    tty: true
    stdin_open: true

Dockerfile

Dockerfile

FROM ubuntu:22.04

# 必要なパッケージをインストール
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    build-essential \
    cmake \
    curl \
    git \
    wget \
    python3 \
    python3-pip \
    git-lfs \
    ca-certificates \
    g++ \
    make \
    && rm -rf /var/lib/apt/lists/*

# Python依存関係のインストール
RUN pip3 install --upgrade pip && \
    pip3 install torch numpy sentencepiece transformers huggingface_hub

# llama.cppをクローンしてビルド
WORKDIR /app
RUN git clone https://github.com/ggerganov/llama.cpp && \
    cd llama.cpp && \
    ls -la && \
    make -j$(nproc) || cat Makefile

# llama.cppの依存関係をインストール
RUN cd /app/llama.cpp && \
    pip3 install -r requirements.txt

# モデルを格納するためのディレクトリを作成
RUN mkdir -p /app/models

# downloadsディレクトリを作成
RUN mkdir -p /app/downloads

# 作業ディレクトリを設定
WORKDIR /app/llama.cpp

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

devcontainer.json

devcontainer.json

{
    "name": "Llama CPP Converter",
    "dockerComposeFile": "../docker-compose.yml",
    "service": "llama-cpp-converter",
    "workspaceFolder": "/app"
}

download_model.py

download_model.pyを作成します。今回はMODEL_NAMEにSB Intuitions社がMITライセンスで公開しているsarashina2.2-3b-instruct-v0.1を指定しています。

download_model.py

from huggingface_hub import snapshot_download

# ダウンロードするモデル名を定義
MODEL_NAME = "sbintuitions/sarashina2.2-3b-instruct-v0.1"

# ダウンロード先のディレクトリを定義
DOWNLOADS_DIR =  f"/app/downloads/{MODEL_NAME.split('/')[-1]}"

if __name__ == "__main__":
    print(f"{MODEL_NAME} のダウンロードを開始します...")
    snapshot_download(
        repo_id=MODEL_NAME,
        local_dir=DOWNLOADS_DIR,
        local_dir_use_symlinks=False,
        revision="main"
    )
    print(f"{MODEL_NAME} のダウンロードが完了しました。")

HuggingFace上のモデルをGGUF形式に変換する手順

VSCodeによるコンテナの起動

次の手順でコンテナを起動します。

• VSCodeを起動して左下の [><] アイコンをクリックし、[WSLへの接続] を実行する
• プロジェクトのルートディレクトリを開く
• ポップアップ表示される [コンテナで再度開く] を実行する
• VSCodeがDevContainerを構築し、コンテナ内の環境が起動するまで待つ

モデルダウンロードの実行

コンテナ内のターミナルで以下のコマンドを実行し、HuggingFaceからモデルをダウンロードします。

python3 /app/download_model.py

必要に応じて、download_model.pyのMODEL_NAME変数を変更して、ダウンロードするモデルを指定できます。

「You must have access to it and be authenticated to access it」などのエラーが出た場合は以下のコマンドを実行します。

# HuggingFaceのTokenを使ってログイン
huggingface-cli login --token {HuggingFaceのToken}

# ダウンロードスクリプトを実行
python3 /app/download_model.py

HuggingFaceのTokenを所持していない場合は以下の手順で作成します:

• Hugging Face でアカウントを作成
• 設定ページから「Access Tokens」→「Create new Token」を選択
• Token type を「Read」に設定
• Token Name を「model-download」などわかりやすい名前に設定
• 「Create token」をクリック
• 表示されたトークンを保存（表示は一度きりなので注意）

制限付きモデルの場合の追加手順:

• ブラウザでHuggingFaceの該当モデルのページにアクセス
• 利用規約に同意して「Access repository」などのボタンをクリック
• 必要に応じてKaggle認証との連携を許可

GGUF形式への変換

コンテナ内のターミナルで以下のコマンドを順番に実行し、ダウンロードしたモデルをGGUF形式に変換します。

cd /app/llama.cpp
python3 convert_hf_to_gguf.py \
    --outfile /app/models/sarashina2.2-3b-instruct-v0.1.gguf \
    --outtype f16 \
    /app/downloads/sarashina2.2-3b-instruct-v0.1

今回はsarashina2.2-3b-instruct-v0.1を例としていますが、違うモデルを扱う場合は次のようにします。

cd /app/llama.cpp
python3 convert_hf_to_gguf.py \
    --outfile /app/models/{モデル名}.gguf \
    --outtype f16 \
    /app/downloads/{モデル名}

量子化（オプション）

変換したモデルをさらに軽量化したい場合は、量子化を適用します。

cd /app/llama.cpp
./quantize /app/models/sarashina2.2-3b-instruct-v0.1.gguf \
    /app/models/sarashina2.2-3b-instruct-v0.1-q4_0.gguf q4_0

主要な量子化オプション: q4_0, q5_k, q8_0

コンテナ外部へのモデルの取り出し

モデルをコンテナ外部で利用するには、プロジェクトフォルダのmodelsディレクトリから必要なファイルを移動させます。docker volumeのマッピングにより、コンテナ内の/app/modelsディレクトリはホストの./modelsディレクトリと同期しているため、変換されたモデルはホストからも直接アクセスできます。

まとめ

WSL2+Docker+llama.cppを組み合わせることで、HuggingFaceのモデルをGGUF形式に効率的に変換できる環境を構築しました。
Windowsネイティブ環境でllama.cppを利用しようとすると、C++コンパイラの設定や依存関係の解決など、環境構築に手間がかかりますがWSL2+Dockerで環境を構築することで、アクセスしやすい形でllama.cppの機能を利用できます。