# 高德天气预报查询插件的集成与编写

# 01. 高德城市与天气预报接口

高德 Web 服务 API 向开发者提供了大量的 HTTP 接口，涵盖了：地理/逆地理编码、路径规划、行政区域查询、IP定位、天气查询、坐标转换、轨迹纠偏等接口，并且向开发者提供了足量的调用额度，用于开发/调试各类地图类型的应用（商用需付费）。

高德 Web 服务 API 链接： https://lbs.amap.com/api/webservice/summary
高德开放平台控制台： https://console.amap.com/dev/index

在 LLMOps 项目中，我们会集成一个根据城市查询天气预报的自定义工具，所以可以考虑使用高德提供的服务，在使用之前，必须实名认证高德开放平台，并且创建应用，获取好对应的秘钥，并将其配置到环境变量中，例如：

GAODE_API_KEY=00b0****e6e7

在高德提供的服务中，天气预报查询接口必须传递城市编码才可以获取对应城市的信息（天气预报），接口如下：

https://restapi.amap.com/v3/weather/weatherInfo?city=<城市编码>&key=<用户key>

例如 110101 代表北京，所以需要一个额外的接口来根据传入的城市名获取到相应的城市编码（行政区域查询），接口如下：

https://restapi.amap.com/v3/config/district?keywords=<城市名>&subdistrict=0&key=<用户的key>

所以要完成一个输入城市名查询天气预报的函数/工具，必须先调用行政区域查询将城市转换为城市编码，然后在利用城市编码调用天气预报接口，从而完成整个流程，如下：

图片描述

# 02. 天气预报查询工具实现

由于该接口并没有已经实现好的任何代码，所以可以考虑使用 BaseTool子类的形式来实现，即工具接收一个参数 city 表示需要查询天气预报的城市名，然后调用行政区域查询接口获取该城市对应的行政编码，接下来将行政编码传递给天气预报接口，获取最终天气信息。

示例代码如下：

import json
import os
from typing import Type, Any

import dotenv
import requests
from langchain_core.pydantic_v1 import Field, BaseModel
from langchain_core.tools import BaseTool

dotenv.load_dotenv()


class GaodeWeatherArgsSchema(BaseModel):
    city: str = Field(description="需要查询天气预报的目标城市，例如：广州")


class GaodeWeatherTool(BaseTool):
    """根据传入的城市名查询天气"""
    name = "gaode_weather"
    description = "当你想询问天气或与天气相关的问题时的工具。"
    args_schema: Type[BaseModel] = GaodeWeatherArgsSchema

    def _run(self, *args: Any, **kwargs: Any) -> str:
        """运行工具获取对应城市的天气预报"""
        try:
            
            gaode_api_key = os.getenv("GAODE_API_KEY")
            if not gaode_api_key:
                return f"高德开放平台API秘钥未配置"

            
            city = kwargs.get("city", "")
            session = requests.session()
            api_domain = "https://restapi.amap.com/v3"
            city_response = session.request(
                method="GET",
                url=f"{api_domain}/config/district?keywords={city}&subdistrict=0&extensions=all&key={gaode_api_key}",
                headers={"Content-Type": "application/json; charset=utf-8"},
            )
            city_response.raise_for_status()
            city_data = city_response.json()

            
            if city_data.get("info") == "OK":
                if len(city_data.get("districts")) > 0:
                    ad_code = city_data["districts"][0]["adcode"]

                    weather_response = session.request(
                        method="GET",
                        url=f"{api_domain}/weather/weatherInfo?city={ad_code}&extensions=all&key={gaode_api_key}&output=json",
                        headers={"Content-Type": "application/json; charset=utf-8"},
                    )
                    weather_response.raise_for_status()
                    weather_data = weather_response.json()
                    if weather_data.get("info") == "OK":
                        return json.dumps(weather_data)

            session.close()
            return f"获取{kwargs.get('city')}天气预报信息失败"
            
        except Exception as e:
            return f"获取{kwargs.get('city')}天气预报信息失败"


gaode_weather = GaodeWeatherTool()

print(gaode_weather.invoke({"city": "广州"}))

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

输出内容：

{"status": "1", "count": "1", "info": "OK", "infocode": "10000", "forecasts": [{"city": "广州市", "adcode": "440100", "province": "广东", "reporttime": "2024-08-12 15:30:27", "casts": [{"date": "2024-08-12", "week": "1", "dayweather": "中雨", "nightweather": "中雨", "daytemp": "34", "nighttemp": "25", "daywind": "北", "nightwind": "北", "daypower": "1-3", "nightpower": "1-3", "daytemp_float": "34.0", "nighttemp_float": "25.0"}, {"date": "2024-08-13", "week": "2", "dayweather": "中雨", "nightweather": "中雨", "daytemp": "33", "nighttemp": "25", "daywind": "北", "nightwind": "北", "daypower": "1-3", "nightpower": "1-3", "daytemp_float": "33.0", "nighttemp_float": "25.0"}, {"date": "2024-08-14", "week": "3", "dayweather": "中雨", "nightweather": "中雨-大雨", "daytemp": "33", "nighttemp": "25", "daywind": "北", "nightwind": "北", "daypower": "1-3", "nightpower": "1-3", "daytemp_float": "33.0", "nighttemp_float": "25.0"}, {"date": "2024-08-15", "week": "4", "dayweather": "中雨-大雨", "nightweather": "中雨-大雨", "daytemp": "33", "nighttemp": "25", "daywind": "北", "nightwind": "北", "daypower": "1-3", "nightpower": "1-3", "daytemp_float": "33.0", "nighttemp_float": "25.0"}]}]}

# 最新版 LangChain 用法提示

新版 LangChain 更推荐用 LCEL、Runnable、ChatModel.bind_tools()、结构化输出和 LangGraph 来组织复杂链路；老式 Chain、部分 AgentExecutor 写法可以读懂，但新项目应优先选择更清晰的图或 Runnable 编排。
工具调用相关代码要区分两层：模型是否原生支持 tool/function calling，以及业务侧如何定义工具 schema、参数校验、错误兜底和观测日志。
如果示例中的导入路径和你当前安装版本不同，优先查当前版本包内导出位置；常见迁移方向是从 langchain 拆到 langchain-core、langchain-community、langchain-openai、langgraph 等包。

# 拓展

工具或插件不要只看能不能调通，更要看是否可观测、可限流、可重试、可审计。联网类工具还要处理超时、空结果、搜索噪声和结果时效性。
Agent 场景里，Prompt 只是调度策略的一部分；工具描述、参数 schema、历史状态、错误反馈、停止条件和人工介入点同样会影响最终稳定性。

# 常见问题

为什么模型没有调用工具？常见原因是工具描述不清晰、参数 schema 过宽或过窄、用户问题不需要工具、模型本身不支持工具调用，或者工具绑定位置不对。
为什么工具调用后回答仍然不准？先看工具返回是否正确，再看工具结果是否被放回模型上下文，最后检查输出解析、历史消息和异常兜底是否覆盖了真实错误。

# 面试题

解释函数调用、工具调用和 Agent 的区别。
LangChain 中 tool schema 的作用是什么？为什么参数校验对生产环境很重要？
ReACT Agent 和 tool-calling Agent 的核心差异是什么？分别适合什么场景？
LangGraph 相比 LCEL 更适合解决哪些复杂编排问题？

# 生产问题排查

问题	常见原因	处理方式
工具没有被调用	工具描述弱、绑定失败、模型不支持	打印绑定后的模型配置，补充工具描述，换用支持工具调用的模型
参数格式错误	schema 设计不清晰，模型生成字段不稳定	使用 Pydantic/JSON Schema 校验，失败后把错误反馈给模型重试
联网结果不可用	搜索为空、接口超时、命中低质量页面	增加超时、重试、结果过滤、来源白名单和降级回答
Agent 循环不停止	缺少终止条件或工具返回被误判	设置最大迭代次数，记录每轮 thought/action/observation，增加停止规则
线上难以复现	缺少输入、工具请求和模型响应日志	给每次调用加 trace id，记录工具入参、出参、耗时和异常

← 创建自定义工具的 3 种技巧与使用场景谷歌实时信息搜索插件的集成与编写 →