千问API上下文缓存分隐式与显式两种：隐式自动识别≥1024 Token前缀并缓存，命中后按20%计费；显式需手动添加cache_control字段创建5分钟或1小时缓存，首次写入按125%或200%计费，后续命中仅按10%计费。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您调用千问API时发现多轮对话或重复文档处理中存在大量固定提示词、工具定义或项目背景说明，但每次请求仍为全部内容计费，则可能是未启用上下文缓存功能。以下是千问API上下文缓存的具体使用方法与多种降本增效方案：
一、启用隐式缓存：零配置自动识别前缀
隐式缓存由千问服务端自动触发，无需修改请求参数或添加标记，适用于通用场景。系统会持续扫描连续请求中字节级一致的输入前缀（通常要求≥1024 tokens），一旦识别到重复静态内容，即在后台自动缓存其KV状态，后续相同前缀的请求将跳过预填充计算。
1、确保所有不变内容严格置于请求prompt最前端，包括角色设定、格式约束、工具描述、项目上下文等；
2、动态内容（如用户当前问题、实时API返回数据）必须统一置于prompt末尾，并使用标准化占位符如{user_query}替代原始变量；
3、禁用引入不确定性的采样参数，强制设置temperature=0且显式指定seed值，保障相同输入必然生成相同KV状态；
4、避免在prompt开头插入时间戳、用户ID、随机数等易变字段，否则将导致缓存每轮失效。
二、配置显式缓存：手动创建确定性缓存Key
显式缓存需主动开启，通过cache_control字段声明缓存意图，适用于对命中率和成本控制有明确要求的场景。该模式支持设置5分钟或1小时有效期，在有效期内可实现100%确定性命中，且读取阶段仅按输入token标准单价的10%计费。
1、在请求消息体中为需要缓存的前缀段添加cache_control: {"type": "ephemeral", "ttl": 300}（5分钟）或{"type": "ephemeral", "ttl": 3600}（1小时）；
2、确保cache_control仅作用于静态部分，动态内容段不得携带该标记；
3、首次请求发送含cache_control的完整prompt，服务端将执行带溢价的写入（5分钟写入按125%计费，1小时写入按200%计费）；
4、后续请求保持前缀完全一致（含空格、换行、标点），即可触发缓存读取，仅对新增动态内容计费。
三、对接OpenAI兼容接口：复用现有SDK无缝启用
千问API提供OpenAI兼容模式，隐式缓存在此模式下自动生效，无需任何代码变更。开发者可直接使用现有OpenAI Python SDK、curl命令或Postman模板发起请求，服务端将依据输入特征自主判断是否启用缓存。
1、将API请求地址替换为千问提供的OpenAI兼容Endpoint（如https://dashscope.aliyuncs.com/compatible-mode/v1）；
2、保持Authorization头为Bearer + 千问API Key；
3、请求体结构维持标准OpenAI格式，包括model、messages、temperature等字段；
4、确认响应头中包含x-prompt-cache-hit: true字段，表示本次请求已成功命中缓存。
四、前端协同优化：结构化拼接与会话摘要
前端作为请求发起方，可通过标准化prompt构造与上下文管理进一步提升缓存效率。重点在于维持前缀稳定性与降低无效token传输，尤其适用于Web UI、移动端集成等场景。
1、将system message与document context合并为单一message对象，并置于messages数组首位；
2、对历史对话进行摘要压缩，仅保留关键决策点与用户意图，避免整段复制早期交互；
3、使用客户端本地缓存记录最近使用的cache_key或session_id，配合服务端缓存路由策略；
4、在用户切换会话或重置上下文时，主动清空本地缓存并生成新请求标识，防止跨会话污染。
五、验证缓存效果：解析响应头与监控指标
千问API在响应中嵌入缓存行为元数据，开发者可通过解析HTTP响应头实时验证缓存是否生效，并据此调整prompt结构或缓存策略。
1、检查响应头x-prompt-cache-hit是否存在且值为true，确认命中状态；
2、读取x-prompt-cache-write-cost字段，确认本次是否发生缓存写入及对应token开销；
3、对比x-input-tokens与x-cached-input-tokens差值，计算实际缓存节省的token数量；
4、在阿里云百炼控制台查看“上下文缓存命中率”与“平均缓存节省token数”两个核心监控指标。
