使用AI智能体构建应用-第十章生产环境监控

Alan

1 天前

无论你是产品负责人、机器学习 (ML) 工程师，还是站点可靠性工程师 (SRE)，一旦智能体（Agent）上线生产环境，就需要了解它们在做什么以及为什么这样做。发布智能体系统仅仅是走完了一半的路程。真正的挑战始于你的智能体在动态、不可预测且高风险的环境中运行之时。监控是从现实中学习的方式——它是如何在故障升级前捕捉它们，在用户注意到之前识别回退（Regression），并根据现实世界的信号调整系统的关键。

与传统软件不同，智能体的行为具有概率性。它们依赖于基础模型，将各种工具链接在一起，并响应不受限制的用户输入。无法为每一个场景编写详尽的测试。这就是为什么监控会成为所部署智能体基础设施的神经系统。

监控不仅仅是为了发现问题。它是紧密反馈循环的骨干，能够加速学习和迭代。监控做得好的团队学得更快，发布更安全，并且随着每一次部署提高可靠性。

在本章中，我们将重点关注开源监控。虽然有像 Arize AX、Langfuse 和 WhyLabs 这样优秀的商业平台，但我们在这里将专注于你可以自托管并自由扩展的工具。我们的参考技术栈包括：

OpenTelemetry：用于智能体工作流的插桩（Instrumenting）。
Loki：用于日志聚合和搜索。
Tempo：用于分布式追踪（Distributed Traces）。
Grafana：用于可视化、警报和仪表板。

我们将逐步介绍如何将这些工具中逐一与基于 LangGraph 的智能体系统集成，然后展示这些部分如何组合成一个反馈循环，从而弥合观察与改进之间的差距。

本书代码请见：https://github.com/alanhou/ai-agent。

监控是学习的方式

了解智能体故障的根本原因——从软件错误和基础模型变异到架构限制——对于主动维护和系统适应性至关重要。每种类型都需要针对性的检测、分析和修复，以维持生产环境的稳定性。

最好的智能体系统通过不断的反馈一步步改进。传统的监控针对崩溃或吞吐量下降做出响应，但对于智能体来说，基石是：揭示概率行为中出现的问题，并在不确定性中指导开发。

智能体的故障是微妙的——一个工具调用成功了但引发了级联错误，LLM 的输出看起来很流畅但具有误导性，或者一个计划部分有效但未达成目标。这些不匹配很少会导致系统崩溃；监控必须迅速暴露问题，这使得生产环境的可观测性成为必选项。

故障不仅仅是事故——它们是测试用例。每当智能体在生产中出现故障时，该场景都应被捕获并转化为回归测试。但成功也是如此：当智能体很好地处理了一个复杂案例时，该追踪（Trace）可以成为值得保留的“黄金路径”。通过将故障追踪和典型成功案例导出到测试套件中，可以创建一个反映真实世界条件的、鲜活的 CI/CD 语料库。这种做法有助于“左移”你的监控策略——在开发早期捕捉问题，并确保持续针对生产行为的实际复杂性来验证新的智能体版本。

监控像智能体这样的概率系统的一个关键挑战是区分真正的“故障”（需要修复的系统性问题）与预期内的变体（固有的非确定性，输出虽有不同但仍可接受）。一个简单的决策树可以对此进行指导。从输出开始——它是否符合成功标准（例如，评估分数 > 0.8）？如果是，监控趋势即可，无需采取行动。如果否，检查可复现性（重新运行 3-5 次；失败率 > 80% 表明存在系统性 Bug，需工程审查）。如果不可复现，评估置信度/方差（例如，LLM 分数 > 0.7，与基线的 Kullback-Leibler 散度 < 0.2）。在界限内意味着预期内的变体（记录以观察漂移），而在界限外则通过暗示异常故障（例如，通过群体稳定性指标 > 0.1 检测到输入漂移，触发缓解措施如重新训练或添加护栏）。这个流程图应用在 Grafana 等工具中，可以防止对噪声的过度反应，同时尽早捕捉到真正的性能退化。

有效的监控跨越基础设施信号（延迟、错误率、CPU）和语义行为（意图理解、工具选择、幻觉、任务放弃）。用户的意图是否被理解了？是否选择了正确的工具？系统是否产生了幻觉内容？用户是否中途放弃了任务？这些不是传统监控系统所要回答的问题，但它们对于确保智能体保持可信、有用和一致至关重要。

构建一个分层的反馈循环：对运行时事件（工具调用、生成、回退）进行带上下文的插桩，流式传输到 Loki（日志）、Tempo（追踪）和 Grafana（可视化/警报）等后端。通过外部批评者（Critics）实时附加评估信号——幻觉分数或漂移指标。

值得强调的是，所有这些可以——也应该——是用于生产服务的一套可观测性管道的一部分。用于跟踪服务运行状况的同一个 Prometheus 实例也可以跟踪智能体的成功率。SRE 使用的同一个 Grafana 仪表板可以包含语义错误率、模型延迟分布和工具使用图表。不需要单独的监控技术栈；智能体受益于与所有其他关键软件服务相同的严谨性和可见性。

当然，可观测性数据通常包含敏感内容。日志可能包括用户消息、工具输入或中间的 LLM 生成内容。为了保持合规性和用户隐私，团队应配置具有严格基于角色的访问控制（RBAC）的独立监控集群。敏感数据可以路由到具有静态加密和访问审计的隔离后端，确保在不损害信任或合规义务的情况下进行调试和性能分析。在导出之前从可观测性日志中编辑、哈希处理或屏蔽个人身份信息（PII）也是常见的做法。OpenTelemetry 提供了在 Span 导出期间进行数据清洗的钩子，从而能够细粒度地控制什么数据可以离开应用程序的边界。

最终，监控将指标转化为行动——帮助团队发现关键问题并快速响应。以下部分将展示开源工具如何构建此循环，从而加速实时环境中的开发、鲁棒性和可靠性。

在深入研究插桩细节之前，定义实际上想要观察的内容很有帮助。有效的监控始于选择正确的指标——这些指标不仅揭示系统是否启动，还揭示其是否按预期工作。

表 10-1 是一个实用的指标分类法，按抽象层级组织，可以指导收集、可视化和警报的内容。

表 10-1. 指标分类法

指标	目的	示例行动
基础设施层
CPU/内存使用率	监控系统健康状况和扩展压力	自动扩展或优化内存密集型工具
正常运行时间/可用性	跟踪服务可用性和故障恢复	触发事故响应
请求延迟 (P50, P95, P99)	确保负载下的响应能力	参与调整缓存或重试逻辑
工作流层
任务成功率	确定智能体完成预期工作流的频率	调查故障或更新提示词 (Prompts)
Token 用量	测量工作流级别的 Token 消耗	快速增加或减少可能表明有问题
工具调用成功/失败率	检测集成的降级或工具的滥用	修补包装器 (Wrappers) 或自动回退
工具使用超出速率限制	跟踪智能体工具调用在特定时间窗口内超过预定义限制的实例	调整限制或调整调用频率
重试频率	识别计划或工具中的不稳定性或不可靠性	对重试进行去抖动 (Debounce) 或优化规划逻辑
回退 (Fallback) 频率	显露主要工作流中的故障	提高鲁棒性或升级至人工处理
输出质量
Token 用量 (输入/输出)	跟踪冗长程度、成本和生成效率	删减长提示词或切换模型层级
幻觉指标	测量生成内容的语义准确性	引入基准 (Grounding) 或 LLM 批评步骤
嵌入 (Embedding) 较基线的漂移	检测用户输入或任务框架中的分布偏移	调整工作流或微调模型
用户反馈
重新查询/改写率	测量用户是否在第一次尝试时就被理解	改进意图分类
任务放弃率	识别让用户困惑或沮丧的工作流	简化流程或添加澄清提示词
显式评分 (赞/踩)	收集系统有用性的定性评估	用它来筛选输出以进行评估

所有这些指标都可以通过 OpenTelemetry 记录，在 Prometheus 或 Loki 中聚合，在 Grafana 中可视化，并在（适当的情况下）链接到 Tempo 中的追踪。目标不是收集所有事件，而是收集检测有意义的变化所必需的部分——并以支持快速诊断和持续改进的方式进行。

监控技术栈

选择正确的监控是一个重要的决定，既可能加速也可能阻碍智能体系统的开发进度。可观测性不仅必须捕获传统的基础设施指标（例如延迟、正常运行时间），还必须捕获语义洞察，如幻觉率、工具功效和用户输入的分布偏移。当前的生态强调开源工具，这些工具可以与 LangGraph、CrewAI 和 AutoGen 等框架无缝集成，支持分布式追踪、日志记录和警报，同时处理基础模型的概率特性。许多公司已经拥有用于托管日志技术栈（例如 Splunk、Datadog 或 New Relic）的既定企业计划，基础模型或智能体不一定需要全新的监控解决方案。在大多数情况下，继承现有的技术栈是明智的——利用其熟悉度、可扩展性和集成——除非你有强烈的需求，需要像基础模型原生的评估或轻量级自托管这样的专门功能。我们将在以下小节中探索几个同等的开源选项，重点介绍功能、集成和权衡，以帮助你根据环境进行选择或调整。

Grafana 配合 OpenTelemetry, Loki, 和 Tempo

该技术栈提供高可组合性，使其成为围绕智能体构建自定义可观测性团队的灵活选择：

设置与集成
在 LangGraph 应用程序中初始化 OpenTelemetry (OTel) 以导出 Span（例如，用于工具调用或 LLM 生成）和指标（例如，Token 用量）。日志路由到 Loki 进行结构化查询，追踪进入 Tempo 获得端到端的可见性。Grafana 从两者中提取数据，建立将智能体行为（例如规划延迟）与系统健康状况相关联的仪表板。示例：用 OTel Span 包装一个 LangGraph 节点以跟踪 tool_recall 指标，导出到 Tempo 以查询失败的会话。
关键特性
关键特性是针对语义指标的实时仪表板（例如通过自定义插件的幻觉分数）；对重试峰值等异常情况的警报；以及强大的 AI 扩展社区（例如 2025 Grafana LLM 漂移检测插件）。它可用于生产环境扩展，自托管时开销低。
优缺点
优点是灵活性（混合搭配组件）和无供应商锁定；缺点是多工具设置（需要分别管理 Loki/Tempo）以及非基础设施团队的学习曲线较陡峭。这对于将现有基础设施监控扩展到智能体的企业来说是理想的选择。

ELK Stack (Elasticsearch, Logstash/Fluentd, Kibana)

ELK Stack 是一个成熟的选项，强调强大的搜索和分析，通常从现有的企业配置扩展到 AI 工作负载：

设置与集成
使用 OTel 收集器将智能体追踪/日志发送到 Elasticsearch（通过 Logstash 摄取）。Kibana 提供用于查询和仪表板的 UI。对于 LangGraph，插桩节点以记录结构化事件（例如带有工具参数的 JSON），利用 Elasticsearch 的 ML 任务对智能体输出进行异常检测。示例：跨会话查询“置信度 < 0.7 的幻觉事件”，并与用户反馈相关联。
关键特性
关键特性包括针对 LLM 输出的高级全文和向量搜索（例如基于嵌入的漂移检测）；用于预测性警报的内置 ML（例如预测工具故障率）；以及针对海量日志的集群可扩展性。
优缺点
优点是卓越的搜索和分析（例如对提示词的模糊匹配，更适合长尾故障）和企业级的可扩展性。缺点是资源需求较高（Elasticsearch 是内存密集型的）和更复杂的部署（多个服务）。它最适合已拥有 ELK 的团队，将其扩展用于特定于智能体的语义日志记录，而无需从头开始。

Arize Phoenix

Phoenix 专注于 LLM 追踪和评估，为现有环境中的智能体监控提供面向调试的扩展：

设置与集成
使用 Phoenix 的 Python SDK 对 LangGraph 进行插桩（例如，跟踪带有评估的 LLM 调用）。它支持混合使用的 OTel 导出。示例：使用自动评分器可视化智能体追踪获取准确性，并导出到 Notebooks 进行分析。
关键特性
关键特性包括带有评估的结构化追踪（例如 RAG 质量、幻觉检测）；用于 ML 工作流的 Jupyter 集成；以及 2025 年针对多智能体协调指标的增强功能。
优缺点
优点是它专门用于评估/调试（更快地获得关于智能体质量的洞察）且对于原型设计来说是轻量级的。缺点是它仅限于追踪/评估（作为全量日志/指标的补充），并且更面向开发而非运维。它非常适合研究或机器学习团队将智能体洞察添加到托管的企业技术栈中。

SigNoz

SigNoz 是一个统一的、OTel 原生的平台，在一个工具中结合了指标、追踪和日志，适合简化基本监控设置的扩展：

设置与集成
SigNoz 直接接收 OTel 数据，并为 Python（例如 LangGraph）提供自动插桩。为智能体步骤（例如规划延迟）添加 Span 并通过其 UI 进行查询。示例：跟踪一个多步骤智能体流程，按 token_usage > 1000 过滤以发现低效之处，并带有针对 LLM 质量的内置评估。
关键特性
它具有集成的 AI 驱动洞察（例如智能体追踪上的异常检测）；针对 LLM 指标的自定义仪表板（例如提示词漂移）；以及基于 ClickHouse 后端的轻量级自托管来提升效率。
优缺点
优点包括设置更简单（单个应用程序），小团队的开销更低，以及强大的 OTel 支持和 AI 扩展（例如 2025 年针对幻觉自动评分的更新）。缺点是它的生态系统扩展性较差（插件较少），可视化虽然功能齐全但不如高级工具先进。它非常适合初创公司或专注于 ML 的团队扩展轻量级监控，而无需繁重的基础设施添加。

Langfuse

Langfuse 专注于基础模型和智能体可观测性，使其易于扩展现有技术栈，为智能体提供以语义为重点的追踪：

设置与集成
通过 LangGraph 中的 SDK 集成（例如，用 Langfuse 追踪器封装节点）。它会捕获提示词、输出和评估（例如一致性的自定义评分器）。示例：记录完整的智能体会有，自动评估幻觉，并导出追踪以进行回归测试。
关键特性
具有 LLM 原生指标（例如 Token 成本跟踪、提示词的 A/B 测试）；用于调试的会话回放；并且可以使用 PostgreSQL 等数据库后端进行自托管。
优缺点
优点是它专为智能体/LLM 量身定制（因为内置评估节省了自定义工作），并且对开发团队很容易（专注于应用级洞察）。缺点是它的范围较窄（在 CPU 等基础设施指标上较弱；需与 Prometheus 搭配使用），并且对于非 LLM 遥测的可扩展性较差。它非常适合在不彻底改革核心技术栈的情况下，用特定于智能体的功能扩展企业日志记录。

选择正确的技术栈

所有这些开源技术栈都可行，是同一级选择——应先评估当前的技术栈。如果你有企业托管的解决方案，请使用 OTel 插桩扩展它以获取智能体信号，除非需要像自动评估（倾向于 Langfuse/Phoenix）或高级搜索（ELK）这样的 LLM 特定功能。对于新项目，Grafana 或 SigNoz 提供了广泛的覆盖范围。根据团队专业知识、数据量和集成需求进行评估——许多可以混合使用（例如，OTel 到多个后端）。表 10-2 一目了然地展示了这些比较。

表 10-2. 监控和可观测性技术栈比较

技术栈	关键优势	最适合	权衡（相对于 Grafana）
Grafana + Loki/Tempo	可组合性和可视化	企业运维 (Ops)	需要管理的组件更多
ELK Stack	高级搜索/分析	大规模日志	资源使用率较高
Phoenix	追踪和调试	开发迭代	生产规模有限
SigNoz	统一且轻量级	初创公司/ML 团队	可扩展性较差
Langfuse	基础模型/智能体特定评估	语义监控	基础设施覆盖范围较窄

虽然可观测性领域提供了多种强大的选择——每种都在可扩展性、易用性或 LLM 特定功能方面具有独特的优势——但这种竞争推动了创新，并确保团队能够找到适合其需求的方案，无论是扩展企业技术栈还是重新开始。对于我们在以下部分的示例，我们将专注于带有 Grafana、Loki 和 Tempo 的 OTel，因为它提供了一个高度可组合的开源基础，已被广泛采用，并能与 LangGraph 等智能体框架无缝集成，使我们能够在没有供应商锁定的情况下演示核心概念。选定技术栈后，下一步是插桩——将遥测直接嵌入到你的智能体运行时中以捕获有意义的信号，如下一节所探讨的。

OTel 插桩 (OTel Instrumentation)

构建有效监控循环的第一步是插桩。如果没有高质量的信号直接嵌入到智能体运行时中，就如同盲人摸象。OTel 为跨追踪、指标和日志的结构化、可互操作的遥测提供了基础——并且它与基于 LangGraph 的智能体系统集成良好。

LangGraph 被构建为异步函数调用的图。图中的每个节点代表智能体工作流中的一个功能步骤——可能是规划、调用工具或使用 LLM 生成响应。因为每个步骤都已经隔离并显式声明，所以用 OTel Span 对每个步骤进行插桩是很直接的。这些 Span 创建了一个结构化的追踪，不仅记录了步骤何时开始和结束，还记录了它们试图做什么以及表现如何。

对于每个节点，我们建议在函数开始时启动一个 Span，并用相关的元数据对其进行注释。例如，在工具调用节点中，可能会捕获工具名称、调用的具体方法、响应的延迟、成功或失败状态以及任何已知的错误代码。在 LLM 生成输出的节点中，Span 可以包括提示词标识符、Token 计数、模型延迟以及幻觉风险或置信度分数的标志。

这种插桩不需要重大的架构更改。OTel 的 Python SDK 可以在启动时初始化一次，并且可以使用简单的上下文管理器创建和关闭 Span。分布式追踪上下文会自动在异步调用中传播，即使在复杂的分支智能体流中也能轻松关联端到端行为。下面是一个简化的示例，展示了如何用追踪 Span 包装一个 LangGraph 节点：

from opentelemetry import trace

tracer = trace.get_tracer("agent")

async def call_tool_node(context):
    with tracer.start_as_current_span("call_tool", attributes={
        "tool": context.tool_name,
        "input_tokens": context.token_usage.input,
        "output_tokens": context.token_usage.output,
    }):
        result = await call_tool(context)
        return result

from opentelemetry import trace

tracer = trace.get_tracer("agent")

async def call_tool_node(context):

with tracer.start_as_current_span("call_tool", attributes={

"tool": context.tool_name,

"input_tokens": context.token_usage.input,

"output_tokens": context.token_usage.output,

}):

result = await call_tool(context)

return result

Span 可以包括事件（如回退触发或重试）、嵌套子 Span（用于测量下游 API 调用）以及用于自动错误标记的异常捕获。这些追踪被实时导出到 Tempo 或 Jaeger 等后端，并在 Grafana 中与日志和指标一起可视化。

除了追踪，OTel 还可以发出结构化日志和运行时指标。例如，你可以记录特定工具被调用的次数、每个规划节点的平均响应时间，或每个模型版本的任务失败百分比。这些指标对于创建跟踪长期性能和检测早期退化迹象的仪表板非常宝贵。

插桩必须经过深思熟虑的范围界定。太多的细节会变成噪音；太少则使根本原因分析变得困难。关键是在每个步骤附加刚好足够的上下文——用户请求 ID、会话元数据、智能体配置状态、技能名称和评估信号——以便当出现问题时，证据线索是连贯的、完整的且易于搜索的。

Tempo 充当追踪后端。在 LangGraph 中插桩的每个 Span——每个工具调用、计划生成或回退——都是分布式追踪的一部分。Tempo 以高度可扩展的方式存储这些追踪并支持深度查询。例如，可以过滤规划步骤耗时超过 1.5 秒的所有追踪，或者特定工具调用因给定错误代码而失败的追踪。这使得能够精确调试仅在真实世界的多步骤执行条件下出现的微妙问题。

相比之下，Loki 充当日志聚合层。它捕获来自整个智能体基础设施的结构化日志——通常是 JSON 格式。每个 LangGraph 节点都可以在其执行期间发出结构化日志事件：收到用户查询时、调用工具时、LLM 产生模棱两可的响应时，或当触发回退路径时。日志可以用 Span 和 Trace ID 进行注释，从而可以轻松关联来自同一用户会话或智能体工作流的日志和追踪。虽然 Loki 非常适合结构化日志，但需要全文搜索、基于角色的视图或更高摄取吞吐量的团队也可以考虑 Elasticsearch 或商业选项，如 Datadog 日志或 Honeycomb。

Grafana 将这两个数据流统一到一个单一的界面中。它提供了可视化层，可以在其中并排探索来自 Loki 的日志和来自 Tempo 的追踪。在 Grafana 内，可以构建显示实时追踪数据的仪表板，深入挖掘单个请求，并将结构化日志与性能指标相关联。还可以构建自定义警报规则——例如，标记特定智能体的错误率何时飙升至阈值以上，或者工具响应延迟何时越过定义的边界。

OTel、Tempo、Loki 和 Grafana 共同构成了用于智能体系统的完整开源可观测性技术栈。它们能够对行为进行深度检查、快速根本原因分析、历史趋势评估和主动异常检测。这种集成将原始遥测转化为运营情报——并将运营情报转化为开发加速剂。这种可观测性实现了实时调试、趋势分析和持续学习——所有这些对于智能体在生产中的安全和可扩展部署都是必不可少的。

可视化和警报

一旦你的 LangGraph 智能体通过 OTel 插桩并将日志和追踪流式传输到 Loki 和 Tempo，最后也是最具影响力的一层是可视化和警报——通过 Grafana 实现。Grafana 不仅仅是一个仪表板工具；它是可观测性的运维前端，在这里信号变成故事，指标变成行动。

Grafana 与 Loki 和 Tempo 作为原生数据源无缝连接。对于追踪，Grafana 的 Tempo 集成使你能够浏览单个智能体运行的完整执行追踪。这包括查看代表智能体采取的步骤顺序和时间的 Span 层次结构——从接收用户查询到选择计划、调用工具和组合最终输出。可以按延迟、状态、Span 名称或在 LangGraph 节点中附加的任何自定义属性过滤追踪。这对于调试多步骤智能体行为非常宝贵，特别是在性能下降或出现边缘情况 Bug 时。

对于日志，Loki 插件支持查询智能体执行期间发出的结构化日志事件。Grafana 的日志面板能够可视化所有智能体的实时日志；按智能体名称、用户会话、错误类型或 Trace ID 过滤；并将日志与相关追踪相关联。因为日志和追踪共享通用元数据——如请求或会话 ID——Grafana 能直接从日志量或错误消息的峰值跳转到触发它们的确切追踪。

但 Grafana 真正的力量在于构建适合智能体语义和成功标准的仪表板。如图 10-1 所示，GenAI 可观测性仪表板可以显示关键指标，如请求率、使用成本、Token 消耗以及基础模型和向量数据库的请求分布。例如，你可能会构建一个显示以下内容的仪表板：

每小时每个智能体的 Token 用量（以检测模型冗余回退）
工具调用和规划节点的 P95 延迟
按工作流或提示词模板版本的任务成功率
按工具或技能划分的回退频率
基于随时间推移的用户查询嵌入相似度的漂移指标

图 10-1. 用于 AI 可观测性的 Grafana：该仪表板可视化了基础模型和向量数据库使用的关键指标，包括请求率、成功计数、成本、Token 消耗、请求持续时间、按使用量排名的顶级模型，以及按平台、类型和环境的细分，提供了关于智能体性能和效率的可操作洞察。

这些面板中的每一个不仅有助于可视化系统性能，还可以指导正在进行的开发。如果某个特定工具开始更频繁地失败，或者如果 Token 用量意外增加，这些信号有助于优先考虑调试和优化。

Grafana 还支持自定义警报。你可以定义任何指标的阈值，并通过 Slack、电子邮件、PagerDuty 或任何其他集成触发警报。例如，你可以在以下情况下触发警报：

过去 30 分钟内幻觉率超过 5%
单次会话中重试循环发生超过三次
关键工具的平均响应时间增加超过 50%

警报确保你的团队实时了解回退和异常情况，即使没有人主动观看仪表板。结合 Loki 日志和 Tempo 追踪，这些警报有助于迅速关闭反馈循环。

Grafana 的警报系统具有高度可扩展性，可与 PagerDuty 等流行的事故管理工具无缝集成，以便将通知升级给待命团队——确保高严重性问题（如幻觉率突然飙升或任务失败）触发带有自动寻呼和确认的结构化响应工作流。对于更专业的错误监控，可以分层引入 Sentry 来捕获和分析智能体代码中的异常，提供技术栈跟踪、面包屑（Breadcrumb）和发布健康指标，以补充 Grafana 的仪表板；这对于调试基础模型调用或工具调用中的概率性 Bug 特别有用，Sentry 的 SDK 可以很容易地与 OTel 一起插桩。

对于寻求专为智能体系统定制的一体化解决方案的团队，像 AgentOps.ai 这样的平台提供了一个简化的替代方案，将追踪、指标、评估和警报结合在一个针对基础模型和智能体优化的单一包中。AgentOps.ai 处理语义监控（例如，对输出质量进行自动评分）并与现有技术栈集成，与组合 Grafana 组件相比减少了设置开销——但可能会引入供应商依赖。这些选项创造了灵活性：根据运维成熟度和重点，使用 PagerDuty/Sentry 扩展 Grafana 以获得强大的警报，或者采用 AgentOps.ai 获取更快的智能体具体洞察。

通过将 Grafana 深入集成到智能体开发生命周期中，你为已部署的系统创建了一个动态接口。它成为产品团队、工程师和SRE人员可以观察、调试、迭代和改进的共享画布。在基于智能体的系统世界中——Bug 是概率性的，故障模式是涌现的——这种统一的可见性不仅仅是锦上添花。它是必不可少的。

监控模式

一旦可观测性技术栈就位——涵盖插桩、日志、追踪、仪表板和警报——问题就变成了：我们如何安全地向本质上是概率性、适应性且难以完全预测的智能体系统发布变更？答案在于采用具有监控意识的开发模式，这些模式可以降低实验风险对生产变更建立安全网。在本节中，我们探讨团队可以采用的几种关键模式，以确保其智能体持续安全且响应迅速地进化。

影子模式 (Shadow Mode)

在影子模式下，智能体的新版本或实验版本与当前生产智能体一起运行，处理相同的输入，但不向用户提供其输出。这使开发人员能够在真实世界条件下记录和追踪新智能体的行为，而不会影响用户体验。

使用 OTel，可以对生产智能体和影子智能体都进行插桩，并附加一个共享的请求 ID。来自影子智能体的日志和追踪可以在 Loki 和 Tempo 中相应地标记，从而可以轻松比较行为。你可能会查看工具选择、延迟、Token 用量或幻觉频率方面的差异。这些比较在试用新模型版本、规划策略或提示技术时特别有用。

影子模式实现了更安全的创新。它使团队能够回答：新智能体在实时流量上的表现是更好还是更差？哪里出问题了？哪里改进了？并且它允许你与正常操作并行地持续收集这些数据。

金丝雀发布 (Canary Deployments)

影子模式在不暴露的情况下收集信息，而金丝雀发布则更进一步。金丝雀发布将新的智能体版本提供给一小部分真实用户——比如 1% 或 5% 的流量——而大多数用户继续与基线版本交互。

Grafana 仪表板在此设置中至关重要。通过按版本标签过滤所有指标和追踪，可以直接比较金丝雀智能体和基线智能体之间的成功率、延迟、工具使用情况和错误计数。可以配置警报，以便在金丝雀显示出显著的回退或异常时触发。

如果金丝雀表现良好，部署可以逐渐扩大。如果不行，它可以立即回滚，对用户的影响最小。金丝雀发布提供了在生产环境中快速迭代所需的运维安全性。

回归 Trace 收集 (Regression Trace Collection)

每当智能体在生产中失败时——无论是通过幻觉、规划错误还是工具滥用——它都创造了一个学习的机会。通过自动将这些故障追踪（来自 Tempo）或日志快照（来自 Loki）导出到测试套件中，可构建一个持续更新的回归语料库。

这将生产故障转化为训练信号。失败的工具调用或未对齐的输出成为一个新的测试用例。一旦实施修复，重新运行此追踪应该通过。随着时间的推移，这种策略用真实世界的边缘情况加强了评估集，并有助于防止相同故障模式的复发。

自愈智能体 (Self-Healing Agents)

最后，监控不仅可以检测故障——它还可以帮助智能体从中恢复。被设计为实时读取自身遥测数据的智能体可以在检测到问题时实施回退机制。

例如，如果工具调用重复失败，智能体可能会重新路由到更简单的回退计划或要求用户澄清。如果延迟飙升，智能体可以跳过可选的推理步骤。如果幻觉分数很高，它可以发布免责声明或推迟到人工审查。

当有详细的监控数据支持时，这些自愈行为最为有效。每个回退决策都可以被记录和追踪，使团队能够分析何时以及为何触发回退，以及它们是否有助于解决问题。

用户反馈作为可观测性信号

虽然本章的大部分内容都集中在日志、追踪和指标上，但用户反馈提供了一个补充视角——直接洞察智能体满足人类期望的程度。反馈可以是隐式的，例如用户改写他们的输入、放弃任务或在交互过程中犹豫。它也可以是显式的，像拇指向下的图标、星级评分或自由文本评论。这两种形式都提供了实时信号，可以并且应该集成到你的监控技术栈中。

在实践中，隐式反馈指标——例如任务放弃率或重新查询频率——可以在 Loki 中记录和聚合，并在 Grafana 中可视化，就像任何其他性能指标一样。它们提供了摩擦或困惑的早期指标。显式反馈事件，如低评分，可以绑定到 Tempo 中的特定追踪，并在不满情绪飙升时触发警报。结合用户情绪指标和基于追踪的技术数据的仪表板，使团队能够将性能问题与用户挫败感相关联，从而提供更完整的智能体健康图景。

至关重要的是，用户反馈还可以驱动改进循环。例如，与低用户评分相关的追踪可以直接导出到评估集中进行事后审查。如果多个用户放弃特定的流程，这可能需要重新审视规划策略或重新训练基础模型提示词。通过将用户信号集成到更广泛的可观测性和行动框架中，团队确保其监控实践不仅在运维上有效，而且是以用户为中心的。

分布偏移 (Distribution Shifts)

监控基于智能体的系统中最微妙但也最关键的挑战之一是识别和管理分布偏移。当智能体环境的统计属性随时间发生变化时——无论是通过不断演变的用户语言、新产品术语、API 响应的变化，甚至是对基础模型本身的更新——就会发生这种情况。虽然这种偏移可能不会触发明确的错误，但它们通常表现为性能下降、输出未对齐或回退使用增加。

监控系统是抵御这种缓慢漂移的第一道防线。跟踪任务成功率、工具调用失败和语义指标（如 Token 用量趋势或幻觉频率）的仪表板可以浮现早期信号。对于定量检测，采用统计测试，如 Kolmogorov-Smirnov (KS) 检验来比较输入特征或输出的分布。KS 检验是一种非参数统计检验，用于比较两个数据集的经验累积分布函数，以确定它们是否来自相同的潜在分布，这使其非常适合检测连续特征（如查询长度、延迟或数值指标）中的偏移，而无需假设正态性。它计算分布之间的最大垂直距离（KS 统计量）以及统计显著性的 $p$ 值；像 KS > 0.1（通常搭配 $p$ 值 < 0.05）这样的阈值表明有意义的发散，触发对智能体输入或输出中潜在漂移的警报。在此代码中，应用 SciPy 的 ks_2samp 函数来采样历史和当前数据的数组，如果统计量超过阈值，则打印检测消息。这是一个使用 SciPy 检测查询长度漂移的小型 Python 示例：

import numpy as np
from scipy import stats

# 历史和当前查询长度（例如，字符数）
historical = np.array([10, 15, 20, 12])  # 基线数据
current = np.array([25, 30, 28, 35])     # 新数据

ks_stat, p_value = stats.ks_2samp(historical, current)

if ks_stat > 0.1:
    print(f"Drift detected: KS statistic = {ks_stat}")

import numpy as np

from scipy import stats

# 历史和当前查询长度（例如，字符数）

historical = np.array([10, 15, 20, 12]) # 基线数据

current = np.array([25, 30, 28, 35]) # 新数据

ks_stat, p_value = stats.ks_2samp(historical, current)

if ks_stat > 0.1:

print(f"Drift detected: KS statistic = {ks_stat}")

Kullback-Leibler (KL) 散度测量一个概率分布与另一个概率分布的发散程度，常用于通过量化 Token 分布的偏移（例如，表明用户语言演变或新术语的词频变化）来检测概念漂移。它是不对称的 $$KL(P||Q) \neq KL(Q||P)$$ ，并且可以发出信号表明当前数据 ( $Q$ ) 显著偏离历史基线 ( $P$ )，较高的值表明漂移较大——例如，阈值 > 0.5 可能标记嵌入中的概念变化。在此代码中，我们将频率向量归一化为概率，添加一个小的 epsilon 以避免 log(0) 错误，并计算 $$P * log(P/Q)$$ 的总和；该示例假设历史和当前数据的简化 Token 计数数组：

import numpy as np

def kl_divergence(p, q, epsilon=1e-10):
    p = p + epsilon
    q = q + epsilon
    p = p / np.sum(p)
    q = q / np.sum(q)
    return np.sum(p * np.log(p / q))

# Token 频率向量（例如，[word1, word2, ...] 计数）
historical_tokens = np.array([0.4, 0.3, 0.3])
current_tokens = np.array([0.2, 0.5, 0.3])

kl = kl_divergence(historical_tokens, current_tokens)

if kl > 0.5:
    print(f"Concept drift detected: KL = {kl}")

import numpy as np

def kl_divergence(p, q, epsilon=1e-10):

p = p + epsilon

q = q + epsilon

p = p / np.sum(p)

q = q / np.sum(q)

return np.sum(p * np.log(p / q))

# Token 频率向量（例如，[word1, word2, ...] 计数）

historical_tokens = np.array([0.4, 0.3, 0.3])

current_tokens = np.array([0.2, 0.5, 0.3])

kl = kl_divergence(historical_tokens, current_tokens)

if kl > 0.5:

print(f"Concept drift detected: KL = {kl}")

群体稳定性指标 (PSI) 是一种用于检测分类或分箱连续变量（例如“退款”、“取消”、“修改”等工具使用类别）偏移的指标，通过比较历史和当前数据集之间的百分比分布（通常划分为桶以进行粒度分析）。它对各类别中的 $$natural\_logarithm(actual\_percent / expected\_percent)$$ 求和，其中低 PSI (< 0.1) 意味着稳定，0.1–0.25 表明轻微漂移（需监控），而 > 0.25 信号表明重大漂移（需干预——例如重新训练）。这有助于在不假设正态性的情况下标记模式变化，使其适合像调用频率这样的智能体指标：

import numpy as np

def psi(expected, actual):
    expected_percents = expected / np.sum(expected)
    actual_percents = actual / np.sum(actual)
    psi_values = ((actual_percents - expected_percents) * np.log(actual_percents / expected_percents))
    return np.sum(psi_values)

# 工具使用计数（例如，['refund', 'cancel', 'modify']）
historical = np.array([50, 30, 20])
current = np.array([20, 50, 30])

psi_value = psi(historical, current)

if psi_value > 0.25:
    print(f"Major drift: PSI = {psi_value}")
elif psi_value > 0.1:
    print(f"Minor drift: PSI = {psi_value}")

import numpy as np

def psi(expected, actual):

expected_percents = expected / np.sum(expected)

actual_percents = actual / np.sum(actual)

psi_values = ((actual_percents - expected_percents) * np.log(actual_percents / expected_percents))

return np.sum(psi_values)

# 工具使用计数（例如，['refund', 'cancel', 'modify']）

historical = np.array([50, 30, 20])

current = np.array([20, 50, 30])

psi_value = psi(historical, current)

if psi_value > 0.25:

print(f"Major drift: PSI = {psi_value}")

elif psi_value > 0.1:

print(f"Minor drift: PSI = {psi_value}")

准确率突然下降（例如，在 24 小时滚动窗口内 > 5–10%）、任务放弃增加（> 15%）或重试激增（> 20% 会话率）都是输入或概念漂移的潜在指标。基于嵌入的技术，例如计算当前和历史查询向量之间的余弦相似度，也可用于将新输入与基线进行比较（例如，平均相似度 < 0.8 触发审查），通常通过像 Evidently AI 这样的库实施，以便在 Grafana 中进行自动警报。

响应这些偏移是构建弹性系统的一部分。瞬态变化可以通过调整阈值或更新解析逻辑来解决，而持久性偏移可能需要重新训练工作流或适应新的 API——由统计测量的漂移严重程度指导（例如，如果 PSI > 0.25 持续超过 48 小时，则优先重新训练）。反馈循环，如记录和导出降级的追踪以进行分析，有助于团队确定问题是暂时的还是系统性的——也许在检测后通过 A/B 测试来验证修复。一如既往，响应策略受益于强大的可观测性技术栈提供的实时可见性——使团队能够在漂移变成故障之前采取行动。

指标所有权和跨职能治理

随着团队部署基于智能体的系统，一个微妙但严峻的组织挑战出现了：谁拥有哪些指标？在传统软件栈中，分工明确：基础设施团队拥有延迟和正常运行时间，产品团队拥有转化率或用户成功，而 ML 团队（如果存在）构建模型，并管理它们的健康和性能，同时对工程和产品影响负责。但由基础模型驱动的智能体不会管这些界限——你的监控策略也不应受限。

基础模型的响应不仅仅是一个模型工件——它是产品。一连串的工具调用、重试、回退和生成步骤不是后端骚操作——它是用户体验。五秒钟的计划生成延迟不仅仅是模型限制——它通常是产品团队某人做出的提示词或工作流设计决策。

这就是为什么来自智能体的日志、追踪和评估信号属于核心可观测性平台，与服务健康和系统指标并列。如果智能体指标只出现在产品仪表板和模型笔记本，就会错过全貌——并且可能掩盖了系统性问题。

延迟是一个完美的例子。团队经常采用“基础模型很慢”的心态，然后不经意地将延迟构建到所有事物中——从冗长的提示词到不必要的重试再到臃肿的计划。如果没有严格的、基于追踪的插桩，这种漂移就不会被发现。不久之后，整个系统感觉迟缓——不是因为基础设施动力不足，而是因为产品和 ML 团队将延迟常态化为不可避免。

解决方案不是将延迟推卸给基础设施或将 UX 推卸给产品。而是构建共享的仪表板，让团队可以做以下事情：

产品负责人可以看到规划延迟和回退率如何与任务放弃相关联。
ML 工程师可以监控幻觉率和漂移以及用户反馈。
基础设施/SRE 团队可以对影响系统可靠性的 Token 峰值和工具不稳定性进行警报。

每个团队必须拥有部分智能体遥测——没有一个团队可以孤立地解释它。为了解决指标所有权的组织挑战，团队可以使用责任分配矩阵 (RACI 图表) 来阐明跨职能的角色。在 RACI 图表中，每个任务或指标被分配以下一项或多项：R (Responsible: 负责执行)，A (Accountable: 对结果负责)，C (Consulted: 提供输入)，或 I (Informed: 保持更新)。

表 10-3 是为智能体监控量身定制的模板，你可以根据团队的结构、规模和具体指标进行调整。这通过确保没有指标被遗漏，同时避免孤岛，促进了跨职能协作。

表 10-3. 监控指标和跨职能责任的 RACI 矩阵

指标/活动	产品团队	ML 工程师	基础设施/SRE 团队
延迟 (例如规划或工具调用延迟)	A (拥有用户影响) / C (咨询 UX 阈值)	R (优化提示词/模型) / I (知悉回退)	R (监控基础设施原因) / C (咨询扩展)
幻觉率	C (提供用户反馈上下文) / I (知悉趋势)	A/R (通过评估拥有检测/缓解)	I (知悉警报设置)
任务成功率	A (拥有产品目标) / R (定义成功标准)	C (咨询模型改进)	I (知悉系统可靠性关联)
Token 用量/成本	C (咨询业务影响)	R (优化生成) / I (知悉峰值)	A (拥有预算/扩展) / R (监控基础设施效率)
分布偏移 (例如输入漂移)	I (知悉产品调整)	A/R (通过嵌入/评估检测)	C (咨询数据管道稳定性)
回退/重试频率	C (咨询 UX 回退)	R (优化规划逻辑)	A (拥有可靠性) / I (知悉模式)
用户反馈/情绪	A/R (拥有聚合和优先级)	C (咨询模型关联)	I (知悉运维警报)
仪表板维护和分类仪式	C (提供产品上下文)	C (提供 ML 洞察)	A/R (拥有平台和跨团队审查)

一个显示工具在循环中被调用四次，紧接着是长时间生成、模糊的响应和用户放弃的追踪——这不仅仅是一个工程细节。这是一个产品故障。只有当日志和 Span 通过 Loki 和 Tempo 这样的共享平台路由，而不是隐藏在断开连接的指标选项卡中时，它是才可见的。

为了实现这一点，请使用以下实践：

使用带有版本标签和语义指标的共享可观测性仪表板。高效的团队不争论哪个仪表板更准确——他们跨越职能边界共同努力改善客户体验。
用产品上下文标记 Span 和日志（功能标志、用户层级、工作流 ID）。
跨职能共审机制：产品、基础设施和 ML 一起审查遥测——特别是在发布或重大回退之后。
避免双重标准：不要对基础模型延迟持有与其他服务不同的标准。缓慢是每个人的问题，它影响用户。

智能体系统需要跨职能的可观测性。监控技术栈不仅仅用于检测中断——它是工程、ML 和产品学会用同一种语言交流系统在做什么、表现如何以及哪里需要进化的接口。

结论

监控基于智能体的系统不仅仅是一项安全检查——它是使智能系统能够在现实世界环境中茁壮成长的学科。在本章中，我们看到监控不仅仅是被动的；它是团队从生产中学习、适应变化和加速进步的方式。

从使用 OpenTelemetry 的基础插桩，到通过 Loki 和 Tempo 进行实时日志和追踪收集，再到 Grafana 中的仪表板和警报，我们概述了如何构建一个开源反馈循环，在问题演化为中断之前使其浮出水面——并将每一次部署转化为改进的机会。

我们探索了实用技术，如影子模式、金丝雀发布、回退日志记录和用户情绪跟踪。我们不仅强调了要测量什么，还强调了如何行动。并且展示了监控如何帮助检测的不仅是故障，还有上下文、数据或行为中的缓慢漂移，如果不加以控制，这些漂移会悄悄地破坏性能。

前进的道路是清晰的：在构建智能体系统时考虑到可观测性的团队——那些在运行中对智能体进行插桩、可视化和学习的团队——将获得强大的优势。他们迭代得更快。他们的指标值得依赖。在出错时，能优雅地恢复。

在一个智能体系统正成为核心基础设施的世界里，健壮的监控不是可选项——它是基础性的。那些掌握它的人将带头大规模创建智能、弹性和可信赖的智能体。

翻译整理自Building Applications with AI Agents一书，仅供学习交流使用