缓存与请求亲和

Updated: 2026-07-02

长上下文请求通常会使用提示词缓存。为了让缓存更稳定，建议同一个项目、会话或任务的请求尽量携带稳定的缓存标识或亲和标识。

先看结论

X-Affinity-Key 是 HTTP 请求头 Header，不是 JSON 请求体字段。只有在客户端、SDK、代理工具或网页工具支持自定义 Header 时，才可以手动添加。

X-Affinity-Key: project-or-session-id

这个值可以是项目 ID、会话 ID、工作区 ID 或你自己生成的稳定字符串。不要使用每次请求都会变化的随机值。

HTTP / curl

如果你直接发 HTTP 请求，把 X-Affinity-Key 放在请求头里：

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Affinity-Key: project-or-session-id" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "Continue the task."
      }
    ]
  }'

如果你使用的是 Claude 原生 /v1/messages，同样放在请求头里：

curl https://api.example.com/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Affinity-Key: project-or-session-id" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Continue the task."
      }
    ]
  }'

OpenAI 兼容请求

如果你的工具使用 OpenAI 兼容接口，有两种常见方式：

• X-Affinity-Key：放在 HTTP 请求头里。
• prompt_cache_key：放在 JSON 请求体里。

{
  "model": "gpt-5.4",
  "prompt_cache_key": "project-or-session-id",
  "messages": [
    {
      "role": "user",
      "content": "Continue the task."
    }
  ]
}

如果客户端同时支持自定义 Header 和请求体参数，可以同时传：

X-Affinity-Key: project-or-session-id

{
  "model": "gpt-5.4",
  "prompt_cache_key": "project-or-session-id",
  "messages": [
    {
      "role": "user",
      "content": "Continue the task."
    }
  ]
}

OpenAI SDK

使用 SDK 时，X-Affinity-Key 通常放在默认请求头或单次请求头里。

JavaScript 示例：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: "https://api.example.com/v1",
  defaultHeaders: {
    "X-Affinity-Key": "project-or-session-id"
  }
});

await client.chat.completions.create({
  model: "gpt-5.4",
  prompt_cache_key: "project-or-session-id",
  messages: [
    {
      role: "user",
      content: "Continue the task."
    }
  ]
});

Python 示例：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.example.com/v1",
    default_headers={
        "X-Affinity-Key": "project-or-session-id",
    },
)

client.chat.completions.create(
    model="gpt-5.4",
    prompt_cache_key="project-or-session-id",
    messages=[
        {
            "role": "user",
            "content": "Continue the task.",
        }
    ],
)

Claude 原生请求

Claude 原生接口使用 /v1/messages。如果请求中有较长且重复的 system prompt、工具说明或上下文片段，可以在对应内容块上添加 cache_control。

cache_control 放在请求体的稳定内容块里，X-Affinity-Key 放在请求头里；它们不是同一个位置。

X-Affinity-Key: project-or-session-id

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "metadata": {
    "user_id": "stable-user-or-session-id"
  },
  "system": [
    {
      "type": "text",
      "text": "Long stable system prompt or project context...",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Continue the task."
    }
  ]
}

建议尽量满足以下任意一种：

• 请求体里有稳定的 metadata.user_id。
• 请求头里有稳定的 X-Affinity-Key。
• 请求头里有稳定的 Session_id。
• 请求内容里有带 cache_control 的稳定内容块。

Claude Desktop / Claude Code / Cherry Studio 等工具

这类工具是否能设置，取决于工具本身有没有提供自定义 Header 或高级请求参数配置。

通常可以按这个顺序检查：

• 在 Provider、API Endpoint、模型供应商或高级设置里查找 Custom Headers、Headers、自定义请求头。
• 如果有，添加 Header 名称 X-Affinity-Key，值填写稳定的项目、会话或工作区标识。
• 如果工具支持 Claude / Anthropic provider，优先选择 Claude / Anthropic provider。
• 如果工具把 Claude 请求转换成 OpenAI 格式，可能会丢失 Claude 原生的 cache_control。
• 如果工具不支持自定义 Header，也不支持 metadata 或 cache 参数，就无法在工具侧强制添加，只能依赖网关侧兜底和请求内容本身。

示例配置含义：

Header Name: X-Affinity-Key
Header Value: project-or-session-id

第三方代理、切换器或网页工具

如果你使用第三方代理、模型切换器、网页工具或浏览器里的聊天工具，请重点确认它是否会保留请求头和请求体字段。

• 如果工具支持自定义 Header，添加 X-Affinity-Key。
• 如果工具支持 OpenAI 兼容请求体参数，可以添加 prompt_cache_key。
• 如果工具支持 Claude 原生请求，确认它不会丢弃 cache_control 和 metadata。
• 如果工具只提供普通聊天输入框，没有 Header 或高级参数配置，通常无法手动设置缓存或亲和标识。

检查方式

发起长上下文请求后，可以在用量日志中查看是否出现缓存读取、缓存创建，以及长任务请求是否保持稳定。短上下文请求通常不会明显体现缓存效果。