创建前缀缓存
更新时间:2025-11-07
POST
https://qianfan.baidubce.com/v2/caching
创建上下文缓存,通过缓存前缀信息降低后续API调用的成本。
支持模型列表
- deepseek-v3.1-250821
- deepseek-v3.1-think-250821
相关信息参见千帆-模型列表。
权限说明
调用本文API,需使用API Key鉴权方式。使用API Key鉴权调用API流程,具体调用流程,请查看认证鉴权。
请求参数
Headers 参数
除公共头域外,无其它特殊头域
Body 参数
model
string
大模型ID
必选
messages
array
聊天历史信息列表
必选
显示子属性
隐藏子属性
items
object {3}
显示子属性
隐藏子属性
role
string
当前支持:
- system:人设
- user:用户
- assistant:对话助手
必选
name
string
message名
可选
content
anyOf {2}
多选一,只需要符合下列任意一组子节点
- 不能为空
- 最后一个message对应的content不能为blank字符,如空格、"\n"、“\r”、“\f”等
必选
显示子属性
隐藏子属性
content
string
content
array
显示子属性
隐藏子属性
items
object {2}
显示子属性
隐藏子属性
type
string
仅支持text类型
必选
text
string
文本内容
必选
mode
string
本次请求创建的上下文缓存的类型
仅支持common_prefix,默认值common_prefix
可选
ttl
integer
缓存过期时长(单位:秒),范围:[3600, 604800],默认值:86400
信息创建时开始计时,每次使用时重置计时,在过期时长内未使用将从缓存中自动删除。
可选
请求结构
POST /v2/caching HTTP/1.1
Host: qianfan.baidubce.com
Authorization: Bearer <API Key>
Content-Type: application/json
{
"model": "deepseek-v3.1-250821",
"messages":[
{
"role":"user",
"content": [
{
"type": "text",
"text": "请介绍下百度千帆。"
}
]
}
],
"ttl":3600
}
示例代码
curl --location 'https://qianfan.baidubce.com/v2/caching' \
--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
--header 'Content-Type: application/json' \
--data '{
"model": "deepseek-v3.1-think-250821",
"messages":[
{
"role": "system",
"content": "你是一个专业的百度千帆技术客服,回答问题必须严谨、简短、并且使用中文。"
},
{
"role": "user",
"content": "请用一句话介绍一下千帆的caching接口。"
}
],
"ttl":3600
}'
import requests
import json
def main():
url = "https://qianfan.baidubce.com/v2/caching"
payload = json.dumps({
"model": "deepseek-v3.1-think-250821",
"messages":[
{
"role": "system",
"content": "你是一个专业的百度千帆技术客服,回答问题必须严谨、简短、并且使用中文。"
},
{
"role": "user",
"content": "请用一句话介绍一下千帆的caching接口。"
}
],
"ttl":3600
})
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer bce-v3/ALTAK-*********/614fb**********'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
if __name__ == '__main__':
main()
返回响应
Headers 参数
除公共头域外,无其它特殊头域
返回参数
id
string
缓存ID
必选
model
string
本次请求使用的大模型ID
必选
mode
string
本次请求创建的上下文缓存的类型
必选
ttl
integer
本次请求创建的上下文缓存过期时长(单位:秒)
必选
usage
object {3}
token统计信息
必选
显示子属性
隐藏子属性
prompt_tokens
integer
输入的prompt token数量
必选
completion_tokens
integer
模型生成的token数量
必选
total_tokens
integer
本次请求消耗的总token数量,包括输入和输出的数量
必选
响应示例
{
"id": "cache-20251105******-4h*****0ka",
"model": "deepseek-v3.1-think-250821",
"mode": "common_prefix",
"ttl": 3600,
"usage": {
"prompt_tokens": 36,
"completion_tokens": 0,
"total_tokens": 36
}
}
错误码
如果请求错误,服务器返回的JSON文本包含以下参数。
| 名称 | 描述 |
|---|---|
| code | 错误码 |
| message | 错误描述信息,帮助理解和解决发生的错误 |
| type | 错误类型 |
更多相关错误码,请查看模型错误码说明。
