天气搜索（Weather Search）

天气搜索是蜀农 API 提供的实时天气查询工具，能查询中国大陆城市的实时天气或未来 7 日天气预报（如气温、降水、风力、湿度等）。

核心能力

能力	说明
实时天气	获取指定城市的当前天气与实时气温、风力、湿度等信息
未来 7 日预报	支持查询未来 7 日天气预报
城市编码	支持城市名（如"成都"）或 9 位天气网城市编码
多工具混合调用	可与自定义 Function、知识库检索等工具协同使用，模型自动判断调用优先级与必要性
响应模式灵活	支持流式和非流式响应，两种方式都会返回天气与总结内容

前提条件

确保账号已开通天气搜索服务。
准备 API Key，参考获取 API Key 与鉴权。
天气搜索产生的费用按计费说明执行。

API 示例

Python 示例（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SHUNONG_API_KEY"],
    base_url="https://ai.agriwis.com/api/v1",
)

completion = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "武汉明天天气怎么样？"}
    ],
    tools=[
        {
            "type": "agriwis_weather_search",
            "location": "武汉",
            "date": "forecast",
            "unit": "celsius",
        }
    ],
    tool_choice="auto",
)

print(completion.model_dump_json())

curl 示例

curl https://ai.agriwis.com/api/v1/chat/completions \
  -H "Authorization: Bearer $SHUNONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "武汉明天天气怎么样？"}
    ],
    "tools": [
      {
        "type": "agriwis_weather_search",
        "location": "武汉",
        "date": "forecast",
        "unit": "celsius"
      }
    ],
    "tool_choice": "auto"
  }'

请求参数

agriwis_weather_search 工具参数

参数	类型	说明
`type`	string	固定为 `"agriwis_weather_search"`
`location`	string	必填。城市名（如 `成都`）或 9 位天气网城市编码
`date`	string	可选。`now`=实时天气（默认），`forecast`=未来 7 日预报
`unit`	string	可选。温度单位，`celsius`（默认）或 `fahrenheit`

tools、tool_choice 等通用参数说明参见 Chat Completions 与工具调用。

响应格式

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "auto",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "武汉明天（2026年8月20日，周四）白天多云转阴，最高气温 34℃，最低气温 27℃，南风 2-3 级，空气湿度 78%。建议外出携带遮阳伞，注意防暑补水。",
        "annotations": [
          {
            "type": "weather_citation",
            "provider": "example-weather",
            "location": "武汉",
            "date": "2026-08-20",
            "summary": "多云转阴，最高 34°C，最低 27°C，南风 2-3 级",
            "updated_at": "2026-08-19T18:00:00+08:00"
          }
        ],
        "tool_calls": null
      }
    }
  ],
  "usage": {
    "prompt_tokens": 900,
    "completion_tokens": 150,
    "total_tokens": 1050,
    "agriwis_weather_search_usage": {
      "tool_usage": 1
    }
  }
}

响应字段说明

字段	说明
`choices[].message.content`	模型基于天气数据的总结回答
`choices[].message.annotations`	天气数据来源标注数组，`type` 为 `weather_citation`，包含 `provider`、`location`、`date`、`summary`、`updated_at`
`choices[].message.tool_calls`	工具调用信息，纯天气查询场景下通常为 `null`
`usage.agriwis_weather_search_usage.tool_usage`	天气搜索工具使用次数
`finish_reason`	生成结束原因，如 `stop`

计费说明

天气搜索的费用由两部分组成：

查询服务使用次数：按每次天气查询调用计费。
模型 Token 消耗：天气数据会拼接到提示词中，增加输入 Token，按模型标准价格计费。

具体价格与可用额度以控制台展示为准，参见计费说明。

常见问题

天气搜索与知识库检索有什么区别？

天气搜索获取的是实时天气数据，适合气温、降水、风力等时效性查询。
知识库检索面向的是平台农业知识库，适合种植、植保等专业知识问答。
两者可同时声明，由模型根据问题类型选择调用。

返回的天气与当地实际情况不符？

可能的原因：

地理位置不准确：location 缺失或错误时，可能匹配到邻近地区的数据，建议显式指定城市名或 9 位天气网城市编码。
数据时效：天气数据为最近一次更新的结果，极端天气下可能滞后，请以气象部门最新发布为准。
预报偏差：多日预报存在不确定性，临近日期的预报更可靠。

可以结合农事场景使用吗？

可以。可将天气搜索与生长周期识别、知识库检索等工具结合使用，例如根据作物生长阶段与天气预报给出灌溉、施肥、打药等农事建议。