构建AI智能体：四十二、使用 Qwen-Agent Assistant 调用高德 API 实现天气查询

minhuan2025-09-24 13:57

一、系统概述

随着大模型技术的发展，智能助手（Agent）已成为连接用户需求与外部服务的核心载体。Qwen-Agent作为基于通义千问大模型的智能框架，支持通过工具调用扩展能力，而高德天气API则提供了稳定、实时的气象数据服务。本文旨在实现Qwen-Agent的Assistant助手与高德天气API的无缝集成，构建一个能响应用户自然语言查询、返回精准天气信息的智能系统。

项目目标：

  • 掌握高德天气API的参数配置与数据解析方法
  • 理解Qwen-Agent的工具调用机制与Assistant初始化流程
  • 实现从用户自然语言到天气数据的端到端处理
  • 提供多平台交互接口（命令行 + Web 界面）
  • 对比Function Call实现和Assistant助手实现的差异性

执行流程：

流程解析：

  1. 用户输入 - 用户通过自然语言提出问题
  2. Qwen-Agent - 接收并初步处理用户输入
  3. 意图识别 - 分析用户意图，判断是否需要调用天气工具
  4. 工具调用 - 触发天气查询工具函数
  5. 高德API - 向高德地图服务发送天气查询请求
  6. 数据返回 - 接收高德API返回的原始天气数据
  7. 结果格式化 - 将原始数据转换为友好的自然语言描述
  8. 用户输出 - 向用户展示最终的天气信息

二、高德天气API详解

1. 注册与创建应用

  • 访问高德开放平台，使用支付宝或手机号注册账号
  • 进入控制台，点击"创建应用"，填写应用名称（如"Qwen-Weather-Assistant"），选择应用类型为"Web服务"
  • 在应用下点击"添加Key"，服务平台选择"Web服务"，提交后获取API密钥（Key）

2. API基础信息

3. 请求参数说明

|----------------|--------|-----------------------------|----------------|
| 参数名 | 必选 | 说明 | 示例值 |
| key | 是 | 开发者申请的Web服务API密钥 | 3376f9xxxxxxxx |
| city | 是 | 城市编码（adcode），可从高德城市编码表下载 | 110000（北京） |
| extensions | 否 | 气象类型：base（实况天气）/all（未来3天预报） | 默认base all |
| output | 否 | 返回格式：JSON/XML，默认JSON | JSON |

4. 响应格式解析

4.1 实况天气（extensions=base）

返回lives数组，包含实时天气数据：

javascript 复制代码 
{
  "status": "1",  // 1=成功，0=失败
  "count": "1",   // 返回结果总数
  "lives": [
    {
      "province": "北京",
      "city": "北京市",
      "adcode": "110000",
      "weather": "晴",          // 天气现象
      "temperature": "25",     // 实时气温（℃）
      "winddirection": "南风",  // 风向
      "windpower": "2",        // 风力（级）
      "humidity": "45",        // 湿度（%）
      "reporttime": "2025-09-23 14:30:00"  // 数据更新时间
    }
  ]
}

4.2 预报天气（extensions=all）

返回forecasts数组，包含未来3天预报：

javascript 复制代码 
{
  "forecasts": [
    {
      "city": "北京市",
      "casts": [
        {
          "date": "2025-09-23",
          "week": "2",          // 星期几（1=周一，7=周日）
          "dayweather": "晴",   // 白天天气
          "nightweather": "多云",// 夜间天气
          "daytemp": "28",      // 白天温度（℃）
          "nighttemp": "18"     // 夜间温度（℃）
        },
        // 后续2天预报...
      ]
    }
  ]
}

5. API调用示例

使用Python的requests库直接调用API：

python 复制代码 
import os
import requests

def get_amap_weather(city_code="110000", extensions="base"):
    url = "https://restapi.amap.com/v3/weather/weatherInfo"
    params = {
        "key": os.getenv("AMAP_TOKEN"),
        "city": city_code,
        "extensions": extensions
    }
    response = requests.get(url, params=params)
    return response.json()

# 测试调用
weather_data = get_amap_weather("110000", "base")
print("北京实时天气：", weather_data["lives"][0]["weather"], weather_data["lives"][0]["temperature"], "℃")

三、Qwen-Agent 中的 Assistant介绍

Assistant 类是 Qwen-Agent 框架中的核心组件，它封装了大语言模型的对话能力和工具调用功能。下面从多个维度详细解析这个类：

1. 类的基本定义

python 复制代码 
class Assistant:
    """基于大语言模型的智能助手，支持工具调用和多轮对话"""

2. 设计特点：

  • 面向对话：专门为多轮对话场景设计
  • 工具集成：支持函数调用扩展模型能力
  • 状态管理：自动维护对话历史上下文
  • 易于使用：提供简洁的API接口

3. 核心配置参数

python 复制代码 
def __init__(
    self,
    llm: Union[Dict, BaseChatModel] = None,  # 语言模型配置
    name: str = "Assistant",                 # 助手名称
    description: str = "",                   # 助手描述
    system_message: str = "",               # 系统提示词
    function_list: Optional[List] = None,   # 工具函数列表
    files: Optional[List[str]] = None,      # 文件列表
    knowledge: Optional[Union[str, List[str]]] = None,  # 知识库
    response_format: str = "message",       # 响应格式
    **kwargs
):

llm参数 - 语言模型配置

python 复制代码 
llm_cfg = {
    'model': 'qwen-turbo',           # 模型名称
    'model_server': 'dashscope',     # 服务提供商
    'api_key': 'your-api-key',       # API密钥
    'max_retries': 3,               # 最大重试次数
    'timeout': 30,                  # 超时时间
    'temperature': 0.7,             # 生成温度
    'top_p': 0.8,                   # 核采样参数
}

function_list 参数 - 工具集成

python 复制代码 
function_list = [
    'get_current_weather',          # 注册的工具名称
    'search_internet',              # 网络搜索工具
    'calculate_math',               # 数学计算工具
    {
        'name': 'custom_tool',      # 自定义工具配置
        'description': '工具描述',
        'parameters': {...}
    }
]

使用示例：

python 复制代码 
# 初始化助手
assistant = Assistant(llm=llm_cfg, function_list=['weather_tool'])

# 构建消息
messages = [
    {'role': 'user', 'content': '北京今天天气怎么样？'}
]

# 执行对话（流式）
for response_chunk in assistant.run(messages):
    print(response_chunk)
    # 输出示例：
    # {'role': 'assistant', 'content': '正在查询天气...'}
    # {'role': 'assistant', 'content': '北京今天晴，温度25°C...'}

总而言之，Assistant 类是 Qwen-Agent 框架的核心，它提供了：

  • 简化的API接口：让开发者快速构建智能助手应用
  • 强大的工具集成：通过函数调用扩展模型能力
  • 灵活的配置选项：支持多种使用场景和需求
  • 生产级可靠性：内置错误处理和性能优化
  • 良好的扩展性：支持自定义工具和预处理逻辑

这个设计体现了现代AI应用开发的最佳实践，平衡了易用性和功能性，是构建企业级AI助手应用的理想选择。

四、对比 function call 的实现

在《构建AI智能体：七、Function Calling - 解锁大语言模型的实际行动力+案例解析》一文中我们讲过通过Function Calling调用的实现方式，不过调用的方法是固定的，没有通过高德api获取，今天我们修改一下，顺便了解两者的差异；

1. 定义高德天气API工具

python 复制代码 
# 高德天气 API 的 天气工具定义（JSON 格式）
weather_tool = {
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city name, e.g. 北京",
                },
                "adcode": {
                    "type": "string",
                    "description": "The city code, e.g. 110000 (北京)",
                }
            },
            "required": ["location"],
        },
    },
}

2. 调用高德地图API查询天气

python 复制代码 
def get_weather_from_gaode(location: str, adcode: str = None):
    """调用高德地图API查询天气"""
    gaode_api_key = "df62*******"  # 替换成你的高德API Key
    base_url = "https://restapi.amap.com/v3/weather/weatherInfo"
    
    params = {
        "key": gaode_api_key,
        "city": adcode if adcode else location,
        "extensions": "base",  # 可改为 "all" 获取预报
    }
    
    response = requests.get(base_url, params=params)
    if response.status_code == 200:
        return response.json()
    else:
        return {"error": f"Failed to fetch weather: {response.status_code}"}

3. 使用 Qwen3 + 查询天气并检测工具调用

python 复制代码 
def run_weather_query():
    """使用 Qwen3 + 查询天气，并让大模型输出最终结果"""
    messages = [
        {"role": "system", "content": "你是一个智能助手，可以查询天气信息。"},
        {"role": "user", "content": "北京现在天气怎么样？"}
    ]
    
    print("第一次调用大模型...")
    response = dashscope.Generation.call(
        model="qwen-turbo",  # 可使用 Qwen3 最新版本
        messages=messages,
        tools=[weather_tool],  # 传入工具定义
        tool_choice="auto",  # 让模型决定是否调用工具
    )
    print(response)
    if response.status_code == HTTPStatus.OK:
        tool_map = {
            "get_current_weather": get_weather_from_gaode,
            # 如有更多工具，在此添加
        }
        
        # 从响应中获取消息
        assistant_message = response.output.choices[0].message

4. 结果展示

五、示例：基于Qwen-Agent智能天气查询助手

一个基于Qwen大模型的智能天气查询助手的示例，具备通过自然语言查询天气信息、支持终端和Web两种交互界面、集成高德地图API获取实时天气数据、使用函数调用技术实现工具调用的功能；

1. 重要配置模块

python 复制代码 
import os
import asyncio
import requests
from typing import Optional
import dashscope
from qwen_agent.agents import Assistant
from qwen_agent.gui import WebUI
import pandas as pd
from sqlalchemy import create_engine
from qwen_agent.tools.base import BaseTool, register_tool
  • dashscope: 阿里云通义千问API的Python SDK
  • qwen_agent: Qwen智能代理框架，提供对话和工具调用能力
  • 其他标准库用于文件操作、网络请求、数据处理等

2. 定义配置文件

python 复制代码 
# DashScope API 配置
# 请在此处填写您的 API Key
DASHSCOPE_API_KEY = "your_api_key_here"

# 高德地图 API 配置
GAODE_API_KEY = "df623d********"

# 模型配置
MODEL_CONFIG = {
    'model': 'qwen-turbo-2025-04-28',
    'timeout': 30,
    'retry_count': 3,
}

3. 配置加载机制

python 复制代码 
try:
    from config import DASHSCOPE_API_KEY, GAODE_API_KEY, MODEL_CONFIG
except ImportError:
    # 使用环境变量或默认值
  • 设计模式：使用配置管理单独配置参数
  • 优先从config.py加载配置
  • 失败时使用环境变量或硬编码默认值
  • 提供明确的错误提示

4. 天气查询工具实现

python 复制代码 
@register_tool('get_current_weather')
class WeatherTool(BaseTool):
    def call(self, params: str, **kwargs) -> str:
        return self.get_weather_from_gaode(location, adcode)
  • 装饰器注册：@register_tool将类注册为可用工具
  • 继承BaseTool：遵循Qwen Agent的工具接口规范
  • 参数解析：从JSON字符串解析位置参数
  • 错误处理：完整的异常捕获和友好错误信息

5. 高德地图API集成

python 复制代码 
def get_weather_from_gaode(self, location: str, adcode: str = None) -> str:
    params = {
        "key": gaode_api_key,
        "city": adcode if adcode else location,
        "extensions": "base",
    }
  • 使用高德地图天气API v3
  • 支持城市名称或行政编码查询
  • 返回结构化天气信息（温度、湿度、风力等）
  • 处理API响应状态码和错误信息

6. 助手服务初始化

python 复制代码 
def init_agent_service():
    bot = Assistant(
        llm=llm_cfg,
        name='天气助手',
        description='天气助手，查询天气',
        function_list=['get_current_weather'],
    )

Agent配置：

  • 指定使用的语言模型（qwen-turbo）
  • 定义助手身份和功能描述
  • 注册可用的工具列表
  • 设置系统提示词

7. 终端交互模式 (TUI)

python 复制代码 
def app_tui():
    while True:
        query = input('user question: ')
        file = input('file url (press enter if no file): ').strip()
        
        # 构建消息并获取响应
        for response in bot.run(messages):
            print('bot response:', response)

交互流程：

  • 持续对话循环
  • 支持纯文本和文件输入
  • 实时流式输出响应
  • 维护对话历史上下文

8. 图形界面模式 (GUI)

python 复制代码 
def app_gui():
    chatbot_config = {
        'prompt.suggestions': ['北京今天的天气怎么样？']
    }
    WebUI(bot, chatbot_config=chatbot_config).run()

Web界面特性：

  • 基于Web的聊天界面
  • 预置提示建议
  • 更友好的用户体验
  • 自动检测依赖并优雅降级

9. 主程序入口

python 复制代码 
if __name__ == '__main__':
    try:
        from qwen_agent.gui import WebUI
        app_gui()  # 优先使用GUI
    except ImportError:
        app_tui()  # 降级到TUI

智能启动策略：

  • 自动检测GUI依赖可用性
  • 优先提供更好的用户体验（GUI）
  • 无依赖时自动切换到终端模式
  • 完整的错误处理和日志记录

运行过程示例：

用户输入： "北京今天天气怎么样？"

AI处理流程：

  1. 理解用户查询意图 → 天气查询

  2. 提取参数 → location="北京"

  3. 调用WeatherTool → 高德API

  4. 返回结构化结果 → 温度、湿度、风力等

  5. 自然语言格式化输出

这个代码实现了一个企业级的智能天气查询助手，展示了如何将大语言模型与实际API服务结合，提供有价值的AI应用服务。

查询其他城市的天气返回结果：

六、应用场景

  • 智能客服系统：为用户提供实时天气查询，支持多轮对话（如"北京今天天气如何？明天会下雨吗？"）
  • 物联网设备集成：结合智能家居设备，根据天气数据自动调节室内环境（如高温时启动空调）
  • 出行助手：为用户提供包含天气信息的行程建议（如"今天有雨，建议携带雨伞"）

七、总结

本文档详细介绍了如何使用 Qwen-Agent Assistant 结合高德 API 开发智能天气查询系统。通过这个项目，可以了解到：

  • 申请高德与通义千问API密钥，配置开发环境
  • 解析高德天气API的请求参数与响应格式
  • 通过Qwen-Agent注册工具、初始化Assistant，实现自然语言到天气数据的转换
  • 测试验证功能并解决常见问题

这个项目不仅提供了实用的天气查询功能，更重要的是展示了如何将 AI 大模型与实际 API 服务相结合，构建真正有用的智能应用。可以根据这个基础框架，进一步扩展更多有趣的功能。

扩展建议：

  • 多城市同时查询：支持批量查询多个城市天气
  • 天气预警功能：集成气象局预警信息
  • 历史天气查询：查询过去某天的天气情况
  • 天气趋势分析：提供天气变化趋势分析
  • 个性化推荐：根据天气给出穿衣、出行建议

附录：完整实例代码

python 复制代码 
import os
import asyncio
import requests
from typing import Optional
import dashscope
from qwen_agent.agents import Assistant
from qwen_agent.gui import WebUI
import pandas as pd
from sqlalchemy import create_engine
from qwen_agent.tools.base import BaseTool, register_tool

# 导入配置
try:
    from config import DASHSCOPE_API_KEY, GAODE_API_KEY, MODEL_CONFIG
    print("成功加载配置文件")
except ImportError:
    print("警告：未找到配置文件，将使用环境变量或默认值")
    DASHSCOPE_API_KEY = os.getenv('DASHSCOPE_API_KEY', '')
    GAODE_API_KEY = "df623d56********************"
    MODEL_CONFIG = {
        'model': 'qwen-turbo-2025-04-28',
        'timeout': 30,
        'retry_count': 3,
    }

# 定义资源文件根目录
ROOT_RESOURCE = os.path.join(os.path.dirname(__file__), 'resource')

# 配置 DashScope
dashscope.api_key = DASHSCOPE_API_KEY
print(f"使用的 API Key: {dashscope.api_key}")
dashscope.timeout = 30  # 设置超时时间为 30 秒


functions_desc = [
    {
        "name": "get_current_weather",
        "description": "获取指定位置的当前天气情况",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市名称，例如：北京",
                },
                "adcode": {
                    "type": "string",
                    "description": "城市编码，例如：110000（北京）",
                }
            },
            "required": ["location"],
        },
    }
]

# ====== 天气查询工具实现 ======
@register_tool('get_current_weather')
class WeatherTool(BaseTool):
    """
    天气查询工具，通过高德地图API查询指定位置的天气情况。
    """
    description = '获取指定位置的当前天气情况'
    parameters = [{
        'name': 'location',
        'type': 'string',
        'description': '城市名称，例如：北京',
        'required': True
    }, {
        'name': 'adcode',
        'type': 'string',
        'description': '城市编码，例如：110000（北京）',
        'required': False
    }]

    def call(self, params: str, **kwargs) -> str:
        import json
        args = json.loads(params)
        location = args['location']
        adcode = args.get('adcode', None)
        
        return self.get_weather_from_gaode(location, adcode)
    
    def get_weather_from_gaode(self, location: str, adcode: str = None) -> str:
        """调用高德地图API查询天气"""
        gaode_api_key = "df623d56***********"  # 高德API Key
        base_url = "https://restapi.amap.com/v3/weather/weatherInfo"
        
        params = {
            "key": gaode_api_key,
            "city": adcode if adcode else location,
            "extensions": "base",  # 可改为 "all" 获取预报
        }
        
        try:
            response = requests.get(base_url, params=params)
            if response.status_code == 200:
                data = response.json()
                if data.get('status') == '1' and data.get('lives'):
                    weather_info = data['lives'][0]
                    result = f"天气查询结果：\n城市：{weather_info.get('city')}\n天气：{weather_info.get('weather')}\n温度：{weather_info.get('temperature')}°C\n风向：{weather_info.get('winddirection')}\n风力：{weather_info.get('windpower')}\n湿度：{weather_info.get('humidity')}%\n发布时间：{weather_info.get('reporttime')}"
                    return result
                else:
                    return f"获取天气信息失败：{data.get('info', '未知错误')}"
            else:
                return f"请求失败：HTTP状态码 {response.status_code}"
        except Exception as e:
            return f"获取天气信息出错：{str(e)}"

# ====== 初始化助手服务 ======
def init_agent_service():
    """初始化助手服务"""
    llm_cfg = MODEL_CONFIG
    try:
        bot = Assistant(
            llm=llm_cfg,
            name='天气助手',
            description='天气助手，查询天气',
            system_message="你是一名有用的助手",
            function_list=['get_current_weather'],  # 增加天气工具
        )
        print("助手初始化成功！")
        return bot
    except Exception as e:
        print(f"助手初始化失败: {str(e)}")
        raise

def app_tui():
    """终端交互模式
    
    提供命令行交互界面，支持：
    - 连续对话
    - 文件输入
    - 实时响应
    """
    try:
        # 初始化助手
        bot = init_agent_service()

        # 对话历史
        messages = []
        while True:
            try:
                # 获取用户输入
                query = input('user question: ')
                # 获取可选的文件输入
                file = input('file url (press enter if no file): ').strip()
                
                # 输入验证
                if not query:
                    print('user question cannot be empty！')
                    continue
                    
                # 构建消息
                if not file:
                    messages.append({'role': 'user', 'content': query})
                else:
                    messages.append({'role': 'user', 'content': [{'text': query}, {'file': file}]})

                print("正在处理您的请求...")
                # 运行助手并处理响应
                response = []
                for response in bot.run(messages):
                    print('bot response:', response)
                messages.extend(response)
            except Exception as e:
                print(f"处理请求时出错: {str(e)}")
                print("请重试或输入新的问题")
    except Exception as e:
        print(f"启动终端模式失败: {str(e)}")


def app_gui():
    """图形界面模式，提供 Web 图形界面"""
    try:
        print("正在启动 Web 界面...")
        # 初始化助手
        bot = init_agent_service()
        # 配置聊天界面，列举3个典型门票查询问题
        chatbot_config = {
            'prompt.suggestions': [
                '北京今天的天气怎么样？',
            ]
        }
        print("Web 界面准备就绪，正在启动服务...")
        # 启动 Web 界面
        WebUI(
            bot,
            chatbot_config=chatbot_config
        ).run()
    except Exception as e:
        print(f"启动 Web 界面失败: {str(e)}")
        print("请检查网络连接和 API Key 配置")


if __name__ == '__main__':
    # 运行模式选择
    print("开始运行程序...")
    try:
        # 检查是否已安装 GUI 依赖
        try:
            from qwen_agent.gui import WebUI
            print("GUI 依赖已安装，启动图形界面模式...")
            app_gui()          # 图形界面模式
        except ImportError:
            print("GUI 依赖未安装，启动终端模式...")
            print("如需使用图形界面，请运行: pip install \"qwen-agent[gui]\"")
            app_tui()          # 终端模式
    except Exception as e:
        print(f"运行出错: {str(e)}")
        import traceback
        traceback.print_exc()
相关推荐
OliverYeung3 小时前
【AskAI系列课程】：P3.Agno从阿里云百炼知识库中检索知识库片段并回答用户问题
人工智能·ai·llm·rag·agentic·deepseek·agno
陈橘又青3 小时前
通过无代码工作流在 Dify 中进行人工智能驱动的网络抓取
大数据·人工智能·ai
麒羽7604 小时前
PyTorch 神经网络工具箱核心知识梳理
人工智能·pytorch·神经网络
Lkygo4 小时前
一键部署CosyVoice AI语音模型
人工智能
我不是QI4 小时前
《从零到精通：PyTorch （GPU 加速版） 完整安装指南
人工智能·pytorch·python·程序人生·gpu算力
产品设计大观4 小时前
一站式AI项目管理平台：高保真PMS系统原型案例拆解
人工智能·产品经理·墨刀·项目管理系统·ai项目管理·pms系统·ai项目管理平台
快手技术4 小时前
生成式强化学习在广告自动出价场景的技术实践
人工智能
IT_陈寒4 小时前
Vue 3.4性能优化实战：这5个技巧让我的应用加载速度提升了300%！🚀
前端·人工智能·后端
Memene摸鱼日报4 小时前
「Memene 摸鱼日报 2025.9.24」阿里 Qwen 团队放出 Qwen3-Next、Qwen-VL 等多个大招，Sam 提出“丰盛智能”愿景
人工智能·aigc
热门推荐
01UV 工具安装与国内镜像源配置指南02Spec-Kit 使用指南03GitHub 镜像站点0446个Nano-banana 精选提示词，持续更新中05UV安装并设置国内源06保姆级教程：手把手教你用Dify实现完美多轮对话（附Chatflow和提示词）07KGG转MP3工具|非KGM文件|解密音频08解决 WSL Ubuntu 中 /etc/resolv.conf 自动重置问题09jdk21下载、安装（Windows、Linux、macOS）10Linux下V2Ray安装配置指南