結果を変えるエンジンノブ

エンジンのデフォルトの大半はデモには健全で、実用には間違っている。結果を変えるのは3〜4個のノブ。コンテキスト長、GPUオフロード、KVキャッシュ型、フラッシュアテンション。残りは際(きわ)のチューニング。このページはllama.cppのフラグ名を使い、最後にOllamaの対応を示す——概念はすべてのエンジンに移る。

コンテキスト長:黙示のデフォルトの罠

エンジンは保守的なデフォルトを出荷する。llama.cppは歴史的に512、次に4096。Ollamaはバージョンにより2048〜4096(執筆時点でOLLAMA_CONTEXT_LENGTHは4k前後に着地)。その間、あなたのモデルはネイティブで32k〜128kをサポートしているかもしれない。4kコンテキストに2万トークンの文書を貼ると、2つのことのどちらかが起きる。どちらも悪い。ハードエラー(「リクエストが利用可能コンテキストを超過」)か、最も古いメッセージの黙示切り捨て。どちらのエラーメッセージも初心者に自分を説明しない。

実例:約12kトークンの契約書+質問を、デフォルトの4096ウィンドウにロードする。エンジンは最も新しい素材を保持し、文書の冒頭を切り捨て、モデルはファイルの間違った半分について自信満々に答える。愚かなモデルに見えるが、実際は切り捨てられたプロンプト。

修正は機械的。毎回の起動でコンテキストサイズを明示的に渡す。実際のプロンプト+想定出力に合わせ、起動ログがn_ctx = 16384(選んだもの)を示すことを確認する。韓国語の注記:同じトークナイザでも韓国語テキストは英語より低密度にトークン化されることが多く——韓国語1ページは英語1ページより多くのトークンを要し得る(トークンを参照)——コンテキスト圧力は予想より早く来る。

# 罠: デフォルトはエンジンとバージョンごとに異なる
llama-server -m model.gguf                  # n_ctx = 4096 程度で起動

# 修正: 明示指定し、起動ログで検証
llama-server -m model.gguf -c 16384         # ログが出力: n_ctx = 16384

GPUオフロード:n_gpu_layers

-ngl / --n-gpu-layersは、GPUに載るtransformerレイヤーの数を設定する。「全部」を意味するのに99のような大きな数(対応環境では-1)を使う。部分オフロードの症状は特徴的。まともなGPUのあるマシンで3〜10 tok/s。ロードログ行(offloaded 33/33 layers to GPUなど)で検証。VRAMがモデル+KVキャッシュを保持できないなら、正直な選択肢はより小さい量子化、KVキャッシュの量子化、オフロードレイヤー数の削減——ただしCPUに残す各レイヤーがループ全体をCPUのリズムに引きずり下ろすことを知っておく(速度を参照)。ほぼ収まるモデルを半分オフロードするのは、量子化を1段下げるより大抵悪い。

逆方向の健全性確認も。-ngl 0は純CPUを強制し、それが「GPU」構成と同じ速度で動くなら、GPUは何もしていなかった。

スレッド(CPUモードのみ)

CPUモードでは-tをSMTスレッド数ではなく物理コア数に設定する。8コア/16スレッドのチップなら8。物理コアを超えるスレッドは競合を起こしデコードを遅くする。プロンプト処理には別のノブ(--threads-batch)があり、同じルールが適用される。

メモリ:mmapと--mlock

llama.cppはデフォルトでモデルファイルをメモリマップする。起動は速く、未触達のレイヤーはRAMを消費しない。トレードオフは、OSがメモリ圧力下でページを退避させ、セッション数時間後に謎の停止を引き起こし得ること。--mlockはモデルを固定し退避を防ぐ——繁忙マシンで有用、代償はギガバイトを他のすべてから遠ざけてロックすること。Ollamaはこれを内部で処理する。共有マシンで生のllama.cppを使う人は、このフラグの存在を知っておくべき。

フラッシュアテンション

-fa / --flash-attnはアテンションステップのメモリトラフィックを減らし、最近のllama.cppビルドではデフォルトでオン(または自動)。最重要なのは長いコンテキストで、現在のビルドではVキャッシュの量子化に必須。新しいビルドがGPUバックエンドで誤動作するなら、最初にトグルするフラグはこれ——そして最近のビルドでは、最初に確認すべきは、これが黙ってオフになっていないこと。

KVキャッシュ量子化

--cache-type-k q8_0 --cache-type-v q5_0はKVキャッシュを16ビット浮動小数点の代わりに8ビット/5ビットで格納し、わずかな品質コストでKVメモリを半分近くまで削減——同じVRAMでより長いコンテキストを意味する。KVキャッシュの正体と正確なサイズ計算はKVキャッシュ。

典型的な利得:q8_0 K + q5_0 VでKVサイズをほぼ半分、チャットタスクではほとんど見た目が変わらない——信じる前に自分のワークロードで検証を。

プロンプトバッチサイズ

-b / --batch-sizeはプリフィル(プロンプト処理)のチャンクサイズ。大きいバッチは長いプロンプトで初回トークンまでの時間を速め、わずかなピークVRAMと引き換え。長い貼り付けの開始が遅く感じられるなら、モデルのせいにする前にこれを上げる。

コンテキストの引き伸ばし:ropeスケーリングとYaRN

--rope-scaling yarn --rope-factor 2.0は位置周波数を再スケールして、32kネイティブのモデルを64k方向へ引き伸ばす。動くが、品質には勾配がある。ネイティブウィンドウ付近の劣化は小さく、引き伸ばしすぎると成長する。重要なものには、小さいウィンドウを引き伸ばすより、ネイティブコンテキストが要件を既にカバーするモデルを優先(モデル選択を参照)。

執筆時点でOllamaはModelfileでropeスケーリングを公開していない。引き伸ばしコンテキストの実験はllama.cppの直接起動を意味する。

注釈付き起動行

llama-server -m qwen3-8b-q4_k_m.gguf --host 127.0.0.1 --port 8080 -c 16384 -ngl 99 -fa on -b 2048 --cache-type-k q8_0 --cache-type-v q5_0

フラグ	機能	注意
`-c 16384`	コンテキストウィンドウ(プロンプト+出力で共有)	デフォルトに頼らない。明示的に設定
`-ngl 99`	GPUへオフロードするレイヤー数(99=全部)	`offloaded N/N`のログ行を確認
`-fa on`	フラッシュアテンション	最近のビルドではデフォルトauto。Vキャッシュ量子化に必須
`-b 2048`	プロンプト処理バッチ	ピークVRAMをわずかに上げる。TTFTに効く
`--cache-type-k/-v`	KVキャッシュdtype	V量子化にはフラッシュアテンションが必要
`--host 127.0.0.1`	ループバックのみにバインド	公開のルールはサービング

Ollamaでの対応

# モデルごと、Modelfile内:
PARAMETER num_ctx 16384
PARAMETER num_gpu 99

# またはグローバルに、サービス起動前に:
export OLLAMA_CONTEXT_LENGTH=16384
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0

リクエストがnum_ctxを超えるとOllamaは警告をログに出す——これらを変更したら一度ログを読むこと。環境変数による変更にはサービスの再起動が必要。

Ollamaが実際に適用した内容を見るには:ollama show model --modelfileが解決済みパラメータを出力し、OLLAMA_DEBUG=1でサービスが実際のコンテキストとオフロード数をログに出す。

サンプラはエンジンノブではない

temperature、top-p、繰り返しペナルティ——これらはどのトークンが選ばれるかを形作るのであって、速さやメモリの収まりではない。彼らの家はサンプリング。出力が奇妙だが速度とメモリが正常なら、欲しいのはこのページではなくあちら。

ルール

コンテキストは明示的に設定。起動構成を変えるたびにログ行——n_ctx = ...とoffloaded N/N layers——で検証。デフォルトは最初のデモが始まるように調整されていて、あなたのワークロードがサーブされるようにではない。

llm_load_tensors: offloaded 33/33 layers to GPU
n_ctx = 16384

どちらの行も起動後数秒で出力される。一度検索すれば、設定は俗説でなくなる。