Spring AI + Spring AI Alibaba 接入观测云最佳实践

文章介绍 Spring AI 与 Spring AI Alibaba 应用接入观测云的实践方案，通过 OpenTelemetry 自动采集 Agent、LLM 与 Tool 调用链路，实现性能、Token、模型及工具调用的统一观测，提升 AI 应用故障排查与性能优化效率。

产品架构师 刘锐 7 分钟阅读
最佳实践
banner.png

让 Agent 应用的可观测性不再停留于"服务是否存活"，而是能清晰回答：为什么这样回答、为什么这么慢、问题出在模型还是 Tool？

概述

在 AI 大模型浪潮席卷各行各业的今天，越来越多的企业开始将大语言模型（LLM）集成到自己的业务系统中，以构建智能客服、知识助手、自动化运维、代码辅助等应用。然而，Java 生态长期以来缺乏一套标准化、统一、易扩展的大模型接入框架——开发者往往需要为不同模型提供商（OpenAI、阿里云、Azure 等）编写各自的客户端代码，模型切换成本高昂，且难以与 Spring Boot 等主流开发框架无缝融合。

Spring AI 应运而生。作为 Spring 官方推出的 AI 抽象层，它为 Java 开发者提供了统一的 API 来对接各类大模型（包括聊天、嵌入、图像生成等），并内置了 Prompt 管理、输出解析、RAG（检索增强生成）等常用工具。开发者只需通过简洁的配置和调用方式，就能快速集成模型能力，而无需关心底层 API 的差异。

Spring AI Alibaba 则是阿里云基于 Spring AI 构建的企业级增强方案。它不仅提供了对 DashScope（通义系列模型）的深度适配，更带来了 Agent Framework——一个用于构建 ReAct 风格智能代理的编排框架。借助它，开发者可以轻松定义 Tool（工具）、编排多轮推理、实现从"简单问答"到"自主决策"的跃升。同时，Spring AI Alibaba 还提供了 Studio 等辅助工具，帮助团队快速搭建原型和测试环境。

对于企业而言，选择 Spring AI + Spring AI Alibaba 意味着：

  • 降低技术选型风险：统一抽象层让模型更换变得轻松，避免被单一厂商锁定。
  • 加速产品迭代：开箱即用的 Agent 框架和 Tool 机制，让复杂 AI 场景的开发周期从数月缩短到数周。
  • 复用现有 Java 人才：无需引入 Python 技术栈，即可借助 Spring Boot 的成熟生态完成 AI 应用开发。
  • 生产级稳定性：依托阿里云的企业级支持和大规模实践，确保高并发、低延迟场景下的可靠性。

正因如此，这套技术组合已成为众多企业落地 AI 应用的首选方案。

可观测性：AI 应用落地的"最后一公里"

然而，即便有了强大的开发框架，AI 应用在生产环境的稳定性与排障效率依然是企业面临的最大挑战。传统微服务的监控方法——记录接口耗时、错误率、调用链路——在大模型场景下显得力不从心，因为：

  • 模型是黑盒：你不知道它收到了什么样的 System Prompt 和用户输入，也无法直接看到它的原始输出。
  • Agent 推理是动态的：一次用户请求可能触发多轮 LLM 调用和多次 Tool 执行，且路径随上下文变化，无法用固定拓扑描述。
  • Token 成本不可控：输入输出长度直接影响费用和延迟，没有精确的 Token 用量统计，成本优化无从下手。
  • Tool 执行是关键环节：Tool 的输入参数、返回结果、异常信息往往直接影响 Agent 的最终回答，但这些信息在传统日志中极易丢失。

这些问题导致 AI 应用出现故障时，开发团队往往束手无策——"模型回答错了"究竟是 Prompt 问题、Tool 调用出错，还是模型本身幻觉？一次请求耗时过长，是模型推理慢还是 Tool 执行卡住？当需要回答"这个版本到底有没有正确接入 Agent"时，仅仅看到 HTTP 200 是远远不够的。

因此，针对 AI 应用的可观测性方案不是可选项，而是必选项。它不仅是运维保障，更是开发调试、成本优化、模型评估的核心基础设施。观测云作为国内领先的全链路可观测平台，天然支持 GenAI 相关标准，能够与 Spring AI 生态完美对接，让上述所有痛点一一化解。

本文正是基于这一背景，提供一套可直接复用的接入方案，帮助你在观测云中完整呈现 Spring AI + Spring AI Alibaba 应用的内部运行细节。

接入步骤

我们使用 Spring AI Alibaba 官方示例中的 chatbot 模块，这是一个典型的 ReAct Agent 应用，包含模型调用、Tool 执行和流式响应。

  • 示例工程：examples/chatbot
  • 核心类：ChatbotApplication、ChatbotAgent、PythonTool

关键版本：

  • Spring Boot：3.5.7
  • Spring AI：1.1.2
  • Spring AI Alibaba：1.1.2.2
  • Java：17+

核心依赖

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-agent-framework</artifactId>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-studio</artifactId>
</dependency>
  • starter-dashscope：将 DashScope 模型接入 Spring AI
  • agent-framework：提供 ReAct Agent 编排与 Tool 调用能力
  • studio：提供 /chatui/index.html 交互页面，方便本地测试

1. 准备应用并启动验证

确保示例工程可以正常启动。配置 DashScope API Key：

export AI_DASHSCOPE_API_KEY=your-api-key

构建 jar 包：

cd /path/to/spring-ai-alibaba
./mvnw -f examples/chatbot/pom.xml -DskipTests package

产物位于：examples/chatbot/target/chatbot-0.0.1-SNAPSHOT.jar

2. 准备 Java Agent

下载 Java Agent

https://github.com/GuanceCloud/opentelemetry-java-instrumentation/releases/tag/v2.30.2

3. 新建 LLM 应用

登录到观测云平台，点击 【Agent 监测】，选择 LLM，点击【接入 LLM】 按钮进行新建操作。复制对应的环境变量，下一步使用。点击【创建】按钮，完成创建工作。

4. 启动应用

相关命令如下：

export AI_DASHSCOPE_API_KEY=<AI_DASHSCOPE_API_KEY>

export LANGFUSE_PUBLIC_KEY='<LANGFUSE_PUBLIC_KEY>'
export LANGFUSE_SECRET_KEY='<LANGFUSE_SECRET_KEY>'


BASIC_AUTH="$(
printf '%s:%s' "$LANGFUSE_PUBLIC_KEY" "$LANGFUSE_SECRET_KEY" |
base64 -w 0
)"

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${BASIC_AUTH},x-langfuse-public-key=${LANGFUSE_PUBLIC_KEY}"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<LANGFUSE_HOST>/api/public/otel/v1/traces"

export OTEL_TRACES_EXPORTER=otlp
export OTEL_SERVICE_NAME=<service_name>
export OTEL_INSTRUMENTATION_SPRING_AI_EXPERIMENTAL_CAPTURE_MESSAGE_CONTENT_AS_SPAN_ATTRIBUTES_ENABLED=true
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
java -javaagent:opentelemetry-javaagent-2.30.1.jar  -Dotel.exporter.otlp.protocol=grpc -jar chatbot-0.0.1-SNAPSHOT.jar

参数说明：

  • OTEL_INSTRUMENTATION_SPRING_AI_EXPERIMENTAL_CAPTURE_MESSAGE_CONTENT_AS_SPAN_ATTRIBUTES_ENABLED=true：务必开启，否则只能看到模型 Span，却看不到 Prompt 和 Output 的具体内容。

5. 打开前端页面验证

访问：http://localhost:8080/chatui/index.html

可测试以下场景：

  • 普通问答："今天星期几"
  • Tool 调用："帮我查看某个文件内容"
  • Shell 调用："列出当前目录文件"
  • Python 执行："帮我算 123 * 456"

效果

查看 Span 列表

链路详情

对于 Agent 应用，理想的链路结构是：

HTTP Span (POST /run_sse)
└── Agent Span (stream_agent SAA)
    ├── LLM Span (chat qwen-plus)
    ├── Tool Span (execute_shell_command)
    ├── LLM Span (chat qwen-plus)
    ├── Tool Span (execute_python_code)
    └── LLM Span (chat qwen-plus)

这套结构能清晰回答：

  • 请求是否进入 Agent？
  • Agent 调用了多少轮模型？
  • 哪个 Tool 被触发？参数和结果是什么？
  • 耗时主要集中在模型还是 Tool？

观测价值

观测层级 你能看到什么 解决什么问题
请求层 POST /run_sse 耗时、状态码 请求是否到达应用？
Agent 层 Agent 总耗时、推理轮次 应用是否执行了 Agent 编排？
模型层 模型名称、token 用量、prompt/output 模型收到了什么？产出了什么？
Tool 层 Tool 名称、参数、结果、错误 Agent 为什么会这样回答？

得益于 Java Agent 的自动插桩，上述所有 Span 的关键属性（如 Prompt 内容、Tool 参数、Token 用量、错误信息等）都会自动作为 Span 标签上报，你无需编写任何额外的埋点代码。这些属性足以支撑日常的故障排查、性能分析和成本核算。

总结

对于 Spring AI + Spring AI Alibaba 这类 Agent 应用，接入观测云的核心不是"把一次请求打成一个 Trace"那么简单，而是要将应用拆解为 HTTP、Agent、LLM、Tool 四个可理解、可定位、可优化的观测层次。

Java Agent 方案的价值在于：

  • 不要求业务代码大改，接入成本极低
  • 自动将 Spring AI 的模型调用和 Spring AI Alibaba Agent Framework 的执行过程统一串联
  • 让一次 /run_sse 请求背后的模型轮次、系统提示、用户输入、模型输出、Tool 参数、Tool 结果以及整体耗时分布，全部落到同一条链路中

从此，AI 应用的观测不再停留在"服务是否可用"，而是真正进入 "为什么这样回答、为什么这么慢、问题出在模型还是 Tool、当前版本是否真的接入成功" 的深度排障与优化闭环。

继续阅读

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通，按量计费，真正的云服务！

立即开始

选择观测云版本

免费版 商业版 企业版

代码托管平台

GitHub Gitee