概述

云信大模型 API 服务（以下简称 AIHub）通过 路由亲和策略 提升上游模型缓存的复用概率，在目标环境已启用路由亲和、系统默认 Sticky 已放量且请求命中生效范围时，调用方为可复用上下文提供稳定关联标识后，AIHub 会尽量将请求路由到同一条健康上游渠道，减少多渠道调度对 Provider KV Cache/Prompt Cache 的打散。未启用、未放量或未命中生效范围时，请求继续使用普通加权路由。

路由亲和不是网关级响应缓存。AIHub 不会按关联标识保存或直接返回历史模型响应，也不会绕过 Provider 发起推理请求。实际是否命中缓存、缓存有效期及计费方式，均由模型与 Provider 的缓存机制决定。

适用接口

路由亲和适用于以下标准推理接口：

协议	接口	推荐关联方式
OpenAI Chat Completions	POST https://ai.yunxinapi.com/hub/v1/chat/completions	X-AIHub-Affinity-Key
OpenAI Responses	POST https://ai.yunxinapi.com/hub/v1/responses	首轮使用 X-AIHub-Affinity-Key；连续响应使用 previous_response_id
Anthropic Messages	POST https://ai.yunxinapi.com/hub/v1/messages	X-AIHub-Affinity-Key；也兼容 metadata.user_id

工作原理

AIHub 收到请求后，依次完成模型权限、路由绑定、协议能力与运行时健康检查，再从当前可用最高优先级候选组中选择渠道。

系统默认 Sticky 的行为如下（平台针对特定访问范围配置的高级路由策略可能覆盖）：

• 相同访问范围、模型、调用模式和关联标识，在候选集合不变时稳定选择同一渠道。
• 不同关联标识按渠道权重分散，避免所有会话集中到单一渠道。
• 候选渠道新增、移除或故障时，仅重新分配受影响请求，软重绑到当前可用渠道。
• 未提供有效关联标识时，请求继续使用普通加权路由，不会因缺少缓存参数而失败。

关联标识会与访问范围、逻辑模型、端点协议和调用模式共同隔离。即使两个请求使用相同标识，只要模型或访问范围不同，也不会被强制绑定到同一渠道。

关联标识优先级

系统默认亲和策略下，AIHub 按以下优先级选择第一个有效标识：

优先级	字段	适用范围	说明
1	X-AIHub-Affinity-Key	标准推理接口	（推荐）对请求 Body 无侵入
1	metadata.aihub_affinity_key	JSON Body	与 Header 语义相同；两者同时存在时 Header 优先
2	X-AIHub-Session-Id	标准推理接口	会话级软亲和
2	metadata.session_id	接受该 metadata 的 JSON 协议	与 Session Header 语义相同；两者同时存在时 Header 优先
3	metadata.user_id	Anthropic Messages	Anthropic external user identifier，仅作为软亲和键
4	prompt_cache_key	支持该字段的 OpenAI-compatible 请求	兼容自动生成该字段的客户端

• metadata.session_id 不是 AIHub 保留字段，亲和提取后不会被网关统一删除，可能按原协议继续透传或转换。只有目标协议和 Provider 接受该 metadata 时才应使用；不确定时请使用 X-AIHub-Session-Id。
• https://ai.yunxinapi.com/hub/v1/responses 的 previous_response_id 是 OpenAI Responses API 的公开请求字段，不属于上述普通软亲和键。客户端可将上一轮成功响应的 id 原样传入下一轮请求，AIHub 会尽力保持连续调用所需的路由一致性。实际是否支持连续调用取决于所选模型和上游渠道。
• 平台可能针对特定模型或访问范围配置高级路由策略，亲和是尽力而为的稳定性优化，不是对固定 Provider 账号或物理实例的永久绑定。

推荐接入方式

使用 X-AIHub-Affinity-Key（推荐）

在请求头中添加稳定、脱敏的业务关联标识：

httpX-AIHub-Affinity-Key: aff_7f5c9e2a6d4b...

该 Header 是 AIHub 路由控制字段，不是 Provider 的缓存协议字段。原生 Provider 调用路径会重新构造出站请求，不携带该 Header；平台管理的受信二级网关字节转发路径可能将其传递给二级网关。请务必使用脱敏 opaque value。

请参考以下场景的建议，选择请求头：

场景	推荐
业务系统已有稳定会话 ID	X-AIHub-Session-Id
需表达更细粒度的工作负载或缓存域	X-AIHub-Affinity-Key（优先）

若两个 Header 同时存在时，X-AIHub-Affinity-Key 优先。AIHub 当前不使用 X-Conversation-Id 作为亲和字段。

Chat Completions 示例：

bashcurl "https://ai.yunxinapi.com/hub/v1/chat/completions" \
  -H "Authorization: Bearer <AIHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "X-AIHub-Affinity-Key: aff_7f5c9e2a6d4b" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Summarize the following text."}
    ]
  }'

在后续可复用同一上下文前缀的请求中，继续传递相同的 X-AIHub-Affinity-Key。

使用 JSON Body

不方便增加 Header 时，可在 JSON Body 中使用 AIHub 专用 metadata：

json{
  "model": "glm-5.3",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "metadata": {
    "aihub_affinity_key": "aff_7f5c9e2a6d4b"
  }
}

metadata.aihub_affinity_key 是 AIHub 网关保留字段，提取后会在调用上游前删除，避免影响 Provider 的 metadata 校验。

Anthropic Messages

Anthropic Messages 请求可使用 metadata.user_id 作为低优先级软亲和键：

json{
  "model": "glm-5.3",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "metadata": {
    "user_id": "usr_7f5c9e2a6d4b"
  }
}

• metadata.user_id 是 Anthropic 协议字段，可能按协议透传或转换给上游。请只使用 UUID、哈希或其他不可识别个人身份的 opaque identifier，不要传入姓名、邮箱、手机号或明文内部账号。
• 如需区分同一用户下的多个工作负载、缓存域或会话，应优先使用粒度更准确的 X-AIHub-Affinity-Key。metadata.user_id 本身不是 Provider 的 Prompt Cache Key，不能单独保证缓存命中。

OpenAI Responses 连续调用

首轮请求可使用 X-AIHub-Affinity-Key。收到成功响应中的 id 后，下一轮将该值放入 previous_response_id：

json{
  "model": "glm-5.3",
  "previous_response_id": "resp_abc123",
  "input": "Continue from the previous response."
}

previous_response_id 应填写上一轮成功响应返回的 id，作为 Responses 请求体字段传递；不需要放入 Header，也不要复制到 X-AIHub-Affinity-Key。

关联标识设计建议

推荐按缓存复用边界生成标识，例如：

textSHA-256(canonical_json({
  "v": 1,
  "tenant_id": tenant_id,
  "app_id": app_id,
  "workload": workload,
  "cache_domain": cache_domain,
  "conversation_id": conversation_id
}))

canonical_json 表示字段顺序、字符编码和空值表示均固定的序列化结果。不要直接无分隔地拼接多个字段，否则不同字段组合可能产生相同输入。

设计时遵循以下原则：

• 稳定：可复用相同上下文前缀的连续请求使用相同标识，不要每次请求生成随机值。
• 隔离：租户、应用、权限域、工作负载或缓存语义变化时应使用不同标识，避免无关请求争用同一亲和域。
• 脱敏：只传不可逆哈希、随机 UUID 或其他 opaque identifier，不传 prompt、message、API Key、手机号、邮箱或明文个人标识。
• 短小：建议使用 ASCII；默认最大长度 128 个 UTF-8 字节，空值或超限值不会用于亲和选择。
• 可轮换：业务隔离边界或安全策略变化时生成新标识，不要永久复用一个全局固定值。

AIHub 使用关联标识生成不可逆指纹用于路由计算；亲和相关日志、路由存储和 Console 不记录或回显原始关联标识及完整 HMAC。

该约束不等同于请求字段对所有上游跳点不可见：Provider 原生协议字段可能按协议透传或转换，亲和 Header 在受信二级网关字节转发路径中也可能被传递。调用方始终只能使用脱敏值。

如何提高实际缓存命中率

路由亲和只解决“请求尽量落到同一上游渠道”的问题。要提高 Provider 侧真实缓存命中率，还需同时满足：

• 使用相同的逻辑模型和兼容的 Provider 缓存能力。
• 保持可缓存内容位于消息或 input 的稳定前缀，避免在前缀中插入时间戳、随机数等动态内容。
• 按 Provider 协议正确设置 cache_control、prompt_cache_key 等缓存字段（不同 Provider 的字段和规则可能不同）。
• 在 Provider 缓存有效期内发起后续请求。
• 避免在连续请求之间频繁切换模型、协议入口、访问凭证或业务缓存域。

是否命中、命中 token 数、价格优惠与过期时间，以 Provider 返回的 usage 和对应模型说明为准。AIHub 不承诺固定缓存命中率或固定费用降幅。

预期行为与限制

• 尽力保持稳定：候选集合、渠道健康、优先级、权重或平台配置变化时，同一标识可能重新绑定。
• 普通亲和优先可用性：普通软亲和渠道不可用时，请求会软重绑到其他健康渠道；缓存可能重新预热，但正常推理优先。
• 无标识正常服务：未传、传空值或标识不可用时，请求按普通加权路由处理。
• 流式与非流式一致：亲和选择发生在请求发送上游之前，不改变 SSE 或普通 JSON 的响应协议。
• 不固定供应商账号：关联标识表达的是缓存复用意图，不是指定 Provider、渠道或账号的路由指令。
• 不缓存响应内容：相同请求仍会调用上游模型，模型输出也可能不同。

排查建议

若相同会话仍频繁切换渠道或缓存命中率低，请依次检查：

1. 目标环境是否已启用路由亲和，默认 Sticky 是否已放量，请求是否命中生效范围。
2. 每次请求实际发送的关联标识是否完全一致，且不为空、不超过当前环境限制（默认 128 个 UTF-8 字节）。
3. 是否在同一模型、同一协议入口和同一访问范围内调用。
4. Prompt/Messages 的可缓存前缀是否保持一致，Provider 要求的缓存控制字段是否正确。
5. 原亲和渠道是否发生故障、熔断、下线或路由配置变化。
6. 使用 Body 传递时，Content-Type 是否为 application/json 或 application/*+json。

联系云信技术支持时，请提供响应 Header 中的 X-AIHub-Request-Id、请求时间、模型和接口路径。请勿提供完整 API Key、关联标识、Prompt 或用户敏感数据。