【第1篇】Spring AI Alibaba 示例项目 - 最佳学习路线（从易到难）

📚 项目概况

开源项目镜像地址：https://gitcode.com/gh_mirrors/sp/examples/tree/main 它是一个完整的 Spring AI Alibaba 示例集合，涵盖了从基础对话到高级 AI 应用开发的 30+ 个功能模块，支持阿里云通义千问、OpenAI、Azure、DeepSeek、ZhiPu、Moonshot 、本地模型等多个模型。

核心价值：这是 Java 开发者进入 AI 应用开发的最短路径——基于熟悉的 Spring 生态，无需学习 Python 或前端技术，就能构建生产级的 AI 应用。

🗺️ 学习路线图

🟢 第一阶段：Hello World 入门

目标：搭建环境，理解基本概念，建立信心

这是你的第一个 AI 应用。就像学习任何新框架时先写 “Hello World” 一样，这个阶段让你快速验证环境是否就绪，并理解 Spring AI Alibaba 最基础的调用方式。

#mermaid-svg-H1FJZJvvvlclRu5o{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-H1FJZJvvvlclRu5o .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-H1FJZJvvvlclRu5o .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-H1FJZJvvvlclRu5o .error-icon{fill:#552222;}#mermaid-svg-H1FJZJvvvlclRu5o .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-H1FJZJvvvlclRu5o .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-H1FJZJvvvlclRu5o .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-H1FJZJvvvlclRu5o .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-H1FJZJvvvlclRu5o .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-H1FJZJvvvlclRu5o .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-H1FJZJvvvlclRu5o .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-H1FJZJvvvlclRu5o .marker{fill:#333333;stroke:#333333;}#mermaid-svg-H1FJZJvvvlclRu5o .marker.cross{stroke:#333333;}#mermaid-svg-H1FJZJvvvlclRu5o svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-H1FJZJvvvlclRu5o p{margin:0;}#mermaid-svg-H1FJZJvvvlclRu5o .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-H1FJZJvvvlclRu5o .cluster-label text{fill:#333;}#mermaid-svg-H1FJZJvvvlclRu5o .cluster-label span{color:#333;}#mermaid-svg-H1FJZJvvvlclRu5o .cluster-label span p{background-color:transparent;}#mermaid-svg-H1FJZJvvvlclRu5o .label text,#mermaid-svg-H1FJZJvvvlclRu5o span{fill:#333;color:#333;}#mermaid-svg-H1FJZJvvvlclRu5o .node rect,#mermaid-svg-H1FJZJvvvlclRu5o .node circle,#mermaid-svg-H1FJZJvvvlclRu5o .node ellipse,#mermaid-svg-H1FJZJvvvlclRu5o .node polygon,#mermaid-svg-H1FJZJvvvlclRu5o .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-H1FJZJvvvlclRu5o .rough-node .label text,#mermaid-svg-H1FJZJvvvlclRu5o .node .label text,#mermaid-svg-H1FJZJvvvlclRu5o .image-shape .label,#mermaid-svg-H1FJZJvvvlclRu5o .icon-shape .label{text-anchor:middle;}#mermaid-svg-H1FJZJvvvlclRu5o .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-H1FJZJvvvlclRu5o .rough-node .label,#mermaid-svg-H1FJZJvvvlclRu5o .node .label,#mermaid-svg-H1FJZJvvvlclRu5o .image-shape .label,#mermaid-svg-H1FJZJvvvlclRu5o .icon-shape .label{text-align:center;}#mermaid-svg-H1FJZJvvvlclRu5o .node.clickable{cursor:pointer;}#mermaid-svg-H1FJZJvvvlclRu5o .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-H1FJZJvvvlclRu5o .arrowheadPath{fill:#333333;}#mermaid-svg-H1FJZJvvvlclRu5o .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-H1FJZJvvvlclRu5o .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-H1FJZJvvvlclRu5o .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-H1FJZJvvvlclRu5o .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-H1FJZJvvvlclRu5o .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-H1FJZJvvvlclRu5o .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-H1FJZJvvvlclRu5o .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-H1FJZJvvvlclRu5o .cluster text{fill:#333;}#mermaid-svg-H1FJZJvvvlclRu5o .cluster span{color:#333;}#mermaid-svg-H1FJZJvvvlclRu5o div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-H1FJZJvvvlclRu5o .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-H1FJZJvvvlclRu5o rect.text{fill:none;stroke-width:0;}#mermaid-svg-H1FJZJvvvlclRu5o .icon-shape,#mermaid-svg-H1FJZJvvvlclRu5o .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-H1FJZJvvvlclRu5o .icon-shape p,#mermaid-svg-H1FJZJvvvlclRu5o .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-H1FJZJvvvlclRu5o .icon-shape .label rect,#mermaid-svg-H1FJZJvvvlclRu5o .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-H1FJZJvvvlclRu5o .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-H1FJZJvvvlclRu5o .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-H1FJZJvvvlclRu5o :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户请求

ChatClient

AI模型

流式响应

对话记忆Advisor

核心概念解析：

• ChatClient：面向开发者的友好 API，封装了与 AI 模型的交互细节。你可以把它想象成一个"翻译官"——你说人话，它帮你转成模型能懂的格式，再把模型的回复转成人话。
• ChatModel：底层模型接口，更灵活但需要你手动处理提示词模板。
• Advisor（对话记忆）：Spring AI 的"记忆插件"，让 AI 记得你们之前的对话内容，实现多轮对话。

模块：spring-ai-alibaba-helloworld

代码示例：

@GetMapping("/simple/chat")
public String simpleChat() {
return chatClient.prompt()
.user("你好，介绍一下你自己")
.call()
.content();
}

动手实操步骤：

避坑指南：

• 确保 Java 版本 ≥ 17（Spring AI Alibaba 的硬性要求）
• 如果 API 调用失败，先检查环境变量是否正确设置
• 流式响应需要前端支持 SSE（Server-Sent Events），测试时可以用 curl 观察效果

如果不想用阿里模型，也可以使用自己想用的，第2篇中会做一下些许的微调实现。

🟡 第二阶段：多模型对话

目标：掌握多模型切换和参数配置，理解不同模型的特点

当你能调用通义千问后，自然会想：能不能换成 GPT-4？能不能用 DeepSeek？这个阶段让你掌握"一个代码库，多模型切换"的能力。

#mermaid-svg-3uH7B1FVGQMuzsj3{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-3uH7B1FVGQMuzsj3 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-3uH7B1FVGQMuzsj3 .error-icon{fill:#552222;}#mermaid-svg-3uH7B1FVGQMuzsj3 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-3uH7B1FVGQMuzsj3 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-3uH7B1FVGQMuzsj3 .marker.cross{stroke:#333333;}#mermaid-svg-3uH7B1FVGQMuzsj3 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-3uH7B1FVGQMuzsj3 p{margin:0;}#mermaid-svg-3uH7B1FVGQMuzsj3 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-3uH7B1FVGQMuzsj3 .cluster-label text{fill:#333;}#mermaid-svg-3uH7B1FVGQMuzsj3 .cluster-label span{color:#333;}#mermaid-svg-3uH7B1FVGQMuzsj3 .cluster-label span p{background-color:transparent;}#mermaid-svg-3uH7B1FVGQMuzsj3 .label text,#mermaid-svg-3uH7B1FVGQMuzsj3 span{fill:#333;color:#333;}#mermaid-svg-3uH7B1FVGQMuzsj3 .node rect,#mermaid-svg-3uH7B1FVGQMuzsj3 .node circle,#mermaid-svg-3uH7B1FVGQMuzsj3 .node ellipse,#mermaid-svg-3uH7B1FVGQMuzsj3 .node polygon,#mermaid-svg-3uH7B1FVGQMuzsj3 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-3uH7B1FVGQMuzsj3 .rough-node .label text,#mermaid-svg-3uH7B1FVGQMuzsj3 .node .label text,#mermaid-svg-3uH7B1FVGQMuzsj3 .image-shape .label,#mermaid-svg-3uH7B1FVGQMuzsj3 .icon-shape .label{text-anchor:middle;}#mermaid-svg-3uH7B1FVGQMuzsj3 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-3uH7B1FVGQMuzsj3 .rough-node .label,#mermaid-svg-3uH7B1FVGQMuzsj3 .node .label,#mermaid-svg-3uH7B1FVGQMuzsj3 .image-shape .label,#mermaid-svg-3uH7B1FVGQMuzsj3 .icon-shape .label{text-align:center;}#mermaid-svg-3uH7B1FVGQMuzsj3 .node.clickable{cursor:pointer;}#mermaid-svg-3uH7B1FVGQMuzsj3 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-3uH7B1FVGQMuzsj3 .arrowheadPath{fill:#333333;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-3uH7B1FVGQMuzsj3 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-3uH7B1FVGQMuzsj3 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-3uH7B1FVGQMuzsj3 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-3uH7B1FVGQMuzsj3 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-3uH7B1FVGQMuzsj3 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-3uH7B1FVGQMuzsj3 .cluster text{fill:#333;}#mermaid-svg-3uH7B1FVGQMuzsj3 .cluster span{color:#333;}#mermaid-svg-3uH7B1FVGQMuzsj3 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-3uH7B1FVGQMuzsj3 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-3uH7B1FVGQMuzsj3 rect.text{fill:none;stroke-width:0;}#mermaid-svg-3uH7B1FVGQMuzsj3 .icon-shape,#mermaid-svg-3uH7B1FVGQMuzsj3 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-3uH7B1FVGQMuzsj3 .icon-shape p,#mermaid-svg-3uH7B1FVGQMuzsj3 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-3uH7B1FVGQMuzsj3 .icon-shape .label rect,#mermaid-svg-3uH7B1FVGQMuzsj3 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-3uH7B1FVGQMuzsj3 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-3uH7B1FVGQMuzsj3 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-3uH7B1FVGQMuzsj3 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

dashscope

openai

moonshot

deepseek

ollama

配置文件

模型选择

通义千问

GPT-4

月之暗面

DeepSeek

本地模型

统一ChatClient接口

核心概念解析：

• Temperature（温度）：控制 AI 的"创造力"。0.1 是严谨的书呆子（适合代码生成），1.0 是脑洞大开的艺术家（适合创意写作）。
• MaxTokens（最大令牌）：控制回复长度。一个 token 约等于 0.75 个汉字，2000 tokens 大概能输出 1500 字。
• 多模态：让 AI 能"看懂"图片，实现图文对话。

模块：spring-ai-alibaba-chat-example

配置示例：

spring:
ai:
dashscope:
api-key: ${AI_DASHSCOPE_API_KEY}
chat:
model: qwen–plus # 可选: qwen-turbo, qwen-max, qwen-coder
options:
temperature: 0.7 # 0-1之间，越小越确定，越大越创意
max-tokens: 2000 # 控制回复长度

支持的模型平台：

动手实操：

🟠 第三阶段：工具调用（Tool Calling）

目标：让 AI 调用外部工具，实现真实业务场景

这是 AI 从"聊天机器人"进化到"智能助手"的关键一步。通过工具调用，AI 可以查天气、调 API、操作数据库，真正帮你干活。

工具服务

AI模型

用户

工具服务

AI模型

用户

#mermaid-svg-dkfKDlc2vIMGDiGk{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-dkfKDlc2vIMGDiGk .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-dkfKDlc2vIMGDiGk .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-dkfKDlc2vIMGDiGk .error-icon{fill:#552222;}#mermaid-svg-dkfKDlc2vIMGDiGk .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-dkfKDlc2vIMGDiGk .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-dkfKDlc2vIMGDiGk .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-dkfKDlc2vIMGDiGk .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-dkfKDlc2vIMGDiGk .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-dkfKDlc2vIMGDiGk .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-dkfKDlc2vIMGDiGk .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-dkfKDlc2vIMGDiGk .marker{fill:#333333;stroke:#333333;}#mermaid-svg-dkfKDlc2vIMGDiGk .marker.cross{stroke:#333333;}#mermaid-svg-dkfKDlc2vIMGDiGk svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-dkfKDlc2vIMGDiGk p{margin:0;}#mermaid-svg-dkfKDlc2vIMGDiGk .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-dkfKDlc2vIMGDiGk text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-dkfKDlc2vIMGDiGk .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-dkfKDlc2vIMGDiGk .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-dkfKDlc2vIMGDiGk .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-dkfKDlc2vIMGDiGk .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-dkfKDlc2vIMGDiGk #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-dkfKDlc2vIMGDiGk .sequenceNumber{fill:white;}#mermaid-svg-dkfKDlc2vIMGDiGk #sequencenumber{fill:#333;}#mermaid-svg-dkfKDlc2vIMGDiGk #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-dkfKDlc2vIMGDiGk .messageText{fill:#333;stroke:none;}#mermaid-svg-dkfKDlc2vIMGDiGk .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-dkfKDlc2vIMGDiGk .labelText,#mermaid-svg-dkfKDlc2vIMGDiGk .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-dkfKDlc2vIMGDiGk .loopText,#mermaid-svg-dkfKDlc2vIMGDiGk .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-dkfKDlc2vIMGDiGk .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-dkfKDlc2vIMGDiGk .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-dkfKDlc2vIMGDiGk .noteText,#mermaid-svg-dkfKDlc2vIMGDiGk .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-dkfKDlc2vIMGDiGk .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-dkfKDlc2vIMGDiGk .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-dkfKDlc2vIMGDiGk .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-dkfKDlc2vIMGDiGk .actorPopupMenu{position:absolute;}#mermaid-svg-dkfKDlc2vIMGDiGk .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-dkfKDlc2vIMGDiGk .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-dkfKDlc2vIMGDiGk .actor-man circle,#mermaid-svg-dkfKDlc2vIMGDiGk line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-dkfKDlc2vIMGDiGk :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

重庆今天天气怎么样？

分析意图：需要天气数据

调用 getWeather("北京")

返回：晴天，25°C

重庆今天晴天，气温25度，适合出门！

核心概念解析：

• @Tool 注解：把 Java 方法"注册"给 AI，AI 需要时自动调用。就像给 AI 一本"工具说明书"。
• Function Calling 模式：AI 决定"要不要调用工具"以及"传什么参数"，你的代码负责执行。
• 四种调用模式对比：

代码示例：

@Service
public class WeatherService {

@Tool(name = "getWeather", description = "获取指定城市的天气信息")
public String getWeather(
@ToolParam(description = "城市名称，如重庆、北京") String city,
@ToolParam(description = "温度单位，可选celsius/fahrenheit") String unit
) {
// 实际调用天气 API
return weatherApiClient.query(city);
}
}

// 在 ChatClient 中注册工具
chatClient.prompt()
.user("重庆今天天气怎么样？")
.tools(weatherService) // 注册工具
.call()
.content();

动手实操：

避坑指南：

• 工具描述（description）要写清楚，这决定了 AI 会不会正确调用
• 参数校验要做好，AI 可能会传奇怪的值
• 超时处理：外部 API 可能很慢，要设置合理的超时时间

🟣 第四阶段：RAG（检索增强生成）

目标：构建知识库问答系统，让 AI 基于你的私有数据回答

RAG 是"让 AI 懂你的业务"的核心技术。它把大模型的"通识能力"和你的"私有知识"结合，实现客服问答、文档分析、知识管理等场景。

#mermaid-svg-dv0OwFXimXbveCwc{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-dv0OwFXimXbveCwc .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-dv0OwFXimXbveCwc .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-dv0OwFXimXbveCwc .error-icon{fill:#552222;}#mermaid-svg-dv0OwFXimXbveCwc .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-dv0OwFXimXbveCwc .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-dv0OwFXimXbveCwc .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-dv0OwFXimXbveCwc .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-dv0OwFXimXbveCwc .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-dv0OwFXimXbveCwc .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-dv0OwFXimXbveCwc .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-dv0OwFXimXbveCwc .marker{fill:#333333;stroke:#333333;}#mermaid-svg-dv0OwFXimXbveCwc .marker.cross{stroke:#333333;}#mermaid-svg-dv0OwFXimXbveCwc svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-dv0OwFXimXbveCwc p{margin:0;}#mermaid-svg-dv0OwFXimXbveCwc .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-dv0OwFXimXbveCwc .cluster-label text{fill:#333;}#mermaid-svg-dv0OwFXimXbveCwc .cluster-label span{color:#333;}#mermaid-svg-dv0OwFXimXbveCwc .cluster-label span p{background-color:transparent;}#mermaid-svg-dv0OwFXimXbveCwc .label text,#mermaid-svg-dv0OwFXimXbveCwc span{fill:#333;color:#333;}#mermaid-svg-dv0OwFXimXbveCwc .node rect,#mermaid-svg-dv0OwFXimXbveCwc .node circle,#mermaid-svg-dv0OwFXimXbveCwc .node ellipse,#mermaid-svg-dv0OwFXimXbveCwc .node polygon,#mermaid-svg-dv0OwFXimXbveCwc .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-dv0OwFXimXbveCwc .rough-node .label text,#mermaid-svg-dv0OwFXimXbveCwc .node .label text,#mermaid-svg-dv0OwFXimXbveCwc .image-shape .label,#mermaid-svg-dv0OwFXimXbveCwc .icon-shape .label{text-anchor:middle;}#mermaid-svg-dv0OwFXimXbveCwc .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-dv0OwFXimXbveCwc .rough-node .label,#mermaid-svg-dv0OwFXimXbveCwc .node .label,#mermaid-svg-dv0OwFXimXbveCwc .image-shape .label,#mermaid-svg-dv0OwFXimXbveCwc .icon-shape .label{text-align:center;}#mermaid-svg-dv0OwFXimXbveCwc .node.clickable{cursor:pointer;}#mermaid-svg-dv0OwFXimXbveCwc .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-dv0OwFXimXbveCwc .arrowheadPath{fill:#333333;}#mermaid-svg-dv0OwFXimXbveCwc .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-dv0OwFXimXbveCwc .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-dv0OwFXimXbveCwc .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-dv0OwFXimXbveCwc .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-dv0OwFXimXbveCwc .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-dv0OwFXimXbveCwc .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-dv0OwFXimXbveCwc .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-dv0OwFXimXbveCwc .cluster text{fill:#333;}#mermaid-svg-dv0OwFXimXbveCwc .cluster span{color:#333;}#mermaid-svg-dv0OwFXimXbveCwc div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-dv0OwFXimXbveCwc .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-dv0OwFXimXbveCwc rect.text{fill:none;stroke-width:0;}#mermaid-svg-dv0OwFXimXbveCwc .icon-shape,#mermaid-svg-dv0OwFXimXbveCwc .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-dv0OwFXimXbveCwc .icon-shape p,#mermaid-svg-dv0OwFXimXbveCwc .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-dv0OwFXimXbveCwc .icon-shape .label rect,#mermaid-svg-dv0OwFXimXbveCwc .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-dv0OwFXimXbveCwc .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-dv0OwFXimXbveCwc .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-dv0OwFXimXbveCwc :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

私有文档

文档切片Chunking

Embedding模型向量化

向量数据库pgvector/Milvus

用户提问

向量化

相似度检索

相关片段

构建提示词Context + Question

大模型生成回答

核心概念解析：

• Embedding（嵌入）：把文字转成数学向量。语义相近的文字，在向量空间中也相近。这是"语义搜索"的基础。
• Chunking（切片）：长文档要切成小段，否则向量会"稀释"语义。就像一本书，按章节建立索引比整本书一个索引更精确。
• 向量数据库：专门存储和检索向量的数据库，支持"找相似"的数学运算。

子模块概览：

动手实操 – 构建企业知识库：

避坑指南：

• 切片大小很关键：太小会丢失上下文，太大会稀释语义。通常 500-1000 字为宜。
• 中文 Embedding 模型推荐：BGE-large-zh、text-embedding-v3
• 检索结果要加"相关性阈值"，过滤掉不相关的内容

🔵 第五阶段：MCP（Model Context Protocol）

目标：掌握模型上下文协议，实现 AI 与外部服务深度集成

MCP 是 Anthropic 推出的开放协议，被称为 “AI 的 USB-C 接口”。它标准化了 AI 与外部工具的连接方式，让你的工具可以被任何支持 MCP 的 AI 应用使用。

#mermaid-svg-9LErSbCbTsY32oAX{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-9LErSbCbTsY32oAX .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-9LErSbCbTsY32oAX .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-9LErSbCbTsY32oAX .error-icon{fill:#552222;}#mermaid-svg-9LErSbCbTsY32oAX .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-9LErSbCbTsY32oAX .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-9LErSbCbTsY32oAX .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-9LErSbCbTsY32oAX .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-9LErSbCbTsY32oAX .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-9LErSbCbTsY32oAX .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-9LErSbCbTsY32oAX .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-9LErSbCbTsY32oAX .marker{fill:#333333;stroke:#333333;}#mermaid-svg-9LErSbCbTsY32oAX .marker.cross{stroke:#333333;}#mermaid-svg-9LErSbCbTsY32oAX svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-9LErSbCbTsY32oAX p{margin:0;}#mermaid-svg-9LErSbCbTsY32oAX .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-9LErSbCbTsY32oAX .cluster-label text{fill:#333;}#mermaid-svg-9LErSbCbTsY32oAX .cluster-label span{color:#333;}#mermaid-svg-9LErSbCbTsY32oAX .cluster-label span p{background-color:transparent;}#mermaid-svg-9LErSbCbTsY32oAX .label text,#mermaid-svg-9LErSbCbTsY32oAX span{fill:#333;color:#333;}#mermaid-svg-9LErSbCbTsY32oAX .node rect,#mermaid-svg-9LErSbCbTsY32oAX .node circle,#mermaid-svg-9LErSbCbTsY32oAX .node ellipse,#mermaid-svg-9LErSbCbTsY32oAX .node polygon,#mermaid-svg-9LErSbCbTsY32oAX .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-9LErSbCbTsY32oAX .rough-node .label text,#mermaid-svg-9LErSbCbTsY32oAX .node .label text,#mermaid-svg-9LErSbCbTsY32oAX .image-shape .label,#mermaid-svg-9LErSbCbTsY32oAX .icon-shape .label{text-anchor:middle;}#mermaid-svg-9LErSbCbTsY32oAX .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-9LErSbCbTsY32oAX .rough-node .label,#mermaid-svg-9LErSbCbTsY32oAX .node .label,#mermaid-svg-9LErSbCbTsY32oAX .image-shape .label,#mermaid-svg-9LErSbCbTsY32oAX .icon-shape .label{text-align:center;}#mermaid-svg-9LErSbCbTsY32oAX .node.clickable{cursor:pointer;}#mermaid-svg-9LErSbCbTsY32oAX .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-9LErSbCbTsY32oAX .arrowheadPath{fill:#333333;}#mermaid-svg-9LErSbCbTsY32oAX .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-9LErSbCbTsY32oAX .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-9LErSbCbTsY32oAX .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-9LErSbCbTsY32oAX .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-9LErSbCbTsY32oAX .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-9LErSbCbTsY32oAX .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-9LErSbCbTsY32oAX .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-9LErSbCbTsY32oAX .cluster text{fill:#333;}#mermaid-svg-9LErSbCbTsY32oAX .cluster span{color:#333;}#mermaid-svg-9LErSbCbTsY32oAX div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-9LErSbCbTsY32oAX .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-9LErSbCbTsY32oAX rect.text{fill:none;stroke-width:0;}#mermaid-svg-9LErSbCbTsY32oAX .icon-shape,#mermaid-svg-9LErSbCbTsY32oAX .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-9LErSbCbTsY32oAX .icon-shape p,#mermaid-svg-9LErSbCbTsY32oAX .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-9LErSbCbTsY32oAX .icon-shape .label rect,#mermaid-svg-9LErSbCbTsY32oAX .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-9LErSbCbTsY32oAX .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-9LErSbCbTsY32oAX .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-9LErSbCbTsY32oAX :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

MCP Server工具服务

MCP Client协议客户端

MCP HostAI应用

Claude Desktop

Cursor IDE

Spring AI Alibaba应用

StdioClient

HTTP Client

文件系统服务

数据库服务

GitHub服务

自定义业务服务

核心概念解析：

• MCP 协议：基于 JSON-RPC 2.0 的通信协议，定义了 AI 如何发现、调用外部工具。
• 传输方式：
  • Stdio：本地进程通信，适合本地工具（如文件操作）
  • HTTP：远程服务调用，适合分布式部署
  • Streamable HTTP：长连接流式传输，适合实时场景
• 服务发现：通过 Nacos 等注册中心，实现 MCP 服务的动态发现和负载均衡。

子模块概览：

动手实操：

避坑指南：

• MCP 是新兴协议，生态还在快速发展，要关注版本兼容性
• Stdio 模式有平台差异，Windows 和 Linux 的进程管理不同
• 生产环境一定要用 HTTP + 认证，不要直接暴露本地进程

🟤 第六阶段：Graph 工作流

目标：构建复杂 AI 工作流，实现多 Agent 协作和高级编排

Graph 是 Spring AI Alibaba 的核心差异化能力，借鉴了 LangGraph 的设计理念，让你用"搭积木"的方式构建复杂的 AI 应用。

#mermaid-svg-t4DBtH2ntKk4uFbU{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-t4DBtH2ntKk4uFbU .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-t4DBtH2ntKk4uFbU .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-t4DBtH2ntKk4uFbU .error-icon{fill:#552222;}#mermaid-svg-t4DBtH2ntKk4uFbU .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-t4DBtH2ntKk4uFbU .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-t4DBtH2ntKk4uFbU .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-t4DBtH2ntKk4uFbU .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-t4DBtH2ntKk4uFbU .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-t4DBtH2ntKk4uFbU .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-t4DBtH2ntKk4uFbU .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-t4DBtH2ntKk4uFbU .marker{fill:#333333;stroke:#333333;}#mermaid-svg-t4DBtH2ntKk4uFbU .marker.cross{stroke:#333333;}#mermaid-svg-t4DBtH2ntKk4uFbU svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-t4DBtH2ntKk4uFbU p{margin:0;}#mermaid-svg-t4DBtH2ntKk4uFbU .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-t4DBtH2ntKk4uFbU .cluster-label text{fill:#333;}#mermaid-svg-t4DBtH2ntKk4uFbU .cluster-label span{color:#333;}#mermaid-svg-t4DBtH2ntKk4uFbU .cluster-label span p{background-color:transparent;}#mermaid-svg-t4DBtH2ntKk4uFbU .label text,#mermaid-svg-t4DBtH2ntKk4uFbU span{fill:#333;color:#333;}#mermaid-svg-t4DBtH2ntKk4uFbU .node rect,#mermaid-svg-t4DBtH2ntKk4uFbU .node circle,#mermaid-svg-t4DBtH2ntKk4uFbU .node ellipse,#mermaid-svg-t4DBtH2ntKk4uFbU .node polygon,#mermaid-svg-t4DBtH2ntKk4uFbU .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-t4DBtH2ntKk4uFbU .rough-node .label text,#mermaid-svg-t4DBtH2ntKk4uFbU .node .label text,#mermaid-svg-t4DBtH2ntKk4uFbU .image-shape .label,#mermaid-svg-t4DBtH2ntKk4uFbU .icon-shape .label{text-anchor:middle;}#mermaid-svg-t4DBtH2ntKk4uFbU .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-t4DBtH2ntKk4uFbU .rough-node .label,#mermaid-svg-t4DBtH2ntKk4uFbU .node .label,#mermaid-svg-t4DBtH2ntKk4uFbU .image-shape .label,#mermaid-svg-t4DBtH2ntKk4uFbU .icon-shape .label{text-align:center;}#mermaid-svg-t4DBtH2ntKk4uFbU .node.clickable{cursor:pointer;}#mermaid-svg-t4DBtH2ntKk4uFbU .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-t4DBtH2ntKk4uFbU .arrowheadPath{fill:#333333;}#mermaid-svg-t4DBtH2ntKk4uFbU .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-t4DBtH2ntKk4uFbU .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-t4DBtH2ntKk4uFbU .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-t4DBtH2ntKk4uFbU .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-t4DBtH2ntKk4uFbU .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-t4DBtH2ntKk4uFbU .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-t4DBtH2ntKk4uFbU .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-t4DBtH2ntKk4uFbU .cluster text{fill:#333;}#mermaid-svg-t4DBtH2ntKk4uFbU .cluster span{color:#333;}#mermaid-svg-t4DBtH2ntKk4uFbU div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-t4DBtH2ntKk4uFbU .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-t4DBtH2ntKk4uFbU rect.text{fill:none;stroke-width:0;}#mermaid-svg-t4DBtH2ntKk4uFbU .icon-shape,#mermaid-svg-t4DBtH2ntKk4uFbU .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-t4DBtH2ntKk4uFbU .icon-shape p,#mermaid-svg-t4DBtH2ntKk4uFbU .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-t4DBtH2ntKk4uFbU .icon-shape .label rect,#mermaid-svg-t4DBtH2ntKk4uFbU .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-t4DBtH2ntKk4uFbU .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-t4DBtH2ntKk4uFbU .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-t4DBtH2ntKk4uFbU :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

简单问题

Bug报告

紧急问题

是

否

审核通过

需修改

Start

邮件分类器ClassifierNode

文档检索KnowledgeRetrievalNode

Bug追踪ToolNode

人工审核HumanNode

起草回复LlmNode

需要审核?

发送回复End

核心概念解析：

• StateGraph（状态图）：整个工作流的"共享内存"，每个节点可以读写状态，实现数据流转。
• 节点类型：
  • LlmNode：调用大模型生成内容
  • ToolNode：调用外部工具
  • ConditionNode：条件判断，实现分支逻辑
  • HumanNode：人工介入，等待用户输入
• 持久化与恢复：工作流可以暂停、保存状态，稍后从断点恢复（Human-in-the-Loop 的基础）。

子模块概览：

代码示例 – 智能写作助手：

@Bean
public Graph<WorkFlowState> writingAssistantGraph() {
// 定义节点：摘要生成器
Node summarizerNode = new LlmNode(summarizer);
// 分类器：判断质量是否达标
Node classifierNode = new ConditionNode(feedbackClassifier);
// 改写器：优化内容
Node reworderNode = new LlmNode(reworder);
// 标题生成器
Node titleNode = new LlmNode(titleGenerator);

// 构建图：摘要 -> 分类 -> [改写或标题] -> 标题
return GraphSpec.builder(summarizerNode)
.transitionTo(classifierNode)
.conditionalTransitionFrom(classifierNode,
(state) -> state.feedback == "positive" ? reworderNode : summarizerNode)
.transitionTo(titleNode)
.build();
}

动手实操：

避坑指南：

• 状态管理是关键：不要存太多数据，也不要丢失关键上下文
• 循环要设置终止条件：避免无限循环消耗 Token
• 错误处理：每个节点都可能失败，要考虑降级策略

📊 学习路线图总览（个人建议）

入门阶段 (1-5天)
├── Hello World (⭐) → 建立信心，验证环境
└── 多模型对话 (⭐⭐) → 理解模型差异，掌握配置

进阶阶段 (6-14天)
├── 工具调用 (⭐⭐) → AI 开始"干活"
└── RAG 知识库 (⭐⭐⭐) → AI 懂"你的业务"

高级阶段 (15-35天)
├── MCP 协议集成 (⭐⭐⭐⭐) → 标准化工具生态
└── Graph 工作流 (⭐⭐⭐⭐⭐) → 构建复杂智能体

🎓 学习建议

📅 时间规划（总计 25-35 天）

💡 学习方法

1. 先跑通，再读懂

• 每个模块先按照 README 运行起来，观察输出结果
• 然后逐行阅读源代码，理解"为什么这样写"
• 最后尝试修改参数，观察变化

2. 边学边实践

• 每个阶段完成后，结合自己的业务场景做小项目
• 例如：工具调用阶段，可以做一个"智能运维助手"调用你的监控 API
• RAG 阶段，可以整理你们的技术文档做知识库

3. 做好笔记

• 记录配置要点（yaml 文件是关键）
• 总结各模块的适用场景（什么情况下用什么）
• 整理常见错误和解决方案

4. 善用社区资源

• Spring AI Alibaba 官网
• GitHub 仓库
• 阿里云开发者社区有大量实战案例

🚀 快速开始命令

环境准备

# 设置 API Key（必须）
export AI_DASHSCOPE_API_KEY=your_api_key_here

# 克隆项目
git clone https://github.com/alibaba/spring-ai-alibaba-examples.git
cd spring-ai-alibaba-examples/examples-main

启动示例

# Hello World（第1阶段）
mvn -pl spring-ai-alibaba-helloworld spring-boot:run

# 多模型对话（第2阶段）
mvn -pl spring-ai-alibaba-chat-example spring-boot:run

# 工具调用（第3阶段）
mvn -pl spring-ai-alibaba-tool-calling-example spring-boot:run

# RAG（第4阶段）
mvn -pl spring-ai-alibaba-rag-example spring-boot:run

# MCP（第5阶段）
mvn -pl spring-ai-alibaba-mcp-example spring-boot:run

# Graph（第6阶段）
mvn -pl spring-ai-alibaba-graph-example spring-boot:run

🎯 学习目标检查清单

基础 ✅

• 配置好 Java 17+ 和 Maven
• 获取阿里云 DashScope API Key（新用户有免费额度）
• 跑通 Hello World 示例，看到 AI 回复
• 理解 ChatClient 和 ChatModel 的区别（前者友好，后者灵活）

进阶 ✅

• 能切换不同模型（OpenAI、ZhiPu、Moonshot）并对比效果
• 理解工具调用机制（AI 决定调用→你的代码执行→AI 生成回复）
• 能自定义工具函数（至少实现天气查询、计算器、数据库查询）
• 构建简单的 RAG 知识库（能基于你的文档回答问题）

高级 ✅

• 理解 MCP 协议和工作原理（Stdio vs HTTP，服务发现）
• 能配置 MCP 微服务集成（Nacos 注册中心）
• 构建基于 Graph 的工作流（至少包含 3 个节点）
• 实现多 Agent 协作系统（如：一个 Agent 负责查询，一个负责总结）

💬 常见问题

Q1: 需要学习哪些前置知识？

• ✅ Java 17+ 基础（Lambda、Stream API）
• ✅ Spring Boot 基本使用（自动配置、REST API）
• ✅ Maven 构建工具
• ❌ 不需要：Python、机器学习理论、深度学习框架

Q2: 需要购买阿里云服务吗？

• ✅ 可以使用免费额度（新用户通常有 100 万 token 免费额度）
• ✅ 也可以使用本地模型（Ollama 运行 Llama、DeepSeek 等）
• ✅ 或者使用其他平台的 API Key（OpenAI、Moonshot 等）

Q3: 遇到 API 调用失败怎么办？

Q4: 学习过程中卡住了怎么办？

• 先确保示例代码能原样运行，不要一上来就改代码
• 查看 GitHub Issues，看是否有人遇到类似问题
• 降低复杂度：如果 Graph 工作流看不懂，先回去巩固 Tool Calling

建议按照阶段顺序学习，每个阶段都完成检查清单后再进入下一阶段。祝你学习顺利！