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

文脈を伸ばしたときの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バイト |
計算を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キャッシュの値は公式の式と設定値からの計算で、実行時の作業領域・ランタイムの実装・ドライバにより実際の使用量は変わります。長い文脈での品質は各モデルの公式情報をご確認ください。
出典
- Qwen3-8B config.json(num_hidden_layers 36 / num_key_value_heads 8 / head_dim 128 / max_position_embeddings 40960): https://huggingface.co/Qwen/Qwen3-8B/blob/main/config.json
- Qwen3-8B モデルカード(8.2B、GQA 32/8、32,768ネイティブ・YaRNで131,072、40,960の内訳、静的YaRNの注意): https://huggingface.co/Qwen/Qwen3-8B
- Qwen3-14B config.json(40層 / KV 8 / head_dim 128): https://huggingface.co/Qwen/Qwen3-14B/blob/main/config.json
- Qwen3-32B config.json(64層 / KV 8 / head_dim 128): https://huggingface.co/Qwen/Qwen3-32B/blob/main/config.json
- Qwen3-32B モデルカード(32.8B、GQA 64/8、32,768 / 131,072): https://huggingface.co/Qwen/Qwen3-32B
- Qwen3-30B-A3B config.json(48層 / KV 4 / head_dim 128): https://huggingface.co/Qwen/Qwen3-30B-A3B/blob/main/config.json
- Qwen3-30B-A3B モデルカード(30.5B・活性3.3B、GQA 32/4、32,768 / 131,072): https://huggingface.co/Qwen/Qwen3-30B-A3B
- phi-4 config.json(40層 / 注意ヘッド40 / KV 10 / hidden_size 5120、head_dimなし): https://huggingface.co/microsoft/phi-4/blob/main/config.json
- phi-4 モデルカード(14B、16Kトークン): https://huggingface.co/microsoft/phi-4
- Hugging Face Transformers ドキュメント Mistral(num_key_value_heads とMHA/GQA/MQA、head_dim省略時の既定): https://huggingface.co/docs/transformers/model_doc/mistral
- NVIDIA Technical Blog「Mastering LLM Techniques: Inference Optimization」(KVキャッシュの式): https://developer.nvidia.com/blog/mastering-llm-techniques-inference-optimization/
- Ollama Context length(VRAM別の既定、OLLAMA_CONTEXT_LENGTH、ollama psのCONTEXT列): https://docs.ollama.com/context-length
- Ollama FAQ(KVキャッシュ量子化 f16/q8_0/q4_0、Flash Attention、PROCESSOR列): https://docs.ollama.com/faq
- llama.cpp server README(-c / -ctk / -ctv / -fa / -np): https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md
- Ollamaライブラリ qwen3 タグ一覧(8b 5.2GB / 14b 9.3GB / 32b 20GB): https://ollama.com/library/qwen3/tags
- Ollamaライブラリ phi4(9.1GB、16K): https://ollama.com/library/phi4