天气
更新时间：2024-09-20
注意：插件应用相关功能已于2024年7月31日迁移至AppBuilder，如有需要请查看AppBulier。本文内容不再更新，且于2024年7月19日下线。
功能介绍
本接口用于借助实时天气信息，回答天气相关问题，预报未来天气状况。
注意事项
调用天气API前，需先确保已安装天气插件，安装方式请查看插件列表。
SDK调用
SDK支持使用平台插件能力，以帮助用户快速构建 LLM 应用或将 LLM 应用到自建程序中。在使用这一功能前需要先创建应用、设定服务地址、将服务地址作为参数传入千帆 SDK。该插件可以实现OCR能力。
使用说明
调用本文API，需使用应用AK/SK鉴权，调用流程及鉴权介绍详见SDK安装及使用流程。
调用示例（非流式）
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-weatherforecast"], query="北京今天天气如何？")
print(resp)返回示例（非流式）
QfResponse(code = 200, headers = {
...
},
body = {
'id': 'as-wdzd39c76f',
'object': 'chat.completion',
'created': 1698131719,
'result': '今天是2023-10-24，北京天气：晴，9~23℃，无持续风向<3级，空气质量轻度，空气质量指数163。',
'is_truncated': False,
'need_clear_history': False,
'usage': {
'prompt_tokens': 1116,
'completion_tokens': 33,
'total_tokens': 1149
},
'log_id': xxx
}, image = None)调用示例（流式）
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-weatherforecast"], stream=True, query="北京今天气温如何？")
for r in resp:
print(r)返回示例（流式）
QfResponse(code=200, headers={...},
body={'id': 'as-82rib6qfnz', 'object': 'chat.completion', 'created': 1698231214, 'sentence_id': 0, 'is_end': False, 'is_truncated': False, 'result': '今天是2023', 'need_clear_history': False, 'usage': {'prompt_tokens': 1105, 'completion_tokens': 4, 'total_tokens': 1109}, 'log_id': 6594110414596782517}, image=None)
QfResponse(code=200, headers={...},
body={'id': 'as-82rib6qfnz', 'object': 'chat.completion', 'created': 1698231215, 'sentence_id': 1, 'is_end': True, 'is_truncated': False, 'result': '-10-25，北京气温：10~25℃。', 'need_clear_history': False, 'usage': {'prompt_tokens': 1105, 'completion_tokens': 7, 'total_tokens': 1116}, 'log_id': 6594110414596782517}, 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-weatherforecast"] （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）如果query中使用了变量，推理时可以填写具体值； （2）如果query中未使用变量，该字段不填。 参数示例： "input_variables"：{"key1":"value1","key2":"value2",} key1、key2为配置时query中使用了变量key |
| history | dict | 否 | 聊天上下文信息。 参数示例： [{"role":"user","content":"..."},{"role":"assistant","content":"..."},...] |
| verbose | bool | 否 | 是否返回插件的原始请求信息，默认false，可选值如下： true：是，返回插件的原始请求信息meta_info false：否，不返回插件的原始请求信息meta_info |
返回参数
| 名称 | 类型 | 描述 |
|---|---|---|
| log_id | int | 唯一的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 | dict | token统计信息，token数 = 汉字数+单词数*1.3 （仅为估算逻辑） |
usage说明
| 名称 | 类型 | 描述 |
|---|---|---|
| prompt_tokens | int | 问题tokens数 |
| completion_tokens | int | 回答tokens数 |
| total_tokens | int | tokens总数 |
注意： 同步模式和流式模式，响应参数返回不同，详细内容参考示例描述。
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-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":"assistant","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 | 请求天气插件失败 | 连接异常，请在百度智能云控制台提交工单咨询 |