# Spring AI Alibaba Agent 开发教程 ## 1. AI 基础概念 ### 1.1 什么是 LLM LLM（Large Language Model，大语言模型）是一种通过海量文本数据训练得到的人工智能模型，能够理解并生成自然语言。 常见模型： - GLM（智谱AI） - DeepSeek - OpenAI GPT - 阿里千问 --- ### 1.2 Token Token 是模型处理文本时的最小单位。 大致规则： - 一个中文 ≈ 1 个 token - 英文单词可能会被拆分成多个 token Token 会直接影响： - 调用成本 - 上下文长度 - 响应速度 --- ### 1.3 Prompt Prompt（提示词）是发送给 AI 的指令。 示例： \`\`\`text 你是一个 Java 专家，请帮我解释 SpringBoot 自动装配原理。 \`\`\` Prompt 的质量会直接影响模型输出结果。 --- ### 1.4 Message 消息角色 目前主流大模型接口通常支持以下消息类型： \| 角色 \| 说明 \| \|---\|---\| \| system \| 系统消息，定义 AI 角色 \| \| user \| 用户输入 \| \| assistant \| AI 回复 \| \| tool \| 工具调用消息 \| --- ## 2. Spring AI Alibaba 概述 Spring AI Alibaba 是基于 Spring AI 的增强组件。 核心能力： - 多模型统一接入 - Tool Calling - RAG - MCP - Graph 工作流 - 多智能体编排 支持模型： - 智谱AI - DeepSeek - OpenAI - 千问 官方文档： \`\`\`text https://java2ai.com/docs/ \`\`\` --- # 3. Spring AI Alibaba 快速入门 ## 3.1 环境要求 \| 组件 \| 版本 \| \|---\|---\| \| JDK \| 17 \| \| SpringBoot \| 3.4.0 \| \| Spring AI \| 1.0.0 \| \| Spring AI Alibaba \| 1.0.0.4 \| --- ## 3.2 API Key 配置 建议使用环境变量保存 API Key。 ### Windows \`\`\`text 系统环境变量： ZHIPU_KEY=你的APIKey \`\`\` ### Mac/Linux \`\`\`bash export ZHIPU_KEY="你的APIKey" \`\`\` --- ## 3.3 Maven 依赖 ### 父工程依赖管理 \`\`\`xml org.springframework.boot spring-boot-dependencies 3.4.0 pom import org.springframework.ai spring-ai-bom 1.0.0 pom import \`\`\` --- ### 子工程依赖 \`\`\`xml org.springframework.boot spring-boot-starter-web org.springframework.ai spring-ai-starter-model-zhipuai \`\`\` --- ## 3.4 application.yml \`\`\`yaml server: port: 8080 spring: ai: zhipuai: api-key: ${ZHIPU_KEY} base-url: https://open.bigmodel.cn/api/paas chat: options: model: glm-4.5 \`\`\` --- ## 3.5 启动类 \`\`\`java @SpringBootApplication public class ZhipuAIApplication { public static void main(String\[\] args) { SpringApplication.run(ZhipuAIApplication.class,args); } } \`\`\` --- ## 3.6 ChatModel 调用模型 \`\`\`java @RestController @RequestMapping("/zhipuai") public class ZhipuChatController { private final ChatModel chatModel; public ZhipuChatController(ChatModel chatModel) { this.chatModel = chatModel; } @GetMapping("/simple") public String simpleChat(String query){ return chatModel.call(query); } } \`\`\` 测试接口： \`\`\`text http://localhost:8080/zhipuai/simple?query=你是谁 \`\`\` --- # 4. Spring AI 核心 API ## 4.1 Message Spring AI 将请求中的消息抽象为 Message。 主要实现： - UserMessage - SystemMessage - AssistantMessage - ToolMessage 示例： \`\`\`java SystemMessage systemMessage = new SystemMessage("你是一个Java专家"); UserMessage userMessage = new UserMessage("什么是IOC"); chatModel.call(systemMessage,userMessage); \`\`\` --- ## 4.2 Prompt Prompt = 消息 + 模型参数。 示例： \`\`\`java Prompt prompt = new Prompt( List.of(systemMessage,userMessage), zhiPuAiChatOptions ); \`\`\` --- ## 4.3 ChatOptions 常用参数： \| 参数 \| 作用 \| \|---\|---\| \| temperature \| 随机性 \| \| top-p \| 多样性 \| \| maxTokens \| 最大输出长度 \| \| model \| 使用模型 \| 示例： \`\`\`java ZhiPuAiChatOptions options = ZhiPuAiChatOptions.builder() .model("glm-4.5") .temperature(0.7) .maxTokens(4096) .build(); \`\`\` --- # 5. ChatClient ## 5.1 ChatClient 概述 ChatClient 是 Spring AI 提供的高级 API。 相比 ChatModel： - 使用更简单 - 支持链式调用 - 支持 Tool Calling - 支持 RAG - 支持 Advisor - 支持结构化输出 --- ## 5.2 创建 ChatClient \`\`\`java private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient = builder.build(); } \`\`\` --- ## 5.3 调用模型 \`\`\`java @GetMapping("/simple") public String simpleChat(){ return chatClient.prompt() .system("你是一个AI助手") .user("介绍一下SpringBoot") .call() .content(); } \`\`\` --- ## 5.4 流式响应 \`\`\`java @GetMapping("/stream") public Flux stream(){ return chatClient.prompt() .user("介绍一下Spring Cloud") .stream() .content(); } \`\`\` --- ## 5.5 结构化输出 ### 定义实体类 \`\`\`java @Data public class Book { private String name; private String author; } \`\`\` --- ### AI 返回对象 \`\`\`java @GetMapping("/book") public Book book(){ return chatClient.prompt() .user("随机生成一本中文书籍") .call() .entity(Book.class); } \`\`\` --- # 6. Advisors ## 6.1 Advisor 概述 Advisor 类似于 Spring MVC 的拦截器。 主要作用： - 对请求增强 - 对响应增强 - 对话记忆 - 敏感词过滤 - RAG --- ## 6.2 自定义 Advisor \`\`\`java @Slf4j public class SGCallAdvisor1 implements CallAdvisor { @Override public ChatClientResponse adviseCall(ChatClientRequest request, CallAdvisorChain chain) { log.info("请求进入Advisor"); ChatClientResponse response = chain.nextCall(request); log.info("响应离开Advisor"); return response; } @Override public String getName() { return "SGCallAdvisor1"; } @Override public int getOrder() { return 0; } } \`\`\` --- ## 6.3 添加 Advisor \`\`\`java chatClient.prompt() .user(query) .advisors(new SGCallAdvisor1()) .call() .content(); \`\`\` --- # 7. PromptTemplate ## 7.1 为什么需要 PromptTemplate 避免硬编码字符串拼接。 传统写法： \`\`\`java String prompt = "你是" + name + "请回答" + question; \`\`\` 推荐写法： \`\`\`java PromptTemplate template = new PromptTemplate( "你是{name}，请回答：{question}" ); \`\`\` --- ## 7.2 使用方式 \`\`\`java PromptTemplate template = new PromptTemplate( "你是{name}，请回答：{question}" ); template.add("name","小白"); template.add("question","什么是SpringBoot"); String result = template.render(); \`\`\` --- # 8. RAG 检索增强生成 ## 8.1 什么是 RAG RAG（Retrieval-Augmented Generation）即： 检索增强生成。 流程： \`\`\`text 用户问题 ↓ 向量检索 ↓ 获取相关知识 ↓ 知识 + 问题发送给大模型 ↓ 生成最终回答 \`\`\` --- ## 8.2 向量相关概念 \| 概念 \| 说明 \| \|---\|---\| \| Embedding \| 文本向量化 \| \| 向量数据库 \| 存储向量 \| \| 相似度搜索 \| 查找语义相近内容 \| --- ## 8.3 Docker 安装 redis-stack \`\`\`bash docker run -d \\ --name redis-stack \\ -p 6379:6379 \\ -p 8001:8001 \\ redis/redis-stack:latest \`\`\` --- ## 8.4 Redis VectorStore 配置 \`\`\`yaml spring: ai: vectorstore: redis: initialize-schema: true index: sangeng_rag_index prefix: sangeng_rag_prefix \`\`\` --- ## 8.5 VectorStore 存储数据 \`\`\`java @GetMapping("/import") public void importData(String content){ List documents = List.of(new Document(content)); vectorStore.add(documents); } \`\`\` --- ## 8.6 相似度搜索 \`\`\`java @PostMapping("/search") public List search(String query){ SearchRequest request = SearchRequest.builder() .query(query) .topK(10) .similarityThreshold(0.8) .build(); return vectorStore.similaritySearch(request); } \`\`\` --- # 9. Tool Calling ## 9.1 什么是 Tool Calling Tool Calling 可以让 AI 调用外部工具。 例如： - 获取当前时间 - 查询天气 - 调用数据库 - 调用第三方 API --- ## 9.2 定义工具 \`\`\`java public class TimeTools { @Tool(description = "根据时区获取时间") public String getTimeByZoneId( @ToolParam(description = "时区ID") String zoneId){ ZoneId zid = ZoneId.of(zoneId); return ZonedDateTime.now(zid).toString(); } } \`\`\` --- ## 9.3 使用工具 \`\`\`java @GetMapping("/ask") public String ask(String question){ return chatClient.prompt() .user(question) .tools(new TimeTools()) .call() .content(); } \`\`\` --- # 10. MCP ## 10.1 什么是 MCP MCP（Model Context Protocol）是 Anthropic 推出的开放协议。 作用： 统一 AI 与外部工具的通信协议。 --- ## 10.2 MCP 核心角色 \| 角色 \| 说明 \| \|---\|---\| \| MCP Host \| AI应用 \| \| MCP Client \| MCP客户端 \| \| MCP Server \| 提供工具服务 \| --- ## 10.3 MCP 服务端依赖 \`\`\`xml org.springframework.ai spring-ai-starter-mcp-server-webflux \`\`\` --- ## 10.4 MCP 客户端依赖 \`\`\`xml org.springframework.ai spring-ai-starter-mcp-client-webflux \`\`\` --- # 11. Graph 工作流 ## 11.1 什么是 Graph Graph 是 Spring AI Alibaba 提供的 AI 工作流编排引擎。 用于： - Agent 工作流 - 多智能体协作 - 条件流转 - 状态管理 --- ## 11.2 Graph 核心概念 \| 概念 \| 说明 \| \|---\|---\| \| State \| 状态 \| \| Node \| 节点 \| \| Edge \| 边 \| --- ## 11.3 Graph 依赖 \`\`\`xml com.alibaba.cloud.ai spring-ai-alibaba-graph-core \`\`\` --- ## 11.4 定义 Graph \`\`\`java StateGraph stateGraph = new StateGraph("quickStartGraph", keyStrategyFactory); \`\`\` --- ## 11.5 添加节点 \`\`\`java stateGraph.addNode("node1", node_async(state -\> { return Map.of("input1",1); })); \`\`\` --- ## 11.6 添加边 \`\`\`java stateGraph.addEdge(StateGraph.START,"node1"); stateGraph.addEdge("node1","node2"); stateGraph.addEdge("node2",StateGraph.END); \`\`\` --- ## 11.7 编译 Graph \`\`\`java CompiledGraph graph = stateGraph.compile(); \`\`\` --- ## 11.8 调用 Graph \`\`\`java Optional result = graph.call(Map.of()); \`\`\` --- # 12. 英语学习助手案例 ## 12.1 功能需求 输入一个单词： - AI 自动造句 - 自动翻译 - 返回中英文结果 --- ## 12.2 工作流设计 \`\`\`text 输入单词 ↓ 造句节点 ↓ 翻译节点 ↓ 输出结果 \`\`\` --- ## 12.3 造句节点 \`\`\`java public class SentenceConstructionNode implements NodeAction { @Override public Map apply(OverAllState state) throws Exception { String word = state.value("word",""); String result = chatClient.prompt() .user("请使用单词造句：" + word) .call() .content(); return Map.of("sentence",result); } } \`\`\` --- ## 12.4 翻译节点 \`\`\`java public class TranslationNode implements NodeAction { @Override public Map apply(OverAllState state) throws Exception { String sentence = state.value("sentence",""); String result = chatClient.prompt() .user("翻译下面句子：" + sentence) .call() .content(); return Map.of("translation",result); } } \`\`\` --- # 13. 总结 Spring AI Alibaba 核心能力： - ChatModel - ChatClient - PromptTemplate - Advisor - Tool Calling - RAG - MCP - Graph 推荐学习顺序： \`\`\`text ChatModel → ChatClient → Advisor → PromptTemplate → RAG → Tool Calling → MCP → Graph \`\`\` --- # 14. 参考资料 ## Spring AI \`\`\`text https://docs.spring.io/spring-ai/reference/ \`\`\` ## Spring AI Alibaba \`\`\`text https://java2ai.com/docs/ \`\`\` ## MCP 官方文档 \`\`\`text https://modelcontextprotocol.io/docs/ \`\`\` --- # END