🌤️ Weather Agent - 智能天气助手

基于 Spring AI + 通义千问的智能天气查询 Agent

---

📖 项目简介

Weather Agent 是一个基于 Spring AI Alibaba 和 通义千问大模型 构建的智能天气助手。它支持自然语言交互，用户可以像和朋友聊天一样询问天气情况，AI 会自动理解意图、调用天气 API 并给出贴心的生活建议。

🎯 核心亮点

• 自然语言理解 - 无需固定格式，自然对话即可查询天气
• 智能建议 - 不仅告诉你天气，还提供穿衣、出行建议
• 流式响应 - 打字机效果，体验更自然流畅
• 多轮对话 - 支持上下文记忆，对话更连贯

---

✨ 功能特性

特性	描述
🗣️ 自然语言查询	支持 "上海今天需要带伞吗？"、"北京明天天气怎么样？" 等自然语言查询
🔧 AI 函数调用	基于 Spring AI Function Calling，自动识别意图并调用天气 API
📡 流式响应	支持 SSE 流式输出，实现打字机效果
💬 多轮对话	内置对话记忆，支持上下文理解
🌍 多城市支持	支持北京、上海、杭州、广州、深圳等主要城市
💡 智能建议	根据天气状况提供穿衣、出行、健康等生活建议

---

🛠️ 技术栈

技术	版本	说明
Spring Boot	3.5.11	核心框架
Spring AI Alibaba	1.1.2.2	AI 能力集成
通义千问	qwen-plus	大语言模型
和风天气 API	v7	天气数据来源
Java	17	开发语言
WebFlux	-	响应式 HTTP 客户端
Fastjson2	2.0.61	JSON 处理
Lombok	-	代码简化

---

📁 项目结构

WeatherAgent/
├── src/
│   ├── main/
│   │   ├── java/com/weather/agent/
│   │   │   ├── config/
│   │   │   │   └── AiConfig.java          # AI 配置（ChatClient、对话记忆）
│   │   │   ├── controller/
│   │   │   │   └── WeatherAssistantController.java  # REST API 控制器
│   │   │   ├── model/
│   │   │   │   ├── WeatherRequest.java    # 请求模型
│   │   │   │   └── WeatherResponse.java   # 响应模型
│   │   │   ├── service/
│   │   │   │   └── WeatherService.java    # 天气服务（@Tool 注解）
│   │   │   └── WeatherAgentApplication.java  # 启动类
│   │   └── resources/
│   │       └── application.yaml           # 配置文件
│   └── test/
│       └── java/com/weather/agent/
│           └── WeatherAgentApplicationTests.java
├── pom.xml                                 # Maven 依赖配置
└── README.md

核心组件说明

组件	文件	职责
AI 配置	AiConfig.java	配置 ChatClient、系统提示词、对话记忆、工具注册
控制器	WeatherAssistantController.java	提供 REST API 接口
天气服务	WeatherService.java	封装天气查询逻辑，使用 @Tool 注解暴露给 AI
数据模型	WeatherResponse.java	定义天气数据结构

---

🚀 快速开始

环境要求

• JDK 17+
• Maven 3.6+
• 阿里云百炼 API Key (申请地址)
• 和风天气 API Key (申请地址)

安装步骤

1. 克隆项目

git clone https://github.com/your-repo/weather-agent.git
cd weather-agent

2. 配置 API Key

编辑 src/main/resources/application.yaml：

spring:
  ai:
    dashscope:
      api-key: 你的百炼API_KEY  # 替换为你的阿里云百炼 API Key

weather:
  api:
    key: 你的和风天气API_KEY     # 替换为你的和风天气 API Key
    base-url: https://devapi.qweather.com/v7  # 或使用私有域名

3. 编译运行

# 编译项目
mvn clean package -DskipTests

# 运行项目
mvn spring-boot:run

4. 验证启动

启动成功后，控制台会显示：

========================================
🌤️  天气助手 Agent 已启动！
访问地址: http://localhost:8080/api/weather/ask?question=上海今天需要带伞吗？
========================================

---

📡 API 接口文档

基础信息

• Base URL: http://localhost:8080/api/weather
• Content-Type: application/json

---

1. 聊天接口

POST /chat

支持自然语言查询，返回完整响应。

请求参数

参数	类型	必填	说明
message	String	是	用户消息

请求示例

curl -X POST http://localhost:8080/api/weather/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "上海今天需要带伞吗？"}'

响应示例

上海今天是多云天气，温度 26°C，湿度 65%，降水概率很低，您不需要带伞。
建议穿着轻薄透气的衣物，出门记得做好防晒哦！

---

2. 流式聊天接口

POST /chatStream

支持流式输出，实现打字机效果。

请求参数

参数	类型	必填	说明
message	String	是	用户消息

请求示例

curl -X POST http://localhost:8080/api/weather/chatStream \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{"message": "杭州明天穿什么衣服合适？"}'

响应说明

• Content-Type: application/x-ndjson
• 响应为流式输出，每次返回一段文本

---

3. 简单查询接口

GET /ask

简单的 GET 请求接口，适合快速测试。

请求参数

参数	类型	必填	说明
question	String	是	查询问题

请求示例

curl "http://localhost:8080/api/weather/ask?question=北京今天天气怎么样？"

浏览器访问

直接在浏览器中访问：

http://localhost:8080/api/weather/ask?question=深圳明天会下雨吗？

---

💡 使用场景示例

场景 1：出行建议

用户：明天去杭州出差，需要带伞吗？
AI：杭州明天是晴天，温度 25°C，降水概率仅 5%，您不需要带伞。
    不过早晚温差较大，建议带一件薄外套备用。

场景 2：穿衣建议

用户：上海今天穿什么衣服合适？
AI：上海今天多云，温度 22°C，湿度适中，建议穿着长袖衬衫或薄毛衣。
    如果您需要长时间户外活动，可以搭配一件轻便外套。

场景 3：多轮对话

用户：北京今天天气怎么样？
AI：北京今天晴，温度 18°C，空气质量良好，非常适合户外活动！

用户：那明天呢？
AI：北京明天同样是晴天，温度会升至 21°C，您可以继续享受好天气！

---

⚙️ 配置说明

完整配置项

spring:
  application:
    name: weather-agent

  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}  # 百炼 API Key
      chat:
        options:
          model: qwen-plus           # 模型选择：qwen-turbo/qwen-plus/qwen-max
          temperature: 0.7           # 创造性参数 (0-1)
          max-tokens: 500            # 最大输出 token
          function-callback-enabled: true  # 启用函数调用
          cache-mode: SYSTEM_AND_TOOLS     # 缓存模式
          cache-ttl: 1h              # 缓存时长

server:
  port: 8080

weather:
  api:
    key: ${QWEATHER_API_KEY}         # 和风天气 API Key
    base-url: https://devapi.qweather.com/v7

模型选择建议

模型	特点	适用场景
qwen-turbo	响应快，成本低	简单查询，高并发场景
qwen-plus	平衡性能与成本	推荐日常使用
qwen-max	能力最强	复杂推理场景

---

🏗️ 架构设计

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    用户请求   │────▶│  Controller  │────▶│  ChatClient  │
└──────────────┘     └──────────────┘     └──────────────┘
                                                 │
                                                 ▼
                     ┌──────────────┐     ┌──────────────┐
                     │  通义千问模型  │◀───│  AI Advisor  │
                     └──────────────┘     └──────────────┘
                            │
                            ▼ Function Calling
                     ┌──────────────┐     ┌──────────────┐
                     │ WeatherService│────▶│ 和风天气 API │
                     │   (@Tool)     │     └──────────────┘
                     └──────────────┘

核心流程

1. 用户发送自然语言查询
2. ChatClient 将请求发送给通义千问
3. AI 识别意图，决定是否调用 getWeather 工具
4. WeatherService 调用和风天气 API 获取实时数据
5. AI 整合天气数据，生成个性化回复

---

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

贡献流程

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

开发规范

• 遵循 Java 编码规范
• 提交信息使用中文，格式清晰
• 新功能需要添加相应测试

---

📄 许可证

本项目采用 Apache License 2.0 许可证。

---

🙏 致谢

• Spring AI - AI 能力集成框架
• Spring AI Alibaba - 阿里云 AI 集成
• 和风天气 - 天气数据服务
• 阿里云百炼 - 大模型服务

---

如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！