Spring AI 简介

更新:2025-11-25

·

字数:0 字

·

时长:0 分钟

·

阅读:--次

什么是 Spring AI

Spring AI 是 Spring 官方推出的 AI 应用开发框架，旨在简化 AI 功能的集成，让 Java 开发者能够轻松构建包含人工智能能力的应用程序。Spring AI 提供了统一的抽象接口，支持多种 AI 模型提供商，包括 OpenAI、Anthropic、Google、Azure、Amazon 等主流服务商。

Spring AI 的设计理念是解决 AI 集成的核心挑战：如何将企业数据和 API 与 AI 模型无缝连接。它通过提供可移植的 API 抽象层，让开发者可以在不同的 AI 提供商之间轻松切换，而无需重写大量代码。

Spring AI 的起源

Spring AI 项目受到了 Python 生态中 LangChain 和 LlamaIndex 等优秀项目的启发，但它并不是这些项目的直接移植。Spring AI 的创建基于一个核心理念：下一代生成式 AI 应用不应该仅限于 Python 开发者，而应该普及到所有编程语言生态中。

作为 Spring 生态系统的一部分，Spring AI 继承了 Spring 框架的核心优势：依赖注入、自动配置、可测试性等。这使得它能够无缝集成到现有的 Spring Boot 应用中，为 Java 开发者提供了一个熟悉且强大的 AI 开发工具。

Spring AI 发展历程

2023-11-22

• Spring AI 项目启动
• Spring 官方团队宣布启动 Spring AI 项目
• 项目初始概念和设计理念确定

2024-05-01

• 首个 Milestone 版本发布
• Spring AI 发布首个 Milestone 版本
• 支持 OpenAI、Azure OpenAI 等基础模型集成
• 提供 Chat、Embedding 等核心 API

2024-11-14

• Spring AI 1.0.0 GA 正式发布
• 首个稳定版本发布，标志着框架的成熟
• 支持 20+ 种 AI 模型提供商
• 支持 14+ 种向量数据库
• 完整的 RAG、Tool Calling、Chat Memory 等功能

2025-05-20

• Spring AI 1.1.0 GA 发布
• 支持 Model Context Protocol（MCP）集成
• 新增 Prompt Caching（提示缓存）功能
• 支持 Reasoning / "Thinking" Mode（推理模式）
• 增强的 RAG 功能和向量存储支持
• 改进的工具调用和 Chat Memory 功能
• 增强的安全性和可观测性

为什么选择 Spring AI

对于 Java 开发者的天然优势

如果你是一名 Java 开发者，并且已经在使用 Spring Boot、Spring Framework 等 Spring 生态的技术栈，那么选择 Spring AI 是一个水到渠成的决定：

1. 统一的技术栈：无需学习新的框架或工具，Spring AI 完全遵循 Spring 的设计理念和编程模型
2. 无缝集成：可以轻松集成到现有的 Spring Boot 项目中，利用 Spring 的依赖注入、自动配置等特性
3. 熟悉的开发体验：API 设计风格与 Spring WebClient、RestClient 等类似，学习成本低
4. 企业级支持：作为 Spring 官方项目，享有 Spring 生态的完整支持和社区资源

与 LangChain、LangChain4j 的区别

虽然 Spring AI 受到了 LangChain 的启发，但它们之间有着本质的区别：

特性	Spring AI	LangChain	LangChain4j
生态定位	Spring 官方项目，深度集成 Spring 生态	Python 生态的主流框架	LangChain 的 Java 移植版本
设计理念	遵循 Spring 的设计模式，提供可移植的抽象	Python 优先，链式调用模式	尽量保持与 LangChain 的 API 一致性
集成能力	原生支持 Spring Boot 自动配置、依赖注入	需要手动集成到 Java 项目	需要手动集成到 Spring 项目
学习曲线	对 Spring 开发者来说几乎零学习成本	需要学习 Python 生态	需要学习新的 API 模式
企业支持	Spring 官方维护，企业级支持	社区维护	社区维护

核心区别总结：

• LangChain：Python 生态的 AI 框架，专注于链式调用和 Agent 构建
• LangChain4j：LangChain 的 Java 移植，保持了原框架的 API 风格
• Spring AI：Spring 官方项目，深度集成 Spring 生态，提供 Spring 风格的 API 设计

对于已经在使用 Spring 技术栈的 Java 开发者来说，Spring AI 提供了最自然、最无缝的 AI 集成方案。

一直观望在 LangChain 和 Spring AI 这 2 个项目, 之前觉得 Spring AI 1.0.0 版本还不够成熟, 不过现在 1.1.0 版本正式发布后, 在以下几个方面显著增强:

1. Model Context Protocol（MCP）集成
   • Spring AI 1.1 GA 支持 MCP（Model Context Protocol）。
   • 你可以用注解方式定义 Tool / Resource /Prompt：例如 @McpTool、@McpResource、@McpPrompt。
   • 支持多种传输方式（HTTP SSE、STDIO、Streamable HTTP）作为 MCP 通道。
   • 这个协议帮助你构建真正能与模型上下文强耦合并且结构化的交互系统。
2. Prompt Caching（提示缓存）
   • Spring AI 1.1 对部分模型（例如 Anthropic Claude, AWS Bedrock）支持 prompt 缓存策略。这样可以减少调用成本、减少延迟。
   • 支持不同缓存策略（比如系统消息缓存、工具定义缓存、对话历史缓存等）。
3. 思考 / 推理模式（Reasoning / “Thinking” Mode）
   • 1.1 版本引入对一些模型“推理内容 (ReasoningContent)”的支持，你能访问模型内部推理过程。
   • 还提供递归 Advisor（recursive advisors）——可以让一个 advisor 调用另一个 advisor，形成级联 / 多步思考 / self-improving agent。
4. RAG (向量检索 / 检索增强生成)
   • 在 1.0 版本，Spring AI 就支持 RAG，通过 RetrievalAugmentationAdvisor 或 QuestionAnswerAdvisor。
   • 1.1 增强了向量存储 /检索能力：新 vector store 支持（比如 GemFire 的 metadata 过滤机制）。
   • 文档处理方面也改进了（例如 Markdown 文档批量读取器等）。
5. 工具调用 (Tool Calling)
   • Spring AI 一直有 @Tool 注解支持工具调用 (function calling)，1.0 就能做。
   • 在 1.1 / MCP 模式下，工具 (Tool) 可以通过 MCP 协议注册。
   • 工具的 schema（输入 / 输出类型）在 MCP 上可以更严格定义；与 MCP 资源 (Resource) 更好协作。
6. Chat Memory（对话记忆）
   • 支持多种 ChatMemory 后端 (JDBC, Cassandra 等) 来持久化对话历史。
   • 向量形式记忆 (semantic memory) 也支持，通过 vector store 检索历史对话。
7. 安全和可观测性
   • MCP 的安全文档 (OAuth2 等)有介绍。
   • 日志 / 监控增强 (observability) 能力更强。

---

不过 Spring AI 和 LangChain 还是存在差距:

维度	Spring AI 1.1.0	LangChain （以 Python 为主流）
Tool / Function Calling	支持 @Tool + MCP Tool，通过 MCP 协议进行结构化调用。可以注册服务 / API，模型通过 MCP 请求。	支持工具调用 (tools)，LangChain Agent 本身非常依赖工具。定义 Python 函数 / API，然后链式调用。
Agent / 规划	部分支持。Spring AI 更多专注 Advisor 模式 (Advisor 是拦截 /增强 Chat 的机制)，而不是像 LangChain 那种 “Agent planner + executor 的 ReAct 风格” 框架。- 1.1 引入了 recursive advisor，但这不太等同于完整 Agent loop / task planner + executor 模型。	Agent 是核心。LangChain 支持不同类型 Agent（React, MRKL, Planner 等）。Agent 负责规划、决策、工具路由。
RAG / 检索 (retrieval)	支持。通过 Advisor (比如 RetrievalAugmentationAdvisor) 实现 RAG。1.1 支持更多 vector store，增强检索灵活性。Memory + 向量检索都可以和对话结合。	LangChain 对 RAG 建模非常成熟：Document loaders, Embedding, Retriever, Re-rank, Chain，各种检索 + 生成组合都很自然。
Memory (记忆)	支持 ChatMemory (历史) + 向量记忆 (semantic memory) + MCP 资源记忆 (取决你怎么设计)	LangChain 支持 memory 模块：buffer memory, summary memory, vector memory 等。Memory 可以很灵活地插到 chain / agent 中。
多模型 /上下文协议 (MCP)	1.1 支持 MCP (Model Context Protocol)，适用于结构化资源、工具和 prompt 模板。这非常强：可以把工具、资源和提示统一为 MCP 端点。	LangChain 本身没有 “MCP 协议”，但是可以自己封装对不同 LLM 后端 /协议 (HTTP, WebSocket) 使用。LangChain 更自由但协议化程度不如 MCP。
成本优化 /性能	Prompt 缓存 (减少调用成本)；MCP 协议可以做高效交互	主要靠调用策略 +自己管理缓存 /chain /embedding。LangChain 本身没有内置 prompt 缓存（除非你自己做）
生态 & 语言	Java / Spring 生态。如果你在 Spring Boot 系统里，集成非常自然	Python 生态为主，也有 Java (LangChain4j) / JS 版本。用于快速构建 Proof-of-Concept 或 Agent 比较方便。
复杂工作流 /任务规划	通过 Advisor + MCP + 自定义逻辑可以搭建复杂工作流，但不是 “开箱任务规划 Agent”	LangChain 本身就是为了复杂 chain + agent 设计，可以非常容易地定义“agent 做多步任务”的逻辑

• Spring AI 更偏 企业 / Spring Boot 应用 场景：MCP、Advisor、工具注册、安全、Spring 配置非常贴 Java 企业级系统。
• LangChain 更偏 Python 快速构原型 / Agent 强调：它本身就是为“智能 agent”而生。

---

Spring AI 的核心优势

1. 可移植的 API 抽象

Spring AI 提供了统一的 API 接口，支持多种 AI 模型提供商。无论是 OpenAI、Anthropic、Google 还是其他服务商，你都可以使用相同的代码进行开发，只需修改配置即可切换提供商。

2. 全面的模型支持

Spring AI 支持多种类型的 AI 模型：

• Chat 模型：对话生成模型（如 GPT、Claude）
• Embedding 模型：文本嵌入模型（用于向量化）
• Image 模型：图像生成模型（如 DALL-E、Stable Diffusion）
• Audio 模型：音频处理模型（语音转文字、文字转语音）
• Moderation 模型：内容审核模型

3. 企业级特性

• Spring Boot 自动配置：开箱即用的配置，减少样板代码
• 向量数据库集成：支持 20+ 种向量数据库（PostgreSQL、MongoDB、Redis 等）
• RAG 支持：内置检索增强生成（RAG）功能
• 工具调用（Tool Calling）：支持函数调用和工具集成
• 结构化输出：将 AI 输出映射到 POJO 对象
• 对话记忆（Chat Memory）：管理多轮对话的上下文
• 可观测性：提供 AI 操作的监控和追踪能力

4. 开发体验优化

• Fluent API：类似 WebClient 的流式 API 设计，代码简洁易读
• Advisors API：封装常见的 AI 模式，提供可复用的组件
• 测试支持：集成 Testcontainers，方便进行集成测试
• 文档完善：官方文档详细，社区资源丰富

适用场景

Spring AI 特别适合以下场景：

• ✅ 已有 Spring Boot 项目，需要集成 AI 功能
• ✅ 需要支持多个 AI 模型提供商，并能够灵活切换
• ✅ 需要构建企业级 AI 应用，要求稳定性和可维护性
• ✅ 需要实现 RAG（检索增强生成）功能
• ✅ 需要将 AI 功能与现有业务系统深度集成

---

相关资源

官方资源

• 官方文档：Spring AI Reference Documentation
• 官方博客：Your First Spring AI 1.0 Application
• GitHub 仓库：spring-projects/spring-ai

学习资源

• Awesome Spring AI：社区整理的优秀资源集合
• Baeldung 教程：Spring AI 教程
• 语雀文档：Spring AI 中文文档

社区资源

• Spring AI 社区：GitHub Discussions、Stack Overflow
• 示例项目：官方和社区提供的各种示例代码

---

环境准备

在开始学习 Spring AI 之前，我们需要准备好开发环境。由于 Spring AI 需要调用各种 AI 模型的 API，而大多数模型服务都需要 API Key 才能使用。对于国内开发者来说，获取和使用 API Key 可能会遇到一些挑战。

本节将介绍三种推荐的方案，帮助你快速搭建开发环境，无需担心 API Key 的问题。

方案一：使用国内兼容 OpenAI API 的服务商

国内有很多服务商提供了兼容 OpenAI API 格式的服务，这些服务通常对国内用户更友好，访问速度也更快。

推荐服务商

1. 通义千问（阿里云百炼）

   • 提供兼容 OpenAI API 的接口
   • 支持多种模型（Qwen 系列）
   • 访问地址：https://www.aliyun.com/product/bailian

   目前不建议直接使用 qwen3-coder-plus, 因为现在资费太贵了, 3 个小时干掉我 249 软妹币.

2. 硅基流动

   • 提供多种 AI 模型的统一 API 接口
   • 支持 OpenAI、Anthropic 等多种模型
   • 访问地址：https://www.siliconflow.cn/

3. 其他服务商

   • 智谱 AI（GLM 模型）
   • MiniMax（多模态模型）
   • 百度千帆（文心一言）

使用方式

这些服务商通常都提供了兼容 OpenAI API 格式的接口，你只需要：

1. 注册账号并获取 API Key
2. 在 Spring AI 配置中使用兼容的 API 端点
3. 按照服务商的文档配置相应的参数

优点：

• ✅ 对国内用户友好，访问速度快
• ✅ 通常有免费额度或较低的使用成本
• ✅ API 格式兼容，配置简单

缺点：

• ⚠️ 模型能力可能与原版有差异
• ⚠️ 部分服务商可能有调用限制

关于 Spring AI Alibaba

如果你选择使用阿里云通义千问（DashScope）服务，推荐使用 spring-ai-alibaba 项目。这是阿里巴巴基于 Spring AI 框架开发的扩展项目，专门用于集成阿里云 DashScope 模型服务。

项目链接：spring-ai-alibaba

为什么 Spring AI 官方没有集成 DashScope？

Spring AI 作为一个通用的 AI 集成框架，主要关注于提供统一的 API 抽象和多模型支持。我想有以下几点原因，Spring AI 官方并未直接集成 DashScope：

1. 地域性服务：DashScope 是阿里云面向中国市场的 AI 服务，而 Spring AI 作为国际化的开源项目，优先集成了更具全球影响力的模型服务商（如 OpenAI、Anthropic、Google 等）

2. API 兼容性：虽然 DashScope 提供了兼容 OpenAI API 的接口，但其底层实现和特性与标准 OpenAI API 存在差异，需要专门的适配层

3. 社区驱动：Spring AI 鼓励社区贡献扩展项目，阿里巴巴团队开发了 spring-ai-alibaba 来满足国内开发者的需求，这种模式更符合开源社区的分工协作

4. 维护成本：官方维护所有模型集成需要大量资源，而由服务商或社区维护专门的扩展项目，能够提供更好的本地化支持和更快的更新速度

通过使用 spring-ai-alibaba，你可以享受到：

• ✅ 完整的 DashScope 模型支持（Chat、Embedding、Image 等）
• ✅ 与 Spring AI 框架无缝集成
• ✅ 阿里巴巴团队的官方支持和维护
• ✅ 针对国内网络环境的优化

方案二：使用 claude-code-router 代理 Anthropic

claude-code-router 是一个开源项目，可以代理 Anthropic 的 API，并且可以免费使用 ModelScope 提供的多个模型。不过会存在一些 调用限制:

特点

• 支持代理 Anthropic API
• 可以免费使用 ModelScope 的多个模型
• 开源项目，可以自行部署

使用限制

• 有调用频率限制
• 适合学习和开发测试使用

使用方式

1. 部署 claude-code-router 服务

   claude-code-router 项目的初衷是为了解决国内使用 claude-code 的模型限制, 并且开放了代理端口, 因此也为其他客户端使用 Anthropic API 提供了可能.

   claude-code-router 可以通过 WebUI 进行配置管理:

2. 配置 Spring AI 使用代理端点

3. 按照项目文档获取访问凭证

使用 CC Switch 管理配置（推荐）

CC Switch 是一个跨平台桌面应用，专门用于管理 Claude Code、Codex 和 Gemini CLI 的配置。如果你同时使用多个 AI 客户端，CC Switch 可以帮你统一管理配置，提升使用体验。

主要功能：

• ✅ 提供者管理：统一管理多个 AI 服务提供商的配置（Claude、Codex、Gemini 等）
• ✅ MCP 服务器管理：可视化管理 MCP（Model Context Protocol）服务器配置
• ✅ Prompt Presets：创建和管理系统提示词预设，支持 Markdown 编辑和实时预览
• ✅ 配置同步：支持云同步（Dropbox、OneDrive、iCloud 等），实现多设备配置同步
• ✅ 快速切换：一键切换不同的 AI 提供商和配置

与 claude-code-router 配合使用：

使用 CC Switch 可以更方便地管理 Anthropic 相关的配置：

1. 统一配置管理：将 claude-code-router 的配置通过 CC Switch 统一管理
2. 快速切换：在不同代理端点之间快速切换，无需手动编辑配置文件
3. 配置备份：自动备份配置，防止配置丢失
4. 多环境支持：为开发、测试、生产环境配置不同的代理设置

项目链接：CC Switch GitHub

支持的配置目录：

• Claude Code: ~/.claude/settings.json
• Codex: ~/.codex/auth.json 和 config.toml
• Gemini: ~/.gemini/.env 和 settings.json
• CC Switch 主配置: ~/.cc-switch/config.json（SSOT - 单一数据源）

方案三：使用 Ollama 搭建本地环境（推荐）

Ollama 是一个强大的本地 AI 模型运行工具，支持在本地运行各种开源模型。更重要的是，Ollama 还提供了云端模型服务，注册账号后可以免费试用多个强大的云端模型。

Ollama 云端模型

注册 Ollama 账号后，你可以免费试用以下云端模型：

• gpt-oss:120b-cloud - 120B 参数的 GPT 模型
• gpt-oss:20b-cloud - 20B 参数的 GPT 模型
• deepseek-v3.1:671b-cloud - DeepSeek 671B 模型
• qwen3-coder:480b-cloud - Qwen3 代码生成模型（480B）
• qwen3-vl:235b-cloud - Qwen3 视觉语言模型（235B）
• minimax-m2:cloud - MiniMax M2 多模态模型
• glm-4.6:cloud - GLM 4.6 模型

使用方式

1. 注册 Ollama 账号

   • 访问 https://ollama.com/ 注册账号
   • 获取 API Key

2. 配置 Spring AI

   • 在 Spring AI 中配置 Ollama 作为模型提供商
   • 使用云端模型或本地模型

3. 本地部署（可选）

   • 下载 Ollama 客户端
   • 在本地运行开源模型（完全免费，无需 API Key）

方案四：使用 One API + Free API 组合

One API 是一个 LLM API 管理与分发系统，支持 OpenAI、Azure、Anthropic Claude、Google Gemini、DeepSeek 等 20+ 种主流模型，提供统一的 API 适配和密钥管理功能。结合 Free API 提供的免费 API 服务，可以实现对多种大模型的统一管理和免费调用。

使用方式：

1. 部署 One API（提供 Docker 镜像，一键部署）
2. 在 One API 中配置 Free API 作为渠道
3. 在 Spring AI 中使用 One API 的统一接口地址进行调用

⚠️ 注意：Free API 仅供测试使用，禁止对外提供服务或商用。

方案选择建议

场景	推荐方案	理由
快速上手学习	Ollama（云端模型）	免费试用，模型强大，配置简单
本地开发测试	Ollama（本地模型）	完全免费，无需网络，响应快速
生产环境	国内服务商	稳定可靠，有技术支持
多模型切换	One API + Free API	统一接口，支持多种模型，免费使用
预算有限	Ollama 或 One API + Free API	免费或低成本方案
测试对比	One API + Free API	可同时测试多种模型，方便对比

下一步

选择好环境方案后，你就可以开始学习 Spring AI 了。在后续的教程中，我们会使用这些方案之一来演示 Spring AI 的各种功能。

💡 提示：本教程的代码示例会尽量使用兼容性最好的配置，确保你无论选择哪种方案都能顺利运行。

常见问题

作为初学者，在了解 Spring AI 时可能会有以下疑问：

如何判断调用哪个 Tool 或 MCP？

核心答案：工具调用的选择完全由 LLM（大模型）决定，框架只负责提供工具信息和执行工具。

无论是 Spring AI、LangChain 还是 MCP，工具调用的决策流程都是：

用户输入 → LLM 推理 → 选择工具 → 执行工具 → LLM 继续推理 → 输出结果

工具调用的工作机制

1. 工具注册阶段

框架将工具信息（描述、参数 schema、用途）提供给 LLM：

• Spring AI：通过 @Tool 注解将 Java 方法转换为 JSON Schema
• LangChain：通过函数定义和描述注册工具
• MCP：通过 MCP 协议注册工具和资源

2. LLM 决策阶段

LLM 根据以下信息决定是否调用工具以及调用哪个工具：

• 用户输入的意图
• 工具的描述和用途
• 工具的参数要求
• 当前对话上下文

3. 工具执行阶段

框架接收 LLM 的工具调用指令，执行对应的工具，并将结果返回给 LLM 继续处理。

Spring AI 的工具调用流程

1. Spring AI 将 @Tool 注解的方法编译为 JSON Schema
2. 将工具 schema 和用户输入一起发送给 LLM
3. LLM 根据工具描述和用户需求，决定是否调用工具
4. Spring AI 根据 LLM 返回的 tool_call 执行对应的 Java 方法
5. 将工具执行结果返回给 LLM，LLM 继续推理并可能调用更多工具
6. 重复步骤 3-5，直到 LLM 给出最终响应

Spring AI 支持两种工具调用方式：

• Function Calling：基于 OpenAI、Claude、Gemini 等模型的 Function Calling / Tool Calling 机制
• MCP Tool：基于 Model Context Protocol 的工具调用

实际应用示例：博客发布 Agent

假设我们要构建一个自动发布博客的 Agent，场景如下：

发布博客通常需要：编写 Markdown、处理图片、压缩静态文件、上传到 CDN、编译 Markdown、提交 Git 记录等多个步骤。能否开发一个 Agent，只需说"帮我发布博客"就能自动完成这些操作？

第一步：定义工具

为 Agent 注册多个工具，每个工具负责一个具体任务：

• compressImage() - 压缩图片
• uploadToCDN() - 上传到 CDN
• compileMarkdown() - 编译 Markdown
• gitCommit() - 提交 Git
• publishBlog() - 发布博客

每个工具都包含结构化的描述（JSON Schema），包括：

• 工具名称
• 输入参数类型和约束
• 工具用途描述（LLM 用来判断何时调用）

第二步：LLM 自动选择工具

当用户说"帮我发布博客"时，LLM 会：

1. 分析任务需求：需要完成博客发布的完整流程
2. 查看可用工具：发现 publishBlog 工具可以完成这个任务
3. 决定调用工具：选择调用 publishBlog 工具
4. 如果 publishBlog 内部需要多个步骤，LLM 可能会依次调用其他工具（如 compressImage、uploadToCDN 等）

关键点：

• 工具的选择完全由 LLM 决定，不是框架预设的
• 框架的作用是：提供工具列表、执行工具调用、管理工具执行结果
• 工具调用 = LLM 负责决策 + 框架负责执行

---

AI Agent 的工具调用是否可靠？是否会破坏强类型流程？

作为初学者，可能会有这样的疑问：像博客发布、CI/CD 这类流程，我们完全可以用脚本或工作流来完成，而且脚本有强类型校验，参数不对就会直接失败。相比之下，使用 AI Agent 的话，整个流程都依赖 LLM，而 LLM 的不确定性可能导致工具调用失败，比如某个工具需要多个参数，但 LLM 只提供了一个参数。

那么，工具调用（Tool / MCP）到底是不是强类型的？LLM 能否按照工具定义的参数规范来调用？如果 LLM 传错了参数怎么办？

工具调用是强类型的

核心结论：工具参数是强类型的，LLM 生成的是结构化的 JSON 请求。

无论是 Spring AI、LangChain、OpenAI Function Calling 还是 MCP Tool，工具本身都使用严格的参数 schema 定义：

.json

{
  "name": "publishBlog",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {"type": "string"},
      "content": {"type": "string"},
      "tags": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["title", "content"]
  }
}

LLM 的任务是根据用户指令填充这个 JSON，框架会进行严格的类型校验。

双重安全保障机制

第一层：模型本身的 schema 遵循能力

现代 LLM（如 OpenAI、Claude、DeepSeek）的 Function Calling / Tool Calling 已经非常成熟。如果参数描述清晰、required 字段明确、示例充分，模型在大多数情况下会完全按照 schema 返回正确的参数。

第二层：框架的参数校验

Spring AI / LangChain 等框架会：

1. 将模型生成的 JSON 转换为对象
2. 按照 schema 进行 JSON Schema 校验
3. 类型不匹配时直接抛出错误，不会执行工具
4. 将错误反馈给模型，让模型重新生成正确的参数

如果参数校验失败，框架会抛出类似 ArgumentValidationError: field 'title' is required 的错误，并将错误信息反馈给模型，让模型重新生成符合要求的参数。这个过程框架会自动处理，无需手动编写。

工具调用的本质

工具调用并不是"弱类型化"，而是"强类型接口 + LLM 负责构造参数 + 自动错误补偿"。

• 工具执行时仍然是强类型的：最终调用的 Java 方法或函数接口是强类型的
• LLM 只负责参数构造：根据任务目标和工具描述，自动填充参数 JSON
• 框架负责校验和纠错：确保参数符合 schema 后才执行工具

AI Agent = 强类型接口 + LLM 负责构造参数 + 自动补偿错误

Agent vs 脚本：动态性 vs 固定性

脚本（固定流程）：

• 需要手动编写和维护
• 需要手动输入参数
• 流程固定，无法动态决策
• 无法根据场景自动调整

Agent（动态逻辑）：

• 可以根据任务自动规划流程
• 可以动态组合工具
• 可以根据错误自动重试并纠错
• 可以理解自然语言指令
• 可以根据上下文自动补充信息
• 可以跨系统操作（Git、CDN、编译器、Docker 等）

关键区别：Agent 提供了动态决策能力，而脚本是固定的执行流程。

例如，对于指令："帮我发布昨天的博客草稿，但图片压缩成 WebP，顺便检查 SEO，最后推送到 Twitter"，脚本很难处理这种动态需求，而 Agent 可以自动规划并执行。

总结

常见疑问	解答
LLM 调工具会不会乱传参数？	工具是强类型的，LLM 根据 schema 填充 JSON，框架会校验，校验失败会自动重试
会不会破坏原来强类型流程？	工具执行仍然是强类型；LLM 只是生成参数，不控制执行逻辑
脚本能做的事情为什么要用 Agent？	Agent 能动态决策流程、补充信息、跨系统操作、处理不确定性场景
Agent 工程师的工作是什么？	将业务流程拆解成工具，构建 Agent 工作流，让复杂流程可以通过自然语言自动执行

---

自然语言转 Schema：信息不足或参数错误时如何处理？

在实际使用中，可能会遇到以下情况：

1. 信息不足：用户的问题或上下文无法提供足够信息来填充工具的 schema，工具还会被调用吗？
2. 提示来源：如果不能调用，返回给用户的提示是谁生成的？是工具本身还是框架？
3. 错误判断：如果是框架生成的提示，它是如何区分工具调用失败的错误信息和工具成功执行后的正常返回信息？
4. 参数错误：如果 LLM 在填充 schema 时使用了错误的信息（比如错误的文件路径），会导致什么后果？

工具调用的核心原则

关键点：工具调用完全由 LLM 主导，框架只负责执行。

工具调用的流程是：

用户输入 → LLM 分析 → LLM 决定是否调用工具 → LLM 构造参数 → 框架执行工具 → 返回结果给 LLM → LLM 继续处理

框架的作用仅限于：

1. 将工具的 schema 提供给 LLM
2. 解析 LLM 输出的工具调用指令
3. 执行工具并将结果返回给 LLM

框架不做业务逻辑判断，它只负责：

• LLM 要调用工具？执行它
• LLM 不调用工具？不执行

情况一：信息不足时，工具不会被调用

当用户输入和上下文无法提供足够信息来填充必需的 schema 参数时，LLM 会主动拒绝调用工具，并生成澄清问题。

示例：

工具 schema 要求：

{
  "type": "object",
  "properties": {
    "articlePath": {"type": "string"},
    "cdn": {"type": "string"},
    "minify": {"type": "boolean"}
  },
  "required": ["articlePath", "cdn"]
}

用户输入："帮我发布博客"

如果上下文没有 articlePath 信息，LLM 会直接输出：

要发布博客，我需要知道文章的路径（articlePath）。请告诉我文章文件的位置？

重要：

• 这个澄清提示是 LLM 自己生成的，不是框架生成的
• 框架不会判断"信息是否充足"，因为框架不知道业务含义
• 框架只是将 LLM 的输出原样返回给用户

情况二：参数错误时的处理机制

当 LLM 填充的参数出现错误时，有三种处理方式：

A. Schema 校验失败 → 框架拒绝调用

如果参数类型不符合 schema 要求（例如需要 boolean 但传了字符串），框架会在执行前进行校验并拒绝调用：

ArgumentValidationError: field 'minify' must be boolean, got string

框架会将这个错误信息返回给 LLM，LLM 通常会：

1. 识别错误
2. 自动修正参数
3. 重新尝试调用工具

B. Schema 校验通过，但工具执行失败

如果参数类型正确，但语义错误（如文件路径不存在），工具执行时会抛出异常：

FileNotFoundException: article.md not found

框架会捕获这个异常，并将错误信息返回给 LLM。LLM 通常会：

1. 理解错误原因
2. 向用户询问正确的信息
3. 或尝试从上下文推断正确的参数

C. 参数语义正确，但业务逻辑错误

如果用户表达不严谨，而工具也没有额外的业务校验，可能会产生错误结果。这是业务设计问题，需要在工具层面进行：

• 参数验证
• 业务约束检查
• 明确的错误提示

错误信息的来源和判断

错误信息的来源：

1. Schema 校验错误：由框架生成（如 Spring AI、LangChain）
2. 工具执行错误：由工具代码抛出（你编写的业务逻辑）
3. 澄清问题：由 LLM 生成（当信息不足时）

框架如何判断错误：

框架通过以下方式区分错误和正常返回：

1. 异常机制：工具执行抛出异常 → 框架捕获 → 识别为错误
2. 返回状态：工具返回成功/失败状态码 → 框架识别
3. 错误类型：框架会区分不同类型的错误（校验错误、执行错误、业务错误）

框架会将所有错误信息（无论是校验错误还是执行错误）都返回给 LLM，由 LLM 决定如何处理：

• 如果是参数错误，LLM 会尝试修正
• 如果是业务错误，LLM 会向用户询问更多信息
• 如果是系统错误，LLM 会告知用户并建议解决方案

实际应用示例

假设有一个 publishBlog(path: string, cdn: string) 工具：

第一轮：用户说"帮我发布博客"

• LLM 判断：缺少必需参数 path
• LLM 输出："要发布博客，我需要知道文章路径，请告诉我 md 文件的位置？"
• 框架：直接将 LLM 输出返回给用户

第二轮：用户提供路径 "/home/me/blog/new_post.md"

• LLM 构造参数：{path: "/home/me/blog/new_post.md", cdn: "default"}
• 工具执行：发现 cdn="default" 不存在
• 工具抛出错误：error: cdn=default 不存在
• 框架：将错误返回给 LLM
• LLM 输出："default CDN 不存在，请告诉我要使用的 CDN？"

第三轮：用户提供 "cloudflare"

• LLM 重新构造参数：{path: "/home/me/blog/new_post.md", cdn: "cloudflare"}
• 工具执行成功
• 框架：将成功结果返回给 LLM
• LLM：生成最终响应给用户

如何提高工具调用的可靠性？

为了减少 LLM 的不确定性带来的问题，可以采用以下策略：

1. 严格的 Schema 定义：尽可能详细地描述参数类型、约束和用途
2. 业务层校验：在工具代码中进行参数验证和业务约束检查
3. 清晰的错误信息：提供明确的错误提示，帮助 LLM 理解如何修正
4. Few-shot 示例：在工具描述中提供使用示例，引导 LLM 正确调用
5. 多轮对话支持：允许 LLM 通过多轮对话收集完整信息
6. 上下文增强：在对话中维护上下文信息，减少重复询问

总结

问题	答案
信息不足时工具会被调用吗？	不会，LLM 会主动拒绝调用并生成澄清问题
澄清提示是谁生成的？	LLM 自己生成的，框架只是传递消息
框架如何判断错误？	通过异常机制、返回状态和错误类型来识别
参数错误怎么办？	Schema 校验失败由框架拒绝；执行错误由工具抛出，LLM 自动修正
工具调用是强类型吗？	是的，Schema 就是强类型约束，确保参数类型正确

---

LLM 是否会无限纠正重试？

由于 LLM 在工具调用失败时会自动纠正和重试，可能会担心：如果 LLM 一直纠正不过来，会不会无限重试，导致死循环？

框架的保护机制

答案：不会无限重试。所有主流框架都提供了最大重试次数限制机制。

重试流程：

LLM 生成参数 → Schema 校验失败 → 框架返回错误 → LLM 重试
    ↓
LLM 再次生成参数 → Schema 校验失败 → 框架返回错误 → LLM 重试
    ↓
...（重复 N 次）
    ↓
达到最大重试次数 → 框架停止重试 → 返回错误提示给用户

各框架的重试机制

• LangChain：提供 max_retries 参数，可以设置最大重试次数
• OpenAI Function Calling：内置退避机制，自动限制重试次数
• Spring AI：通过 Advisor 可以设置最大尝试次数
• MCP：协议层面支持重试限制配置

当达到最大重试次数时，框架会输出类似以下提示：

我尝试多次仍然无法生成合法参数，请你补充更多信息。

三种错误情况的处理

1. Schema 校验错误（参数类型/结构错误）

• 框架会拒绝调用工具
• 将错误信息返回给 LLM
• LLM 尝试修正参数
• 如果多次修正失败，达到上限后停止

2. 工具执行错误（语义错误，如文件不存在）

• 工具执行时抛出异常
• 框架捕获异常并返回给 LLM
• LLM 根据错误信息尝试修正
• 如果多次修正失败，达到上限后停止

3. 信息不足（无法从上下文获取必需参数）

• LLM 判断信息不足，不会调用工具
• LLM 直接生成澄清问题询问用户
• 不会进入重试循环

如何配置重试策略？

在实际开发中，你可以通过以下方式控制重试行为：

1. 设置最大重试次数：根据业务需求设置合理的上限（通常 3-5 次）
2. 自定义错误处理：在达到重试上限时，提供更友好的错误提示
3. 超时机制：设置工具调用的超时时间，避免长时间等待
4. 降级策略：重试失败后，可以回退到手动处理或使用默认值

最佳实践建议

为了避免无限重试和提升用户体验：

1. 清晰的 Schema 定义：详细的参数描述和示例可以减少重试次数
2. 合理的重试上限：根据工具复杂度设置 3-5 次重试上限
3. 友好的错误提示：在重试失败时，提供明确的指导信息
4. 业务层校验：在工具代码中进行参数验证，提前发现问题
5. 上下文增强：在对话中维护足够的上下文信息，减少信息不足的情况

总结

问题	答案
LLM 会无限重试吗？	不会，所有框架都有最大重试次数限制
达到重试上限后会发生什么？	框架停止重试，返回错误提示给用户
如何避免过多的重试？	提供清晰的 Schema、详细的工具描述、足够的上下文信息
重试失败是工具执行失败吗？	不是，重试失败是 LLM 无法生成合法参数，工具本身不会被调用

---

为什么选择框架而不是可视化 AI 工作流平台？

现在有很多可视化 AI 工作流产品，通过拖拽就能快速开发 Agent，那为什么还要使用 LangChain、Spring AI 这类框架呢？

可视化 AI 工作流 vs 编程框架

可视化 AI 工作流平台的特点：

• 低代码/零代码：通过拖拽节点、连线形成逻辑
• 快速原型：适合简单的文档问答、自动化客服、日志分析等场景
• 集成生态：平台提供 LLM、工具、RAG、函数节点等
• 易上手：适合业务人员，无需编写 Agent 循环、工具调用逻辑

可视化平台的局限性：

1. 灵活性有限：对复杂逻辑（多步 Agent、多工具协作、多层 Planner）实现困难
2. 扩展性有限：企业内部系统（私有 API、内部模板、CI/CD）可能无法直接集成
3. 可控性不足：对参数校验、调用顺序、错误处理、日志追踪等可控性要求高时，拖拽方式可能不够

编程框架（LangChain / Spring AI）的优势：

1. 完全可编程：可以完全控制 Agent 循环逻辑、工具调用、参数校验、错误处理
2. 强类型和安全：Spring AI 支持 Java 强类型工具（@Tool + DTO），结合 MCP，避免参数错误
3. 可集成现有系统：可以直接集成 CI/CD、日志系统、GitOps 工具等内部系统
4. 可测试和可维护：可以做单元测试、集成测试、版本管理，代码易于复用和维护

场景对比

场景	可视化工作流	编程框架
简单任务/快速原型	✅ 快速便捷	✅ 可以但可能过重
多工具协作 + Planner	⚠ 实现复杂	✅ 自由可控
强类型参数/校验	⚠ 支持有限	✅ 完全可控
私有系统/企业内部工具	⚠ 节点受限	✅ 可直接调用内部 API
可测试和可审计	⚠ 不方便	✅ 完全可控
重试/纠错/状态管理	⚠ 可能受限	✅ 自己写 Agent Loop 控制

实际应用场景

以博客发布为例：

可视化工作流可以做到：

• 拖拽节点：MD 编译 → 图片压缩 → 上传 CDN → Git 提交
• 手动配置对应参数

使用编程框架的优势：

• 可以说"帮我发布博客"，LLM 理解意图，自动选择工具节点
• 如果参数缺失或错误，Agent 可以：
  • 多轮询问用户补全参数
  • 调用校验逻辑
  • 结合业务规则和强类型工具安全调用

关键区别：框架让"自然语言 → 工具调用"变得可控、可编程，而不仅仅是固定流程的节点连接。

总结

特性	可视化平台	编程框架
适用场景	快速原型、简单业务自动化	企业级 Agent、复杂业务逻辑
灵活性	受限于平台提供的节点	完全可编程，无限扩展
集成能力	依赖平台生态	可集成任何系统
可控性	有限	完全可控
学习成本	低（拖拽即可）	中高（需要编程）
维护性	依赖平台	代码化管理，易于维护

选择建议：

• 可视化平台：适合快速原型、业务人员、简单自动化场景
• 编程框架：适合复杂业务、企业内部系统集成、强类型校验、多工具协作、需要完全控制权的场景

贡献者

dong4j

页面历史

最后编辑于 1 天前

查看完整历史

7a20f94-fix: 修复 StartedApplication.java 中的代码格式，优化 package.json 和 config.js 配置

184ce2d-refactor(docs): 优化文档侧边栏菜单结构和配置逻辑