前缀缓存对话
使用已经创建的前缀缓存信息,进行对话。
支持模型列表
- deepseek-v3.1-250821
- deepseek-v3.1-think-250821
相关信息参见千帆-模型列表。
权限说明
调用本文API,需使用API Key鉴权方式。使用API Key鉴权调用API流程,具体调用流程,请查看认证鉴权。
请求参数
大模型ID
聊天历史信息列表
- 非空,首条消息为user/system/assistant,末条消息为user/tool
- 总内容长度不得超模型限制
- 合并连续角色后,模式应为 (user/tool) -> assistant -> (user/tool)……
- 含tool_calls的assistant消息不可合并,其前必为user,其后必有数量匹配的连续tool消息
显示子属性
隐藏子属性
显示子属性
隐藏子属性
当前支持:
- system:人设
- user:用户
- assistant:对话助手
- tool:函数
message名
多选一,只需要符合下列任意一组子节点
对话内容,说明:
- 不能为空
- 最后一个message对应的content不能为blank字符,如空格、"\n"、“\r”、“\f”等
显示子属性
隐藏子属性
显示子属性
隐藏子属性
显示子属性
隐藏子属性
当前支持以下类型:
- text:文本
- image_url:图像url
- video_url:视频url
文本信息,当参数type为text时必填
图片信息,当参数type为image_url时必填
- 多图支持,无数量上限
- 所有图片的总Token数需在8K以内
- 每张图片大小不超过10MB(URL图片的下载大小或Base64图片解码后的大小)
显示子属性
隐藏子属性
图片数据的url或者base64
- 通过Base64传入
- 支持格式:JPG, JPEG, PNG, BMP
- 数据格式:data:image/<图片格式>;base64,<Base64编码>
- 通过URL传入
- 支持格式:JPG, JPEG, PNG, BMP, WEBP
图像/分辨率质量
- low:低分辨率
- high:高分辨率,默认为high
视频信息,当参数type为video_url时必填
显示子属性
隐藏子属性
视频数据的url或者base64
单个视频最大为64MB
每秒钟从视频中抽取指定数量的图像
取值范围:[0.2, 5],默认值是2
函数调用
模型返回的函数调用请求(tool_calls)及其结果,必须作为历史信息传入下一轮对话的 messages中,以确保模型拥有连续的对话上下文
显示子属性
隐藏子属性
显示子属性
隐藏子属性
function call的唯一标识,由模型生成
固定值function
function call的具体内容
显示子属性
隐藏子属性
函数名称
函数参数
- 当role为tool时,必填
- 模型生成的function call id,对应tool_calls中的tool_calls[].id
- 需传递真实的、由模型生成id,否则严重影响模型后续回复的质量
是否以流式接口的形式返回数据,默认false
流式响应的选项,当设置stream为true时生效
显示子属性
隐藏子属性
流式响应是否输出usage
设为true时,在最后一个输出的数据块中包含一个附加的usage字段,记录整个请求的token统计信息
温度值控制输出的随机性,默认0.8,范围[0, 2]
温度值高,输出结果更具随机性和创造性
温度值低,输出结果更集中、确定和可预测
输出文本的多样性,取值越大,生成文本的多样性越强。
默认0.8,取值范围[0, 1]
重复惩罚,默认1,范围 [1,2]
此值越大,对已出现内容的惩罚越重,能有效降低文本重复率。
- 取值范围(0,2147483647),由模型随机生成,默认值为空
- 如果指定,系统将尽最大努力进行确定性采样,以便使用相同seed和参数的重复请求返回相同的结果
生成停止标识。若生成内容以列表中任一字符串结尾,则停止生成
元素长度≤20,最多4个
显示子属性
隐藏子属性
用户唯一标识符,用于安全风控
登录用户传passportid,未登录传空
频率惩罚。设为正值时,惩罚已频繁出现的词元,降低重复率
默认值因模型而异,取值范围[-2.0, 2.0],仅百亿模型支持
存在惩罚。设为正值时,惩罚所有已出现的词元,鼓励谈论新主题
默认值因模型而异,取值范围[-2.0, 2.0],仅百亿模型支持
可触发函数的描述列表
显示子属性
隐藏子属性
显示子属性
隐藏子属性
工具类型,取值function
函数说明
显示子属性
隐藏子属性
多选一,只需要符合下列任意一组子节点
控制模型如何选择调用函数,仅千亿模型支持
显示子属性
隐藏子属性
当前支持:
- none:禁用函数调用。模型只会生成普通文本回复
- auto:默认模式。由模型智能判断是否需要调用函数,以及调用哪个函数
- required:强制模型必须调用至少一个函数
强制指定具体函数,该函数必须存在于提供的function列表中。
显示子属性
隐藏子属性
指定工具类型,取值function
指定要使用的函数
显示子属性
隐藏子属性
指定要使用的函数名
- true:开启函数并行调用,默认开启
- false:关闭函数并行调用
安全参数配置
显示子属性
隐藏子属性
文本输入安全等级,默认standrard
- none:完全不经安全过滤模块
- minimal:较宽松等级,不主动过滤,但会对输出结果进行安全校验
- base:宽松等级,仅拦截干预类、攻击涉政、高危涉政涉习内容,其余视为安全
- moderate:在standard基础上去掉涉黄,保留涉政
- standard:默认等级,对涉政、涉黄、暴恐、违禁等内容进行标准拦截
- strict:最严格等级,全面强化敏感内容识别与拦截
图像输入安全等级,默认standrard
- none:完全不经安全过滤模块
- base:宽松等级,仅对高危涉政和黄赌毒做基础管控
- moderate:在standard基础上仅对涉政场景做图审管控
- standard:默认等级,对涉政、涉黄、暴恐、违禁等内容进行标准拦截
- strict:最严格等级,全面强化敏感内容识别与拦截
搜素增强
显示子属性
隐藏子属性
是否开启实时搜索功能,默认关闭
如果关闭实时搜索,角标和溯源信息都不会返回
是否开启上角标返回,默认关闭
开启后,触发搜索增强场景下,响应内容附上角标及对应搜索溯源信息
如果检索内容包含非公开网页,角标不生效
是否返回搜索溯源信息,默认关闭
开启后,触发搜索增强场景下,返回搜索溯源信息
如果检索内容为非公开网页,即使触发搜索也不返回溯源信息。
是否返回搜索信号,默认关闭
开启后,触发搜索时通过delta_tag:search_status表示信号包
参考文章数量,默认由系统内部指定,取值范围:[1, 28]
返回检索网页的数量,默认由系统内部指定,取值范围:[1, 28],不能小于reference_number
指定响应内容的格式
显示子属性
隐藏子属性
指定响应内容的格式
- json_object:以json格式返回
- text:以文本格式返回,默认选项
- json_schema:以json_scheam规定的格式返回
json_schema格式,会校验json格式
当type为json_schema时,必填此项
显示子属性
隐藏子属性
暂无参数
POST /v2/chat/completions HTTP/1.1
Host: qianfan.baidubce.com
Authorization: Bearer <API key>
{
"messages": [
{
"role": "user",
"content": "请用一句话介绍一下千帆的caching接口。"
}
// 可以继续添加新消息
],
"model": "deepseek-v3.1-250821",
"cache_id": "cache-20251105******-etw****xnr", // 使用之前创建的缓存
"stream": false
}
示例代码
curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
--data '{
"messages": [
{
"role": "user",
"content": "请解释一下RESTful API"
}
],
"model": "deepseek-v3.1-250821",
"cache_id": "cache-20251105*****-s9h****djn",
"stream": false,
"temperature": 0.7,
"max_completion_tokens": 500
}'
import requests
def main():
url = "https://qianfan.baidubce.com/v2/chat/completions"
payload_dict= {
"messages": [
{
"role": "system",
"content": "你是一个资深软件工程师,擅长用比喻解释技术概念"
},
{
"role": "user",
"content": "请解释一下RESTful API"
}
],
"model": "deepseek-v3.1-250821",
"cache_id": "cache-20251105*****-s9h****djn",
"stream": false,
"temperature": 0.7,
"max_completion_tokens": 500
}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer bce-v3/ALTAK-*********/614fb**********'
}
response = requests.request("POST", url, headers=headers, json=payload_dict)
print(response.text)
if __name__ == '__main__':
main()
返回响应
一分钟内允许的最大请求次数
一分钟内允许的最大token消耗,包含输入和输出
达到RPM速率限制前,剩余可发送的请求数配额,如果配额用完,将会在0-60s后刷新
达到TPM速率限制前,剩余可消耗的tokens数配额,如果配额用完,将会在0-60s后刷新
本次请求的唯一标识,可用于排查问题
回包类型
chat.completion:多轮对话返回
时间戳
本次请求使用的大模型ID
多选一,只需要符合下列任意一组子节点
响应列表
显示子属性
隐藏子属性
stream=false时,返回该内容,返回类型为choices
显示子属性
隐藏子属性
choice列表中的序号
响应信息
显示子属性
隐藏子属性
- system:人设
- user:用户
- assistant:对话助手
message名
对话内容
输出完成原因标识
- normal:输出内容由大模型生成,未触发截断、替换
- stop:输出结果命中入参stop中指定的字段后被截断
- length:达到token限制
- content_filter:内容安全过滤
- tool_calls:使用function call功能
安全细分类型
- 0或不返回:安全
- 1:低危不安全场景,可以继续对话
- 2:禁聊,不允许继续对话,但可以展示内容
- 3:禁止上屏,不允许继续对话且不能上屏展示
- 4:撤屏
当flag != 0 时,该字段会告知第几轮对话有敏感信息,如果是当前问题,ban_round = -1
透传的插件的信息状态
显示子属性
隐藏子属性
显示子属性
隐藏子属性
暂无参数
透传的插件元信息
显示子属性
隐藏子属性
显示子属性
隐藏子属性
暂无参数
stream=true时的响应列表
显示子属性
隐藏子属性
choice列表中的序号
响应信息
显示子属性
隐藏子属性
仅在流式第一帧返回
流式响应内容
由模型生成的函数调用,包含函数名称,和调用参数
显示子属性
隐藏子属性
显示子属性
隐藏子属性
function call的唯一标识,由模型生成
取值: function
function call的具体内容
显示子属性
隐藏子属性
函数名称
函数参数
响应信息标识
search_status:触发搜索信号
输出完成原因标识
- normal:输出内容由大模型生成,未触发截断、替换
- stop:输出结果命中入参stop中指定的字段后被截断
- length:达到token限制
- content_filter:内容安全过滤
- tool_calls:使用function call功能
返回flag表示触发安全
当flag != 0 时,该字段会告知第几轮对话有敏感信息,如果是当前问题,ban_round = -1
透传的插件的信息状态
显示子属性
隐藏子属性
显示子属性
隐藏子属性
暂无参数
透传的插件元信息
显示子属性
隐藏子属性
显示子属性
隐藏子属性
暂无参数
token统计信息,同步请求默认返回,流式请求默认不返回
当开启stream_options.include_usage=true时,会在最后一个chunk返回实际内容,其他chunk仅返回null
显示子属性
隐藏子属性
问题token数,包含历史问答
问题token详情
显示子属性
隐藏子属性
触发检索增强以后膨胀的token
用户可以通过usage.prompt_tokens_details.search_tokens>0判断是否触发检索增强,并且计算触发检索增强的次数
触发插件以后膨胀的token
显示子属性
隐藏子属性
插件名称
token数
回答token数
总token数
搜索结果列表
显示子属性
隐藏子属性
序号
搜索结果url
搜索结果标题
搜索来源ID
{
"id": "as-s******4yiv",
"object": "chat.completion",
"created": 1762344232,
"model": "deepseek-v3.1-250821",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "就像一位高效又讲究的餐厅服务员。\n\n想象一下你去餐厅点餐:\n- 你不需要知道厨房如何做菜(服务器内部逻辑)\n- 只需按菜单(API文档)点菜(发送请求)\n- 服务员(API)按标准方式处理你的需求\n- 最后给你上菜(返回响应)\n\nRESTful的特点就像优秀服务员的工作原则:\n1. 每道菜都有固定编号(URI统一资源标识)\n2. 你点牛排不会上来一碗面(无状态性)\n3. 点餐、加菜、退菜都有标准流程(HTTP方法:GET/POST/PUT/DELETE)\n4. 不管哪个服务员服务,体验都一样(统一接口)\n\n这样设计的好处是:简单、标准、可扩展,就像标准化服务让餐厅能高效服务更多顾客。"
},
"finish_reason": "stop",
"flag": 0
}
],
"usage": {
"prompt_tokens": 31,
"completion_tokens": 175,
"total_tokens": 206,
"prompt_tokens_details": {
"cached_tokens": 11
}
}
}
错误码
如果请求错误,服务器返回的JSON文本包含以下参数。
| 名称 | 描述 |
|---|---|
| code | 错误码 |
| message | 错误描述信息,帮助理解和解决发生的错误 |
| type | 错误类型 |
更多相关错误码,请查看模型错误码说明。
