agents llm architecture typescript python rag

利用Langfuse和OCI实现企业级AI智能体的可观测性。

为何日志、指标和追踪无法满足生成式AI智能体的需求，以及如何利用OCI Agents上的开源Langfuse来追踪提示词、工具调用、令牌和会话。

发布者：REACTAPP.TOP加入本站 2026年10月28日阅读约 10 分钟2299 词

来源: Observability for Enterprise AI Agents: an open-source solution

日志、指标和追踪数据无法说明企业级 AI 智能体为何会给出错误答案。要理解这些系统，还需要查看提示词、传递给模型的上下文、工具调用情况、令牌使用量、响应时间以及输出质量。本文将阐述为什么生成式 AI 需要不同的可观测性方法，随后通过展示基于 Langfuse 的具体架构来说明如何利用其与 OpenAI Responses API 的兼容性将相关功能集成到 OCI 企业级 AI 智能体中。

为何这很重要

凡是调用一个或多个大型语言模型来生成结果的工作流都被称为“智能体”，但这模糊了真正的区别。真正的智能体具备自主性、工具使用能力和上下文管理能力，同时也带来了更高的运营复杂性。

企业在面临另一个更为紧迫的问题：人们往往关注人工智能的“神奇”之处，却忽视了为确保这些系统稳定运行、可控且保持高质量所需做的工作。可观测性正是这类工作中的首要任务。对于复杂的生成式AI模型而言，这并非技术上的琐事，而是帮助理解模型行为、分析错误、评估回答质量以及控制成本与延迟的关键。

下文前半部分将阐述可观测性的含义及其在生成式AI中的应用。后半部分则介绍一种可在OCI上轻松运行的开源方案，并举例说明该方案会收集哪些数据，以及这些数据为何能发挥作用。

可观测性的含义

可观测性是复杂系统所具备的属性。简单来说，如果能够通过系统发出的、可被收集和分析的信号来推断出其内部行为，那么该系统就是可观测的。更正式地表述，两种不同的内部状态必须能够通过外部信号区分开来。系统发出的信号必须能够可靠地揭示其内部状况。

由此可得出两个结论：在包含众多组件、依赖关系及交互作用的系统中，可观测性尤为重要；此外，仅从外部观察是不够的，因为系统需要经过专门设计并配备相应工具，才能生成有用的信息。要正确运行诸如企业级AI代理这样的系统，就必须收集能够反映其状态、行为、异常情况及性能的遥测数据。

这就是可观测性与传统监控的不同之处。监控能够回答你事先想好的问题，比如某个服务使用了多少CPU资源，或者某个请求的处理速度有多慢。而可观测性则必须让你能够调查那些意外情况，即设计阶段无人预料到的问题与疑问，这类问题通常被称为“未知的未知”。

生成式AI出现之前的可观测性

此处所说的“传统系统”指的是在生成式AI成为主流之前构建的应用程序，大致时间在2023年之前。这类系统的可观测性依赖于三种类型的数据：日志、指标和追踪信息。

日志和指标我们都很熟悉。而追踪则是对单个请求或交互的端到端记录，由描述各个步骤的片段组成。在微服务架构中，一个追踪可能涵盖整个应用事务，其中包含 API 调用、数据库查询或对外部服务的调用等片段。要使这种方法发挥作用，就必须跟随请求遍历它所涉及的每一个组件。

对于生成式 AI 智能体而言，仅靠这种传统模型是不够的。除了日志、指标和追踪之外，还需要观察模型具体做了什么、接收了什么上下文、调用了哪些工具，以及其响应的实际质量如何。

生成式 AI 带来了哪些变化

传统软件的行为相对容易预测。而基于生成式AI构建的系统则不然，尤其是当它们拥有自主决策能力时。大型语言模型的输出受到的影响因素远不止用户的输入，所有这些因素都必须清晰可见。

针对大型语言模型系统的可观测性设计至少需要涵盖以下四方面：

模型及其调用参数
发送的指令及实际提示内容
提供的上下文，包括之前的对话记录
系统的执行过程，包括工具调用、中间输出、延迟以及令牌使用情况

仅查看最终答案是远远不够的。要理解一个生成式AI系统，就必须能够针对任何痕迹还原出所有影响响应的因素。

一旦模型拥有操作自由度，这一点就更为重要。如果它能够选择要调用的工具、行动的顺序、参考的资料来源以及何时停止，那么仅靠提示词和输出结果是不够的。你需要看到决策过程本身，包括工具调用的顺序、时间节点以及中间结果。

即便有完整的追踪记录，往往也无法判断输出结果的好坏。为此，通常需要为每条追踪记录附加评分，这些评分可以来自传统逻辑，也可以来自另一款大型语言模型，也就是现在常见的“以大型语言模型作为评判者”的技术。

可以考虑对RAG的回答进行评估。它的答案可能部分正确，或者在没有检索到相关来源支持的情况下仍显得合理。此时至少需要区分两个问题：根本原因，如信息检索、重排序或生成过程；以及依据性，即该答案是否真正基于检索到的文档。依据性检查能够发现没有依据的陈述，从而识别出可能的幻觉。

所有这些意味着通用型可观测性平台并不足以应对生成式AI。你需要一种能够原生捕获这些信息且不会增加过多监控成本的工具。真正的区别在于覆盖范围——对于生成式AI，除了像以往一样关注基础设施和速度外，还需关注模型所看到的上下文、它所做的决策、生成内容的质量以及其行为的一致性。

从理论到实际应用环境

因此，企业级智能体的可观测性除了传统的指标外，还必须涵盖提示词、上下文、工具调用、响应时间、令牌消耗、输出质量，以及导致错误或不良回答的可能原因。实际问题在于如何以简单有效的方式获取所有这些信息，并使其适用于企业环境。下面的答案是一种开源方案，可在 OCI 上轻松部署。

Langfuse

在用于LLM和智能体可观测性的开源工具中，Langfuse尤为突出。它是一个用于追踪、可观测性分析以及LLM应用评估（打分）的平台，涵盖了上述大部分数据：提示词、输出结果、追踪信息、元数据、响应时间、令牌使用情况、工具调用记录以及评估分数。它不仅仅是一个日志服务，还能通过以追踪记录和会话为框架的结构化方式，让你清晰了解生成式AI应用的实际运行状况，而无需在杂乱的文本行中手动搜索。

为何OCI能让集成变得如此简单

OCI Enterprise AI Agents 提供的 API 与 OpenAI Responses API 完全兼容。这不仅方便使用，更能让您复用庞大的 OpenAI 兼容生态系统中的各类工具、库以及开发模式。对于 Langfuse 来说，它大幅减少了从模型调用中收集遥测数据以及构建可观测性层的繁琐工作，让您有更多时间用于分析而非基础架构搭建。这正是 OCI 与 Langfuse 能在企业环境中完美结合的重要原因。

快速的概念验证部署

对于概念验证而言，Langfuse 可以通过 Langfuse 仓库中的官方 Docker Compose 部署方式轻松安装在 OCI 上，例如 Linux 虚拟机中。但这并不一定是生产级企业环境的最终架构。它足以用于验证想法、收集真实的遥测数据，并了解集成后可以进行哪些分析。实际上，它很快就能构建出一个可通过浏览器访问的可用平台，能够接收来自 Python 大语言模型应用程序的追踪数据。

连接代码

在 Langfuse 实例运行后，下一步是为应用程序添加监控功能，以便模型调用相关的遥测数据能够自动传输。由于与 Responses API 兼容，对于那些已经基于 OpenAI 风格的调用方式编写的 Python 应用来说，这非常简单。应用程序可以继续以原有的方式调用模型，而 Langfuse 会记录下重要的细节。

需要做的修改很少：

设置几个环境变量。
使用 Langfuse 库提供的客户端，该客户端已内置功能用于收集和发送追踪数据。
将 conversation_id 作为 session_id 传递，这样同一对话中的请求就会被归入同一个会话中。
可选地强制立即发送追踪数据，否则数据会在几秒后自动发送。

会收集哪些数据

集成之后，Langfuse会自动收集大量有用信息。对于客服人员而言，这些信息不仅包括模型的输入和输出，还包括执行流程、中间环节、工具调用以及时间信息，这些都有助于还原结果的生成过程。

最相关的信息包括：

模型及其版本
发送的提示词
生成的输出内容
与调用相关的元数据
追踪结构及各类时间节点
延迟指标，包括面向用户的指标如生成第一个标记的时间
输入和输出标记的数量，用于成本分析
工具调用及其详细信息
与追踪记录相关的评分和评估结果

并非所有有用的信息都会自动出现，这是有意为之，因为平台无法知晓您的业务认为什么是好的答案。特定领域的评分、自定义指标以及业务元数据需要由应用程序来添加，有时甚至是必须如此。正是自动收集与人工补充的结合才使得该工具如此有效。

会话

Langfuse 可以通过 session_id 将同一用户会话中的多个轨迹关联起来。在这种设置下，对话是通过 Responses API 的标准 conversation_id 来识别的，因此将 session_id 设为该值即可将同一对话中的所有请求关联起来。随后即可在用户界面中浏览这些会话，每个会话包含多个轨迹。

查看轨迹详情

分析过程中就能看到相关结果。Langfuse界面允许你详细查看每一项交互，从而找出那些否则会散见于应用日志、零散元数据及代码中的信息。对于单条追踪记录，你可以看到实际发送的提示词、所使用的模型及其参数、执行时间、消耗的令牌数、所有调用的顺序以及每个阶段的输出结果。在调查异常行为、延迟问题、不断上升的成本或质量不佳的回答时，这些信息尤为重要。例如，响应缓慢可能源于一系列复杂的工具调用、过长的提示词或生成第一个令牌的速度过慢，而每种情况都有不同的解决方法。如果没有按时间跨度显示的计时数据和令牌计数并列呈现，就只能凭猜测来判断问题出在哪儿。

由此衍生出一个实用的习惯：将每一次对话都视为日后可以重新回顾的内容。当用户在一周后反馈某个回答不佳时，会话视图能让您查看确切的追踪记录、原始提示词与上下文，以及知晓是哪个工具输出了什么结果，而无需凭记忆重新还原当时的情况。

需牢记的局限

采用 Langfuse 也无法解决生成式 AI 系统中所有的可观测性与评估难题。虽然包含丰富上下文的追踪记录十分必要，但往往并不足够。最有用的评估指标通常取决于应用领域，需要专门设计。此外，真实的企业环境要求我们必须仔细考虑安全性、敏感数据保护、遥测数据保留策略、访问控制以及部署架构等问题。

即便如此，开源平台加上OCI的完整API兼容性，仍为企业代理提供了一套出色的可观测性解决方案基础。

核心结论

对于企业级AI代理而言，可观测性并非技术细节或可选附加功能，而是理解其行为、分析错误、评估答案质量以及降低响应时间和运行成本的前提条件。仅监控基础设施、应用日志和标准指标远远不够，还需要更贴近代理实际操作的数据：提示词、上下文、工具调用记录、令牌消耗情况、用户感知的延迟以及评估分数等。

Langfuse 是一个尤为有趣的开源选项，因为它能够捕获并整理大量遥测数据，而 OCI Enterprise AI Agents 中兼容 OpenAI 的 API 也使得集成变得十分简单。不过，没有哪个平台能够独自解决所有问题——安全性、治理机制、敏感数据处理以及领域特定评分的设计依然至关重要。

如果这些智能体要摆脱演示阶段，成为真实系统中可靠的部分，可观测性绝不能被忽视。虽然无法消除它们的复杂性，但完全可以且应当让这种复杂性变得可见。

一个自然的下一步是通过更系统化的质量评分来丰富追踪数据，尤其是由大语言模型作为评估者生成的评分，这样每条追踪数据就能在技术执行数据之外，还包含对响应质量的评估。