Spring AI 框架完整指南

Spring AI 框架完整指南

Spring AI 是 Spring 生态中专为 AI 工程设计的应用框架，于 2024 年正式推出，并在 2025 年快速发展，已成为 Java 开发者构建生成式 AI 应用的首选工具。它简化了与大型语言模型（LLM）、嵌入模型和向量数据库的集成，让企业级 Java 应用轻松接入 AI 能力，如聊天机器人、RAG（Retrieval Augmented Generation）和智能代理。根据官方文档和 2025 年最新发布（如 Spring AI 1.1 GA），本指南从基础到高级全面解析，结合代码示例和最佳实践，帮助你快速上手。内容基于 Spring 官方文档、GitHub 仓库和 2025 年社区资源。

一、Spring AI 概述

Spring AI 的核心使命是'连接企业数据和 API 与 AI 模型'，它不是 Python AI 框架（如 LangChain）的直接移植，而是为 Java/Spring 生态量身定制，提供可移植的抽象层。不同于传统 Spring 模块，它聚焦生成式 AI，强调简洁性和生产就绪（如自动配置、观测性）。

为什么选择 Spring AI？（2025 年价值）

• Java 原生：无需切换到 Python，保持端到端 Java 开发。
• Spring 集成：无缝嵌入 Spring Boot，支持自动装配和 Starter。
• 多提供商支持：统一 API 接入 OpenAI、Anthropic、Ollama 等，避免供应商锁定。
• 企业级特性：工具调用、RAG、评估框架，解决幻觉（hallucination）和安全性问题。
• 2025 年现状：Spring AI 1.1 GA（2025 年 11 月发布），引入 Agents 框架和 Bench 评估工具；兼容 Spring Framework 7.x 和 Java 21+。

适用场景：聊天助手、文档 Q&A、智能搜索、图像生成、代理式 AI（如代码生成工具）。

二、关键特性

Spring AI 的特性围绕可移植性和易用性设计，以下是核心亮点：

特性	描述	2025 年亮点
ChatClient API	流式/同步聊天接口，类似 WebClient，支持多模型。	集成 MCP（Model Context Protocol）协议，提升代理间通信。
嵌入与向量存储	嵌入模型生成向量，向量数据库（如 PGVector、Neo4j）支持 RAG。	新增 SQL-like 过滤 API，简化元数据查询。
工具/函数调用	模型调用客户端工具（如天气 API），实现实时交互。	@Tool 注解简化服务器暴露，支持 OAuth 安全。
结构化输出	AI 输出映射到 POJO，避免解析 JSON。	增强类型安全，支持复杂对象。
观测性	追踪 AI 操作，支持 Prometheus/OpenTelemetry。	新增聊天完成日志，便于调试。
评估框架	Bench 工具评估生成内容，检测幻觉。	Spring AI Bench：基准测试和评估套件。
文档 ETL	摄取/转换/加载框架，处理企业数据。	升级 Tika 3.2.3，支持多模态（文本 + 图像）。
代理与 Advisors	构建代理模式，封装 AI 模式（如重试、缓存）。	Agents 框架：5 大模式（简单代理、工具链等）。

这些特性让 Spring AI 适用于从简单聊天到复杂代理的场景。