AI開発環境

ローカルLLMのコンテキスト長とVRAM — KVキャッシュの大きさをモデル公式のconfig.jsonから計算する

ローカルLLMで文脈を伸ばすと増えるのがKVキャッシュ。公式config.jsonの層数・KVヘッド数・head_dimの3つを式に入れれば、1トークンあたりの容量と4K〜128K文脈でのVRAMが電卓で出る。Qwen3とphi-4の5モデルで計算する。

夜の資材置き場で、図面を積んだトレイが作業台に一列に並んで延び、幅の決まった搬入スペースへ迫っていくアイソメ図
AI生成のイメージ画像です

文脈を伸ばしたときのVRAMは、config.jsonの3つの数字(層数・KVヘッド数・head_dim)で決まる。パラメータ数では決まらない。

前回の量子化とVRAMの記事では、重みの容量を量子化別に計算した。KVキャッシュは式を1本示しただけだった。

今回はその後半、KVキャッシュだけを掘る。材料は各モデルの公式リポジトリにあるconfig.jsonとモデルカード、Ollamaとllama.cppの公式ドキュメントだけだ。動かした記録ではなく、計算の手順を並べる。

config.jsonで見るのは4つの項目だけ

KVキャッシュは、これまでの会話の各トークンについて、層ごとにキー(K)とバリュー(V)を取っておく置き場だ。NVIDIAの技術ブログは、1トークンあたりの容量を次の式で示している。

2 × 層数 × (ヘッド数 × ヘッドの次元) × 精度のバイト数

この式の材料は、Hugging Faceの公式リポジトリにあるconfig.jsonにそのまま書いてある。見る項目は4つだ。

項目名 意味 式のどこに入るか
num_hidden_layers 層数 層数
num_key_value_heads KV側のヘッド数 ヘッド数
head_dim 1ヘッドの次元 ヘッドの次元
torch_dtype 配布時の精度 (KVの精度は実行側で決まる)

注意点は2つある。1つ目は、ヘッド数に num_attention_heads ではなく num_key_value_heads を入れること。Transformersのドキュメントは、この2つが等しければMHA、1ならMQA、その間ならGQA(グループ化クエリ注意)になると説明している。

2つ目は、head_dim が書かれていないモデルがあること。同じドキュメントでは、省略時は hidden_size ÷ num_attention_heads になるとされている。

精度のバイト数は、Ollamaもllama.cppもKVキャッシュの既定が f16 なので2バイトで計算する(出典: Ollama FAQ、llama.cpp server README)。

5モデルで1トークンあたりを計算する

各モデルのconfig.jsonから拾った値がこれだ(2026-11-11確認)。

モデル(公称パラメータ数) 層数 KVヘッド数 head_dim 1トークンあたり(f16)
Qwen3-8B(8.2B) 36 8 128 147,456バイト
Qwen3-14B(14.8B) 40 8 128 163,840バイト
Qwen3-32B(32.8B) 64 8 128 262,144バイト
Qwen3-30B-A3B(30.5B) 48 4 128 98,304バイト
phi-4(14B) 40 10 128(5120÷40) 204,800バイト
0100200300400500600KB / トークンQwen3-30B-A3B30.5B / 48層 × KV498.3Qwen3-8B8.2B / 36層 × KV8147.5Qwen3-14B14.8B / 40層 × KV8163.8phi-414B / 40層 × KV10204.8Qwen3-32B32.8B / 64層 × KV8262.1(仮定)8BがMHAなら36層 × KV32589.8式: 2(KとV) × 層数 × KVヘッド数 × head_dim(128) × 2バイト。左の数字は公称パラメータ数
棒は1トークンあたりのKVキャッシュ(f16、単位KB=1000バイト)。各モデル公式のconfig.jsonの層数・KVヘッド数・head_dimから計算した。30Bの30B-A3Bが8Bより小さいのはKVヘッドが4本だから。最下段はQwen3-8BのKVヘッドをQ側と同じ32本にした仮定で、GQAで4分の1になっていることを示す。

計算を1本ずつ書いておく。

  • Qwen3-8B: 2 × 36 × 8 × 128 × 2 = 147,456
  • Qwen3-32B: 2 × 64 × 8 × 128 × 2 = 262,144
  • Qwen3-30B-A3B: 2 × 48 × 4 × 128 × 2 = 98,304
  • phi-4: 2 × 40 × 10 × 128 × 2 = 204,800

phi-4の設定ファイルには head_dim が無い。hidden_size 5120 ÷ num_attention_heads 40 = 128 で補った。

面白いのはQwen3-30B-A3Bだ。総パラメータ30.5Bなのに、1トークンあたりは8Bより小さい。モデルカードによればKVヘッドが4本しかないからだ。パラメータ数が大きい=文脈に食うVRAMも大きい、とは限らない。

もう1つ、Qwen3-8Bのクエリ側のヘッドは32本ある。もしKVも32本のMHAだったら、2 × 36 × 32 × 128 × 2 = 589,824バイトで4倍になる。GQAが8本に絞っているおかげで、いまの数字に収まっている。

文脈の長さを掛ける: 4Kから128Kまで

1トークンあたりにトークン数を掛ければ、文脈全体のKVキャッシュになる。単位はGB(10億バイト)、f16での計算値だ。

モデル 4,096 16,384 32,768 131,072
Qwen3-8B 0.60 2.42 4.83 19.33
Qwen3-14B 0.67 2.68 5.37 21.47
Qwen3-32B 1.07 4.29 8.59 34.36
Qwen3-30B-A3B 0.40 1.61 3.22 12.88
phi-4 0.84 3.36 (対象外) (対象外)

例として Qwen3-8B の32K文脈なら、147,456 × 32,768 = 4,831,838,208バイト、約4.83GBだ。

上限の長さはモデルカードで確かめる。Qwen3はどれもネイティブ32,768トークン、YaRNという拡張を使えば131,072トークンとされている。phi-4のモデルカードは16Kトークンなので、32K以上は表から外した。

128Kには但し書きがつく。Qwenのモデルカードによると、YaRNは rope_scaling を設定して有効にするもので、オープンソースのフレームワークの実装は静的なため短い文章で性能に影響しうる。だから長文が必要なときだけ足すように、と書かれている。

なおQwen3のconfig.jsonの max_position_embeddings は40,960だ。モデルカードはこれを出力用32,768+プロンプト用8,192の枠と説明している。

32Bに128Kを持たせると、KVキャッシュだけで34GBを超える。資材置き場(VRAM)の広さを決める前に、どれだけの図面を広げっぱなしにするか決めるのが段取りだ。

Ollamaとllama.cppで「何トークン確保するか」を決める

KVキャッシュは、実際に使ったぶんではなく、確保した文脈の長さで見積もるのが安全だ。だから設定値を知っておく。

Ollamaの文脈の長さのページによると、既定はVRAM容量で変わる。24GiB未満は4K、24〜48GiBは32K、48GiB以上は256Kだ。変えるにはアプリ設定のスライダーか、OLLAMA_CONTEXT_LENGTH=64000 ollama serve のような環境変数を使う。確保された長さは ollama ps のCONTEXT列、GPUに載り切ったかはPROCESSOR列で確かめる(出典: Ollama Context length / FAQ)。

KVキャッシュ自体を小さくするのが OLLAMA_KV_CACHE_TYPE だ。FAQには、q8_0 はf16の約1/2で精度の低下はごく小さい、q4_0 は約1/4で低下は小〜中、とある。Flash Attentionが有効なときに効く設定だ。

llama.cppのサーバーでは -c(--ctx-size)が文脈の長さで、既定の0は「モデルから読み込む」と書かれている。KVの型は -ctk / -ctv で、既定はどちらもf16。q8_0 や q4_0 などを選べる。Flash Attentionは -fa で、既定はauto(出典: llama.cpp server README)。

-c を省いたままにしないのがKY活動だ。たとえばQwen3-8Bで、仮に設定ファイルの40,960トークンぶんが確保されれば、KVはf16で147,456 × 40,960 ≒ 6.04GBになる。重み(5.2GB)と合わせて約11.2GBで、8GBの枠には入らない計算だ。

同時に複数の会話をさばく -np(スロット数)を使うと、KVをスロットで分け合う設定も絡む。1人で使うなら、まず -c を明示するのが先だ。

VRAM容量ごとの当てはめ

重みはOllamaライブラリの既定タグの公称サイズ、KVは上の表の計算値(f16)で足し算する。実行時の作業領域は含まない。

  • 12GB: qwen3:8b(5.2GB)+32K文脈(4.83GB)= 約10.0GB。phi4(9.1GB)なら16K(3.36GB)で約12.5GBと枠を超えるので、文脈を8Kに抑えるかKVをq8_0にする
  • 16GB: qwen3:14b(9.3GB)+32K(5.37GB)= 約14.7GB。余白が薄いので、KVをq8_0にすれば約12.0GBまで下がる
  • 24GB: qwen3:32b(20GB)+4K(1.07GB)= 約21.1GB。32Kにすると28.6GBで超える。KVをq4_0(約1/4)にして約22.1GBだ

VRAMの段ごとに載るモデル規模の早見表はローカルLLMのPCスペック記事、枠を超えてメインメモリにあふれたときの速度の落ち方はqwen3をVRAM 8GBで測った記事にまとめてある。

機体を選ぶ順番は、型番より先に「どのモデルで、何トークン持たせるか」だ。それが決まれば、重み+KVで必要なVRAMが出る。あとは今週のセール機をVRAM基準で仕分けた表と二刀流ランキングで相見積もりすればいい。

最強の1台より、「使いたい文脈の長さまでKVが入る枠」を外さない1台。config.jsonを1回開けば、その枠は計算できる。


※本記事は公開情報(各モデルの公式config.json・モデルカード、Ollama・llama.cppの公式ドキュメント)に基づく解説です。KVキャッシュの値は公式の式と設定値からの計算で、実行時の作業領域・ランタイムの実装・ドライバにより実際の使用量は変わります。長い文脈での品質は各モデルの公式情報をご確認ください。

出典