天气
更新时间:2024-03-13
功能介绍
本接口用于借助实时天气信息,回答天气相关问题,预报未来天气状况。
注意事项
- 调用天气API前,需先确保已安装天气插件,安装方式请查看插件列表。
-
本文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-weatherforecast"] ,参数示例: "plugins":["uuid-weatherforecast"] (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 | 否 | 聊天上下文信息。 参数示例: [{"role":"user","content":"..."},{"role":"assisant","content":"..."},...] |
verbose | bool | 否 | 是否返回插件的原始请求信息,默认false,可选值如下: true:是,返回插件的原始请求信息meta_info false:否,不返回插件的原始请求信息meta_info |
响应说明
名称 | 类型 | 描述 |
---|---|---|
log_id | number | 唯一的log id,用于问题定位 |
id | string | 本轮对话的id |
object | string | 回包类型。 chat.completion:多轮对话返回 |
created | int | 时间戳 |
sentence_id | int | 表示当前子句的序号,只有在流式接口模式下会返回该字段 |
is_end | bool | 表示当前子句是否是最后一句,只有在流式接口模式下会返回该字段 |
result | string | 请求结果 |
meta_info | 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 (仅为估算逻辑) |
usage说明
名称 | 类型 | 描述 |
---|---|---|
prompt_tokens | int | 问题tokens数 |
completion_tokens | int | 回答tokens数 |
total_tokens | int | tokens总数 |
注意 :同步模式和流式模式,响应参数返回不同,详细内容参考示例描述。
- 同步模式下,响应参数为以上字段的完整json包。
- 流式模式下,各字段的响应参数为 data: {响应参数}。
示例
以访问凭证access_token鉴权方式为例,说明如何调用API,示例如下。
请求示例(非流式)
# 步骤一,获取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": "北京今天天气怎么样","plugins":["uuid-weatherforecast"]}'
-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():
"""
替换下列示例中的申请发布时填写的API名称
"""
url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/plugin/[服务地址后缀名称]/?access_token=" + get_access_token()
payload = json.dumps({
"query": "北京今天天气怎么样",
"plugins":["uuid-weatherforecast"]
})
headers = {
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
if __name__ == '__main__':
main()
响应示例(非流式)
{
"log_id": 46009xxxxxx8777,
"id": "as-m4ntrjmcd7",
"object": "chat.completion",
"created": 1693881770,
"result": "北京当前天气:阴,气温22℃,西南风1级,空气质量优,空气质量指数11,湿度96.0%,气压982.5hPa。",
"meta_info": "",
"is_truncated": false,
"need_clear_history": false,
"usage": {
"prompt_tokens": 237,
"completion_tokens": 8,
"total_tokens": 245
}
}
请求示例(流式)
# 步骤一,获取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": "北京今天天气怎么样","plugins":["uuid-weatherforecast"], "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": "北京今天天气怎么样",
"plugins":["uuid-weatherforecast"],
"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()
响应示例(流式)
{"log_id": 46009xxxxxx8777,'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076948, 'sentence_id': 0, 'is_end': False, 'is_truncated': False, 'result': '北京当前天气:阴,气温22℃,西南风1级,空气质量优,空气质量指数11,',"meta_info": "", 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 65, 'total_tokens': 76}}
{"log_id": 46009xxxxxx8777,'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076950, 'sentence_id': 1, 'is_end': False, 'is_truncated': False, 'result': '湿度96.0%,气压982.5hPa。体感温度:23℃,人体感觉较为舒适。', "meta_info": "",'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 79, 'total_tokens': 155}}
{"log_id": 46009xxxxxx8777,'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076951, 'sentence_id': 2, 'is_end': False, 'is_truncated': False, 'result': '紫外线最弱,落日西沉,无需防护。',"meta_info": "", 'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 65, 'total_tokens': 220}}
{"log_id": 46009xxxxxx8777,'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076954, 'sentence_id': 3, 'is_end': False, 'is_truncated': False, 'result': 'Tips:空气很好,可以外出活动,呼吸新鲜空气。', "meta_info": "",'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 160, 'total_tokens': 380}}
{"log_id": 46009xxxxxx8777,'id': 'as-mubgd52bq6', 'object': 'chat.completion', 'created': 1689076955, 'sentence_id': 4, 'is_end': True, 'is_truncated': False, 'result': '', "meta_info": "",'need_clear_history': False, 'usage': {'prompt_tokens': 11, 'completion_tokens': 0, 'total_tokens': 380}}
错误码
更多千帆大模型平台相关错误码,请查看错误码说明。
错误码 | 错误信息 | 描述 |
---|---|---|
337008 | 插件id输入错误 | 一般指插件id输入错误,如插件id超过3个可能会引起此错误 |
337009 | 请求天气插件失败 | 连接异常,请在百度智能云控制台提交工单咨询 |