TransformersでGGUFを読み込む入門

先に結論

Transformersは`gguf_file`を指定するとGGUFをPyTorch modelへ読み戻せます。ただし、量子化された小さなfileをそのまま省memory推論する経路ではありません。公式文書どおりweightを指定`dtype`へ逆量子化して展開するため、最初に対応architecture、空きRAM、保存先を確認し、小型modelと1promptで入口を確かめます。

確認日時: 2026年8月14日（Asia/Tokyo）
対象version: Transformers v5.15.0、commit 5eddc12。GGUFの操作は同日の公式文書とintegration sourceも照合。
検証区分: 公式documentationとrepositoryに基づく机上調査・再現手順です。この制作環境ではmodelをdownloadせず、PyTorch推論、必要RAM、生成結果を実測していません。
適用外: 公式integrationに未登録のarchitecture、tokenizer情報が不足したGGUF、任意の量子化type、追加学習や再変換後の品質保証。

始める前に知っておくこと

GGUFは、modelのtensorとmetadataを配布・推論しやすい一つのbinary形式へまとめたものです。llama.cppなどは量子化GGUFを直接扱えます。一方、TransformersのGGUF loaderは、追加学習やPyTorchでの編集へ戻すため、checkpointをfull weightへ展開します。

公式GGUF文書は既定例をtorch.float32とし、float16やbfloat16も指定できると説明しています。つまり必要memoryは元GGUFのfile sizeだけでは決まりません。展開後のdtype、parameter数、load中の一時領域、Python／PyTorchのoverheadまで含めて余裕を取ります。空きが不明なら、大きいmodelを試す前にlocal LLMのVRAM計算記事でweightとKV cacheを分けて考えてください。

この手順では次を固定します。

Transformers 5.15.0
公式文書に掲載された対応済みの小型GGUF repositoryと正確なfilename
最初はCPU、torch.float32、短いprompt、短い生成上限
model repositoryのrevision、GGUFのSHA-256、license、利用条件

公式例のmodel IDは手順説明用です。配布元やlicenseを確認せずproduction dataへ使いません。環境構築ではOSとacceleratorに合うPyTorchの公式installationを先に確認し、既存Python環境へ直接混ぜず仮想環境を使います。

最短手順

1. 隔離環境を作り、versionを確認する

python3 -m venv .venv-gguf-load
source .venv-gguf-load/bin/activate
python -m pip install "transformers==5.15.0" gguf torch
python -c 'import transformers; print(transformers.__version__)'

最後の表示が5.15.0であることを確認します。PyTorchのinstall方法はOS、CPU、CUDA、Metalで異なります。上のcommandが自分のplatformに適合するとは限らないため、GPUを使う場合はPyTorch公式の導入案内へ合わせます。

2. GGUFをtokenizerとmodelの両方へ指定する

次はTransformers公式文書と同じ形の最小scriptです。MODEL_IDとGGUF_FILEは、確認したrepositoryと実在filenameへ置き換えます。

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

MODEL_ID = "TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF"
GGUF_FILE = "tinyllama-1.1b-chat-v1.0.Q6_K.gguf"

tokenizer = AutoTokenizer.from_pretrained(
    MODEL_ID,
    gguf_file=GGUF_FILE,
)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    gguf_file=GGUF_FILE,
    dtype=torch.float32,
)

prompt = "Explain in one sentence what a local language model is."
inputs = tokenizer(prompt, return_tensors="pt")
with torch.inference_mode():
    output = model.generate(
        **inputs,
        max_new_tokens=32,
        do_sample=False,
    )

print("dtype:", next(model.parameters()).dtype)
print(tokenizer.decode(output[0], skip_special_tokens=True))

tokenizerにもgguf_fileを渡すのが要点です。modelだけを読んで別revisionのtokenizerを組み合わせると、token ID、special token、chat templateの差を見落とします。初回はdevice_map、量子化library、compileなどを追加せず、問題の層を増やしません。

3. 最初の成功を三つに分けて確認する

成功は、自然な文章が一度出ただけではありません。

loaderがarchitectureとGGUFを認識し、例外なくmodelを構築する。
表示されたparameterのdtypeが指定したtorch.float32である。
固定promptをdo_sample=Falseで最後まで生成し、tokenizer decodeが完了する。

実行前後のprocess memoryもOSのmonitorで記録します。量子化GGUFのfile sizeとprocess memoryが近くないこと自体は異常ではありません。full weightへ展開する仕様と整合します。

つまずきやすい点と戻し方

load中にmemory不足になる

model IDやfilenameを変える前に、元GGUF size、parameter数、指定dtype、空きRAMを確認します。別processを無理に終了せず、scriptを停止し、より小さい対応modelで入口を確認します。float16やbfloat16へ変える場合は別条件として記録し、CPU／acceleratorの対応と数値差を再確認します。

architectureが未対応と表示される

Transformersのintegration sourceにはGGUFからconfigへ移すmappingと対応converterがあります。model名が似ていることを根拠に続行せず、v5.15.0のsourceで対象architectureが登録されているか確認します。未対応なら別loaderへ迂回せず、そのartifactでの手順を中止します。

tokenizerまたはspecial tokenで失敗する

modelとtokenizerへ同じMODEL_ID、同じGGUF_FILE、同じrevisionを指定したか確認します。repository上の元tokenizerを混ぜた場合は一度外し、GGUF内のmetadataから読む公式手順へ戻します。chat形式の品質確認は単純promptのload成功後に分けます。

元へ戻す

この手順は入力GGUFを書き換えません。scriptを停止し、作成した仮想環境と新しいcacheだけを対象として削除すれば、元artifactは残ります。削除前に入力fileのSHA-256、repository revision、cache pathを確認し、共有cacheや別projectのfileを消さないでください。

まとめ

TransformersでGGUFを開く最短ルートは、対応済みの小型artifact、固定version、同じgguf_fileを指定したtokenizerとmodel、明示dtype、短い決定的生成です。最重要の前提は、量子化fileの省memory状態がPyTorchへそのまま持ち込まれるのではなく、full weightへ展開されることです。最初の成功とmemory境界を確認してから、保存、編集、再変換へ進みます。

さらに深く理解する

同じテーマの玄人向け監査記事で、source revision、metadata、tokenizer、出力、peak RAMを固定し、Hugging Face形式保存からGGUF再変換までを一つのroundtripとして検証する方法を確認できます。

既存のllama.cppでGGUFを動かす入門は量子化GGUFを推論runtimeで直接扱う役割です。本稿はGGUFをPyTorchのfull weightへ戻す入口に限定しています。

参考資料

Transformers GGUF公式文書（2026年8月14日確認）
Transformers v5.15.0 release（commit 5eddc12、2026年8月10日公開）
Transformers GGML／GGUF integration source（2026年8月14日確認）
GGML公式GGUF仕様（2026年8月14日確認）