Context の圧縮とコンパクション
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/context-compression-and-caching/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
会話が長く続くと、いずれモデルのコンテキストウィンドウの上限に達します。AIGateway は各 turn に渡す会話履歴を自動的にコンパクト化(compaction)することで、コンテキスト長の上限を超えても会話を途切れさせずに継続できるようにします。このページでは、ai_gateway/compaction*.ex の実装に沿ってその仕組みを解説します。
最初に押さえておくべき重要な性質があります。コンパクションは設計上、情報を要約する非可逆(lossy)な処理ですが、裏で密かに履歴を書き換えるものではありません。 古い turn を構造化された要約に置き換える一方で、直近の turn と過去のユーザー発言の原文はそのまま残し、生成された要約自体も会話から参照される永続アーティファクトとして保存します。コンパクション後は元の古い turn がモデル入力から外れ、要約が新しい基準状態となります。Ankole は元の履歴行を保持し、provider の紐付け変更時や /compress による復旧時には、その履歴からローカルチェックポイントを再構築できます。
AIGateway の履歴コンパクション
ステートフルな Responses 会話における自動履歴コンパクションは、すべて AIGateway(Ankole.AIGateway.Compaction)が管理しています。いつ発火し、どのように要約し、何を原文のまま残すかまでが一貫して定義されています。
以下では既定のローカルコンパクションを説明します。ai_gateway.compaction.upstream を true にすると、対応する provider のネイティブ圧縮を利用し、必要に応じてローカル処理へフォールバックします。詳しくは AIGateway を参照してください。
トリガー
AIGateway は直近の provider 報告トークン使用量を基準に、新しい入力、ツール結果、ツール定義、指示の追加分を推定します。その合計をしきい値と比較し、増加量と圧縮効果に基づく抑制規則で、効果の小さいコンパクションの連続実行を避けます。各 turn の使用量スナップショットを足し合わせることはありません。
発火条件や保持量は AppConfigure の ai_gateway.compaction キーで調整できます。
| 設定項目 | 既定値 | 意味 |
|---|---|---|
threshold |
0.90 |
コンパクションを開始するモデル入力コンテキスト長の割合 |
max_threshold_tokens |
400,000 |
算出された発火しきい値の絶対上限(巨大コンテキストモデルで履歴が膨らみすぎるのを防ぐ) |
tail_rows |
4 |
要約とあわせて保持する直近の履歴行数の目安 |
user_message_budget_tokens |
20,000 |
コンパクト化対象区間からユーザー発言の原文を再注入するためのトークン予算 |
モデルのコンテキスト長を取得できない場合は 256,000 トークンを使います。指定された出力予算を差し引き、threshold を適用してから max_threshold_tokens で上限を設けます。64,000 トークンの下限が有効コンテキスト長に達してしまう場合は、その長さの small_context_trigger_ratio(0.85)で発火します。
発火条件はトークン使用量だけではありません。暗号化された推論内容やインライン画像は 1 トークンあたりのバイト数が大きく、トークンのしきい値に届くずっと前に履歴が肥大化することがあります。そのため AIGateway は、保存済みの履歴が、ツールを使う 1 回の応答で保持できる量(1,024 項目または 8 MiB)の 4 分の 3 に達したときにもコンパクションを実行します。このサイズ条件に設定項目はありません。
要約器が行うこと
ローカルコンパクションを行う場合、AIGateway は light プロファイル(未設定時は primary)を呼び出して古い turn 群の構造化サマリーを生成します。このときプロンプトでは、要約を「続きの応答」ではなく参照用の状態スナップショットとして明確に位置づけます(「会話を続けないでください。質問に答えないでください。構造化された要約だけを出力してください」と指示します)。要約にはユーザーの意図、確定した判断、発生したエラーと対処内容が整理され、ファイルパス、関数名、エラーメッセージ、コマンドライン、各種 ID は書き換えずにそのままの文字列で保持されます(パスやエラー文を言い換えてしまうと、後続 turn で参照先が壊れるためです)。
要約は、保持したユーザー原文や直近の履歴とともに、返信を求める発言ではなく前提状態としてモデルへ渡されます。
何が逐語的に残るか
生成された要約とあわせて、次の 2 つが原文のままコンテキストに残されます。
- 直近の履歴行(
tail_rows、既定値4) — 保持行数の目安です。ツールの呼び出しと結果のペアを維持し、コンテキスト予算に収まるよう調整します。 - ユーザー発言の原文 —
CompactionRetentionがuser_message_budget_tokensの範囲内でテキストを再注入し、必要に応じて切り詰めます。圧縮対象の画像ペイロードは長さを制限したプレースホルダーに置き換え、直近の保持対象画像はそのまま残します。
これらの保持内容はモデルが作業を追う助けになりますが、要約では古い作業の細部が失われます。
コンパクションアーティファクト
コンパクションが実行されるたびに、AIGateway は永続的な CompactionArtifact を保存します。会話履歴は最新のコンパクション結果を新しい基点(アンカー)として指し、それ以降の turn はそのアンカーから連なっていきます。
コンパクションとコールド復帰ローテーションの連携
ai_gateway.compaction と sessions.wake_recycle は、ウォームな継続会話とコールドな再開の双方を補完し合います。
- ウォームな継続会話(
ai_gateway.compaction) — 上流プロバイダーのプロンプトキャッシュ有効期間内に turn が続く間、Ankole は同じ AIGateway 会話チェーンを伸ばし続けてプレフィックスキャッシュのヒット率を高く保ち、累積コンテキストがthreshold/max_threshold_tokensを超えるか、保存済みの履歴が上記のサイズ条件に達した時点でのみコンパクションを実行します。 - コールドな再開(
sessions.wake_recycle) —min_cold_gap_seconds(既定3,600秒)以上アイドルで累積コンテキストがmin_context_tokens(既定128,000トークン)以上ある Session が再開された場合、または外部 IM チャネルでim_max_idle_seconds(既定259,200秒 / 72 時間)以上アイドルだった場合は、Ankole.Sessions.WakeRecycleが履歴全体を再送する代わりに古い AIGateway モデル会話を閉じ、上限8,000o200k_baseトークンの決定論的な<wake-briefing>を持つ後続ブランチへ切り替えます。詳しくは Sessions を参照してください。
チューニング
運用状況に応じて、次の指針でパラメータを調整できます。
thresholdを引き上げる — 短めの会話が多いにもかかわらず、コンパクションが早い段階で頻繁に走りすぎる場合(既定の0.90は余裕を見込んだ控えめな値です)。tail_rowsを増やす — コンパクション直後にモデルが直前の細かな作業文脈を見失う場合。原文のまま残る直近 turn が増える分、利用可能な残りコンテキスト枠は少なくなります。user_message_budget_tokensを増やす — 長期会話で過去のユーザー指示が予算上限からあふれて削られ、モデルが当初の依頼条件を追えなくなる場合。
これら 3 つの項目はいずれも Console の AppConfigure から変更でき、実行中の turn ではなく次回発生するコンパクションから反映されます。
このガイドがそうでないもの
このページはプロンプトキャッシングの設定ガイドではありません。上流プロバイダー側のプロンプトキャッシュは各 provider 固有の仕組みであり、対応する provider 設定の promptCacheKey などで制御します。また、完全可逆な履歴アーカイブの説明でもありません(コンパクション後のモデル入力からは元の古い turn は外れます)。さらに、会話を適切に区切る運用の代わりにもなりません。コンパクションによって長い会話を継続することはできますが、数 turn ごとに毎回コンパクションが走るほど肥大化した会話は、新しいセッションへ分けるか Background Agent Job に委任する方が効率的です。
次のステップ
- AIGateway 全体の設計とエンドポイント仕様については、AIGatewayを参照してください。