管道親和性串接指南

使用穩定的工作階段識別碼與請求前綴，提高路由穩定性及上下文快取的重用機會。

連續對話、程式碼助理與長上下文任務可透過穩定識別碼，提高管道重用與上下文快取的機會。

AGTCloud 會根據請求中的穩定識別碼，讓後續請求優先重用先前成功使用的管道。管道無法使用時，平台會自動選擇其他可用管道。這個穩定識別碼稱為「親和鍵」。

管道親和用於穩定路由，上下文快取用於重用計算；管道穩定不代表每次都能命中快取。

選擇串接方式

優先重用協定既有的識別欄位；不方便修改請求本文時，可由 SDK 或閘道透過請求標頭統一傳入穩定識別碼。

模型系列	建議親和識別欄位	搭配使用的快取方式
OpenAI	`prompt_cache_key`	自動前綴快取
Claude / Anthropic	`metadata.user_id` 或 `x-conversation-id`	`cache_control`、自動多輪快取
Gemini	`x-conversation-id`	隱式快取或顯式 `cachedContent`
DeepSeek	`user_id` 或 `x-conversation-id`	自動上下文快取
Qwen	`x-conversation-id`	隱式快取、`cache_control` 或 Session Cache
GLM / Z.AI	`x-conversation-id`	自動上下文快取

統一使用 `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 對話時，可另外加入 previous_response_id，填入上一次回傳的回應 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 的預設並行數限制如下：

模型	預設並行數
deepseek-v4-flash	2500
deepseek-v4-pro	500

未傳入 user_id 時，平台會從已設定的 UID 集區自動分配可用識別碼，請求仍可正常傳送。

透過回應中的 usage.prompt_cache_hit_tokens 與 usage.prompt_cache_miss_tokens，觀察命中與未命中快取的 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 等模型提供自動上下文快取，適合長任務、程式碼及 Agent 情境。同一專案或 Agent 任務應使用穩定的 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": "這裡放穩定的 Agent 任務目標、工具限制與專案背景。"
      },
      {
        "role": "user",
        "content": "繼續執行下一步。"
      }
    ],
    "stream": false
  }'

透過回應中的 usage.prompt_tokens_details.cached_tokens 觀察快取命中 Token。使用思考保留功能時，需要重用的歷史片段也應保持原有順序與內容。

使用建議

前綴保持穩定：固定指令、工具定義、長文件與歷史摘要放在前面；本輪問題、時間及暫時日誌放在後面。避免重排工具、改寫未變動的歷史內容或插入隨機值。
依用途選擇識別碼：對話 ID 在同一對話內固定；使用者 ID 對同一使用者長期固定；專案或知識庫識別碼依專案、版本區分。不要跨租用戶混用，也不要以共用專案識別碼取代需要區分使用者的識別碼。
避免敏感明文：不要以電話號碼、電子郵件、身分證號或 API Key 作為親和鍵。可對業務識別碼進行不可逆處理，不要使用一次性的 Request ID。
注意有效期間：親和對應的有效期由平台設定，建議接近上游快取期間，常見參考為 5 分鐘至 1 小時。請求中不必額外填寫 TTL，保持識別碼不變也不會延長上游快取的有效期。

常見問題排查

遇到的問題	優先檢查
連續請求未穩定重用管道	識別碼是否每輪改變，SDK 或閘道是否確實傳送欄位或標頭；原管道無法使用時會自動切換
快取命中較少	穩定前綴是否變動、工具或歷史訊息是否重排、請求間隔是否超出快取期間，以及可重用內容是否達到模型快取門檻
加入 `cache_control` 後仍未命中	快取斷點不等於管道親和，請檢查對應親和識別碼與快取前綴是否穩定
DeepSeek 未填寫 `user_id`	平台會從 UID 集區自動分配；需要固定使用者親和時，請主動傳入穩定識別碼
不知道如何觀察快取效果	DeepSeek 檢視 `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`；GLM 檢視 `prompt_tokens_details.cached_tokens`，皆位於回應的 `usage` 中

快取未命中不能單獨證明管道親和失效。請求失敗時，請參閱錯誤與疑難排解。