渠道亲和性接入指南

使用稳定会话标识和请求前缀，提高连续请求的路由稳定性与缓存复用机会。

连续对话、代码助手和长上下文任务可以通过稳定标识，提高渠道复用和上下文缓存的机会。

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 或网关是否实际发送了字段或 Header；原渠道不可用时会自动回退
缓存命中较少	稳定前缀是否变化、工具和历史消息是否重排、请求间隔是否超出缓存窗口，以及可复用内容是否达到模型缓存门槛
添加 `cache_control` 后仍未命中	缓存断点不等于渠道亲和，检查对应亲和标识及缓存前缀是否稳定
DeepSeek 没有填写 `user_id`	平台会从 UID 池自动分配；需要固定用户亲和时，主动传入稳定标识
不知道如何观察缓存效果	DeepSeek 查看 `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`；GLM 查看 `prompt_tokens_details.cached_tokens`，均位于响应的 `usage` 中

缓存未命中不能单独证明渠道亲和失效。请求失败时参阅错误与排障。