域内知识搜索增强插件API调用说明

更新时间：2024-06-26

特别注意

域内知识搜索增强将停止维护，卸载后将下线该插件，请卸载前确认已将知识转移到知识库产品内。

功能介绍

本文介绍了域内知识搜索增强插件API调用相关内容。

请求说明

基本信息

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

请求方式： POST

服务后缀名称说明

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

配置插件应用成功后，查看服务地址、服务后缀名称。

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

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

名称	值
Content-Type	application/json

Query参数

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

Body参数

名称	类型	必填	描述
query	string	是	查询信息。说明：（1）成员不能为空（2）长度不能超过1000个字符
stream	bool	否	是否以流式接口的形式返回数据，默认false，可选值如下：（1）true: 是，以流式接口的形式返回数据（2）false：否，非流式接口形式返回数据
llm	Object	否	llm相关参数，不指定参数时，使用调试过程中的默认值。参数示例：`"llm":{"temperature":0.1,"top_p":1,"penalty_score":1}`
plugins	list[string]	是	需要调用的插件，参数为插件ID，插件ID可在插件列表-插件详情中获取。（1）最多3个插件，最少1个插件。（2）当多个插件时，插件触发由大模型意图判断控制。（3）当只有1个插件时，强制指定使用该插件工具。参数示例：`["...", "..."]`
input_variables	object	否	说明：（1）如果prompt中使用了变量，推理时可以填写具体值；（2）如果prompt中未使用变量，该字段不填。参数示例：`"input_variables"：{"key1":"value1","key2":"value2",}` key1、key2为配置时prompt中使用了变量key
history	object	否	聊天上下文信息。参数示例： `[{"role":"user","content":"..."},{"role":"assistant","content":"..."},...]`
verbose	bool	否	是否返回插件的原始请求信息，默认false，可选值如下： true：是，返回插件的原始请求信息meta_info false：否，不返回插件的原始请求信息meta_info
fileurl	string	否	文件的http地址

响应说明

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

usage说明

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

meta_info说明

名称	类型	描述
plugin_id	string	插件 Id，为“uuid-4c850c5b3b2756e”
request	Object	原始请求参数
response	Object	原始返回结果

request说明

名称	类型	描述
query	string	用于查询用户请求
projectId	Integer	查询项目Id
size	Integer	返回的最相关的文档数
docScore	float	用户查询和文档的相关度下限，低于该下限的文档将不会被返回

response说明

名称	类型	描述
errCode	Integer	错误码
errMsg	string	错误信息
max_score	float	最高相似度分数
timed_out	boolean	是否请求超时
took	float	检索耗时
hits	Object	返回的相关文档结果

hits说明

名称	类型	描述
id	number	返回文档分片的 Id
score	Integer	用户查询和文档的相关度下限
source	Object	文档的 meta 信息

source说明

名称	类型	描述
doc	string	上传文档时原始的yaml格式数据
para	string	文档的实际内容
title	string	文档的名称

注意：同步模式和流式模式，响应参数返回不同，详细内容参考示例描述。

同步模式下，响应参数为以上字段的完整json包。
流式模式下，各字段的响应参数为 data: {响应参数}。

示例

# 步骤一，获取access_token，替换下列示例中的API Key与Secret Key
curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[API Key]&client_secret=[Secret Key]'

# 步骤二，调用本文API，使用步骤一获取的access_token，替换下列示例中的“调用接口获取的access_token”
curl 'https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/[服务后缀名称]/?access_token=[步骤一调用接口获取的access_token]' 
    --data '{"query": "怎么申请access_token","verbose":true}'
    -H 'Content-Type: application/json'

import requests
import json

def get_access_token():
    """
    使用 API Key，Secret Key 获取access_token，替换下列示例中的应用API Key、应用Secret Key
    """
        
    url = "https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[应用API Key]&client_secret=[应用Secret Key]"
    
    payload = json.dumps("")
    headers = {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    }
    
    response = requests.request("POST", url, headers=headers, data=payload)
    return response.json().get("access_token")


def main():
        
    url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/[服务后缀名称]/?access_token=" + get_access_token()
    
    payload = json.dumps({
        "query": "怎么申请access_token",
        "verbose":true
    })
    headers = {
        'Content-Type': 'application/json'
    }
    
    response = requests.request("POST", url, headers=headers, data=payload)
    
    for line in response.iter_lines():
        print(line)
    

if __name__ == '__main__':
    main()

响应示例（非流式）

JSON

{
  "id": "as-5cy0kntgcm",
  "object": "chat.completion",
  "created": 1693215318,
  "result": "您好，要申请access_token，您需要按照以下步骤进行操作：\n\n1. 根据您的API Key和Secret Key，通过发送HTTP请求获取access_token。请求的URL为：https://aip.baidubce.com/oauth/2.0/token。\n2. 在发送的HTTP请求中，需要设置参数grant_type为client_credentials，client_id为您的API Key，client_secret为您的Secret Key。\n\n请参考以下示例代码（使用bash或Python）：\n\n\n```bash\ncurl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[API Key]&client_secret=[Secret Key]'\n```\n或\n\n\n```python\nimport requests\nimport json\n\ndef main():\n    url = \"https://aip.baidubce.com/oauth/2.0/token?client_id=[API Key]&client_secret=[Secret Key]&grant_type=client_credentials\"\n    payload = json.dumps(\"\")\n    # 发送HTTP请求并获取access_token\n    response = requests.post(url, data=payload)\n    access_token = response.json().get(\"access_token\")\n    print(access_token)\n```\n请将上述代码中的[API Key]和[Secret Key]替换为您自己的API Key和Secret Key。执行该代码后，您将获得access_token。\n\n请注意，access_token的默认有效期为30天。在生产环境中，请注意及时刷新access_token。",
  "is_truncated": false,
  "need_clear_history": false,
  "usage": {
    "prompt_tokens": 623,
    "completion_tokens": 288,
    "total_tokens": 911
  },
  "log_id": 6929159425717336068,
  "meta_info": {
  "plugin_id": "uuid-baizhong",
  "request": {
    "query": "怎么申请access_token",
    "projectId": 1381,
    "size": 5,
    "docScore": 0
  },
  "response": {
    "errCode": 0,
    "errMsg": "",
    "hits": [
      {
        "_id": "dd4d610d-3820-11ee-9705-0f32403c03c4",
        "_score": 0.18907088041305542,
        "_source": {
          "doc": "{\"url\": \"https://cloud.baidu.com/doc/WENXINWORKSHOP/s/flfmc9do2\", \"urlTitle\": \"API调用指南\", \"title\": \"API鉴权及调用-API调用指南-API 调用流程-步骤三. 获取访问凭证\", \"content_se\": \"根据步骤一获取的API Key、Secret Key，获取access_token。参考以下获取access_token，更多详情方法请参考 鉴权认证机制 。\\n注意：access_token默认有效期30天，生产环境注意及时刷新。\\nbash Python # 填充API Key与Secret Key curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【API Key】&client_secret=【Secret Key】' # 填充API Key与Secret Key import requests import json def main ( ) : url = \\\"https://aip.baidubce.com/oauth/2.0/token?client_id=【API Key】&client_secret=【Secret Key】&grant_type=client_credentials\\\" payload = json . dumps ( \\\"\\\" ) headers = { 'Content-Type' : 'application/json' , 'Accept' : 'application/json' } response = requests\", \"extraIndex\": \"\", \"_id\": \"dd4d610d-3820-11ee-9705-0f32403c03c4\"}",
          "para": "根据步骤一获取的API Key、Secret Key，获取access_token。参考以下获取access_token，更多详情方法请参考 鉴权认证机制 。 注意：access_token默认有效期30天，生产环境注意及时刷新。 bash Python # 填充API Key与Secret Key curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【API Key】&client_secret=【Secret Key】' # 填充API Key与Secret Key import requests import json def main ( ) : url = \"https://aip.baidubce.com/oauth/2.0/token?client_id=【API Key】&client_secret=【Secret Key】&grant_type=client_credentials\" payload = json . dumps ( \"\" ) he",
          "title": "API调用指南"
        }
      }
    ],
    "max_score": 0.18907088041305542,
    "timed_out": "false",
    "took": 33.59
  },
  "log_id": 463273232321288767
}
}

请求示例（流式）

bash
Python

# 步骤一，获取access_token，替换下列示例中的API Key与Secret Key
curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[API Key]&client_secret=[Secret Key]'

# 步骤二，调用本文API，使用步骤一获取的access_token，替换下列示例中的“调用接口获取的access_token”
curl 'https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/[服务后缀名称]/?access_token=[步骤一调用接口获取的access_token]' 
    --data '{"query": "怎么申请access_token","verbose":true,"stream": true}'
    -H 'Content-Type: application/json'

import requests
import json

def get_access_token():
    """
    使用 API Key，Secret Key 获取access_token，替换下列示例中的应用API Key、应用Secret Key
    """
        
    url = "https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[应用API Key]&client_secret=[应用Secret Key]"
    
    payload = json.dumps("")
    headers = {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    }
    
    response = requests.request("POST", url, headers=headers, data=payload)
    return response.json().get("access_token")


def main():
        
    url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/[服务后缀名称]/?access_token=" + get_access_token()
    
    payload = json.dumps({
        "query": "怎么申请access_token",
        "verbose":true,
        "stream": true
    })
    headers = {
        'Content-Type': 'application/json'
    }
    
    response = requests.request("POST", url, headers=headers, data=payload, stream=True)
    
    for line in response.iter_lines():
        print(line)
    

if __name__ == '__main__':
    main()

响应示例（流式）

# 首包需要的回显信息
{"plugin_id":"uuid-baizhong","request":{"query":"怎么申请access_token","projectId":1381,"size":5,"docScore":0},"response":{"errCode":0,"errMsg":"","hits":[{"_id":"dd4d610d-3820-11ee-9705-0f32403c03c4","_score":0.18907088041305542,"_source":{"doc":"{\"url\": \"https://cloud.baidu.com/doc/WENXINWORKSHOP/s/flfmc9do2\", \"urlTitle\": \"API调用指南\", \"title\": \"API鉴权及调用-API调用指南-API 调用流程-步骤三. 获取访问凭证\", \"content_se\": \"根据步骤一获取的API Key、Secret Key，获取access_token。参考以下获取access_token，更多详情方法请参考 鉴权认证机制 。\\n注意：access_token默认有效期30天，生产环境注意及时刷新。\\nbash Python # 填充API Key与Secret Key curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【API Key】&client_secret=【Secret Key】' # 填充API Key与Secret Key import requests import json def main ( ) : url = \\\"https://aip.baidubce.com/oauth/2.0/token?client_id=【API Key】&client_secret=【Secret Key】&grant_type=client_credentials\\\" payload = json . dumps ( \\\"\\\" ) headers = { 'Content-Type' : 'application/json' , 'Accept' : 'application/json' } response = requests\", \"extraIndex\": \"\", \"_id\": \"dd4d610d-3820-11ee-9705-0f32403c03c4\"}","para":"根据步骤一获取的API Key、Secret Key，获取access_token。参考以下获取access_token，更多详情方法请参考 鉴权认证机制 。 注意：access_token默认有效期30天，生产环境注意及时刷新。 bash Python # 填充API Key与Secret Key curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【API Key】&client_secret=【Secret Key】' # 填充API Key与Secret Key import requests import json def main ( ) : url = \"https://aip.baidubce.com/oauth/2.0/token?client_id=【API Key】&client_secret=【Secret Key】&grant_type=client_credentials\" payload = json . dumps ( \"\" ) he","title":"API调用指南"}},{"_id":"dde5746a-3820-11ee-8aa3-0f32403c03c4","_score":0.08064311742782593,"_source":{"doc":"{\"url\": \"https://cloud.baidu.com/doc/WENXINWORKSHOP/s/jlil56u11\", \"urlTitle\": \"ERNIE-Bot\", \"title\": \"API鉴权及调用-API文档-ERNIE-Bot-创建chat-示例-请求示例（多轮）\", \"content_se\": \"bash Python # 步骤一，获取access_token，替换下列示例中的API Key与Secret Key curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[API Key]&client_secret=[Secret Key]' # 步骤二，调用本文API，使用步骤一获取的access_token，替换下列示例中的”调用接口获取的access_token“ curl -XPOST 'https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions?access_token=[步骤一调用接口获取的access_token]' -d '{ \\\"messages\\\": [ {\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"请介绍一下你自己\\\"}, {\\\"role\\\":\\\"assistant\\\",\\\"content\\\":\\\"我是百度公司开发的人工智能语言模型，我的中文名是文心一言，英文名是ERNIE-Bot，可以协助您完成范围广泛的任务并提供有关各种主题的信息，比如回答问题，提供定义和解释及建议。如果您有任何问题，请随时向我提问。\\\"}, {\\\"role\\\":\\\"user\\\",\\\"conten\", \"extraIndex\": \"\", \"_id\": \"dde5746a-3820-11ee-8aa3-0f32403c03c4\"}","para":"bash Python # 步骤一，获取access_token，替换下列示例中的API Key与Secret Key curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[API Key]&client_secret=[Secret Key]' # 步骤二，调用本文API，使用步骤一获取的access_token，替换下列示例中的”调用接口获取的access_token“ curl -XPOST 'https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions?access_token=[步骤一调用接口获取的access_token]' -d '{ \"messages\": [ {\"role\":\"user\",\"content\":\"请介绍一下你自己\"}, {\"role\":\"assistant\",\"content\":\"我是百度公司开发的人工智能语言模型，我的中文名是文心一言，英文","title":"ERNIE-Bot"}},{"_id":"df03dd45-3820-11ee-8cf9-0f32403c03c4","_score":0.03897285461425781,"_source":{"doc":"{\"url\": \"https://cloud.baidu.com/doc/WENXINWORKSHOP/s/4lilb2lpf\", \"urlTitle\": \"ERNIE-Bot-turbo\", \"title\": \"API鉴权及调用-API文档-ERNIE-Bot-turbo-创建chat-示例-请求示例（多轮）\", \"content_se\": \"bash Python # 步骤一，获取access_token，替换下列示例中的API Key与Secret Key curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[API Key]&client_secret=[Secret Key]' # 步骤二，调用本文API，使用步骤一获取的access_token，替换下列示例中的”调用接口获取的access_token“ curl -XPOST 'https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/eb-instant?access_token=[步骤一调用接口获取的access_token]' -d '{ \\\"messages\\\": [ {\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"请介绍一下你自己\\\"}, {\\\"role\\\":\\\"assistant\\\",\\\"content\\\":\\\"我是百度公司开发的人工智能语言模型，我的中文名是文心一言，英文名是ERNIE Bot，可以协助您完成范围广泛的任务并提供有关各种主题的信息，比如回答问题，提供定义和解释及建议。如果您有任何问题，请随时向我提问。\\\"}, {\\\"role\\\":\\\"user\\\",\\\"content\", \"extraIndex\": \"\", \"_id\": \"df03dd45-3820-11ee-8cf9-0f32403c03c4\"}","para":"bash Python # 步骤一，获取access_token，替换下列示例中的API Key与Secret Key curl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[API Key]&client_secret=[Secret Key]' # 步骤二，调用本文API，使用步骤一获取的access_token，替换下列示例中的”调用接口获取的access_token“ curl -XPOST 'https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/eb-instant?access_token=[步骤一调用接口获取的access_token]' -d '{ \"messages\": [ {\"role\":\"user\",\"content\":\"请介绍一下你自己\"}, {\"role\":\"assistant\",\"content\":\"我是百度公司开发的人工智能语言模型，我的中文名是文心一言，英文名","title":"ERNIE-Bot-turbo"}}],"max_score":0.18907088041305542,"timed_out":"false","took":34.08},"log_id":6544712196324357405}
# 后续为用户请求的响应结果
{'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076948, 'sentence_id': 0, 'is_end': False, 'is_truncated': False, 'result': '您好，要申请access_token，您需要按照以下步骤进行操作：', 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 65, 'total_tokens': 76}}
{'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076950, 'sentence_id': 1, 'is_end': False, 'is_truncated': False, 'result': '\n\n1. 根据您的API Key和Secret Key，通过发送HTTP请求获取access_token。', 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 79, 'total_tokens': 155}}
{'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076951, 'sentence_id': 2, 'is_end': False, 'is_truncated': False, 'result': '请求的URL为：https://aip.baidubce.com/oauth/2.0/token。\n2. 在发送的HTTP请求中，需要设置参数grant_type为client_credentials，client_id为您的API Key，client_secret为您的Secret Key。', 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 65, 'total_tokens': 220}}
{'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076954, 'sentence_id': 3, 'is_end': False, 'is_truncated': False, 'result': '\n\n请参考以下示例代码（使用bash或Python）：\n\n\n```bash\ncurl 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=[API Key]&client_secret=[Secret Key]'\n', 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 160, 'total_tokens': 380}}
{'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076955, 'sentence_id': 4, 'is_end': False, 'is_truncated': False, 'result': '```\n或\n\n\n```python\nimport requests\nimport json\n\ndef main():\n    url = \"https://aip.baidubce.com/oauth/2.0/token?client_id=[API Key]&client_secret=[Secret Key]&grant_type=client_credentials\"\n    payload = json.dumps(\"\")\n    ', 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 0, 'total_tokens': 380}}
{'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076955, 'sentence_id': 4, 'is_end': False, 'is_truncated': False, 'result': '# 发送HTTP请求并获取access_token\n    response = requests.post(url, data=payload)\n    access_token = response.json().get(\"access_token\")\n    print(access_token)\n```\n请将上述代码中的[API Key]和[Secret Key]替换为您自己的API Key和Secret Key。执行该代码后，您将获得access_token。', 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 0, 'total_tokens': 380}}
{'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076955, 'sentence_id': 4, 'is_end': False, 'is_truncated': False, 'result': '\n\n请注意，access_token的默认有效期为30天。在生产环境中，请注意及时刷新access_token。', 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 0, 'total_tokens': 380}}
{'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076955, 'sentence_id': 4, 'is_end': True, 'is_truncated': False, 'result': '', 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 0, 'total_tokens': 380}}

错误码

错误码	错误信息	描述
337006	缺少必要参数	· 未找到llm相关参数->插件应用模型AK/SK无效，无法获取access_token · 未找到工具相关参数->缺少插件相关参数或参数配置不正确
337009	请求失败：{error_code}，{error_msg}	用户请求触发错误，错误详情请参考错误码error_code、错误信息error_msg

百度智能云

千帆大模型服务与开发平台ModelBuilder