gguf-fit の使い方だけ ─ 2行で llama-server の起動コマンドをもらう

前回、gguf-fit というツールを紹介する記事を書いた。GGUFファイルを読むだけでllama-serverの起動設定を決める道具の話で、量子化の中身がずれている話や、KVキャッシュを実測した話まで書いた。読んでくれた人から「難しい」という声をもらった。

たしかに、使うだけならあそこまでの話は要らない。今回は使い方だけに絞る。

前記の記事

前回の記事は読まなくていい

先に言っておくと、この記事を読むのに前回の記事は要らない。gguf-fitがなぜその数字を出せるのかは前回に書いたので、気になったらあとで読んでほしい。ここでは「何を打てば何が出てくるか」だけ書く。

gguf-fit が何をしてくれるか

一言でいうと、GGUFファイルを渡すと、自分のGPUに載るかどうかと、ctx(会話として覚えていられる長さの上限)をどこまで伸ばせるかを教えてくれる道具。GPUを1回も動かさずに、ファイルの中身を読むだけで答えを出す。

自分は量子化違いのGGUFファイルを何個も持っていて、どれが自分のGPUに載るのか、起動して確かめては落として、を繰り返していた。それが要らなくなった。

入れる

uv tool install git+https://github.com/zephel01/gguf-fit

uv が無ければ先に入れておく必要があるけど、これ1行でコマンドが3つ増える。

Step 1: ファイルを読ませる

手元のGGUFファイルに向けて、これを打つ。

gguf-probe --json --out gguf.json /models/*.gguf

`/models/*.gguf` のところは自分のファイルの場所に置き換える。フォルダの中のGGUFを全部読んで、gguf.json というファイルに書き出す。数秒で終わる。

--json を付けずに打つと、画面に一覧が出る。実際にQwen3.8-27Bの量子化違いを読ませると、こういう表になる(全12種類のうち5つだけ抜き出した)。

file        GB     GiB   最多の型
Q3_K_S    12.57  11.71   Q3_K
Q4_K_M    17.11  15.93   Q4_K
Q5_K_M    19.83  18.47   Q5_K
Q6_K      22.88  21.31   Q6_K
Q8_0      29.05  27.05   Q8_0

見るのは GiB の列だけでいい。自分のGPUのメモリ(VRAM)より小さければ、そのファイルは載る可能性が高い。

Step 2: 起動コマンドをもらう

さっき作った gguf.json と、載せたいファイル名の一部を渡す。

gguf-plan gguf.json --pick Q5_K_M

VRAMの容量は指定しなくていい。自分のGPUを自動で見て、それに合わせて計算してくれる。手元のRTX 5090(31.4 GiB)で打つと、こんな出力になる。

# ===== Qwen3.8-27B-Q5_K_M / ctx 131,072 / KV f16 =====
# estimate: model 18.47 + KV 8.63 + overhead 1.00 = 28.10 GiB / budget 31.4 GiB
# headroom 3.30 GiB
# native ctx = 262,144  / no rope scaling
# hybrid attention: only 17/65 layers hold KV = 68 KB/token
# KV f16 = 69.1 KB/token, measured here (gguf-calibrate), not derived from the GGUF

# --- llama-server ---
# found 4 MTP tensors -> adding --spec-type draft-mtp
llama-server -m /mnt/data/models/Qwen3.8-27B-GGUF/Qwen3.8-27B-Q5_K_M.gguf \
  --port 8085 --device CUDA0 \
  -ngl 99 -fa on \
  --ctx-size 131072 --parallel 1 \
  --batch-size 2048 --ubatch-size 512 \
  --threads 16 \
  --spec-type draft-mtp

これをそのままコピーして、ターミナルに貼って実行するだけでいい。`-ngl` や `-fa` が何の略かを1個ずつ理解する必要はない。ctxの数字も、KVを圧縮するかどうかも、GPUを1回も起動せずに全部決めてくれている。

自分のGPUがもっと小さければ、同じコマンドでも出てくる ctx-size はもっと小さい数字になる。VRAMに対してファイルが大きすぎるときは、そもそも起動コマンドが出ず、代わりに理由が表示される。

出てくる言葉だけ、ざっくり

VRAM: GPUに載っているメモリ。「24GB」のカードならだいたい24GB。モデルの重さがこれより大きいと、そもそも起動しない。

量子化: モデルの中身の数字を、精度を落として小さくしたもの。Q4のように数字が小さいほどファイルは軽いが、粗くなる。

ctx: 一度の会話でモデルが覚えていられる長さ。長くするほどVRAMを食う。

KVキャッシュ: ctxを伸ばすたびに増えていくメモリ。これをどこまで圧縮できるかで、同じVRAMでもctxをどこまで伸ばせるかが変わる。gguf-planが自動で計算しているのはこの部分。

もっと知りたくなったら

なぜこの数字が出るのか、実測すると計算値とどうずれるのか、みたいな話は前回の記事に書いた。65層あるモデルなのにKVを持っているのは17層だけだった話や、自分が計算をひとつ間違えていた話も。使い方だけ分かれば十分な人は読まなくていい。

おわりに

gguf-fitはPythonで書いたツールで、MITライセンスでGitHubに置いてある。

https://github.com/zephel01/gguf-fit

使ってみて、出てきたコマンドで起動しなかった、みたいな話があれば教えてほしい。手元はRTX 5090・RTX 3090・Radeon 8060Sでしか試せていないので、他の環境でどう動くかは正直分かっていない。

#gguffit #GGUF #llamacpp #ローカルLLM #初心者 #量子化 #Python #個人開発 #uv #VRAM #初心者入門