Pi 与 OpenCode 中上下文窗口及最大输出尺寸的设置技巧

Pi・OpenCodeのコンテキストサイズと最大出力サイズの設定のコツをまとめました。

1. はじめに

「Pi」や「OpenCode」などのAIエージェントハーネスでは、LLMの「コンテキストサイズ」と「最大出力サイズ」の設定が重要です。

モデルが対応する最大値を設定すればよいと思いがちですが、大きく設定すれば必ず性能が上がるわけではありません。特にローカルLLMでは、メモリ使用量や応答速度に影響します。

この記事では、PiやOpenCodeでのおすすめの設定値と、用途に応じた調整方法を紹介します。

2. コンテキストサイズと最大出力サイズ

2-1. コンテキストサイズとは

「コンテキストサイズ」（Context Window）は、LLMが一度に扱えるトークン数の上限です。

AIコーディングエージェントでは、次の情報がコンテキストに含まれます。

・システムプロンプト：AIへの基本的な指示
・会話履歴：これまでの指示や応答
・ソースコード：読み込んだファイルの内容
・ツール実行結果：コマンドの出力やエラーログ
・生成する応答：コードや説明、ツール呼び出し

例えば、64K（65,536トークン）のコンテキストを設定しても、64Kすべてをソースコードの読み込みに利用できるわけではありません。生成する応答のための余裕も必要です。

コンテキストサイズが大きいほど多くの情報を扱えますが、次のデメリットがあります。

・メモリ使用量の増加：長い会話を処理するとKVキャッシュの使用量が増える
・応答速度の低下：実際に処理する入力が長いほどPrefillに時間がかかる
・精度低下の可能性：不要な情報が増えると重要な情報を見落とすことがある

なお、実際のメモリ使用量はコンテキスト長だけでなく、モデル構造、KVキャッシュの精度、同時実行数などにも左右されます。

2-2. 最大出力サイズとは

「最大出力サイズ」（Max Output Tokens）は、LLMが1回の応答で生成できるトークン数の上限です。

例えば、最大出力サイズを8Kに設定しても、エージェントがツールを複数回呼び出せば、合計8K以上のコードを作成できます。
そのため、必ずしも最大出力サイズを大きくする必要はありません。

ただし、Thinkingモデルでは、内部の推論トークンが出力上限に含まれるAPIもあります。Reasoningが長いモデルでは、出力サイズが小さいとコード生成前に上限へ達することがあります。

3. おすすめの設定値

PiやOpenCodeでローカルLLMを利用する場合、おすすめの設定値は次のとおりです。

最初はコンテキスト64K、最大出力16Kを目安にするのがおすすめです。ただし、Thinkingモデルでは出力上限にReasoningトークンが含まれることがあるため、必要に応じて32K以上を検討します。また、モデルと推論サーバーが対応するサイズを超えないようにします。

contextWindow = 65536
maxTokens     = 16384

ただし、モデルや推論サーバーが対応していることが前提です。メモリに余裕がない環境では、コンテキスト32Kから始めるのがよいでしょう。

4. 設定方法

4-1. Piの設定方法

Piでは、標準対応するクラウドモデルのコンテキストサイズと最大出力サイズは、モデルカタログから自動取得されるため、通常は手動設定不要です。

一方、OllamaやvLLMなどのカスタムモデルでは、「~/.pi/agent/models.json」でモデルを登録し、必要に応じてサイズを指定します。

{
  "id": "your-model-id",
  "contextWindow": 65536,
  "maxTokens": 16384
}

・contextWindow：コンテキストサイズ
・maxTokens：最大出力サイズ

省略するとデフォルト値（128K・16K）が使用されます。

4-2. OpenCodeの設定方法

OpenCode 2.0では、Ollama・LM Studio・vLLMのローカルモデルを自動検出できるため、通常はコンテキストサイズや最大出力サイズを手動設定する必要はありません。

Ollamaの場合、モデルのコンテキストサイズなども自動取得されます。取得した設定値を変更したい場合は、「opencode.json」で上書きできます。

5. Compactionによるコンテキストの節約

PiとOpenCodeには、会話履歴が長くなったときに古い情報を要約する「Compaction」機能があります。

例えば、64Kのコンテキストが埋まりそうになると、古い会話を要約し、新しい作業に利用できる領域を確保します。

5-1. PiのCompaction

Piでは、「~/.pi/agent/settings.json」で設定できます。

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

・enabled：自動Compactionの有効化
・reserveTokens：Compaction開始時に確保する空き領域
・keepRecentTokens：要約せずに残す直近の履歴量

これらは公式ドキュメントに示されたデフォルト値です。

5-2. OpenCodeのCompaction

OpenCodeでも自動Compactionが利用できます。

OpenCode V2では、次のように設定できます。

{
  "compaction": {
    "auto": true,
    "keep": {
      "tokens": 15000
    },
    "buffer": "15%"
  }
}

・auto：自動Compactionの有効化
・keep.tokens：要約せずに残す直近の履歴量
・buffer：Compaction前に確保するコンテキストの余裕

OpenCodeのバージョンによって設定項目が異なるため、利用中のバージョンのドキュメントを確認してください。

Compactionでは古い会話が要約されるため、細かい指示や設計判断が失われる可能性があります。重要なルールは「AGENTS.md」などに記録しておくと安心です。

6. まとめ

PiやOpenCodeでの設定は、次の方針がおすすめです。

・コンテキストサイズ：基本64K、必要に応じて32K〜128K
・最大出力サイズ：基本16K、必要に応じて8K〜32K
・Compaction：自動Compactionを有効にする
・ローカルLLM：メモリ使用量とPrefill速度を確認しながら調整
・クラウドAPI：基本的にモデルの標準設定を利用する

大切なのは、モデルの最大値に合わせることではなく、作業に必要なサイズを確保しつつ、メモリ使用量と応答速度のバランスを取ることです。

特にMacやDGX SparkなどでローカルLLMを使う場合は、64K・16Kを基準として、実際の作業内容に合わせて調整するとよいでしょう。