一、系統概述
隨着大模型技術的發展，智能助手（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. 天氣查詢工具實現
@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集成
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"],
},
}
]
# ====== 天氣查詢工具實現 ======
@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()