チャネルアフィニティ接続ガイド

継続的な会話、コーディング支援、長いコンテキストを扱うタスクでは、安定した識別子によってチャネルとコンテキストキャッシュを再利用しやすくなります。

AGTCloud はリクエスト内の安定した識別子を基に、後続のリクエストで以前成功したチャネルを優先的に再利用します。そのチャネルが利用できない場合は、別の利用可能なチャネルを自動選択します。この識別子を「アフィニティキー」と呼びます。

チャネルアフィニティはルーティングを安定させ、コンテキストキャッシュは計算を再利用します。チャネルが安定していても、毎回のキャッシュヒットは保証されません。

接続方法を選ぶ

まず、プロトコルに既存の識別子フィールドを利用します。リクエストボディを変更しにくい場合は、SDK やゲートウェイからヘッダーで安定した識別子を渡せます。

共通ヘッダー x-conversation-id を使う

x-conversation-id はヘッダーで安定した識別子を渡すため、ボディにアフィニティ用フィールドを追加する必要がありません。OpenAI、Anthropic、Gemini などのプロトコルで利用できます。

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: conversation_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "この問題の分析を続けてください。"
      }
    ]
  }'

このヘッダーはプラットフォームのチャネルアフィニティに使用され、標準ではモデルのパラメータとして扱われません。同じ会話では値を固定し、リクエストごとに生成し直さないでください。

例の MODEL_ID は利用するモデルの ID に置き換え、認証にはモデル呼び出し用の API Key を使用します。

モデル系列別の接続方法

OpenAI

OpenAI Prompt Caching は自動で有効になり、主にリクエストのプレフィックスの一致に依存します。Responses と Chat Completions では prompt_cache_key がキャッシュのルーティングに使われます。AGTCloud もこの値をチャネルアフィニティに使用し、対応する上流サービスへ転送します。

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "input": "現在のタスクを続けてください。",
    "prompt_cache_key": "project_knowledge_v3"
  }'

アフィニティキーには会話、プロジェクト、ナレッジベースのバージョン、リポジトリの識別子を使えます。既存の Responses 会話を継続する場合は、前回のレスポンス ID を previous_response_id に指定します。初回のリクエストには不要です。

Claude / Anthropic

Claude はコンテンツブロックの cache_control で再利用可能なプレフィックスを指定し、自動マルチターンキャッシュにも対応します。metadata.user_id はプラットフォームのアフィニティキーとして使え、Claude Code などのクライアントはこの種の安定した識別子を通常送信します。これはキャッシュのブレークポイントではなく、cache_control の代わりにはなりません。

curl 'https://api.agtcloud.cn/v1/messages' \
  -H 'x-api-key: your-api-key' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "metadata": {
      "user_id": "conversation_3cb9dd9a4819594254a779c90a2171"
    },
    "system": [
      {
        "type": "text",
        "text": "安定した業務ルールとツールの制約をここに配置します。",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "このリポジトリの分析を続けてください。"
      }
    ]
  }'

Claude は tools、system、messages の順にキャッシュのプレフィックスを構成します。ツール定義、system、キャッシュ済みメッセージの変更は、その階層と後続のキャッシュに影響します。上流の対応状況に応じて、短期またはより長い TTL を選べます。

Gemini

チャネルアフィニティには x-conversation-id を使い、用途に応じてキャッシュ方式を選びます。

• 暗黙的キャッシュ：Gemini 2.5 以降で標準で有効です。短い期間に安定したプレフィックスを再利用する通常の会話に適しています。
• 明示的キャッシュ：/v1beta/cachedContents でリソースを作成し、cachedContent で参照します。長い文書や動画、固定ナレッジベース、リポジトリ解析に適しています。作成、有効期限、後続の参照はクライアントで管理します。

DeepSeek

DeepSeek はディスクベースのコンテキストキャッシュを自動で有効にし、完全に一致する安定したプレフィックスを再利用します。deepseek-v4-flash と deepseek-v4-pro は user_id でユーザーを区別し、安全性処理、ユーザー単位のレート制限、K/V Cache の分離に使用します。

同じモデルと同じ user_id のリクエストは、以前成功したチャネルを優先的に再利用します。

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "user_id": "user_123",
    "messages": [
      {
        "role": "system",
        "content": "安定した業務ルール、ツールの説明、ナレッジベースの要約をここに配置します。"
      },
      {
        "role": "user",
        "content": "この問題の分析を続けてください。"
      }
    ]
  }'

user_id は ASCII 文字のみで、最大 512 文字です。同じユーザーには長期的に同じ値を使います。ユーザー ID を用意できなければ、アプリケーションで生成した固定識別子を使えます。ボディを変更できなければ、前述の x-conversation-id を使用します。

user_id ごとの標準同時実行数は次のとおりです。

user_id を省略すると、プラットフォームが設定済み UID プールから利用可能な識別子を自動割り当てします。リクエストは通常どおり送信できます。

レスポンスの usage.prompt_cache_hit_tokens と usage.prompt_cache_miss_tokens で、キャッシュにヒットした Token とヒットしなかった Token の数を確認できます。

Qwen

Qwen / DashScope は暗黙的キャッシュ、明示的キャッシュ、Session Cache に対応します。qwen3.6-plus、qwen3.6-flash、qwen3-coder-plus などでは、呼び出しプロトコルに応じて選びます。

• Chat Completions：暗黙的キャッシュは自動で有効です。再利用可能な内容を明示するには、コンテンツブロックに cache_control を追加します。
• Responses の複数ターン：previous_response_id でレスポンスを継続し、ヘッダー x-dashscope-session-cache: enable で Session Cache を有効にします。

どちらの方式でも x-conversation-id を併用してチャネルアフィニティを維持できます。以下は Chat Completions の例です。

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: conversation_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "キャッシュの最低量を超える安定した長いコンテキストをここに配置します。",
            "cache_control": { "type": "ephemeral" }
          }
        ]
      },
      {
        "role": "user",
        "content": "上記の内容に基づいて質問に答えてください。"
      }
    ],
    "stream": false
  }'

GLM / Z.AI

GLM-5、GLM-5.1、GLM-4.7、GLM-4.6、GLM-4.5 などは自動コンテキストキャッシュに対応し、長時間のタスク、コード、エージェントに適しています。同じプロジェクトやエージェントタスクでは安定した x-conversation-id を使います。

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: agent_task_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "system",
        "content": "安定したエージェントの目標、ツールの制約、プロジェクト背景をここに配置します。"
      },
      {
        "role": "user",
        "content": "次の手順を続けてください。"
      }
    ],
    "stream": false
  }'

レスポンスの usage.prompt_tokens_details.cached_tokens でキャッシュされた Token 数を確認できます。思考内容を保持する場合も、再利用する履歴の順序と内容を維持してください。

利用上のポイント

• プレフィックスを固定する：固定指示、ツール定義、長い文書、履歴の要約を先頭に置き、本ラウンドの質問、時刻、一時ログを末尾に置きます。ツールの並べ替え、不変の履歴の書き換え、乱数の挿入を避けます。
• 用途に合った識別子を選ぶ：会話 ID は同じ会話内で、ユーザー ID は同じユーザーに対して長期的に固定します。プロジェクトとナレッジベースはプロジェクトやバージョン別に識別します。テナント間で混用せず、ユーザーを区別する識別子を共有プロジェクトの識別子で代用しないでください。
• 機密情報を平文で使わない：電話番号、メールアドレス、身分証番号、API Key をアフィニティキーにしないでください。業務識別子は不可逆変換できます。一度限りの Request ID は使わないでください。
• 有効期間に注意する：アフィニティの対応関係の有効期間はプラットフォーム側で設定され、上流のキャッシュ期間に近づけることが推奨されます。一般的な目安は 5 分から 1 時間です。リクエストに TTL を追加する必要はなく、識別子を固定しても上流キャッシュの期限は延びません。

よくある問題の確認

キャッシュミスだけではチャネルアフィニティの失敗とは判断できません。リクエストが失敗した場合はエラーとトラブルシューティングを参照してください。

関連資料

• OpenAI Prompt Caching
• Claude Prompt Caching
• Gemini Context Caching
• DeepSeek Context Caching
• Qwen Context Cache
• GLM / Z.AI Context Caching