Prompt 缓存

Prompt caching（也称为 prefix caching）是一种性能优化，让 Workers AI 能够更快响应具有共享输入的 prompt 请求。它通过复用先前计算的 input tensor，而非从头重新处理，来降低 Time to First Token（TTFT）并提高 Tokens Per Second（TPS）吞吐量。

缓存的 input token 按折扣费率计费，低于常规 input token。Workers AI 默认对选定模型启用 prefix caching。兼容性和定价详情列于各模型页面。

LLM 处理请求时经历两个阶段：

1. Prefill 阶段 — 处理 input token（system prompt、tool 定义、对话历史）。
2. Output 阶段 — 生成 output token。

使用 prefix caching 时，Workers AI 存储 prefill 阶段计算的 input tensor。在后续共享相同 prefix 的请求中，模型跳过缓存部分的 prefill，仅处理新的 input token。这节省大量计算时间，尤其对于连续请求共享大量上下文的 agentic 工作负载。

例如，当编码 agent 发送新提示词时，通常会重新发送所有先前的提示词、工具定义和对话历史。连续请求之间的增量往往只是几行新内容。前缀缓存避免对所有共享上下文进行冗余预填充。

前缀缓存仅在请求路由到持有缓存张量的同一模型实例时生效。为最大化缓存命中率，请发送带有会话或 agent 唯一标识符的 x-session-affinity 标头。这会将具有相同标识符的请求路由到同一模型实例，提高前缀缓存命中的可能性。

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/moonshotai/kimi-k2.5" \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -H "x-session-affinity: ses_12345678" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is prefix caching and why does it matter?"
      }
    ],
    "max_tokens": 2400,
    "stream": true
  }'

const response = await env.AI.run(
	"@cf/moonshotai/kimi-k2.5",
	{
		messages: [
			{ role: "system", content: "You are a helpful assistant." },
			{ role: "user", content: "Explain prefix caching." },
		],
	},
	{
		extraHeaders: {
			"x-session-affinity": "ses_12345678",
		},
	},
);

Prefix caching 从 prompt 开头匹配确切的 token 序列。单个 token 差异会从该点起使缓存失效。

为最大化 cache hit：

• 将静态内容放在前面。 System prompt、tool 定义和共享 instruction 应出现在 prompt 开头。将用户特定或动态内容（时间戳、用户查询）放在末尾。
• 避免在 system prompt 中使用时间戳。 在 system prompt 开头包含时间戳会使每次请求的 prefix 发生变化，完全破坏缓存。如需时间上下文，请将其添加到 user 消息中。
• 跨请求复用 tool 定义。 对于 function-calling agent，tool 是 prompt prefix 的一部分。在同一会话中保持 tool 定义一致可提高缓存复用。

Workers AI 在响应 usage 对象中显示缓存 token 计数。使用此信息验证 prefix caching 是否生效并跟踪成本节省。首次请求通常为 cold hit，因此首次命中不返回缓存 token 是预期行为。由于 block size 限制，input 必须足够大才会被缓存。 缓存 token 按低于常规 input token 的费率计费，并计入你的 neuron 计数。