一、系统概述
随着大模型技术的发展，智能助手（Agent）已成为连接用户需求与外部服务的核心载体。Qwen-Agent作为基于通义千问大模型的智能框架，支持通过工具调用扩展能力，而高德天气API则提供了稳定、实时的气象数据服务。本文旨在实现Qwen-Agent的Assistant助手与高德天气API的无缝集成，构建一个能响应用户自然语言查询、返回精准天气信息的智能系统。
项目目标：
- 掌握高德天气API的参数配置与数据解析方法
- 理解Qwen-Agent的工具调用机制与Assistant初始化流程
- 实现从用户自然语言到天气数据的端到端处理
- 提供多平台交互接口（命令行 + Web 界面）
- 对比Function Call实现和Assistant助手实现的差异性
执行流程：
流程解析：
- 用户输入 - 用户通过自然语言提出问题
- Qwen-Agent - 接收并初步处理用户输入
- 意图识别 - 分析用户意图，判断是否需要调用天气工具
- 工具调用 - 触发天气查询工具函数
- 高德API - 向高德地图服务发送天气查询请求
- 数据返回 - 接收高德API返回的原始天气数据
- 结果格式化 - 将原始数据转换为友好的自然语言描述
- 用户输出 - 向用户展示最终的天气信息
二、高德天气API详解
1. 注册与创建应用
- 访问高德开放平台，使用支付宝或手机号注册账号
- 进入控制台，点击“创建应用”，填写应用名称（如“Qwen-Weather-Assistant”），选择应用类型为“Web服务”
- 在应用下点击“添加Key”，服务平台选择“Web服务”，提交后获取API密钥（Key）
2. API基础信息
- 服务地址：https://restapi.amap.com/v3/weather/weatherInfo
- 请求方式：GET
- 数据来源：中国气象局，实况天气每小时更新多次，预报天气每日更新3次（8:00、11:00、18:00左右）
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数组，包含实时天气数据：
{ "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天预报：
{ "forecasts": [ { "city": "北京市", "casts": [ { "date": "2025-09-23", "week": "2", // 星期几（1=周一，7=周日） "dayweather": "晴", // 白天天气 "nightweather": "多云",// 夜间天气 "daytemp": "28", // 白天温度（℃） "nighttemp": "18" // 夜间温度（℃） }, // 后续2天预报... ] } ] }
5. API调用示例
使用Python的requests库直接调用API：
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. 类的基本定义
class Assistant: """基于大语言模型的智能助手，支持工具调用和多轮对话"""
2. 设计特点
- 面向对话：专门为多轮对话场景设计
- 工具集成：支持函数调用扩展模型能力
- 状态管理：自动维护对话历史上下文
- 易于使用：提供简洁的API接口
3. 核心配置参数
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参数 - 语言模型配置
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 参数 - 工具集成
function_list = [ 'get_current_weather', # 注册的工具名称 'search_internet', # 网络搜索工具 'calculate_math', # 数学计算工具 { 'name': 'custom_tool', # 自定义工具配置 'description': '工具描述', 'parameters': {...} } ]
使用示例：
# 初始化助手 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工具
# 高德天气 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查询天气
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 + 查询天气并检测工具调用
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. 重要配置模块
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. 定义配置文件
# 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. 配置加载机制
try: from config import DASHSCOPE_API_KEY, GAODE_API_KEY, MODEL_CONFIG except ImportError: # 使用环境变量或默认值
- 设计模式：使用配置管理单独配置参数
- 优先从config.py加载配置
- 失败时使用环境变量或硬编码默认值
- 提供明确的错误提示
4. 天气查询工具实现
('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集成
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. 助手服务初始化
def init_agent_service(): bot = Assistant( llm=llm_cfg, name='天气助手', description='天气助手，查询天气', function_list=['get_current_weather'], )
Agent配置：
- 指定使用的语言模型（qwen-turbo）
- 定义助手身份和功能描述
- 注册可用的工具列表
- 设置系统提示词
7. 终端交互模式 (TUI)
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)
def app_gui(): chatbot_config = { 'prompt.suggestions': ['北京今天的天气怎么样？'] } WebUI(bot, chatbot_config=chatbot_config).run()
Web界面特性：
- 基于Web的聊天界面
- 预置提示建议
- 更友好的用户体验
- 自动检测依赖并优雅降级
9. 主程序入口
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 服务相结合，构建真正有用的智能应用。可以根据这个基础框架，进一步扩展更多有趣的功能。
扩展建议：
- 多城市同时查询：支持批量查询多个城市天气
- 天气预警功能：集成气象局预警信息
- 历史天气查询：查询过去某天的天气情况
- 天气趋势分析：提供天气变化趋势分析
- 个性化推荐：根据天气给出穿衣、出行建议
附录：完整实例代码
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"], }, } ] # ====== 天气查询工具实现 ====== ('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()
