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
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
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
{
"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
を指定しています。
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
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の機能を利用できます。
Discussion