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

Ollama における num_predict の役割

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

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

num_predict は num_ctx ではありません

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

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

num_predict はモデルが書き出せる量です。これは割り当てではなく、停止条件です。値を増やすと RAM ではなく実行時間が増加します。事前にメモリが確保されることはありません。

両者が関係する箇所は 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 は定義全体を出力します。既存のモデルに組み込まれているパラメーターをコピーする場合にも、これが最も簡単です。

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

リクエストごとに 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 キーを使用し、意味も同じです。ここで指定した値は、その 1 回の呼び出しにだけ適用され、ほかには影響しません。これはツールが使用する層です。チャットフロントエンド、スクリプト、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 は負の値も受け付けます。これらはカウント値ではなく、特殊な値として扱われます。ある負の値は「上限を設けず、生成を続ける」ことを意味します。別の値は「残りのコンテキストを埋める」ことを意味してきました。2026年8月時点の Ollama Modelfile リファレンスでは、デフォルト値は -1 で、無限に生成します。同じ表の以前のバージョンには、コンテキストを埋める値として -2 も記載されていました。

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

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

生成には、速度が大きく異なる2つの段階があります。プロンプトのトークンは、一度に多数をバッチ処理します。出力トークンは1つずつ生成し、それぞれでモデルの重み全体を処理する必要があります。CPU のみの VPS では、この処理がメモリ帯域幅に制限されるため、生成される1トークンのコストはプロンプトの1トークンより大幅に高くなります。

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

"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件のリクエストがコンテキストウィンドウに達するまで CPU コアを占有し続けます。num_predict が上限を設定する項目です。1件の長いリクエストがマシン全体を占有する小規模な Ollama のセルフホスト VPSでは、特に重要です。

出力の切り詰めは、通常、モデルの破損ではなく上限が原因です

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

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

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

もう 1 つ、無駄な時間を避けるために重要な点があります。num_predict を増やしても、モデルがより長く出力するわけではありません。単に上限を取り除くだけです。回答が 200 tokens で done_reason が stop の状態で終わる場合、モデル自身が完了したと判断しています。この場合、上限を増やしても結果は変わりません。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 と 1 件の curl リクエストで値を確認します。

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

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