一、项目愿景：我们的 Agent 能做什么？

传统的客服机器人是“人工智障”，只会关键词匹配。我们要做的 Agent 具备以下能力：

1. 闲聊能力：基于通义千问，像真人一样对话。

2. 企业知识库 (RAG)：用户问“运费怎么算”、“怎么退货”时，它能查阅我们上传的 PDF 文档回答（大模型本身不知道这些私有规定）。

3. 办事能力 (Function Calling)：用户问“我的订单 8888 发货了吗”时，它能自动调用 Java 代码去查数据库，而不是瞎编。

---

二、核心架构与技术栈

• 框架：Spring Boot 3.2+

• AI 核心：Spring AI Alibaba (适配通义千问 Qwen-Max)

• 向量数据库：DashVector (用于 RAG 存储知识)

• JDK：Java 17+

依赖引入 (pom.xml)

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter</artifactId>
    <version>1.0.0-M3.1</version> <!-- 请使用最新版本 -->
</dependency>
<!-- 如果需要 RAG，引入 DashVector -->
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashvector</artifactId>
</dependency>

配置 application.yml：

spring:
  ai:
    dashscope:
      api-key: ${AI_API_KEY} # 你的阿里云通义千问 Key
    dashvector:
      api-key: ${VECTOR_KEY} # 向量数据库 Key
      endpoint: ${VECTOR_ENDPOINT}

---

三、第一招：构建“大脑” (ChatClient)

Spring AI 提供了一个极其强大的流式接口 ChatClient。在 Spring AI Alibaba 中，底层自动对接了 TongYiChatModel。

我们需要配置一个全局的 ChatClient：

@Configuration
public class AiConfig {
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder
                .defaultSystem("你是一个专业的电商客服助手，名字叫'小E'。语气要亲切，多用emoji。")
                .build();
    }
}

---

四、第二招：给大脑装上“外脑” (RAG 知识库)

痛点：通义千问不知道你们公司的“七天无理由退货细则”。
解法：使用 RAG（检索增强生成）。

1. 知识入库 (ETL)

我们需要一个接口，把公司的 PDF/TXT 政策文档读取出来，向量化后存入 DashVector。

@RestController
@RequestMapping("/knowledge")
public class KnowledgeController {

    @Autowired
    private VectorStore vectorStore; // 自动注入 Alibaba DashVector 实现

    @PostMapping("/load")
    public String loadKnowledge() {
        // 1. 读取本地文档
        Resource resource = new ClassPathResource("refund_policy.txt");
        DocumentReader reader = new TextReader(resource);
        
        // 2. 切块 (TokenTextSplitter)
        TokenTextSplitter splitter = new TokenTextSplitter();
        List<Document> documents = splitter.apply(reader.get());

        // 3. 存入向量数据库 (Spring AI Alibaba 会自动调用通义 Embeddings 模型进行向量化)
        vectorStore.add(documents);
        
        return "知识库加载完成！";
    }
}

2. 对话时检索 (Retrieval)

这里我们使用 Spring AI 的神技 QuestionAnswerAdvisor。它能自动拦截用户的提问，去向量库查资料，把资料塞给大模型。

---

五、第三招：给大脑装上“双手” (Function Calling)

痛点：用户问“订单 1001 到了吗？”，大模型无法访问你的数据库。
解法：Function Calling（工具调用）。

1. 定义本地 Java 工具

我们定义一个普通的 Java Function，用来查订单。

codeJava

@Configuration
public class ToolsConfig {

    @Bean
    @Description("根据订单ID查询订单的物流状态和详情") // 这里的描述非常关键，大模型靠它决定是否调用
    public Function<OrderQueryRequest, OrderQueryResponse> orderQueryTool() {
        return request -> {
            // 模拟查询数据库
            System.out.println("正在查询订单系统: " + request.orderId());
            if ("1001".equals(request.orderId())) {
                return new OrderQueryResponse("1001", "已发货", "顺丰快递");
            }
            return new OrderQueryResponse(request.orderId(), "不存在", "无");
        };
    }

    // Request 和 Response 的 Record 定义省略
}

Spring AI Alibaba 能够识别这个 Bean，并将这个函数的签名（Signature）发送给通义千问。

---

六、终极整合：智能客服接口

现在，我们把对话、RAG、Tools 结合在一个接口里。

codeJava

@RestController
@RequestMapping("/chat")
public class ChatController {

    private final ChatClient chatClient;
    private final VectorStore vectorStore;

    public ChatController(ChatClient.Builder builder, VectorStore vectorStore) {
        // 关键构建步骤
        this.chatClient = builder
                // 1. 挂载 RAG 能力：自动去向量库搜索相关上下文
                .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore, SearchRequest.defaults()))
                // 2. 挂载 Tools 能力：允许模型调用名为 'orderQueryTool' 的函数
                .defaultFunctions("orderQueryTool")
                .build();
    }

    @GetMapping
    public String chat(@RequestParam String prompt) {
        return chatClient.prompt()
                .user(prompt)
                .call()
                .content();
    }
}

---

七、 效果实测

让我们看看这个 Agent 是如何工作的：

场景一：咨询政策 (触发 RAG)

用户：“你们的退货运费谁出？”
系统后台逻辑：

1. 用户提问。

2. QuestionAnswerAdvisor 拦截，去 DashVector 搜索“退货运费”相关片段。

3. 搜到文档片段：“...非质量问题退货运费由买家承担...”。

4. 将文档片段 + 用户问题发给通义千问。
   AI 回复：“亲亲 😽，根据我们的规定，如果是非质量问题导致的退货，运费需要您自己承担哦~如果是质量问题，我们包运费！”

场景二：查询业务 (触发 Function Calling)

用户：“帮我查下订单 1001 发货没？”
系统后台逻辑：

1. 通义千问分析语义，发现用户意图是“查订单”，且参数是 1001。

2. 通义千问暂停生成，向 Spring AI 发出指令：“请调用 orderQueryTool，参数 {orderId: '1001'}”。

3. Spring AI 自动执行我们写的 orderQueryTool Java 方法。

4. Java 方法返回：{status: "已发货", carrier: "顺丰"}。

5. 结果回传给通义千问。
   AI 回复：“查到了！您的订单 1001 已经发货啦 🚚，使用的是顺丰快递，请耐心等待哦！”

---

八、总结：用到了什么能力？

在这个实战项目中，我们深度利用了 Spring AI Alibaba 的以下核心优势：

1. 统一的 API 抽象：我们完全不需要学习阿里云 DashScope 原生 SDK 的复杂 JSON 结构，只用写标准的 Java 代码。

2. DashVectorStore 集成：一行代码注入，自动实现 Embedding 和向量存储，解决了 RAG 链路中最麻烦的数据处理环节。

3. Qwen Function Calling 适配：让大模型与 Java 业务代码无缝连接。这对于企业级应用至关重要，因为AI 必须落地到业务系统（ERP/CRM）中才有价值。

4. Advisors 机制：利用 QuestionAnswerAdvisor 优雅地实现了 RAG 逻辑的封装，避免了 Controller 层代码臃肿。