Prompt 缓存（Prompt Caching）

​

使用场景

• 长系统提示词：多个请求复用相同的角色设定、输出规则、安全边界或产品说明。
• 固定工具定义：Function Calling 场景中，工具列表、参数 Schema 和工具说明在多轮请求中保持稳定。
• 长文档多轮问答：用户围绕同一份文档、合同、论文或会议记录连续提问。
• 代码库分析：多次请求复用同一组代码片段、项目结构或约束说明。
• RAG 后续追问：首轮请求传入较长检索结果，后续请求继续围绕相同材料提问。

​

支持的模型

​

工作机制

• 稳定的 system 提示词。
• 固定的工具定义、输出格式或约束说明。
• 重复使用的长文档、代码片段、知识库内容或检索结果。
• 每次请求变化的用户问题、少量新增上下文或会话补充。

1. 将长期复用的内容放在请求前半部分，并保持顺序稳定。
2. 将每次变化的用户问题或临时上下文放在稳定内容之后。
3. 多次请求复用相同前缀和消息顺序，尽量避免无意义改写、重排或插入动态信息。
4. 通过响应中的 usage 或用量统计页面观察是否出现缓存相关字段。
5. 根据延迟、成本和命中情况，决定是否继续使用长上下文、改用 RAG，或调整上下文组织方式。

​

与 Long Context 和 RAG 的关系

​

关键字段

• messages：承载系统提示、历史消息和可复用上下文。为了提升缓存复用机会，应尽量保持可复用部分的顺序和内容稳定。
• model：选择具体模型。不同模型是否支持 Prompt Caching、缓存命中规则和用量字段可能不同。
• usage.prompt_tokens：本次请求的输入 token 数。长上下文请求通常会增加该数值。
• usage.prompt_tokens_details.cached_tokens：如果返回该字段，可用于观察本次输入中可能命中的缓存 token 数。不同模型可能不返回该字段，字段含义和计费口径请以 API 指南为准。

​

使用建议

• 保持可复用内容和消息顺序稳定：把系统提示词、工具定义、长文档或固定约束放在请求前半部分，并在多次请求中保持内容、消息顺序和结构一致。
• 把动态内容放在后面：将用户当前问题、时间戳、临时变量、检索补充或会话新增内容放在稳定前缀之后。
• 避免无意义改写：频繁调整空格、标题、字段顺序或工具描述，可能降低缓存命中机会。
• 控制重复上下文规模：缓存可以降低重复处理成本或延迟，但不应成为无限塞入上下文的理由。
• 结合用量和耗时观察效果：如果响应中返回 cached_tokens 或用量页面展示缓存相关指标，可以结合请求耗时和成本判断是否有效。
• 与 RAG 搭配使用：对于大型知识库，先检索最相关片段，再让可复用的系统提示词、工具定义或固定材料保持稳定。
• 注意输出预算：Prompt Caching 主要作用于输入上下文。生成的输出仍会消耗 max_completion_tokens 预算。

​

限制说明

• Prompt Caching 不保证每次请求都能命中缓存。命中情况可能受模型、请求内容、消息顺序、API 入口和服务端调度影响。
• 首次请求或前几次请求可能不会返回 cached_tokens。即使后续请求命中缓存，不同模型的命中时机和命中范围也可能不同。
• Prompt Caching 不会让模型记住请求之外的内容。需要模型使用的材料仍必须在当前请求中提供，或通过已确认的缓存机制引用。
• Prompt Caching 不改变模型回答质量，也不保证相同输入每次生成完全一致。
• cached_tokens 可以作为观察缓存命中的参考，但不等同于完整计费规则。缓存有效期、是否需要显式开启、是否产生额外费用以及命中后的计费方式，必须以 API 指南和模型详情为准。
• 如果输入超过模型上下文限制，Prompt Caching 不能替代上下文窗口。仍需要减少输入、拆分任务，或选择上下文窗口更大的模型。
• 不要在可复用上下文中放入不应被后续请求复用的敏感信息、一次性凭证或用户私密数据。

​

调用示例

export API_KEY="YOUR_API_KEY"

1. 将固定规则和长材料放在前面。
2. 将每次变化的问题放在后面。
3. 多次请求复用相同的 stable_context。
4. 如响应返回 cached_tokens，打印该字段用于观察。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url="https://api.siflow.cn/model-api",
)

stable_context = """
你是一名严谨的文档分析助手。
请只基于 <document> 中的材料回答问题。
如果材料中没有答案，请说明无法从材料中确认。

<document>
在这里放入会被多次复用的长文档、代码片段、产品说明或检索结果。
后续请求应尽量保持这部分内容不变。
</document>
"""


def ask(question: str):
    response = client.chat.completions.create(
        model="glm-5.2",
        messages=[
            {"role": "system", "content": stable_context},
            {"role": "user", "content": question},
        ],
        max_completion_tokens=512,
    )

    print(response.choices[0].message.content)

    prompt_details = getattr(response.usage, "prompt_tokens_details", None)
    if prompt_details:
        cached_tokens = getattr(prompt_details, "cached_tokens", None)
        print("cached_tokens:", cached_tokens)


ask("请总结这份材料的三个核心结论。")
ask("请列出材料中仍需要确认的问题。")