Java开发者的大模型入门：Spring AI Alibaba组件全攻略（二）九、Studio 管理平台：提示词维护与可

九、Studio 管理平台：提示词维护与可观测性

随着 AI 应用规模的扩大，我们会发现单纯靠代码管理提示词（Prompts）变得越来越困难——业务人员希望调整话术，运维人员需要监控服务状态，开发人员则关心 Token 消耗和响应延迟。Spring AI Alibaba Studio 正是为了解决这些问题而诞生的管理平台，它提供了提示词动态维护、可观测性集成和评估功能，让你的 AI 服务具备生产级的可管理性。

9.1 Studio 管理平台概述

Spring AI Alibaba Studio 是一个配套的管理控制台，可以以独立服务或嵌入模式运行，提供以下核心能力：

提示词管理：将提示词模板从代码中抽离，存储在 Nacos 配置中心，支持动态更新而无需重启服务。
可观测性：集成 Micrometer 和 Actuator，实时监控 AI 服务的调用次数、响应耗时、Token 用量等关键指标。
评估（Evaluation）：通过预设的测试集，定期评估模型回答的质量，帮助优化提示词和模型选择。

组件架构图：

graph TD
    subgraph Spring AI Alibaba Studio
        A[提示词管理UI] --> B[Nacos配置中心]
        C[监控仪表盘] --> D[Micrometer + Actuator]
        E[评估任务] --> F[测试集 + 评估算法]
    end
    
    subgraph AI服务
        G[ChatClient] --> B
        G --> D
        G --> F
    end
    
    subgraph 基础设施
        B --> H[配置文件存储]
        D --> I[Prometheus/ARMS]
        F --> J[评估结果存储]
    end
    
    style A fill:#f9f,stroke:#333
    style C fill:#f9f,stroke:#333
    style E fill:#f9f,stroke:#333

9.2 提示词热更新实践

9.2.1 为什么需要动态提示词？

在传统开发中，提示词通常硬编码在 Java 类中或放在资源文件里。一旦需要调整（例如优化翻译风格、增加业务约束），就必须修改代码并重新部署服务。借助配置中心，我们可以将提示词模板外部化，实现热更新，让非技术人员也能参与提示词优化，极大提升迭代效率。

9.2.2 将提示词存储在 Nacos 配置中心

首先，确保你的项目中已经引入了 Spring Cloud Alibaba Nacos Config 依赖：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    <version>2022.0.0.0</version>
</dependency>

在 bootstrap.yml 中配置 Nacos 地址：

spring:
  application:
    name: ai-service
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        file-extension: yaml
  profiles:
    active: dev

在 Nacos 配置列表中创建配置文件 ai-service-dev.yaml，添加提示词模板：

ai:
  prompts:
    greeting: "你好，我叫 {name}，请用热情的语气向我问好。"
    explain: "请解释一下什么是 {concept}，用通俗易懂的语言。"
    translate: "将以下文本翻译成 {targetLanguage}：{text}"

9.2.3 使用 `@RefreshScope` 动态刷新

创建一个配置类，将提示词映射为 Java 对象：

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
@RefreshScope
@ConfigurationProperties(prefix = "ai.prompts")
public class PromptProperties {
    private Map<String, String> prompts;

    public Map<String, String> getPrompts() {
        return prompts;
    }

    public void setPrompts(Map<String, String> prompts) {
        this.prompts = prompts;
    }

    public String getPrompt(String key) {
        return prompts.get(key);
    }
}

在 Service 中注入 PromptProperties，并使用其中的模板：

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.stereotype.Service;

import java.util.Map;

@Service
public class DynamicPromptService {

    private final ChatClient chatClient;
    private final PromptProperties promptProperties;

    public DynamicPromptService(ChatClient.Builder builder, PromptProperties promptProperties) {
        this.chatClient = builder.build();
        this.promptProperties = promptProperties;
    }

    public String greet(String name) {
        String template = promptProperties.getPrompt("greeting");
        PromptTemplate promptTemplate = new PromptTemplate(template);
        Prompt prompt = promptTemplate.create(Map.of("name", name));
        return chatClient.prompt(prompt).call().content();
    }

    public String explain(String concept) {
        String template = promptProperties.getPrompt("explain");
        PromptTemplate promptTemplate = new PromptTemplate(template);
        Prompt prompt = promptTemplate.create(Map.of("concept", concept));
        return chatClient.prompt(prompt).call().content();
    }
}

9.2.4 测试动态更新效果

启动应用，访问 /greet?name=张三，观察回复内容。
在 Nacos 中修改 greeting 模板，例如改为“嘿，{name}！今天过得怎么样？”，并发布配置。
调用 /refresh 端点（需引入 Actuator 并暴露 refresh 端点）触发配置刷新：

curl -X POST http://localhost:8080/actuator/refresh

再次访问 /greet?name=张三，回复应已更新。

流程图：动态提示词更新

sequenceDiagram
    participant 运维
    participant Nacos
    participant AI服务
    participant Actuator

    运维->>Nacos: 修改提示词模板并发布
    Nacos-->>AI服务: 推送配置变更
    AI服务->>Actuator: 暴露/refresh端点
    运维->>Actuator: POST /refresh
    Actuator->>AI服务: 触发@RefreshScope刷新
    AI服务->>AI服务: PromptProperties重新加载
    用户->>AI服务: 调用接口
    AI服务->>Nacos: 使用最新模板
    AI服务-->>用户: 返回更新后的回答

9.3 Agent Chat UI 快速体验

Spring AI Alibaba Studio 提供了一个内置的聊天界面（Agent Chat UI），可以快速与你的 Agent 交互，并实时查看工作流执行情况。有两种使用方式：

9.3.1 嵌入模式

在项目中添加 Studio 依赖：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-studio</artifactId>
    <version>${spring-ai-alibaba.version}</version>
</dependency>

启动应用后，访问 http://localhost:8080/studio 即可看到聊天界面。它会自动发现你定义的 Agent 和工作流，并提供可视化的调试面板。

9.3.2 独立模式

如果希望将 Studio 部署为独立服务，可以下载官方提供的 agent-chat-ui 前端项目，并配置后端 API 地址。详情可参考官方文档。

界面预览：聊天窗口左侧显示对话历史，右侧可以查看当前工作流的执行轨迹、状态变更、Token 消耗等信息，极大地方便了调试。

9.4 可观测性集成

生产环境需要实时监控 AI 服务的运行状况。Spring AI Alibaba 通过 Micrometer 和 Actuator 提供了标准化的指标暴露。

9.4.1 引入依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

9.4.2 配置 Actuator

在 application.yml 中暴露 Prometheus 端点：

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  metrics:
    tags:
      application: ai-service

9.4.3 自定义指标收集

我们可以通过监听器或切面收集每次 AI 调用的耗时和 Token 用量。以下是使用 ChatClient 的 ChatClientBuilder 添加拦截器的示例：

import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.ChatResponse;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import reactor.core.publisher.Flux;

import java.time.Duration;

@Configuration
public class MonitoringConfig {

    @Bean
    public ChatClient monitoredChatClient(ChatClient.Builder builder, MeterRegistry meterRegistry) {
        return builder
                .build(); // 实际需要扩展，这里简化
    }
}

更推荐的方式是自定义一个 ChatClient 的装饰器，但 Spring AI 目前未提供官方扩展点。我们可以利用 AOP 切面来拦截 ChatClient 的方法，这在之前的章节已经实现过。下面是一个简化的监控切面：

@Aspect
@Component
public class AiMonitoringAspect {

    private final MeterRegistry meterRegistry;

    public AiMonitoringAspect(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
    }

    @Around("execution(* org.springframework.ai.chat.ChatClient.call(..))")
    public Object monitorCall(ProceedingJoinPoint pjp) throws Throwable {
        Timer.Sample sample = Timer.start(meterRegistry);
        try {
            Object result = pjp.proceed();
            sample.stop(Timer.builder("ai.chat.duration")
                    .description("AI chat call duration")
                    .register(meterRegistry));
            // 增加计数器
            meterRegistry.counter("ai.chat.count", "status", "success").increment();
            return result;
        } catch (Exception e) {
            meterRegistry.counter("ai.chat.count", "status", "error").increment();
            throw e;
        }
    }
}

9.4.4 接入 Prometheus 和 Grafana

启动应用后，访问 http://localhost:8080/actuator/prometheus 即可看到所有指标。配置 Prometheus 抓取该端点，即可在 Grafana 中构建仪表盘，监控 AI 服务的 QPS、延迟、Token 消耗等。

9.4.5 阿里云 ARMS 集成

如果使用阿里云 ARMS（应用实时监控服务），只需添加 ARMS 的 SDK 并配置上报地址，即可享受全链路追踪和告警能力。

9.5 评估（Evaluation）功能简介

评估是优化 AI 应用的关键环节。Spring AI Alibaba Studio 提供了一个实验性的评估框架，允许你定义测试集，对不同的模型版本或提示词进行批量测试，并计算指标（如准确率、相关性等）。

9.5.1 定义评估任务

在 Studio UI 中，可以创建评估任务，上传测试集（JSON 格式，包含输入和预期输出），选择要评估的 Agent 或工作流，然后启动评估。系统会逐条调用 Agent，并将实际输出与预期输出对比，生成评估报告。

9.5.2 评估指标

准确率：分类任务的准确匹配率。
BLEU / ROUGE：生成任务的文本相似度。
相关性评分：可使用其他模型作为评判者（LLM-as-a-judge）。

9.5.3 集成自定义评估

你也可以通过编写 Java 代码来触发评估：

@RestController
public class EvaluationController {

    @PostMapping("/evaluate")
    public EvaluationReport evaluate(@RequestBody EvaluationRequest request) {
        // 1. 加载测试集
        // 2. 循环调用 AI 服务
        // 3. 计算指标
        // 4. 返回报告
    }
}

该功能仍在快速迭代中，建议参考官方文档获取最新用法。

9.6 本章小结

通过本章的学习，你掌握了如何将 Spring AI Alibaba 应用接入生产级管理平台：

提示词动态管理：利用 Nacos 配置中心 + @RefreshScope，实现提示词热更新，提升运维效率。
Agent Chat UI：快速体验与调试 Agent，直观查看工作流执行细节。
可观测性：通过 Micrometer + Actuator 暴露关键指标，并可集成 Prometheus/Grafana 或阿里云 ARMS。
评估功能：了解如何使用测试集评估模型效果，为持续优化提供数据支撑。

十、与 Spring Cloud 生态集成

在微服务架构日益普及的今天，任何单一服务都不是孤岛。AI 服务作为企业智能能力的核心，同样需要融入整个微服务体系，享受服务注册发现、配置中心、网关路由、灰度发布等基础设施带来的便利。Spring AI Alibaba 基于 Spring Cloud Alibaba 构建，可以无缝集成这些能力，让你的 AI 服务成为微服务大家庭中的一等公民。

10.1 Spring AI Alibaba 在微服务中的定位

在微服务架构中，AI 能力通常以独立服务的形式提供，称为 AI 服务 或 智能服务。它对外提供统一的 API 接口（如聊天、问答、图像生成），内部封装了与大模型交互的复杂逻辑。其他业务服务（如订单服务、客服服务）通过 HTTP 或 RPC 调用 AI 服务，获取 AI 能力。

典型架构图：

graph TD
    subgraph 业务服务层
        A[订单服务]
        B[客服服务]
        C[商品服务]
    end
    
    subgraph AI服务层
        D[AI服务 - 聊天]
        E[AI服务 - 图像]
    end
    
    subgraph 基础设施层
        F[Nacos配置中心]
        G[Nacos服务注册中心]
        H[Higress AI网关]
    end
    
    A -->|调用| H
    B -->|调用| H
    C -->|调用| H
    H -->|路由| D
    H -->|路由| E
    D -->|获取配置| F
    E -->|获取配置| F
    D -->|注册| G
    E -->|注册| G

这种架构的优势：

职责分离：业务服务无需关心 AI 调用的细节，只需调用 AI 服务的接口。
独立演进：AI 服务可以独立升级模型、调整提示词，不影响业务服务。
统一治理：通过 Nacos 管理配置和服务，通过 Higress 实现统一路由、流控和鉴权。
弹性伸缩：AI 服务可以根据负载水平伸缩，业务服务通过网关实现负载均衡。

10.2 配置中心管理 AI 配置

在第九章中，我们已经学习了如何使用 Nacos 管理提示词模板。这里我们进一步扩展到所有 AI 相关配置，包括 API 密钥、模型参数、超时设置等，实现配置的集中管理和动态刷新。

10.2.1 将 AI 配置移至 Nacos

在 bootstrap.yml 中配置 Nacos 配置中心：

spring:
  application:
    name: ai-service
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        file-extension: yaml
        namespace: public   # 可选，指定命名空间
        group: AI_GROUP      # 可选，指定分组
  profiles:
    active: dev

在 Nacos 中创建配置文件 ai-service-dev.yaml，内容包含所有 AI 相关配置：

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}  # 可以从环境变量读取，也可以直接填写（不安全）
      chat:
        options:
          model: qwen-plus
          temperature: 0.8
      embedding:
        options:
          model: text-embedding-v1

ai:
  prompts:
    greeting: "你好，我叫 {name}，请用热情的语气向我问好。"
    explain: "请解释一下什么是 {concept}，用通俗易懂的语言。"

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus,refresh

注意：敏感信息如 api-key 建议通过环境变量注入，不要在配置中心明文存储。可以使用 Nacos 的加密插件或通过 @Value 引用环境变量。

10.2.2 使用 `@RefreshScope` 动态刷新

配置类使用 @RefreshScope 注解，当配置变更时自动更新 Bean 的属性。

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
@RefreshScope
@ConfigurationProperties(prefix = "ai")
public class AiConfigProperties {
    private Map<String, String> prompts;
    private DashScopeConfig dashscope;

    // getters and setters ...

    public static class DashScopeConfig {
        private String apiKey;
        private ChatConfig chat;
        private EmbeddingConfig embedding;
        // getters and setters ...
    }
}

在需要动态更新的地方注入 AiConfigProperties，当配置变更并调用 /refresh 后，下一次使用时即可获得新值。

10.2.3 配置刷新流程

sequenceDiagram
    participant Admin as 运维人员
    participant Nacos
    participant AIService
    participant Actuator

    Admin->>Nacos: 修改配置并发布
    Nacos->>AIService: 推送配置变更事件
    Admin->>Actuator: POST /actuator/refresh
    Actuator->>AIService: 触发@RefreshScope Bean刷新
    AIService->>AIService: AiConfigProperties重新加载
    User->>AIService: 调用接口
    AIService->>AIService: 使用最新配置
    AIService-->>User: 响应

10.3 服务注册与发现

为了让其他业务服务能够动态发现 AI 服务的地址，我们需要将 AI 服务注册到 Nacos 服务注册中心。

10.3.1 引入依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    <version>2022.0.0.0</version>
</dependency>

10.3.2 配置文件

在 application.yml 中添加服务发现配置：

spring:
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        service: ai-service           # 注册的服务名
        group: AI_GROUP                # 分组
        namespace: public              # 命名空间
        metadata:
          version: v1                  # 自定义元数据，可用于灰度发布
          protocol: http

10.3.3 启用服务发现

在主类上添加 @EnableDiscoveryClient 注解：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient
public class AiServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(AiServiceApplication.class, args);
    }
}

启动服务后，可以在 Nacos 控制台的服务列表中看到 ai-service 实例。

10.3.4 业务服务调用 AI 服务

业务服务（如订单服务）可以通过服务名来调用 AI 服务，实现客户端负载均衡。

订单服务配置：

spring:
  application:
    name: order-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848

配置 RestTemplate 并启用负载均衡：

import org.springframework.cloud.client.loadbalancer.LoadBalanced;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class OrderServiceConfig {

    @Bean
    @LoadBalanced
    public RestTemplate restTemplate() {
        return RestTemplate.builder().build();
    }
}

调用 AI 服务：

@Service
public class OrderAiService {

    @Autowired
    private RestTemplate restTemplate;

    public String askAI(String question) {
        String url = "http://ai-service/assistant?question=" + question;
        return restTemplate.getForObject(url, String.class);
    }
}

http://ai-service 中的 ai-service 是注册的服务名，Ribbon 或 Spring Cloud LoadBalancer 会负责将请求负载均衡到多个 AI 服务实例。

10.4 网关集成（Higress AI 网关）

Higress 是阿里云开源的云原生 API 网关，基于 Envoy 构建，提供了强大的流量管理能力。Higress AI 网关是专为 AI 服务设计的网关插件，支持模型路由、流控、鉴权、缓存等高级功能。

10.4.1 为什么需要 AI 网关？

统一入口：所有 AI 服务通过网关暴露，简化客户端调用。
模型路由：根据请求内容或头部，将请求路由到不同模型（如 qwen-turbo、qwen-plus）。
多服务聚合：一个网关入口背后可以聚合多个 AI 服务（聊天、图像、语音）。
安全防护：API 密钥管理、IP 白名单、限流降级。
可观测性：统一的监控和日志。

10.4.2 部署 Higress

Higress 的部署方式请参考官方文档（higress.io）。这里假设已经部署好 Higress，并配置了 Nacos 作为服务发现。

10.4.3 配置 Higress 路由规则

在 Higress 中，可以通过 Ingress 或 McpBridge 资源来定义路由。以下是一个简单的 McpBridge 配置，将 /chat 路径的请求转发到 ai-service：

apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: ai-service
  namespace: higress-system
spec:
  registries:
    - name: nacos
      type: nacos
      domain: 127.0.0.1  # Nacos 地址
      port: 8848
      nacosGroups:
        - AI_GROUP

然后配置 Ingress 路由规则：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ai-ingress
  namespace: default
  annotations:
    higress.io/destination: ai-service.ai-group  # 格式：服务名.分组
spec:
  rules:
    - host: ai.example.com
      http:
        paths:
          - path: /chat
            pathType: Prefix
            backend:
              service:
                name: ai-service
                port:
                  number: 8080

10.4.4 使用 Higress AI 插件实现模型路由

Higress 提供了 AI 插件，可以根据请求参数动态选择后端模型。例如，通过请求头 x-model 的值来决定调用哪个模型版本。

apiVersion: extensions.higress.io/v1beta1
kind: WasmPlugin
metadata:
  name: ai-router
  namespace: higress-system
spec:
  defaultConfig:
    rules:
      - headers:
          - name: x-model
            value: "turbo"
        targetService: "ai-service-turbo.ai-group"
      - headers:
          - name: x-model
            value: "plus"
        targetService: "ai-service-plus.ai-group"

这样，客户端可以通过设置不同的请求头来调用不同版本的 AI 服务，实现 A/B 测试或模型切换。

10.5 灰度发布与 A/B 测试

当我们需要升级 AI 模型（例如从 qwen-turbo 切换到 qwen-plus）或修改提示词时，直接全量发布存在风险。通过灰度发布，我们可以让一小部分流量先使用新版本，验证无误后再逐步扩大范围。

10.5.1 基于元数据的版本标识

在服务注册时，为不同版本的实例添加元数据：

spring:
  cloud:
    nacos:
      discovery:
        metadata:
          version: v1  # v1 版本

启动另一个实例，将 version 改为 v2。

10.5.2 自定义负载均衡策略

实现一个基于版本请求头的负载均衡规则，让带有特定版本标识的请求路由到对应版本实例。

import org.springframework.cloud.client.ServiceInstance;
import org.springframework.cloud.client.loadbalancer.Request;
import org.springframework.cloud.client.loadbalancer.RequestDataContext;
import org.springframework.cloud.loadbalancer.core.DelegatingServiceInstanceListSupplier;
import org.springframework.cloud.loadbalancer.core.ServiceInstanceListSupplier;
import reactor.core.publisher.Flux;

import java.util.List;
import java.util.stream.Collectors;

public class VersionLoadBalancer extends DelegatingServiceInstanceListSupplier {

    public VersionLoadBalancer(ServiceInstanceListSupplier delegate) {
        super(delegate);
    }

    @Override
    public Flux<List<ServiceInstance>> get() {
        return delegate.get().map(instances -> {
            // 获取当前请求上下文（需要配合 Request 传递）
            Request<?> request = null; // 需要通过 RequestContextHolder 获取，此处简化
            if (request == null) {
                return instances; // 默认返回所有
            }
            RequestDataContext context = (RequestDataContext) request.getContext();
            String version = context.getClientRequest().getHeaders().getFirst("X-Version");
            if (version == null) {
                return instances; // 无版本要求，随机选择
            }
            // 过滤出匹配版本的实例
            return instances.stream()
                    .filter(instance -> version.equals(instance.getMetadata().get("version")))
                    .collect(Collectors.toList());
        });
    }
}

然后配置使用自定义负载均衡器（略，可参考 Spring Cloud LoadBalancer 文档）。

10.5.3 通过网关实现灰度发布

更简单的做法是在 Higress 网关上根据请求头或比例进行灰度路由。例如，希望 10% 的流量到 v2 版本：

apiVersion: networking.higress.io/v1
kind: WasmPlugin
metadata:
  name: gray-release
  namespace: higress-system
spec:
  defaultConfig:
    rules:
      - condition: "true"   # 默认规则，90% 流量
        weight: 90
        targetService: "ai-service-v1.ai-group"
      - headers:
          - name: x-version
            value: "v2"
        weight: 10
        targetService: "ai-service-v2.ai-group"

10.5.4 灰度发布流程图

graph TD
    Client[客户端请求] --> Gateway[Higress AI网关]
    Gateway -->|90%| V1[ai-service-v1]
    Gateway -->|10%| V2[ai-service-v2]
    
    V1 --> Nacos[Nacos注册中心]
    V2 --> Nacos
    
    style Gateway fill:#f9f,stroke:#333
    style V1 fill:#bbf,stroke:#333
    style V2 fill:#bfb,stroke:#333

10.6 本章小结

通过本章的学习，你将 Spring AI Alibaba 服务成功融入了 Spring Cloud 微服务生态：

配置中心：使用 Nacos 管理所有 AI 配置，实现动态刷新，提升运维效率。
服务发现：将 AI 服务注册到 Nacos，业务服务通过服务名调用，实现负载均衡。
网关集成：通过 Higress AI 网关提供统一入口，支持模型路由、流量控制。
灰度发布：利用服务元数据和自定义负载均衡或网关规则，实现平滑升级和 A/B 测试。

十一、未来展望：AgentScope-Java 与 Spring AI Alibaba 的融合

在经历了前面十章的学习后，你已经掌握了 Spring AI Alibaba 从基础到高级的全部组件。然而，AI 技术的发展日新月异，新的编程范式和框架不断涌现。阿里巴巴通义实验室开源的 AgentScope-Java 就是其中之一，它带来了全新的 Agentic 设计理念。本章将带你了解 AgentScope-Java，对比它与 Spring AI Alibaba Graph 的异同，并展望两者未来的融合方向，为你打开通向下一代智能体开发的大门。

11.1 AgentScope-Java 简介

AgentScope-Java 是阿里巴巴通义实验室开源的一款专注于 Agentic（智能体） 的 Java 框架。它的核心设计理念是最大化利用基础模型（LLM）的自主决策能力，让智能体能够在复杂、开放的环境中自主规划、执行和调整，而不是严格遵循预先定义的工作流。

11.1.1 核心概念

概念	说明
Agent	一个自主的智能体，拥有自己的记忆、工具集和决策逻辑。
ReAct Agent	结合 Reasoning（推理）和 Acting（行动）的智能体模式，循环进行“思考→行动→观察”直至任务完成。
Memory	智能体的记忆系统，存储过去的对话、行动和结果，支持短期和长期记忆。
Tool	智能体可调用的外部工具，与 Spring AI Alibaba 的 `@Tool` 类似。
Context Engineering	上下文工程，动态构建提示词，融入记忆和工具信息。

11.1.2 ReAct Agent 工作流程

graph TD
    START((开始)) --> Thought[思考:我需要做什么?]
    Thought --> Action[行动: 调用工具]
    Action --> Observation[观察: 工具返回结果]
    Observation --> Condition{任务完成?}
    Condition -->|否| Thought
    Condition -->|是| Final[生成最终回答]
    Final --> END((结束))

这种循环让智能体能够像人类一样，在面对未知问题时不断尝试和调整，直至找到解决方案。

11.1.3 AgentScope-Java 快速示例

import com.alibaba.agentscope.agent.ReActAgent;
import com.alibaba.agentscope.llm.ChatClient;
import com.alibaba.agentscope.tool.Tool;

public class WeatherAgent extends ReActAgent {
    
    public WeatherAgent(ChatClient chatClient) {
        super(chatClient);
        // 注册工具
        registerTool(new WeatherTool());
    }
    
    @Override
    protected String getSystemPrompt() {
        return "你是一个天气查询助手，可以使用工具获取实时天气。";
    }
}

class WeatherTool implements Tool {
    @Override
    public String getName() { return "get_weather"; }
    
    @Override
    public String getDescription() { return "获取指定城市的天气"; }
    
    @Override
    public String execute(String args) {
        // 解析参数，调用真实天气 API
        return "晴，25℃";
    }
}

11.2 两种设计理念的对比：Graph vs Agentic

Spring AI Alibaba Graph 和 AgentScope-Java 代表了两种不同的智能体构建范式：工作流编排（Workflow Orchestration） 与 智能体自主决策（Agentic Autonomy）。

维度	Spring AI Alibaba Graph	AgentScope-Java
核心理念	预定义的有向图，节点和边明确	智能体自主思考、行动、观察循环
决策方式	根据状态和条件边路由	由 LLM 动态生成下一步计划
确定性	高，流程可控，可预测	低，依赖模型能力，可能出人意料
适用场景	业务流程固定、需要审计的场景（如订单处理、客服分流）	开放域、需要灵活应对未知问题的场景（如个人助理、研究助手）
复杂度	节点和边的数量随复杂度线性增长	单个 Agent 可处理复杂任务，但调试困难
人工介入	支持 Human-in-the-loop，可在特定节点暂停	通常自动运行，也可设计暂停点

11.2.1 何时选择 Graph？

你需要一个高度可靠、可审计的流程，例如“客户投诉处理：先分类 → 再分派 → 最后记录”。
流程中的每个步骤都是确定的，即使使用 AI，也只是完成特定的子任务（如分类）。
需要多人协作开发，流程图本身就是清晰的文档。

11.2.2 何时选择 Agentic？

任务目标明确，但达成路径未知，例如“帮我写一篇关于 AI 的博客，并配图”。
需要智能体根据环境反馈动态调整计划，例如“预订机票：如果某航班满员，尝试其他航班”。
希望构建一个通用的个人助理，能够处理各种随机请求。

11.2.3 两者并非对立，而是互补

实际上，在一个复杂系统中，你可以同时使用两种模式：

外层使用 Graph 定义宏观流程（如“用户请求 → 意图识别 → 分派到不同 Agent”）。
内层使用 Agentic 的 Agent 处理具体子任务（如“写作 Agent”、“预订 Agent”）。

这种分层混合架构既能保证核心流程的可控性，又能发挥智能体的灵活性。

11.3 未来集成计划：Spring AI Alibaba + AgentScope-Java

阿里巴巴内部和社区正在探索将 AgentScope-Java 的能力整合进 Spring AI Alibaba，为 Java 开发者提供一站式的智能体开发体验。未来的集成可能包括以下几个方面：

11.3.1 AgentScope Starter

类似 Spring AI Alibaba 的自动配置，AgentScope 将提供 Spring Boot Starter，让你能够轻松地在 Spring 应用中创建和使用 Agent。

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>agentscope-spring-boot-starter</artifactId>
    <version>${version}</version>
</dependency>

配置 application.yml：

agentscope:
  llm:
    provider: dashscope
    model: qwen-max
  memory:
    type: redis
    ttl: 3600
  tools:
    - com.example.MyTool

然后在 Spring Bean 中注入 Agent：

@Component
public class MyAgent extends ReActAgent {
    
    public MyAgent(AgentLLM llm, AgentMemory memory, List<Tool> tools) {
        super(llm, memory, tools);
    }
    
    @Override
    protected String getSystemPrompt() {
        return "你是一个智能助手。";
    }
}

@Service
public class AgentService {
    @Autowired
    private MyAgent agent;
    
    public String chat(String input) {
        return agent.run(input);
    }
}

11.3.2 Graph 节点中调用 Agent

Spring AI Alibaba Graph 可以将一个 Agent 作为特殊节点，实现 Graph 与 Agentic 的混合编排。

public class AgentNode implements AsyncNodeAction {
    private final MyAgent agent;
    
    @Override
    public CompletableFuture<OverAllState> apply(OverAllState state) {
        String input = (String) state.value("input").orElse("");
        String output = agent.run(input);
        state.update("agent_output", output);
        return CompletableFuture.completedFuture(state);
    }
}

11.3.3 可观测性与评估融合

未来，AgentScope 的运行轨迹也可以被 Spring AI Alibaba Studio 捕获，实现统一的监控和评估。你可以在 Studio 界面中查看 Agent 的思考链条、工具调用记录，以及最终结果。

11.3.4 集成示意图

graph TD
    subgraph Spring AI Alibaba生态
        A[Spring AI Alibaba Graph] --> B[Graph节点1]
        A --> C[Graph节点2]
        A --> D[Agent节点]
        D --> E[AgentScope Agent]
    end
    
    subgraph AgentScope生态
        E --> F[ReAct循环]
        F --> G[Tool1]
        F --> H[Tool2]
        F --> I[Memory]
    end
    
    style A fill:#f9f,stroke:#333
    style E fill:#bfb,stroke:#333
    style F fill:#bbf,stroke:#333

11.4 本章小结

通过本章的学习，你了解了：

AgentScope-Java 的核心概念和 ReAct Agent 模式。
Graph vs Agentic 两种设计理念的对比及适用场景。
未来集成方向：Spring AI Alibaba 将与 AgentScope 融合，提供更完整的智能体开发体验。

十二、总结与最佳实践

恭喜你完成了整个 Spring AI Alibaba 学习之旅！从最初的环境搭建到最新的 AgentScope 展望，你已经系统地掌握了 Spring AI Alibaba 的所有核心组件，并亲手实践了从简单聊天到复杂多智能体协作的各种场景。现在，让我们一起回顾所学内容，总结最佳实践，并为后续深入探索指明方向。

12.1 Spring AI Alibaba 组件全景回顾

在之前的章节中，我们逐步探索了以下组件，每个组件都有其独特的用途。下面的表格可以帮助你快速回顾：

组件类别	核心组件/概念	适用场景	你学到的实践
基础模型	`ChatClient`, 通义千问系列	通用对话、问答	使用 `prompt().user().call().content()` 发送消息，获取回复
流式响应	`stream()`, `Flux<ChatResponse>`	需要实时展示生成内容	结合 WebFlux 返回 SSE，前端用 EventSource 接收
提示词管理	`PromptTemplate`, Nacos 动态配置	动态构造消息，配置热更新	将模板存储在 Nacos，使用 `@RefreshScope` 实现热加载
多模态	`TongYiImagesModel`, 图片消息	图像生成、图像理解	文生图接口、图片描述接口
结构化输出	`entity(Class<T>)`	让 AI 返回 Java 对象	定义 POJO，直接获取类型安全的对象
函数调用	`@Tool` 注解，自动注册	让 AI 获取实时信息或执行操作	编写工具 Bean，AI 自动调用
RAG 基础	`DocumentReader`, `TokenTextSplitter`, `EmbeddingClient`	知识库构建	加载文档、分割、嵌入，存入向量存储
RAG 增强	`VectorStore`, `QuestionAnswerAdvisor`	基于私有知识的问答	配置检索顾问，实现上下文增强
工作流编排	`StateGraph`, `Node`, `Edge`, `ReActAgent`	复杂多步流程，多智能体协作	构建评价分类工作流，实现 ReAct Agent
管理平台	Studio, Nacos 配置, Actuator	提示词热更新，服务监控	动态刷新提示词，监控调用指标
微服务集成	Nacos 注册中心, Higress 网关	将 AI 服务融入微服务架构	服务注册发现，灰度发布，统一路由
未来扩展	AgentScope-Java	自主决策的智能体	了解 Agentic 模式，为未来集成做准备

12.2 生产环境选型建议

当你准备将应用部署到生产环境时，需要根据实际场景做出更细致的选择。以下是一些关键决策点的建议。

12.2.1 模型选择：qwen-turbo / qwen-plus / qwen-max

通义千问系列提供了多个版本，需要根据业务需求权衡性能和成本。

模型	特点	适用场景	成本
qwen-turbo	响应速度最快，成本最低	高频交互、客服对话、简单问答	低
qwen-plus	平衡性能与速度，能力较强	内容生成、中等复杂度推理	中
qwen-max	最强推理能力，质量最高	复杂任务、专业领域问答、代码生成	高

建议：

对于大多数通用场景，qwen-plus 是性价比最高的选择。
如果对响应速度要求极高（如实时聊天），可以选择 qwen-turbo。
只有当任务确实需要强大的推理能力（如数学、逻辑推理）时，才考虑 qwen-max，并注意监控成本。

12.2.2 向量数据库选型

在 RAG 应用中，向量存储是核心组件。Spring AI 的 VectorStore 抽象支持多种实现。

向量数据库	优点	适用场景
Milvus	专业向量数据库，支持十亿级向量，功能强大	大规模生产环境，对性能和扩展性要求高
PGvector	基于 PostgreSQL，与关系数据共存，易于管理	中小型项目，已有 PostgreSQL 基础设施
Redis	内存数据库，性能极高，支持向量搜索	需要低延迟检索，数据量适中
Elasticsearch	全文检索 + 向量检索混合能力	需要同时支持关键词搜索和语义搜索
SimpleVectorStore	内存存储，无需额外部署	开发测试、小型演示

建议：

初创项目或团队已有 PostgreSQL 经验，优先选择 PGvector。
数据规模大、对性能要求高的场景，选择 Milvus 或 Zilliz Cloud。
快速原型验证可用 SimpleVectorStore，后期迁移。

12.2.3 部署模式：公有云 API vs 私有化部署

部署方式	优点	缺点	适用场景
阿里云 DashScope API	无需运维，开箱即用，成本按量计费	数据需发送到云端，存在隐私顾虑	通用场景，对数据隐私要求不高的项目
私有化部署（通义千问本地版）	数据完全私有，低延迟	需要 GPU 资源，运维成本高	金融、医疗等数据敏感行业，或需要离线运行

建议：

初期推荐使用 DashScope API 快速验证业务。
当业务成熟且数据敏感时，可考虑采购通义千问私有化版本，或使用阿里云百炼的专有 VPC 调用。

12.2.4 成本控制策略

缓存：对重复问题使用 Spring Cache 缓存 AI 回复，大幅减少调用次数。
Token 监控：通过 Actuator 收集 Token 用量，设置每日/每月上限，及时告警。
模型降级：对简单问题使用 qwen-turbo，复杂问题才调用 qwen-max。
流式响应：长回复使用流式，减少客户端超时重试。
请求合并：对于非实时场景，可将多个请求合并成一个批量请求。

12.2.5 安全合规

内容审核：在用户输入和 AI 输出两端使用通义千问的审核模型（或第三方服务）过滤不当内容。
数据脱敏：发送前对敏感信息（身份证、手机号）进行脱敏处理。
API 密钥管理：使用 KMS 或配置中心加密存储，定期轮换。
访问控制：通过网关或 Spring Security 对 AI 服务接口进行认证授权。

12.3 后续学习路径

你已经掌握了 Spring AI Alibaba 的绝大部分功能，接下来可以朝以下方向深入：

关注官方动态：Spring AI Alibaba 正在快速发展，关注 GitHub 仓库和官方文档，获取最新特性和最佳实践。
深入 AgentScope-Java：学习 AgentScope-Java，掌握 Agentic 开发模式，为未来融合做准备。
探索 RAG 高级技术：
- 混合检索：结合向量检索和关键词检索，提升准确率。
- 重排序：使用 Cross-encoder 模型对检索结果重新排序。
- 查询规划：对于复杂问题，拆分成多个子查询再聚合答案。
尝试多模态深度应用：将图像生成、理解与业务结合，如生成产品配图、自动审核图片内容等。
参与社区贡献：给项目点 Star，提交 Issue 或 PR，与其他开发者交流经验。

12.4 写在最后

通过本教程的学习，你不仅掌握了 Spring AI Alibaba 的技术细节，更重要的是建立了一套将 AI 能力融入企业级 Java 应用的思维框架。从基础对话到复杂工作流，从本地知识库到微服务治理，你现在已经有能力构建真正能投入生产的智能系统。

AI 技术的发展永无止境，保持学习，持续实践，你一定能在智能时代创造更多价值。感谢你的坚持，祝编码愉快！

附录

A. 常见问题解答（FAQ）

Q1: 为什么我使用 ChatClient 时出现 No qualifying bean of type 'ChatClient.Builder' 错误？ A: 确保引入了 spring-ai-alibaba-starter 依赖，并且 Spring Boot 主类上有 @SpringBootApplication 注解。自动配置会创建 ChatClient.Builder 的 Bean。

Q2: 如何切换使用不同的模型（例如从 qwen-turbo 切换到 qwen-plus）？ A: 修改 application.yml 中的 spring.ai.dashscope.chat.options.model 配置，或者每次调用时通过 DashScopeChatOptions 动态指定。

Q3: 流式响应时，前端收到乱码或无法正确解析？ A: 确保 Controller 的 produces = MediaType.TEXT_EVENT_STREAM_VALUE，并且返回的是 Flux<String> 或 Flux<ServerSentEvent>。前端使用 EventSource 时，注意设置正确的字符编码（默认 UTF-8）。

Q4: 结构化输出时，AI 返回的 JSON 无法解析为我的 Java 类？ A: 检查 Java 类是否有无参构造和 getter/setter（或使用 record）。另外，可以在提示词中明确要求输出 JSON 格式，例如“请以 JSON 格式返回，包含 name、age 字段”。

Q5: 函数调用时，AI 不调用我期望的工具？ A: 检查工具的描述是否清晰，参数描述是否准确。可以调整 @Tool 的 name 和 description，确保 AI 能理解何时调用。另外，注意工具类需要是 Spring Bean。

Q6: RAG 检索结果不相关怎么办？ A: 尝试调整分割块大小（chunk size）和重叠（overlap），或者提高相似度阈值（minScore）。也可以考虑使用混合检索或重排序技术。

Q7: 如何获取 Token 用量？ A: 使用 ChatResponse response = chatClient.prompt().call();，然后从 response.getMetadata() 中获取。对于通义千问，可以通过 DashScopeChatResponse 获取具体用量。

Q8: Nacos 配置动态刷新不生效？ A: 确保类上加了 @RefreshScope，并且配置文件中的 key 与 @ConfigurationProperties 的前缀一致。调用 /actuator/refresh 端点后，需要等待下一次请求才会使用新值。

Q9: Spring AI Alibaba 和 Spring AI 的关系是什么？ A: Spring AI Alibaba 是基于 Spring AI 的扩展，增加了对阿里云通义千问模型和阿里云基础设施的支持。它遵循 Spring AI 的抽象，同时提供了更丰富的企业级功能。

B. 完整代码示例仓库地址

为了方便你查阅和运行，本教程的所有代码示例已整理到一个 GitHub 仓库中：

👉 gitee.com/youhei/spri…

C. 参考资源链接

Spring AI Alibaba 官方文档：sca.aliyun.com/docs/ai/ove…
Spring AI Alibaba GitHub：github.com/alibaba/spr…
阿里云百炼平台：bailian.console.aliyun.com
通义千问 API 文档：help.aliyun.com/zh/dashscop…
Nacos 官方文档：nacos.io
Higress 官网：higress.io
AgentScope-Java 仓库：github.com/agentscope-…

Java开发者的大模型入门：Spring AI Alibaba组件全攻略（二）