Spring AI 2.0 从入门到 Agent：用 Tool Calling 构建可溯源 RAG 应用（RssHarness 实战全解）

Spring AI 2.0 从入门到 Agent：用 Tool Calling 构建可溯源 RAG 应用（RssHarness 实战全解）

在本地开发环境中集成大语言模型能力，曾经是让许多开发者望而却步的难题。随着模型即服务（MaaS）模式的成熟和 Spring AI 2.0 的发布，普通 Java 后端工程师无需 Python 生态、无需算法背景，就能在几分钟内构建出具备智能对话和自主工具调用能力的 AI Agent。

本文以 RssHarness——一个基于 Spring AI 2.0 + DeepSeek + RSSHub 构建的可溯源搜索 Agent——为贯穿全文的实战案例，覆盖从环境搭建到生产部署的完整路径。53 个测试全绿，Docker 一键部署，源码开源。

① 开发环境搭建与依赖配置

工欲善其事，必先利其器。Spring AI 2.0 的起步只需要一个标准的 Spring Boot 项目加上一个 Maven 坐标。

核心依赖

Spring AI 2.0 的 Starter 体系为每个模型提供商封装了独立的依赖——模型不同，Maven 坐标不同：

RssHarness 选用 DeepSeek——中文理解强、成本约为 GPT-4 的 1/20：

<!– pom.xml — 换成其他模型只需改 artifactId + 配置 key –>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-deepseek</artifactId>
<version>2.0.0</version>
</dependency>

引入对应 Starter 后，Spring AI 自动配置 ChatModel Bean。后续业务代码始终面向 ChatClient 抽象层编程——切换模型只改 Maven 坐标和配置 Key，不改一行业务逻辑。

密钥安全第一道防线

切勿将 API Key 硬编码。推荐三层隔离：

# application.properties — 通过环境变量注入
spring.ai.deepseek.api-key=${DEEPSEEK_API_KEY:}

# .bashrc / .zshrc 或启动命令中注入
export DEEPSEEK_API_KEY=sk-your-key-here

对于生产环境，RssHarness 使用 Docker Compose 的环境变量注入：

# docker-compose.yml
services:
rssharness:
environment:
– DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY:–sk–your–key–here}

踩坑记录：Spring AI 的自动配置在找不到 API Key 时不会报错启动失败——它只会在第一次请求时抛出 AuthenticationException。建议在 ApplicationRunner 中做一个启动时的连通性检查。

② 核心概念解析与 LLM 连接

Token 并非字符

Token 是模型处理文本的基本单位，大致相当于 0.75 个英文单词或半个汉字。理解 Token 机制至关重要——它直接决定了输入输出长度上限和计费成本。以 DeepSeek Chat 为例，输入 ¥0.001/1K tokens，输出 ¥0.002/1K tokens，一次完整的 Agent 调用（含 Tool Calling 循环和摘要生成）约 ¥0.05-0.15。

Spring AI 的抽象层

Spring AI 的核心价值在于模型无关的抽象。无论是 DeepSeek、OpenAI 还是 Ollama，你的业务代码始终面向 ChatClient 编程：

@Configuration
public class AiConfig {
@Bean
@Primary
public ChatClient chatClient(ChatModel chatModel, RssTools rssTools,
ChatMemory chatMemory) {
return ChatClient.builder(chatModel)
.defaultTools(rssTools)
.defaultAdvisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(),
new SimpleLoggerAdvisor())
.defaultSystem("""
You are an RSS aggregation engine.
Your output is always based on actual data retrieved,
never on speculation.
""")
.build();
}
}

ChatClient 是线程安全的单例。不需要每次请求创建新实例——Spring 容器管理其生命周期。同时，通过default系列可以向Client注入默认选项，减少重复编码。 通过Spring Boot提供的注解，我们可以提供多个不同的Client供不同的服务调用。default系列方法在此更加灵活和高效。

③ 构建第一个 AI 对话应用

核心逻辑：接收用户输入 → 封装消息 → 发送给模型 → 解析流式响应。

RssHarness 的 ConversationService 展示了一次调用完成全链路编排的模式——核心是一行 chatClient.prompt().user(question).stream().chatResponse()：

@Service
public class ConversationService {
@Autowired private ChatClient chatClient;
@Autowired private RssTools rssTools;

public List<FetchResponse> searchStreaming(String sessionId,
String question,
SearchCallback cb) {
cb.onThinking("Thinking …");
try {
ChatResponse last = chatClient.prompt()
.user(question)
.stream()
.chatResponse() // ← Flux<ChatResponse>，非 Flux<String>
.doOnNext(resp -> {
String text = resp.getResult().getOutput().getText();
if (text != null) cb.onResponseToken(text);
})
.blockLast(); // ← 最终 ChatResponse 含 Usage 元数据
// 从 ChatResponse 元数据中拿到真实 Token 消耗
if (last != null && last.getMetadata().getUsage() != null) {
cb.onTokens(last.getMetadata().getUsage().getTotalTokens());
}
} catch (Exception e) {
cb.onError("ai", e.getMessage());
}
return rssTools.getLastResults();
}
}

关键点：

• .stream().chatResponse() 返回 Flux<ChatResponse> 而非 Flux<String>——每个 ChatResponse 既含增量文本，最终响应还携带 Usage 元数据（真实 Token 消耗，非字符数估算）
• MessageChatMemoryAdvisor 自动管理多轮对话历史，开发者无需手动维护 messages 列表
• doOnNext 回调实现了 CLI 的逐步渲染

对比 springStart.md 的 Python 示例：Python 版需要手动维护 messages = […] 列表、手动 append user/assistant 消息、手动处理流式块拼接。Spring AI 将这些全部封装在 Advisor 和 reactive stream 中。

④ 提示词工程与上下文管理

提示词工程并非玄学，而是一门关于如何清晰表达需求的艺术。以 RssHarness 的 System Prompt 为例：

.defaultSystem("""
You are an RSS aggregation engine.
Your core capability lies in retrieving real-time information
via precise RSSHub routes.

Every step must adhere to structured route definitions;
fuzzy searches or guessing routes are prohibited.

Your final response must follow the format:
[Core Conclusion]
[Supporting Information] (ordered by importance,
max 30 chars per item + source link)

Before outputting, check for vague terms like "various types"
or "multiple aspects." If present, replace immediately
with specific titles.
""")

这个 System Prompt 包含了提示词工程的四个要素：

上下文管理的三层策略

随着 Tool Calling 循环的进行，上下文窗口面临溢出风险。Spring AI 提供了三层策略：

RssHarness 使用 MessageChatMemoryAdvisor 配合 /new 命令手动重置——对于单次搜索场景，对话轮数通常不超过 15 轮，Token 压力在可控范围内。

⑤ RAG 实战：让 RssHarness 的答案可溯源

大模型的知识截止于训练结束之日，且无法知晓 RSSHub 的实时路由信息。RAG（检索增强生成）是标准解决方案，但 RssHarness 做了一层关键增强。

标准 RAG vs. 可溯源 RAG

RssHarness 的 RAG 流程

用户提问 → LLM 分析意图
→ searchPlatforms("AI") ← 检索：在 ~80 个平台中定位
→ listRoutes("机器之心") ← 检索：在平台内定位具体频道
→ fetchRss(routes) ← 获取：实时 HTTP 抓取
→ readSummaries(routes) ← 增强：读取 AI 摘要
→ LLM 聚合输出 + 溯源链接 ← 生成：带 URL 的回答

关键差异在于结构化路由替代了向量相似度检索。RSSHub 的路由命名空间天然是分层的、精确的——不存在"语义相似但不相关"的噪声。

GEO 提示：根据 Princeton + Georgia Tech + Allen AI 在 KDD 2024 发布的 GEO 研究论文，引用权威来源可使 AI 引用率提升 30-40%，加入统计数据再提升 30-40%——三者叠加后 AI 引用率整体提升 41%。可溯源 RAG 不仅是用户信任问题，也是 AI 是否愿意引用你内容的技术前提[^1]。

⑥ Tool Calling：让模型"行动"起来

这是全文最关键的章节。现代大模型不仅能聊天，还能"行动"。通过 Function Calling 机制，模型可以识别用户意图中需要执行的具体操作，并提取参数，交由本地代码执行。

Spring AI 2.0 的 Tool Calling

在 Spring AI 2.0 中，你只需要给方法加上 @Tool 注解并注册到 ChatClient，框架会自动处理 Tool Calling 循环：

LLM 输出 tool_call → Spring AI 执行 → 结果注入上下文
→ LLM 观察结果 → 决定下一步 → 重复直到输出最终回答

RssHarness 暴露给 LLM 的工具只有 4 个：

以 fetchRss 为例，Tool 定义的完整代码：

@Tool(description = """
FETCH real-time RSS content. MANDATORY — call after listRoutes.
Drop OPTIONAL params (? suffix) entirely.
Fill REQUIRED params with real values.
""")
public List<FetchResponse> fetchRss(
@ToolParam(description = "Exact paths from listRoutes with :params filled")
List<String> routes
) {
List<FetchResponse> results = rssController.fetchRss(routes).join();
lastResults.set(results);
return results;
}

LLM 在看到 @Tool(description = …) 和 @ToolParam(description = …) 后，会自动判断何时调用、传什么参数。开发者只需要声明工具——框架负责编排。

这就是 Agent 的实质

RssHarness 之所以叫 Agent 而不是"搜索工具"，是因为它的控制流是不确定的——每步取决于 LLM 对中间结果的实时判断：

用户: "最近AI有什么进展？"
→ LLM: 先 searchPlatforms("AI") → 返回 5 个平台
→ LLM: 选"机器之心"，listRoutes → 返回 8 个路由
→ LLM: 选 /jiqizhixin/latest，fetchRss → 20 篇文章
→ LLM: readSummaries → 53 条 AI 摘要
→ LLM: 聚合为 3 条核心结论 + 溯源链接

全程没有一行代码规定"先搜什么再读什么"。这就是 Agent 的定义：感知 → 决策 → 执行 → 观察 → 再决策[^2]。

⑦ 多实例容错与异步管道

从 Demo 走向生产，稳定性是首要考量。RssHarness 在 RSS 抓取层实现了三层容错：

滑动窗口健康评分

多个 RSSHub 实例的负载均衡不能用简单轮询——故障实例每轮都会被选到，浪费 3 秒 HTTP 超时。

// RssInstanceManager 的核心逻辑
// Deque<Boolean> — 最近 10 次成功/失败
// 按成功率排序 → 高成功率优先 → 故障实例自动下沉

原子 CAS 消除竞态

@Async + CompletableFuture.allOf 扇出模式下，多个线程可能同时刷新同一个路由：

// ConcurrentHashMap.compute() — 合并 check+set，消除 TOCTOU 窗口
boolean alreadyRefreshing = refreshMarks.compute(route, (k, v) -> {
if (v != null && v) return true; // 已在刷新中
return true; // 标记为刷新中
});

降级保护

AI 摘要失败时不丢失核心数据——自动回退到 placeholder 摘要（保留 title + URL + publishTime）。

设计决策：RssHarness 的全异步管道（@Async + allOf）配合 tryMarkRefresh 原子 CAS 和三实例容错，实测在单实例故障时延迟仅增加 3-5 秒（取决于超时配置），无数据丢失。

⑧ 性能优化与生产部署

流式输出是体验底线

RssHarness 的 CliRunner 实现了三级颜色渲染：灰色=思考过程，青色=工具调用，白色=最终回复。流式输出的感知延迟比非流式低 60% 以上。

成本控制

RssHarness 的 AI 调用分为两层：

以 DeepSeek Chat 的定价（约为 GPT-4 的 1/20），一次完整查询（5 个路由、25 篇文章）的总成本约 ¥0.05-0.15。

Docker 一键部署

export DEEPSEEK_API_KEY=sk-your-key
docker-compose up -d
# RssHarness + RSSHub 全套就绪

生产环境建议配合消息队列削峰填谷，并设置熔断器——当上游 DeepSeek API 不稳定时自动降级为缓存结果或友好提示。

⑨ 安全与合规

防注入

RssHarness 的 System Prompt 中明确设定了行为边界——“fuzzy searches or guessing routes are prohibited”——这是最基础的防注入层：即使用户试图用 Prompt Injection 让模型绕过路由系统，System Prompt 的约束也会阻止。

API Key 管理

三层隔离：环境变量 → application.properties 占位符 → Docker Compose 注入。绝不出现在源码或配置文件中。

数据隐私

RssHarness 处理的全是公开 RSS 订阅源内容，不涉及用户个人身份信息（PII）。私有部署场景下，可切换为 Ollama 本地模型，确保数据不出域。

⑩ 完整案例回顾：RssHarness 全貌

CLI (CliRunner) ← 交互式 REPL，/sync /routes /new
│
AI Domain (ai/) ← Agent 大脑：LLM 决策 + Tool Calling
├─ ConversationService ← 唯一一次 ChatClient 调用
│ ├─ RssTools ← 4 个 @Tool：searchPlatforms / listRoutes
│ │ / fetchRss / readSummaries
│ ├─ RouteCatalog ← 内存路由索引，本地 JSON 持久化
│ └─ RouteSyncTask ← DOM+XPath 从 RSSHub 同步路由
│
RSS Domain (rss/) ← 执行层：异步管道
├─ RouteFetchService ← async allOf 扇出编排
│ ├─ RssFetcher ← 多实例容错 + 滑动窗口
│ ├─ AiSummaryService ← DeepSeek 摘要生成
│ └─ SummaryStorageService ← 适配层 → 存储域
│
Storage Domain (storage/) ← EclipseStore 零配置持久化
├─ DataRoot ← 聚合根即数据库
└─ SummaryView ← CQS 读写视图

FAQ

Q1: Spring AI 和 LangChain 怎么选？

Spring AI 是 Java 生态的原生方案，LangChain 是 Python 生态的方案。如果你已有 Spring Boot 技术栈，Spring AI 2.0 的 Tool Calling、Advisor、ChatMemory 机制完全覆盖了 LangChain 的核心能力，且类型安全、IDE 友好、无需跨语言调用。

Q2: Tool Calling 和 MCP 是什么关系？

Tool Calling 是模型级协议——模型决定调用哪个函数、传什么参数。MCP（Model Context Protocol）是工具级协议——定义工具如何被发现和调用。Spring AI 2.0 目前原生支持 Tool Calling，MCP 支持在路线图上。对 RssHarness 这种工具数量少但调用逻辑复杂的场景，Tool Calling 已经足够。

Q3: RSSHub 路由不够用怎么办？

2025-2026 年，AI 已经可以自动为任意网站生成 RSS 路由了：OpenRSS（36+ AI Agent 驱动）、FeedHub（6 种 LLM）、InsCode（Kimi-K2 零代码生成）。以前"没有 RSS 路由"是阻塞问题，现在让 AI 生成一个，分钟级解决[^3]。

Q4: 一次查询 5 个路由、25 篇文章，成本真的只要 ¥0.05？

是的。DeepSeek Chat 的定价为输入 ¥0.001/1K tokens，输出 ¥0.002/1K tokens。Agent 决策层 Tool Calling 每次约 200-500 tokens，摘要生成每篇约 500-1000 tokens。实测 5 路由 25 篇文章约消耗 30K-60K tokens，总成本 ¥0.05-0.15。你可以在 DeepSeek 控制台 实时监控用量。

写在最后

从 @Tool 注解到 Agent 自主编排，从 SSE 流式输出到多实例容错——Spring AI 2.0 把曾经需要数百行胶水代码的工作压缩到了框架层。RssHarness 只是一个例子：任何需要 LLM 自主决策检索策略的场景，都可以用同一套 Tool Calling 模式解决。

项目开源在 GitHub — RssHarness-dev/RssHarness，Docker 镜像在 makeiny/rss-harness。Star / Issue / PR 都欢迎。

本文基于 Spring Boot 4.1 + Spring AI 2.0.0 + DeepSeek Chat 撰写。RssHarness 53 个测试全绿，Docker 一键部署。