> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt 缓存

在开发大模型的多轮对话和固定场景人设问答时，会将用户的输入和大模型的回答构建成对话历史传递在整个对话中，而随着对话轮次增加，整个对话过程中的重复内容也会逐渐增多。

Prompt 缓存可复用请求中的重复前缀。缓存命中的输入 Token 按对应模型的缓存命中单价计费，单价见 [API 定价](https://platform.stepfun.com/docs/zh/guides/pricing/details.md#文本与多模态模型)。

## 缓存支持模型

目前 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash`、`step-3.5-flash-2603`、`step-1o-turbo-vision` 等模型支持 Prompt 缓存，其他模型的支持情况请以对应模型文档和定价表为准。

## Prompt 缓存的基础原理

当请求超过 256 个 Token 时，缓存会自动启用。当您发起一次 API 请求时，会执行如下操作：

1. **缓存查询**：根据您的请求的 Prompt 的前缀，查询当前的 Prompt 是否有系统的缓存。

2. **缓存命中**：如果命中系统的缓存，系统将会使用缓存，并加上本次请求中缓存不包含的内容，进行推理。

3. **缓存未命中**：如果未命中系统的缓存，系统将会进行正常的推理并在处理完成后，将 Prompt 前缀进行缓存，以供下次请求使用。

在包含多 Example、多轮次对话、长上下文或背景信息的场景下，缓存命中率会更高，帮助开发者提升系统整体性能，优化成本。

缓存淘汰采用最近最少使用（LRU）策略，在系统请求高峰期，不使用的缓存会更容易被逐出；在系统请求低峰期，缓存则会拥有更长的生命周期。

## 如何判断自己是否使用了 Prompt 缓存

在调用 Chat API 进行补全时，如果 `response.usage.cached_tokens` 大于 0，则表明该请求命中缓存，其值为命中的输入 Token 数。字段为 0 时表示未命中缓存。

以下为用量字段的示意响应，实际返回内容以请求结果为准：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "22ebae159c8f10c8657253671c8f7f17.6de8d4f65f5ba3dddeb693a1aa83de1e",
    "object": "chat.completion",
    "created": 1730963954,
    "model": "step-5-preview",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "xxx"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "cached_tokens": 512,
        "prompt_tokens": 591,
        "completion_tokens": 120,
        "total_tokens": 711
    }
}
```

以上面这个请求结果为例，输入总量仍为 591 Token，其中 512 Token 按缓存命中单价计费，剩余 591 - 512 = 79 Token 按缓存未命中单价计费。缓存不会减少实际输入 Token 数，也不意味着命中部分免费。输入费用为 `(79 × 缓存未命中单价 + 512 × 缓存命中单价) / 1,000,000`，其中单价的单位为元 / 1M tokens；输出 Token 另行计费。

## 什么样的内容会进入缓存

在进行缓存时，**会以 256 个 Token 作为最小单元开始进行缓存**，当您的 Prompt 长度少于 256 个 Token 时，将不会命中缓存。

具体可缓存的信息会包含如下内容：

* **对话信息**：完整的对话数组会进入到缓存系统当中，其中包含 System Prompt、User Message 以及 Assistant Message。

* **图片信息**：用户消息中包含的图片信息也会进入缓存当中，但需要保证前后使用的是相同的图片。

* **视频信息**：用户消息中包含的视频信息也会进入缓存当中，但需要保证前后使用的是相同的视频。

* **工具调用信息及其结果**：对话信息中的工具调用信息及其调用结果也会参与到缓存当中。

## 最佳实践

* 在 Prompt 的开头使用静态或者重复的内容，而在整个 Prompt 结尾放置动态的内容；
* 监控不同 Prompt 的 Cached Token 和 Prompt Token 的比重、延迟、命中率，来优化 Prompt 结构；
* 近期未使用的缓存会被系统逐出，因此，尽可能保持 Prompt 前缀的稳定，以获得更高的缓存命中率。
* 对于较长的 Prompt，可以放在系统流量非高峰期进行，以减少缓存被逐出的次数，获得更高的缓存命中率。

## 如何对缓存进行排查

如果您的请求没有按照您的预期进行缓存，您可以按照如下的思路进行排查：

1. 确保缓存的部分在每次调用过程中都始终保持一致；
2. 检查是否两次请求间隔时间太长，以避免缓存失效；
3. 验证是否提供了至少 256个 Token 作为输入。

## 常见问题

### 缓存是否影响模型的推理的效果？

缓存不会影响模型的推理效果，每次生成都会使用完整的 Prompt 进行推理。

### 我是否需要为 Prompt 缓存额外付费？

无需单独开通付费缓存功能。未命中的输入 Token（包括首次写入缓存的内容）按缓存未命中单价计费，命中的输入 Token 按缓存命中单价计费。具体单价见 [API 定价](https://platform.stepfun.com/docs/zh/guides/pricing/details.md#文本与多模态模型)。

### 我是否可以手动清除 Prompt 缓存？

目前不提供手动清除缓存的能力。您可以通过修改 Prompt 来使请求不命中缓存；

### 我是否可以让我的请求始终命中缓存？

目前我们不提供保证始终命中的 Prompt 缓存，如果您有相关诉求，可以通过联系我们和我们取得联系，确认您的场景和问题。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.