Spring AI入门教程一简介与ChatClient API详解一、引言什么是Spring AI随着生成式人工智能的爆发Python 生态中出现了 LangChain、LlamaIndex 等优秀框架但 Java 开发者却缺乏类似的原生支持。Spring AI 的出现填补了这一空白。Spring AI 是 Spring 社区推出的一个旨在简化 AI 应用程序开发的框架。它借鉴了 Python 项目的思想但并非简单移植而是为 Java 开发者量身打造了一套与 AI 模型交互的标准化 API。其核心理念是将企业数据和 API 与 AI 模型无缝连接帮助开发者用熟悉的 Spring 范式快速构建 AI 应用避免陷入复杂的底层实现。Spring AI 支持主流的大语言模型如 OpenAI、DeepSeek、智谱AI 等并提供了模型抽象、提示模板、检索增强生成RAG、工具调用Tool Calling等一系列高级功能的封装。二、快速认知几个核心概念在深入代码之前让我们先快速了解几个 Spring AI 中的重要概念模型Model指各类 AI 算法如文本生成、图像生成、嵌入向量等。Spring AI 当前重点支持语言、图像、音频三种输入输出类型。提示Prompt与模型交互的输入。不同于简单字符串Spring AI 支持多角色系统、用户、助手的提示结构。提示模板Prompt Template利用模板引擎如 StringTemplate动态填充提示中的变量类似 Spring MVC 中的视图。嵌入Embedding将文本转换为浮点数向量用于衡量语义相似度是实现 RAG 的基础。Token模型计费和上下文限制的基本单位。1 个 token 约等于 0.75 个英文单词。结构化输出Structured Output将模型生成的字符串解析为 Java 对象如 JSON → POJO。RAG检索增强生成将私有数据分段存入向量数据库并检索相关片段补充到提示中使模型能回答训练数据之外的问题。工具调用Tool Calling允许模型调用外部 API如查询天气、发送邮件扩展模型能力。对于入门而言你只需先理解模型、提示、结构化输出即可其余概念将在后续教程中展开。三、快速开始搭建第一个 Spring AI 项目3.1 创建 Maven 项目并添加依赖使用 Spring Boot 3.x并引入 Spring AI 的 BOM 及对应的模型 starter以 DeepSeek 和智谱AI 为例。?xml version1.0 encodingUTF-8?projectxmlnshttp://maven.apache.org/POM/4.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsdmodelVersion4.0.0/modelVersionparentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion3.5.14/version!-- 请使用你实际可用的版本 --relativePath//parentgroupIdcom.example/groupIdartifactIdspring-ai-demo/artifactIdversion0.0.1-SNAPSHOT/versionpropertiesjava.version17/java.versionspring-ai.version1.1.6/spring-ai.version/propertiesdependencies!-- Spring Boot Web --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Lombok可选 --dependencygroupIdorg.projectlombok/groupIdartifactIdlombok/artifactIdoptionaltrue/optional/dependency!-- Spring AI DeepSeek Starter --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-deepseek/artifactId/dependency!-- Spring AI 智谱AI Starter --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-zhipuai/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependenciesdependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagement/project注意实际使用时请将spring-ai.version替换为官方最新版本。3.2 配置文件application.yaml配置多个模型DeepSeek 和智谱AI注意API Key 建议使用环境变量切勿硬编码到代码中。spring:application:name:spring-ai-demoai:chat:client:enabled:false# 本教程手动配置 ChatClient Bean故禁用自动配置deepseek:base-url:https://api.deepseek.comapi-key:${DEEPSEEK_API_KEY}# 从环境变量读取chat:enabled:trueoptions:model:deepseek-chattemperature:0.7zhipuai:api-key:${ZHIPU_API_KEY}chat:enabled:trueoptions:model:glm-4-flashtemperature:0.7server:port:81883.3 配置 ChatClient BeanChatClient是 Spring AI 的核心 API它提供了流式构建器风格的方法。我们需要为每个模型创建独立的ChatClient实例。packagecom.example.config;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.ai.deepseek.DeepSeekChatModel;importorg.springframework.ai.zhipuai.ZhiPuAiChatModel;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;ConfigurationpublicclassChatClientConfig{BeanpublicChatClientdeepSeekChatClient(DeepSeekChatModelchatModel){returnChatClient.create(chatModel);}BeanpublicChatClientzhiPuAiChatClient(ZhiPuAiChatModelchatModel){returnChatClient.create(chatModel);}}至此项目环境已准备就绪下面正式进入ChatClientAPI 的使用。四、ChatClient API 详解与实战ChatClient采用了流畅的建造者模式核心方法包括prompt()开始构建提示。user()/system()添加用户或系统角色消息。call()同步调用并获取ChatResponse或content()。stream()异步流式调用。entity()将模型输出直接映射为 Java 对象。metadata()为消息附加元数据。下面通过一个RestController来展示各种用法。4.1 基础对话选择合适的模型RestControllerSlf4jpublicclassChatController{Resource(namedeepSeekChatClient)privateChatClientdeepSeekClient;Resource(namezhiPuAiChatClient)privateChatClientzhiPuClient;RequestMapping(/chat)publicStringchat(Stringquestion,Stringmodel){ChatClientclientdeepSeek.equals(model)?deepSeekClient:zhiPuClient;returnclient.prompt(question).call().content();}}访问http://localhost:8188/chat?question你好modeldeepSeek即可获得回答。4.2 多客户端流程演示有时我们需要同时使用不同的 API Key 或不同模型进行对比可以手动创建ChatClient实例。ResourceprivateZhiPuAiChatModelzhiPuAiChatModel;// 注入默认配置的模型RequestMapping(/multi-client)publicStringmultiClientDemo(){// 创建第二个独立配置的智谱模型 (glm-4-plus)ZhiPuAiApiapi2ZhiPuAiApi.builder().apiKey(your-second-api-key).build();ZhiPuAiChatModelmodel2newZhiPuAiChatModel(api2,ZhiPuAiChatOptions.builder().model(glm-4-plus).temperature(0.8).build());ChatClientclient2ChatClient.create(model2);Stringresponse1zhiPuAiChatModel.call(介绍一下人工智能).getResult().getOutput().getText();Stringresponse2client2.prompt(介绍一下人工智能).call().content();returnDefault Model: response1\n\nCustom Model: response2;}4.3 返回结构化实体AI 模型的原始输出是字符串但我们可以通过entity()方法并提供一个 POJO 类让 Spring AI 自动将输出解析为对象。这背后使用了精心构造的提示词和 JSON 转换器。定义实体类publicrecordActorFilms(Stringactor,ListStringmovies){}控制器方法RequestMapping(/entity)publicActorFilmsgetActorFilms(RequestParam(defaultValue周星驰)StringactorName){returnzhiPuClient.prompt().user(请生成演员actorName的代表作电影列表包含5部电影).call().entity(ActorFilms.class);}返回 List 泛型时需要使用ParameterizedTypeReferenceRequestMapping(/entity-list)publicListActorFilmsgetActorList(){returnzhiPuClient.prompt().user(生成 Tom Hanks 和 Leonardo DiCaprio 的电影列表每人5部).call().entity(newParameterizedTypeReferenceListActorFilms(){});}4.4 流式响应对于长文本生成流式输出能提升用户体验。返回类型需设置为text/event-stream。RequestMapping(value/stream,producesMediaType.TEXT_EVENT_STREAM_VALUE)publicFluxStringstreamResponse(RequestParam(defaultValue讲一个故事)Stringquestion){returnzhiPuClient.prompt(question).stream().content();}如果需要获取完整的ChatResponse对象包含 token 使用量等元数据RequestMapping(value/stream-response,producesMediaType.TEXT_EVENT_STREAM_VALUE)publicFluxChatResponsestreamChatResponse(RequestParam(defaultValue讲一个笑话)Stringquestion){returnzhiPuClient.prompt(question).stream().chatResponse();}4.5 使用元数据标记消息metadata()可以为系统或用户消息附加额外的键值对信息便于追踪、调试或下游处理。RequestMapping(/metadata)publicStringmetadataDemo(){returnzhiPuClient.prompt().system(s-s.text(你是一个技术客服).metadata(agentId,agent-001).metadata(version,2.0)).user(u-u.text(Spring AI 如何配置多模型).metadata(userId,12345).metadata(sessionId,UUID.randomUUID().toString())).call().content();}