知识库

更新时间：2024-09-20

注意：插件应用相关功能已于2024年7月31日迁移至AppBuilder，如有需要请查看AppBulier。本文内容不再更新，且于2024年7月19日下线。

功能介绍

本接口用于使用知识库中存储的相关内容进行问答增强。

注意事项

调用知识库API前，需先确保已安装知识库插件，安装方式请查看插件列表。

SDK调用

SDK支持使用平台插件能力，以帮助用户快速构建 LLM 应用或将 LLM 应用到自建程序中。

使用说明

调用本文API，需使用安全认证AK/SK鉴权，调用流程及鉴权介绍详见SDK安装及使用流程。

调用示例（非流式）

Python

import os
import qianfan

# 使用安全认证AK/SK鉴权，通过环境变量方式初始化；替换下列示例中参数，安全认证Access Key替换your_iam_ak，Secret Key替换your_iam_sk
os.environ["QIANFAN_ACCESS_KEY"] = "your_iam_ak"
os.environ["QIANFAN_SECRET_KEY"] = "your_iam_sk"

# Plugin 通过endpoint参数指定插件服务，将your_endpoint替换为服务地址后缀，例如服务地址为https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/testxxx/，则your_endpoint替换为testxxx，更多介绍详见本文插件服务地址说明
plugin = qianfan.Plugin(endpoint="your_endpoint")

# 知识库展示
resp = plugin.do(plugins=["uuid-zhishiku"], query="深度合成服务提供者应当设置哪些入口")
print(resp)

返回示例（非流式）

Python

QfResponse(
    code=200,
    headers={
        ...
    }, 
    body={
        'id': 'as-981vhw8jgi', 
        'object': 'chat.completion', 
        'created': 1698058648, 
        'result': '深度合成服务提供者应当设置便捷的用户申诉和公众投诉、举报入口，公布处理流程和反馈时限，及时受理、处理和反馈处理结果。', 
        'is_truncated': False, 
        'need_clear_history': False, 
        'usage': {'prompt_tokens': 1673, 'completion_tokens': 53, 'total_tokens': 1726}, 
        'log_id': 539802381612933814}, 
        image=None)

调用示例（流式）

Python

import os
import qianfan

# 使用安全认证AK/SK鉴权，通过环境变量方式初始化；替换下列示例中参数，安全认证Access Key替换your_iam_ak，Secret Key替换your_iam_sk
os.environ["QIANFAN_ACCESS_KEY"] = "your_iam_ak"
os.environ["QIANFAN_SECRET_KEY"] = "your_iam_sk"

# Plugin 通过endpoint参数指定插件服务，将your_endpoint替换为服务地址后缀，例如服务地址为https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/testxxx/，则your_endpoint替换为testxxx，更多介绍详见本文插件服务地址说明
plugin = qianfan.Plugin(endpoint="your_endpoint")

# 流式调用
resp = plugin.do(endpoint="your_custom_endpoint", query="政策上规定深度合成服务提供者应当设置哪些内容？", stream=True)
for r in resp:
    print(r["result"])

返回示例（流式）

Python

QfResponse(code=200, headers={...}, 
body={'id': 'as-amnf7c3hg9', 'object': 'chat.completion', 'created': 1698230717, 'sentence_id': 0, 'is_end': False, 'is_truncated': False, 'result': '政策上规定深度合成', 'need_clear_history': False, 'usage': {'prompt_tokens': 1335, 'completion_tokens': 9, 'total_tokens': 1344}, 'log_id': 4287202150558504277}, image=None)

QfResponse(code=200, headers={...}, 
body={'id': 'as-amnf7c3hg9', 'object': 'chat.completion', 'created': 1698230718, 'sentence_id': 1, 'is_end': False, 'is_truncated': False, 'result': '服务提供者应当设置显著标识功能，并提示使用者深度合成情况。', 'need_clear_history': False, 'usage': {'prompt_tokens': 1335, 'completion_tokens': 27, 'total_tokens': 1371}, 'log_id': 4287202150558504277}, image=None)

QfResponse(code=200, headers={...}, 
body={'id': 'as-amnf7c3hg9', 'object': 'chat.completion', 'created': 1698230719, 'sentence_id': 2, 'is_end': True, 'is_truncated': False, 'result': '', 'need_clear_history': False, 'usage': {'prompt_tokens': 1335, 'completion_tokens': 0, 'total_tokens': 1371}, 'log_id': 4287202150558504277}, image=None)

插件服务地址说明

调用插件SDK时，需通过endpoint指定插件服务，endpoint值可以通过插件服务地址获取。

（1）配置插件应用服务成功后，可以查看服务地址等信息。如何配置插件应用服务，详见插件编排使用说明。

说明：只有服务状态为上线状态，才可以查看自动生成的服务地址。

（2）在千帆ModelBuilder控制台-系统配置-插件编排页面，点击某插件服务详情。

（3）在插件的详情页中，查看完整的服务地址。

（4）获取endpoint值。

例如，插件服务地址为https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/testxxx/，则endpoint值为testxxx。

请求参数

名称	类型	必填	描述
query	string	是	查询信息。说明：（1）成员不能为空（2）长度不能超过1000个字符
plugins	list[string]	否	需要调用的插件ID列表，说明：（1）如果使用知识库插件，该字段必填，且为固定值"uuid-zhishiku" （2）如果不填写该字段，是在插件编排时配置范围内进行意图识别，使用模型进行回答
stream	bool	否	是否以流式接口的形式返回数据，默认false，可选值如下：（1）true: 是，以流式接口的形式返回数据（2）false：否，非流式接口形式返回数据
llm	dict	否	llm相关参数，不指定参数时，使用调试过程中的默认值。参数示例：`"llm":{"temperature":0.1,"top_p":1,"penalty_score":1}`
input_variables	dict	否	说明：（1）如果prompt中使用了变量，推理时可以填写具体值；（2）如果prompt中未使用变量，该字段不填。参数示例：`"input_variables"：{"key1":"value1","key2":"value2"}` key1、key2为配置时prompt中使用了变量key
history	dict	否	聊天上下文信息。说明：（1）history可以为空（2）非空情况下数目必须为偶数，奇数位history的role值必须为user，偶数位history的role值为assistant。参数示例：[{"role":"user","content":"..."},{"role":"assistant","content":"..."},...]
verbose	bool	否	是否返回插件的原始请求信息，默认false，可选值如下： true：是，返回插件的原始请求信息meta_info false：否，不返回插件的原始请求信息meta_info

llm说明

名称	类型	必填	描述
temperature	float	否	说明：（1）较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定（2）范围 (0, 1.0]，不能为0
top_p	float	否	说明：（1）影响输出文本的多样性，取值越大，生成文本的多样性越强（2）取值范围 [0, 1.0]
penalty_score	float	否	通过对已生成的token增加惩罚，减少重复生成的现象。说明：（1）值越大表示惩罚越大（2）取值范围：[1.0, 2.0]

history说明

名称	类型	描述
role	string	当前支持以下： · user: 表示用户 · assistant: 表示对话助手
content	string	对话内容，不能为空

返回参数

名称	类型	描述
log_id	int	唯一的log id，用于问题定位
id	string	本轮对话的id
object	string	回包类型。 chat.completion：多轮对话返回
created	int	时间戳
sentence_id	int	表示当前子句的序号，只有在流式接口模式下会返回该字段
is_end	bool	表示当前子句是否是最后一句，只有在流式接口模式下会返回该字段
result	string	插件返回结果
is_truncated	bool	当前生成的结果是否被截断
need_clear_history	bool	表示用户输入是否存在安全，是否关闭当前会话，清理历史会话信息 true：是，表示用户输入存在安全风险，建议关闭当前会话，清理历史会话信息 false：否，表示用户输入无安全风险
ban_round	int	当need_clear_history为true时，此字段会告知第几轮对话有敏感信息，如果是当前问题，ban_round = -1
usage	usage	token统计信息，token数 = 汉字数+单词数*1.3 （仅为估算逻辑）
meta_info	dict	插件的原始请求信息

usage说明

名称	类型	描述
prompt_tokens	int	问题tokens数
completion_tokens	int	回答tokens数
total_tokens	int	tokens总数

meta_info说明

名称	类型	描述
plugin_id	string	插件Id，固定值为"uuid-zhishiku"
request	dict	知识库原始请求参数
response	dict	知识库原始返回结果

request说明

名称	类型	描述
query	string	用于查询知识库的用户请求
kbIds	list[Any]	使用知识库的 Id 列表
score	float	分片和query的相似度分数的下限，低于该下限的文档分片不会被返回
topN	int	返回的最相关的文档数

response说明

名称	类型	描述
retCode	int	错误码
message	string	错误信息
result	dict	返回结果

result说明

名称	类型	描述
besQueryCostMilsec3	int	bes查询耗时
dbQueryCostMilsec1	int	db查询耗时
embeddedCostMilsec2	int	embedding查询耗时
responses	dict	知识库返回的最相关文档信息
urlSignedCostMilsec4	int	bos url生成耗时

responses说明

名称	类型	描述
contentUrl	string	文档分片的下载地址
docId	string	文档 Id
docName	string	文档的名称
kbId	string	文档上传的知识库 Id
score	float	当前分片和用户请求的相关度，取值范围（0-1）
shardId	string	分片 ID
shardIndex	int	分片序号
content	string	分片的实际内容

HTTP调用

鉴权说明

本文API，支持2种鉴权方式。不同鉴权方式，调用方式不同，使用Header、Query参数不同，详见本文请求说明。开发者可以选择以下任一种方式进行鉴权。

请求说明

基本信息

请求地址： https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/{服务地址后缀名称}/

请求方式： POST

服务地址说明

配置插件应用服务成功后，可以查看服务地址等信息。如何配置插件应用服务，详见插件编排使用说明。

说明：只有服务状态为上线状态，才可以查看自动生成的服务地址。

在插件的详情页中，查看完整的服务地址。

Header参数

根据不同鉴权方式，查看对应Header参数。

访问凭证access_token鉴权

名称	类型	必填	描述
Content-Type	string	是	固定值application/json

基于安全认证AK/SK进行签名计算鉴权

名称	类型	必填	描述
Content-Type	string	是	固定值application/json
x-bce-date	string	否	当前时间，遵循ISO8601规范，格式如2016-04-06T08:23:49Z
Authorization	string	是	用于验证请求合法性的认证信息，更多内容请参考鉴权认证机制，签名工具可参考IAM签名工具

Query参数

只有访问凭证access_token鉴权方式，需使用Query参数。

访问凭证access_token鉴权

名称	类型	必填	描述
access_token	string	是	通过API Key和Secret Key获取的access_token，参考Access Token获取

Body参数

名称	类型	必填	描述
query	string	是	查询信息。说明：（1）成员不能为空（2）长度不能超过1000个字符
plugins	list[string]	否	需要调用的插件ID列表，说明：（1）如果使用知识库插件，该字段必填，且固定值为["uuid-zhishiku"]，参数示例："plugins":["uuid-zhishiku"] （2）如果不填写该字段，是在插件编排时配置范围内进行意图识别，使用模型进行回答
stream	bool	否	是否以流式接口的形式返回数据，默认false，可选值如下：（1）true: 是，以流式接口的形式返回数据（2）false：否，非流式接口形式返回数据
llm	object	否	llm相关参数，不指定参数时，使用调试过程中的默认值。参数示例：`"llm":{"temperature":0.1,"top_p":1,"penalty_score":1}`
input_variables	object	否	说明：（1）如果prompt中使用了变量，推理时可以填写具体值；（2）如果prompt中未使用变量，该字段不填。参数示例：`"input_variables"：{"key1":"value1","key2":"value2"}` key1、key2为配置时prompt中使用了变量key
history	object	否	聊天上下文信息。说明：（1）history可以为空（2）非空情况下数目必须为偶数，奇数位history的role值必须为user，偶数位history的role值为assistant。参数示例： `[{"role":"user","content":"..."},{"role":"assistant","content":"..."},...]`
verbose	bool	否	是否返回插件的原始请求信息，默认false，可选值如下： true：是，返回插件的原始请求信息meta_info false：否，不返回插件的原始请求信息meta_info