LLM 应用一旦进入生产，Prompt、Token、延迟和错误就不能再靠日志猜。本文给出一套 Spring AI + OpenTelemetry + 自托管 Langfuse 的落地方案。

很多团队做 AI 应用时，第一阶段最关心的是“模型能不能跑通”。但一旦进入真实业务场景，问题很快就变成： 为什么这次回答变慢了？为什么 Token 成本突然升高？为什么同一个问题昨天正常、今天异常？到底是哪一步 Prompt、工具调用或模型返回出了问题？

这些问题只靠普通日志很难定位。因为 LLM 调用不是一次普通的 HTTP 请求，它往往包含 Prompt 组装、RAG 检索、工具调用、 模型请求、流式响应、Token 统计、异常重试等多个环节。缺少可观测性，就等于在黑盒里调生产问题。

一句话方案：在 Spring AI 应用中接入 OpenTelemetry，把每一次 LLM 调用封装为 Trace/Span， 再通过 OTLP 导出到自托管 Langfuse，实现 Prompt、Token、延迟、成本和错误的统一观测。

一、为什么 Spring AI 应用需要专门的 LLM 可观测性？

传统应用的可观测性通常关注 CPU、内存、数据库查询、接口耗时和错误率。但 LLM 应用多了一批新的关键指标：

Prompt 可追踪知道最终发给模型的输入是什么，而不是只看业务参数。

Token 可统计区分 prompt tokens、completion tokens 和 total tokens。

成本可估算将模型、Token 和调用次数关联起来，避免费用失控。

链路可回放从用户请求一路追到模型调用、工具调用和异常节点。

对企业系统来说，LLM 可观测性不是锦上添花，而是 AI 应用进入生产环境的基础设施。

二、整体架构

推荐的架构可以分为五层：业务入口、Spring AI 调用层、OpenTelemetry 采集层、OTLP 导出层和 Langfuse 观测平台。

图 1：Spring AI + OpenTelemetry + Langfuse 整体架构

在这个架构中，Spring Boot 负责承载业务应用，Spring AI 负责统一模型调用抽象，OpenTelemetry SDK 负责生成和导出 Trace， Langfuse 负责接收、存储和展示 LLM 相关观测数据。

这套设计的关键点是：不要把 LLM 调用当成孤立日志处理，而是把它纳入完整分布式链路追踪体系。 这样排查问题时，就可以从一次用户请求直接看到模型调用、Token 消耗、耗时分布和异常原因。

三、一次请求的完整链路

当用户发起一次请求后，系统会先生成或继承 Trace Context。随后，业务逻辑、RAG 检索、Prompt 组装、Spring AI 调用和模型响应都会被串联起来。

图 2：一次 LLM 请求从进入系统到进入 Langfuse 的流程

最终，在 Langfuse 中可以看到每一次调用的完整上下文，包括：

• 请求对应的 trace_id 和 span_id
• 使用的模型名称，例如 gpt-4o、gpt-4.1 或企业私有模型
• Prompt tokens、Completion tokens、Total tokens
• LLM 调用延迟、总请求耗时和异常类型
• 工具调用、RAG 检索、下游服务调用等上下文

四、接入 OpenTelemetry 的核心思路

在 Spring Boot 应用里，OpenTelemetry 通常有两种接入方式：一种是使用 Java Agent 自动采集，另一种是在关键 LLM 调用处手动创建 Span。 对于 LLM 应用，建议两者结合。

1. 基础链路自动采集

HTTP 请求、数据库访问、Redis、消息队列等常规链路可以交给 OpenTelemetry Java Agent 自动采集。这样可以快速获得完整的后端请求链路。

2. LLM 调用手动增强

Spring AI 的模型调用处需要补充 LLM 语义字段，例如模型名称、Token 使用量、Prompt 长度、响应耗时、错误类型等。 这部分信息通常需要在业务代码或统一拦截器中显式写入 Span Attribute。

// 示例：为一次 LLM 调用补充观测字段span.setAttribute("llm.system", "spring-ai");span.setAttribute("llm.model", modelName);span.setAttribute("llm.prompt_tokens", promptTokens);span.setAttribute("llm.completion_tokens", completionTokens);span.setAttribute("llm.total_tokens", totalTokens);span.setAttribute("llm.latency_ms", latencyMs);

这些字段进入 Langfuse 后，就不只是“有日志”，而是能够按模型、耗时、错误、Token 和成本进行分析。

五、为什么选择自托管 Langfuse？

Langfuse 更贴近 LLM 应用场景。相比只看通用 APM，它能更自然地展示 Prompt、Response、Token、Session、Trace 和模型调用细节。

数据可控自托管部署，适合对 Prompt、用户数据和模型输出有合规要求的团队。

LLM 友好围绕 Prompt、Trace、Token、评估和模型调用设计。

工程兼容通过 OpenTelemetry/OTLP 接入，不强绑定某个模型供应商。

排障直接从异常请求直接定位到具体 Prompt、工具调用或模型返回。

六、生产环境必须考虑的 5 个细节

1. 采样策略

生产环境不一定需要 100% 采集。可以对普通请求按比例采样，对错误请求、慢请求和高成本请求全量采集。

2. 脱敏与合规

Prompt 和 Response 可能包含用户隐私、合同内容、内部知识库信息。进入 Langfuse 前，应支持字段级脱敏、正则脱敏或按场景关闭内容记录。

3. 异步导出

Trace 导出不能阻塞主业务链路。推荐使用批处理和异步导出，避免观测平台波动影响用户请求。

4. 故障降级

Langfuse 或网络不可用时，应允许丢弃 Span，而不是拖垮业务系统。可观测性系统应该服务于稳定性，而不是成为新的单点风险。

5. 统一字段规范

建议在团队内统一字段命名，例如 llm.model、llm.total_tokens、llm.latency_ms、 error.type。字段标准化后，后续统计、告警和报表才有基础。

七、适合哪些团队采用？

这套方案尤其适合以下场景：

• 已经使用 Spring Boot / Spring Cloud 构建企业应用的团队
• 正在用 Spring AI 接入 OpenAI、Azure OpenAI 或私有大模型的团队
• 希望把 LLM 调用纳入现有 OpenTelemetry 体系的团队
• 对 Prompt、模型输出和用户数据有合规要求，需要自托管观测平台的团队
• 希望分析 Token 成本、慢请求、错误率和模型表现的团队

八、落地建议

建议按三个阶段推进：

第一阶段：先看见

接入 OpenTelemetry 基础链路和 Langfuse，确保每一次 LLM 请求都能被追踪。

第二阶段：看清楚

补齐模型名称、Token、延迟、错误类型、用户会话、业务场景等关键字段。

第三阶段：可治理

基于 Trace 数据建立成本报表、慢请求分析、Prompt 质量评估、异常告警和模型对比机制。

最终目标不是多一个监控面板，而是让 LLM 应用从“能跑”进入“可解释、可排障、可优化、可治理”的生产状态。

结语

AI 应用的复杂性，往往不是出现在 Demo 阶段，而是出现在生产环境。模型调用越多，Prompt 越复杂，工具链越长， 可观测性的价值就越高。

对 Spring AI 技术栈来说，OpenTelemetry 提供了标准化链路追踪能力，Langfuse 提供了面向 LLM 的观测与分析界面。 两者结合，可以帮助团队真正掌握每一次 AI 调用背后的成本、质量和风险。

🔗 获取完整可运行代码

完整的项目代码（含 pom.xml、主类、工具实现、Docker Compose、集成测试）以及 执行验证截图，均已发布在：

https://exesolution.com/solutions/spring-ai-opentelemetry-langfuse-observability