Ollamaのnum_predictで出力トークン数を制限する方法

Ollama における num_predict の動作

num_predict は、1 回の応答でモデルが生成できるトークン数の上限を設定する Ollama オプションです。出力トークンだけを数えるため、プロンプトはこの上限に含まれません。モデルが上限に達すると、その時点で生成を停止します。単語の途中で停止する場合もあります。このとき、応答の done_reason は length になります。

機能自体はこれだけです。難しいのは、Ollama には値を設定できる場所が 3 つあり、リクエストに最も近い設定が優先されることです。「num_predict が何もしない」という報告のほとんどは、ある層の設定が別の層の設定を気付かないうちに上書きしています。

num_predict は num_ctx ではありません

この 2 つのオプションは、Ollama でほかのどの組み合わせよりも混同されやすく、実際のデバッグ時間を浪費する原因になります。

num_ctx は、モデルがどれだけ 読み取れるか を指定します。これはコンテキストウィンドウのサイズで、プロンプトと、それまでに生成されたすべての内容を保持します。ウィンドウが大きくなると、モデルがそれらのトークン用に保持する key/value cache も増えるため、メモリ使用量が増加します。ハードウェアに合わせた num_ctx のサイジング は別の作業であり、固有の失敗要因があります。

num_predict は、モデルがどれだけ 書き出せるか を指定します。これは停止条件であり、割り当てる容量ではありません。値を大きくすると RAM ではなく経過時間が増え、事前に容量が確保されることもありません。

この 2 つが関係する箇所は 1 つです。生成されたトークンは生成されるたびにコンテキストウィンドウへ追加されるため、上限に達する前にウィンドウが埋まり、応答が停止することもあります。Ollama はどちらの場合も length を報告するため、両者を区別する数値は eval_count です。詳しくは後述します。

Modelfile で一度設定する

Modelfile に値を埋め込んでモデルを作成します。ファイルを作成します。

FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512

次にビルドし、作成した内容を確認します。

ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-capped

ollama show --parameters は、保存されている各パラメーターとその値を 1 行ずつ出力します。この出力に num_predict がない場合、モデルには上限値が埋め込まれておらず、Ollama 自身のデフォルト値が適用されます。ollama show --modelfile qwen3-capped は定義全体を出力します。既存のモデルに付属するパラメーターをコピーする場合にも、これが最も簡単な方法です。この方法で上限値を設定したモデルを作成しても、追加のディスク容量はほとんど必要ありません。新しいエントリは、ベースモデルがすでにダウンロードした重みの blob をコピーせずに再利用するためです。VPS の root ディスクがいっぱいになる前に、Ollama がこれらの blob を保存する場所を把握しておくと役立ちます。

すべての呼び出し元に継承させたい値には、この層で設定するのが適切です。ただし、この値が最終的な設定になると考えている場合は、この層は適切ではありません。実際には最終値にならないためです。

options オブジェクトでリクエストごとに設定する

すべての生成エンドポイントは options オブジェクトを受け取り、num_predict はその中に指定します。

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Explain what a reverse proxy does.",
  "stream": false,
  "options": { "num_predict": 128 }
}'

/api/chat も同じ options キーを同じ意味で使用します。ここで指定した値は、その呼び出しだけに適用され、ほかには影響しません。これは、ツールが使用する設定層です。チャットフロントエンド、スクリプト、SDK ラッパー、コーディングエージェントなどが該当します。これらは、入力欄が表示されるかどうかに関係なく、すべて options オブジェクトを送信します。

/set パラメーターで 1 セッションに設定する

ollama run 内では、対話セッションで設定したオプションが、そのセッションの残りの期間に適用されます。

>>> /set parameter num_predict 256
>>> /show parameters

/show parameters は、次のメッセージとともにセッションが送信する内容を表示します。変更が反映されたことを確認する最速の方法です。この値は、/bye と入力するまで保持されます。保持するには、/save qwen3-capped を実行します。これにより、現在のセッションをパラメーター込みで新しいモデルとして保存します。ここで /set した内容が、他のクライアントに反映されることはありません。

どの設定が優先されるのか、また設定が無視されているように見える理由

優先順位は単純です。リクエストで送信されたオプションが、他のすべてに優先します。モデルの Modelfile にある PARAMETER num_predict 行は、リクエストに値がない場合に使われるフォールバックです。どちらもない場合は、Ollama の組み込みデフォルトが適用されます。

/set parameter は第3のルールではありません。対話セッションは API クライアントとして動作します。そのため、そこで設定した値は、そのリクエストの options として送信されます。これが、セッション中は Modelfile の設定が上書きされる理由です。

この仕組みで説明できる失敗例を見てみましょう。PARAMETER num_predict 512 を追加してモデルを再ビルドしても、応答が数千トークンまで続くことがあります。設定自体は存在しており、ollama show --parameters で確認できます。しかし、クライアントが独自の数値を含む options オブジェクトを毎回送信するため、設定が上書きされています。その数値は、数か月前に設定画面へ入力したまま忘れている値であることもよくあります。ollama show が読み取るのは保存済みモデルです。HTTP 経由で実際に届いた内容は表示できません。

サーバー側の動作は、1つのコマンドで確認できます。長い応答を生成するリクエストを送信し、上限を低く指定して、2つのフィールドを読み取ります。

curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen3-capped",
  "prompt": "Describe the Linux boot process in detail.",
  "stream": false,
  "options": { "num_predict": 32 }
}' | jq '.done_reason, .eval_count'

これにより "length" と 32 が表示されるはずです。jq が未インストールの場合は、先に sudo apt install -y jq でインストールしてください。"length" と 32 が返る場合、サーバーはオプションを正しく適用しています。アプリケーションが別の値を送信しているということです。リクエストについてサーバー自身の記録を確認するには、環境変数に OLLAMA_DEBUG=1 を設定してサーバーを再起動し、アプリケーションから接続している間に journalctl -u ollama -f を監視します。

負の値と、そのままコピーしてはいけない数値

num_predict は負の値も受け付けます。これらはカウントではなく、特別な値として扱われます。負の値の1つは「上限を設けず、生成を続ける」という意味です。別の値は「残りのコンテキストを埋める」という意味で使われてきました。2026年8月時点では、Ollama Modelfile のリファレンスにおけるデフォルト値は -1 で、無限生成を意味します。同じ表の以前のバージョンには、コンテキストを埋める値として -2 も記載されていました。

これらは変更されてきたため、すべてバージョン依存として扱ってください。リファレンスでは、2024年末に項目が修正されるまで、長期間にわたってデフォルト値を 128 と記載していました。そのため、古い数値を今も掲載しているガイドが多数あります。実際に使用しているバージョンの Modelfile パラメータリファレンス を確認し、前述の eval_count チェックで動作も確認してください。自分の環境で検証した値は、この記事を含め、どこかで読んだ値よりも信頼できます。

CPU のみの VPS では出力長が主なコストになる理由

生成処理には、速度が大きく異なる 2 つの段階があります。プロンプトのトークンは、一度に多数をまとめて評価します。出力トークンは 1 つずつ生成し、そのたびにモデルの重み全体を処理する必要があります。CPU のみの VPS では、この処理速度がメモリ帯域幅によって制限されるため、生成トークン 1 個のコストはプロンプトトークン 1 個より大幅に高くなります。すべての重みを読み込む必要があるため、各重みが占めるバイト数によってトークン生成速度の上限が決まります。そのため、同じモデルでも q8 や fp16 より q4 ビルドのほうが高速にデコードできます。

ストリーミングなしで応答を要求すると、数値を直接確認できます。

"prompt_eval_count": 26,
"prompt_eval_duration": 107345000,
"eval_count": 237,
"eval_duration": 4289432000

時間の単位はナノ秒です。このブロックは、特定のサーバーで測定した値ではなく、Ollama API ドキュメントに掲載されているサンプル応答です。プロンプト 26 トークンの処理には約 0.1 秒かかった一方、出力 237 トークンの生成には約 4.3 秒かかっています。実際の生成速度は、eval_count を eval_duration で割って秒に換算して求めます。自分のハードウェアで 1 秒あたりのトークン数を測定する作業は、ほかの設定を調整する前に一度実施する価値があります。この速度はマシンだけでなくモデルにも大きく依存します。そのため、長い回答が実際のコストになる場合は、VPS 上の Nemotron 3.5 Lightning のように高速デコード向けに構築されたモデルを使うと、低い上限で守っていた時間の一部を取り戻せます。

あとは計算すれば分かります。1 秒あたり 8 トークンの場合、2,000 トークンの回答ではマシンを 4 分以上占有します。モデルは、あなたが段落を 1 つ求めていたことを理解しません。推論モデルは、要求した単語を書き始める前に予算の一部を思考に使います。この思考もほかの処理と同様に 1 トークンずつ生成されるため、要求する推論の強度も同じコストに影響する調整項目です。モデルによってはループし、停止させるまで同じフレーズを繰り返すこともあります。上限を設定しない場合、その 1 件のリクエストはコンテキストウィンドウが埋まるまで CPU コアを使い続けます。上限を設定するのが num_predict です。これは、小規模な セルフホストの Ollama VPS で 1 件の長いリクエストがマシン全体を占有する場合に特に重要です。

切り詰められた出力では、通常、モデルではなく上限が原因です

症状だけを見ると、モデルの失敗に見えます。回答が文の途中で止まる。閉じ中括弧が出力されず、JSON を解析できない。モデルや量子化を原因だと考えがちですが、まずレスポンスを確認してください。

done_reason は質問に直接回答したことを示します。stop は、モデルが終了トークンを出力するか、stop オプションに指定した文字列のいずれかに一致して、自発的に生成を完了したことを示します。length は、生成が上限に達して途中で打ち切られたことを示します。length が表示されたら、eval_count と上限を比較してください。値が完全に一致する場合は、num_predict によって停止しています。値が小さい場合は、先にコンテキストウィンドウが埋まっています。

ストリーミング時は、これらのフィールドが "done": true を含む最後のチャンクに入ります。多くのクライアントライブラリはこのチャンクを破棄し、コードにはテキストだけを渡します。そのため、同じ切り詰めがアプリケーション内では原因不明に見え、curl では明確に確認できます。ライブラリがこの情報を隠している場合は、curl を指定してリクエストを1回送信し、サーバーが実際に返した内容を確認してください。

もう1点を理解しておくと、無駄な時間を使わずに済みます。num_predict を増やしても、モデルがより多く書くわけではありません。単に上限を取り除くだけです。回答が done_reason の stop で200 tokensで終わっている場合、モデルは生成を完了したと判断しています。そのため、上限を大きくしても変化はありません。stop の短い回答はプロンプトの問題です。length の短い回答は上限の問題です。

値の選び方

• 対話形式のチャットでは、上限を設定せず、暴走した応答を止めるときに Ctrl+C を押します。画面を常に確認しているためです。
• スクリプトで使用する場合は、上限を設定します。ループ内で上限なしの生成を実行すると、10 分で終わるはずのバッチジョブが翌朝になっても実行中という事態になります。
• 構造化出力では、想定する最大の有効なドキュメントより高い上限を設定します。そのうえで、done_reason length を超えた場合は重大なエラーとして扱い、返された内容を解析せずに再試行します。
• コーディングエージェントでは、エージェント自身の設定に値を指定します。エージェントはリクエストごとに独自のオプションを送信するためです。コーディングエージェントを Ollama に接続するでは、これらの設定の場所を説明しています。

上限は単語数でも文字数でもなく、トークン数で数えられます。そのため、推測で設定しないでください。上限なしで代表的な回答を1つ生成し、eval_count を確認してから、その値より十分高い制限を設定します。モデルファミリーによってトークン化の方法は異なります。そのため、Llama モデルで収まる値でも、同じ VPS 上のQwen 3 モデルからの同じ回答は途中で切れることがあります。

FAQ

num_ctx と num_predict の違いは何ですか？

num_ctx はコンテキストウィンドウのサイズです。モデルが読み取れる量、つまりプロンプトと、それまでに生成されたすべての内容を決めます。Key/Value キャッシュがこれに応じて増えるため、メモリを消費します。num_predict は、1 回の応答でモデルが書き込めるトークン数を決めます。メモリよりも時間を消費し、事前に予約される領域はありません。生成されたトークンは両方に対して数えられるため、どちらの上限でも応答が途中で終了する可能性があります。

num_predict の設定が無視されているように見えるのはなぜですか？

リクエストで送信した値が、モデルに保存された値を上書きするためです。Modelfile に PARAMETER num_predict 512 を記述して、そのモデルをチャットフロントエンドやコーディングエージェントから使うと、クライアントは独自の options オブジェクトを送信し、その数値が優先されます。ollama show --parameters には設定した値が引き続き表示されます。これは保存されたモデルを読み取るだけで、HTTP 経由で届いた値を確認できないためです。curl を "options": {"num_predict": 32} で指定したリクエストを 1 回送信し、eval_count が 32 として返ることを確認してください。これにより、サーバー自体は正常に動作しており、調査対象をアプリケーション側へ移せます。

出力が num_predict で途中終了したかどうかを確認するにはどうすればよいですか？

"stream": false を指定してリクエストを送信し、done_reason を確認します。stop の値は、モデルが自発的に生成を完了したことを示します。length の値は、生成可能な上限に達したことを示します。次に eval_count と設定した上限を比較します。両方が完全に一致する場合は num_predict が停止させています。eval_count のほうが小さい場合は、先にコンテキストウィンドウが埋まっています。ストリーミング時は、両方のフィールドが "done": true を含む最後のチャンクで届きます。多くのクライアントライブラリは、コードから見える前にこの情報を破棄します。

num_predict のデフォルト値は何ですか？

記事ではなく、自分のインストール環境で確認してください。2026 年 8 月時点では、Ollama Modelfile リファレンスのデフォルト値は -1 です。これは生成に上限がないことを意味します。この記載は、128 と長年説明されていた内容が 2024 年末に訂正されたものです。負の値は個数ではなくセンチネル値です。同じ表の以前のバージョンには、残りのコンテキストを埋める値として -2 も記載されていました。使用しているバージョンの Modelfile パラメータリファレンス を確認し、ollama show --parameters と curl リクエスト 1 回で値を検証してください。

num_predict を増やすと、モデルはより長い回答を書きますか？

いいえ。上限を取り除くだけです。応答が done_reason で stop の状態になって終了した場合、モデル自身が生成完了と判断しています。その場合、上限を増やしても変化しません。この場合の長さは、プロンプトで指定する内容に左右されます。具体的な構成、セクション数、または詳細度を指定してください。num_predict は、done_reason が length として返る場合にだけ増やします。