构建智能天气机器人：Qwen-Agent实战教程
项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent 引言：告别碎片化天气服务，打造你的智能助理
你是否还在为获取天气信息而切换多个应用？是否渴望一个能图文并茂、甚至为你配上应景诗词的个性化天气助手？本文将带你从零开始，基于Qwen-Agent框架构建一个集实时天气查询、智能图像生成和诗词匹配于一体的多模态天气机器人。通过本教程，你将掌握：
- LLM工具调用与多模态整合的核心技术
- Qwen-Agent的Agent初始化与工作流配置
- 第三方API（高德地图）与本地资源（PDF文档）的协同使用
- 图形化界面的快速部署与交互优化
环境准备：5分钟搭建开发环境
1. 核心依赖安装
Qwen-Agent提供了灵活的模块化安装方案，根据天气机器人需求，我们需要安装基础框架、GUI组件和RAG功能（用于PDF诗词文档解析）：
# 基础安装（含LLM调用与工具链）
pip install "qwen-agent[gui,rag]"
# 如需从源码安装最新版本
git clone https://gitcode.com/GitHub_Trending/qw/Qwen-Agent
cd Qwen-Agent
pip install -e ."[gui,rag]"
2. 高德地图API密钥获取
天气查询功能依赖高德开放平台API，需完成以下步骤：
- 访问高德开放平台注册账号
- 创建应用并获取Web服务API密钥
- 设置环境变量：
# Linux/Mac export AMAP_TOKEN="你的高德API密钥" # Windows PowerShell $env:AMAP_TOKEN="你的高德API密钥"
3. 开发环境验证
运行以下命令检查关键依赖版本：
# 验证Qwen-Agent安装
python -c "import qwen_agent; print('Qwen-Agent版本:', qwen_agent.__version__)"
# 验证RAG依赖
python -c "import pdfplumber; print('PDF解析模块就绪')"
核心功能实现：从0到1构建天气机器人
1. 项目结构设计
遵循Qwen-Agent的最佳实践，我们的天气机器人项目采用模块化结构：
weather-bot/
├── main.py # 主程序入口
├── resource/ # 资源文件目录
│ └── poem.pdf # 天气相关诗词文档
└── config.py # 配置参数（可选）
2. 初始化Agent服务
Agent是Qwen-Agent的核心组件，负责协调LLM、工具和用户交互。以下代码完成天气机器人的基础配置：
from qwen_agent.agents import Assistant
def init_agent_service():
# 1. 配置LLM参数（使用通义千问大模型）
llm_cfg = {
'model': 'qwen-max', # 模型名称
'model_type': 'qwen_dashscope', # 使用阿里云DashScope服务
'generate_cfg': {
'top_p': 0.8, # 采样参数，控制输出多样性
'temperature': 0.7
}
}
# 2. 定义系统提示（指导Agent行为）
system_prompt = (
'你扮演一个天气预报助手，具有以下能力：\n'
'- 使用`amap_weather`工具查询指定地区实时天气\n'
'- 使用`image_gen`工具根据天气生成城市景观图\n'
'- 从用户提供的诗词文档中选择最匹配天气的诗句\n'
'注意：必须严格使用文档中的诗词，不得编造'
)
# 3. 注册所需工具
tools = ['amap_weather', 'image_gen'] # 内置天气查询和图像生成工具
# 4. 创建Assistant实例
bot = Assistant(
llm=llm_cfg,
name='智能天气助手',
description='集成天气查询、图像生成和诗词推荐的多模态助手',
system_message=system_prompt,
function_list=tools
)
return bot
关键参数解析：
| 参数 | 说明 | 可选值示例 |
|---|---|---|
model | LLM模型名称 | qwen-max, qwen-plus, qwen-turbo |
model_type | 模型服务类型 | qwen_dashscope, openai |
function_list | 允许调用的工具列表 | amap_weather, image_gen, code_interpreter |
system_message | 定义Agent行为准则和能力范围 | 自然语言指令 |
3. 实现天气查询功能
天气查询功能通过amap_weather工具实现，该工具封装了高德地图天气API。核心代码位于qwen_agent/tools/amap_weather.py，关键逻辑包括：
# 工具核心实现（简化版）
class AmapWeather(BaseTool):
description = '获取对应城市的天气数据'
parameters = {
'type': 'object',
'properties': {
'location': {
'description': '城市/区具体名称，如"海淀区"',
'type': 'string'
}
},
'required': ['location']
}
def call(self, params):
# 1. 解析参数
location = params['location']
# 2. 转换为行政区划代码（ADCode）
adcode = self.get_city_adcode(location)
# 3. 调用高德API
response = requests.get(
f'https://restapi.amap.com/v3/weather/weatherInfo?city={adcode}&key={self.token}'
)
# 4. 解析并返回结果
return f'{location}的天气是{data["lives"][0]["weather"]}，温度{data["lives"][0]["temperature"]}度。'
使用示例：
# 测试天气查询功能
bot = init_agent_service()
messages = [{'role': 'user', 'content': '查询北京市海淀区天气'}]
for response in bot.run(messages):
print(response) # 输出：海淀区的天气是晴，温度25度。
4. 集成多模态能力（图像生成+诗词匹配）
4.1 图像生成工具
image_gen工具通过文本描述生成图像，核心代码位于qwen_agent/tools/image_gen.py：
class ImageGen(BaseTool):
description = '根据文本描述生成图像URL'
parameters = {
'type': 'object',
'properties': {
'prompt': {
'description': '图像内容详细描述（英文）',
'type': 'string'
}
},
'required': ['prompt']
}
def call(self, params):
prompt = urllib.parse.quote(params['prompt'])
return json.dumps({
'image_url': f'https://image.pollinations.ai/prompt/{prompt}'
})
⚠️ 注意：
pollinations.ai为国外服务，国内用户可替换为阿里云图像生成API：# 国内替代方案（需申请阿里云API密钥） return json.dumps({ 'image_url': f'https://dashscope.aliyuncs.com/api/v1/services/aigc/image-generation/generation' })
4.2 文档交互（诗词匹配）
通过向Agent传入PDF文档，实现天气与诗词的智能匹配：
def test_weather_with_poem():
bot = init_agent_service()
# 构造包含文件的用户消息
messages = [
{
'role': 'user',
'content': [
{'text': '查询杭州天气并配图配诗'},
{'file': 'resource/poem.pdf'} # 诗词文档路径
]
}
]
# 执行Agent
for response in bot.run(messages):
print(response)
文档要求：
poem.pdf需包含格式规范的诗词，建议每首诗标注适用天气（如[晴][雨]），便于Agent精准匹配。
5. 构建用户交互界面
Qwen-Agent提供Gradio GUI组件，快速搭建Web交互界面：
from qwen_agent.gui import WebUI
def launch_gui():
bot = init_agent_service()
# 配置WebUI
chat_config = {
'prompt.suggestions': [ # 预设用户问题
'查询北京天气',
'生成上海雨天的图片',
'广州晴天配诗'
],
'title': '智能天气助手',
'description': '一站式天气查询、图像生成与诗词推荐服务'
}
# 启动Web界面
WebUI(bot, chatbot_config=chat_config).run(
server_name='0.0.0.0', # 允许局域网访问
server_port=7860 # 端口号
)
if __name__ == '__main__':
launch_gui()
运行后访问http://localhost:7860即可看到交互界面，包含：
- 聊天输入框（支持文本和文件上传）
- 预设问题快捷按钮
- 多模态输出区域（文本+图像）
核心技术解析：Qwen-Agent工作原理解密
1. Agent工作流程图
2. 工具调用机制详解
Qwen-Agent的工具调用基于JSON Schema规范，核心流程包括：
-
工具注册：通过
@register_tool装饰器声明工具元数据@register_tool('amap_weather') class AmapWeather(BaseTool): description = '获取对应城市的天气数据' parameters = { 'type': 'object', 'properties': { 'location': {'type': 'string', 'description': '城市名称'} }, 'required': ['location'] } -
参数验证：Agent自动校验工具调用参数完整性和格式
-
函数执行：通过
call()方法执行具体逻辑并返回结果 -
结果解析：LLM将工具返回结果转换为自然语言回答
3. 多模态输出整合
Agent通过消息格式标准化实现多模态内容整合：
{
"role": "assistant",
"content": [
{
"text": "北京市当前天气晴朗，气温25°C...",
"image": "https://image.pollinations.ai/prompt/Beijing+sunny+day"
},
{
"text": "推荐诗句：「日出江花红胜火，春来江水绿如蓝」"
}
]
}
功能扩展：打造个性化天气服务
1. 添加语音交互
集成Qwen-Audio模型实现语音输入输出：
# 安装音频依赖
# pip install qwen-agent[audio]
from qwen_agent.tools import audio_recognize, text_to_speech
def add_audio_support(bot):
# 注册音频工具
bot.add_tools(['audio_recognize', 'text_to_speech'])
# 更新系统提示
bot.system_message += '\n- 支持语音输入输出，用户发送语音时自动转换为文本'
return bot
2. 实现天气预警功能
通过扩展amap_weather工具获取预警信息：
# 修改amap_weather.py的call方法
def call(self, params):
# ...原有代码...
# 新增预警信息提取
warnings = data.get('warnings', [])
if warnings:
warning_info = '\n'.join([f"{w['type']}: {w['level']} - {w['content']}" for w in warnings])
return f"{weather_info}\n天气预警：{warning_info}"
3. 多城市天气对比
扩展Agent能力实现批量查询：
system_prompt += '\n- 支持多城市查询，格式："查询北京,上海,广州天气"'
# 在工具调用前解析多城市参数
def parse_multiple_cities(params):
locations = params['location'].split(',')
results = []
for loc in locations:
results.append(amap_weather.call({'location': loc.strip()}))
return '\n'.join(results)
部署与测试：从开发到生产
1. 命令行测试
# 基础功能测试
python main.py --test "查询深圳天气"
# 带文档测试
python main.py --test "查询成都天气配诗" --file resource/poem.pdf
2. 生产环境部署
Docker容器化
FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
ENV AMAP_TOKEN=your_token_here
EXPOSE 7860
CMD ["python", "main.py"]
构建并运行容器：
docker build -t weather-bot .
docker run -p 7860:7860 --env AMAP_TOKEN=xxx weather-bot
服务器部署注意事项
| 环境 | 配置要求 | 优化建议 |
|---|---|---|
| CPU | 4核以上 | 启用多线程处理请求 |
| 内存 | 8GB以上 | 设置适当的LLM缓存大小 |
| 网络 | 稳定外网连接 | 配置API请求超时重试机制 |
| 安全 | 限制文件上传大小和类型 | 仅允许PDF格式，大小<10MB |
3. 性能优化
-
工具调用缓存：对重复查询结果进行缓存
from functools import lru_cache @lru_cache(maxsize=100) # 缓存100条结果 def get_weather(location): return amap_weather.call({'location': location}) -
异步工具调用：并行执行天气查询和图像生成
# 使用Qwen-Agent的并行执行工具 from qwen_agent.utils.parallel_executor import parallel_call results = parallel_call([ {'tool': 'amap_weather', 'params': {'location': '北京'}}, {'tool': 'image_gen', 'params': {'prompt': 'Beijing sunny day'}} ])
总结与展望
通过本教程，你已掌握使用Qwen-Agent构建多模态智能天气机器人的完整流程，包括：
- 环境搭建：安装依赖、配置API密钥
- 核心开发：LLM配置、工具集成、系统提示设计
- 功能扩展：文档交互、多模态输出、界面开发
- 部署优化：容器化、性能调优、安全加固
进阶方向：
- 个性化推荐：基于用户历史查询提供定制化天气服务
- 行业适配：针对农业、旅游等行业开发专用天气助手
- 多端部署：开发微信小程序、移动端App等客户端
学习资源：
- 官方文档：Qwen-Agent GitHub
- API参考：DashScope文档中心
- 社区支持：Qwen开发者微信群（加入方式见GitHub主页）
🌟 行动清单：
- 克隆项目仓库：
git clone https://gitcode.com/GitHub_Trending/qw/Qwen-Agent- 完成
examples/assistant_weather_bot.py的扩展练习- 尝试集成一个新工具（如空气质量查询）
- 在评论区分享你的扩展成果！
Qwen-Agent作为新一代LLM应用开发框架，正在不断进化。期待你基于本文构建的天气机器人基础上，创造出更多创新应用！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
