AI 智链谷
问苏一二 ↗社区交流 ·
生产中的 AI 代理：可观测性与评估
开源教程转载｜生产中的 AI 代理：可观测性与评估。Microsoft 及项目贡献者编写，智链谷平台运营整理。
> 开源教程转载 · 由智链谷平台运营账号整理发布。作者：Microsoft 及项目贡献者。
> [查看原文](https://github.com/microsoft/ai-agents-for-beginners/blob/25b7985f3b2dc37a84f4a7387ccd3c9f0e5b1595/translations/zh-CN/10-ai-agents-production/README.md) · MIT 许可，完整声明见文末。
# 生产中的 AI 代理：可观测性与评估
[](https://youtu.be/l4TP6IyJxmQ?si=reGOyeqjxFevyDq9)
随着 AI 代理从实验原型发展到实际应用，理解其行为、监控其性能并系统地评估其输出的能力变得尤为重要。
## 学习目标
完成本课后，您将了解/掌握：
- 代理可观测性和评估的核心概念
- 提升代理性能、成本和效果的技术
- 如何系统性地评估您的 AI 代理
- 如何在生产环境中部署 AI 代理时控制成本
- 如何为基于 Microsoft Agent Framework 构建的代理配置监测
目标是让您具备将“黑盒”代理转变为透明、可管理且可靠系统的知识。
_**注意：** 部署安全可信的 AI 代理非常重要。也请查看[构建可信 AI 代理](https://github.com/microsoft/ai-agents-for-beginners/blob/25b7985f3b2dc37a84f4a7387ccd3c9f0e5b1595/translations/zh-CN/06-building-trustworthy-agents/README.md)课程。_
## 跟踪与跨度
可观测性工具如 [Langfuse](https://langfuse.com/) 或 [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-azure-ai-foundry) 通常将代理执行表示为跟踪和跨度。
- <strong>跟踪</strong> 代表从开始到完成的完整代理任务（例如处理用户查询）。
- <strong>跨度</strong> 是跟踪中的各个步骤（例如调用语言模型或检索数据）。
<!-- Image URL retained for illustration purposes -->
没有可观测性，AI 代理就像“黑盒子”——其内部状态和推理过程不透明，难以诊断问题或优化性能。有了可观测性，代理变成了“玻璃盒子”，提供了透明度，这对建立信任和确保按预期运行至关重要。
## 为什么可观测性在生产环境中至关重要
将 AI 代理转入生产环境会带来一系列新的挑战和需求。可观测性不再是“锦上添花”，而是一项关键能力：
* <strong>调试与根因分析</strong>：当代理失败或产生意外输出时，可观测性工具提供跟踪以定位错误来源。这在涉及多次 LLM 调用、工具交互和条件逻辑的复杂代理中尤为重要。
* <strong>延迟和成本管理</strong>：AI 代理通常依赖按令牌或调用计费的 LLM 和其他外部 API。可观测性允许精确跟踪这些调用，帮助识别过慢或过于昂贵的操作。团队可以据此优化提示、选择更高效的模型或重新设计流程，以控制运营成本并确保良好用户体验。
* **信任、安全与合规**：许多应用需确保代理行为安全且符合道德规范。可观测性提供代理操作和决策的审计轨迹，可用于检测并缓解提示注入、有害内容生成或个人身份信息（PII）处理不当等问题。例如，您可以通过审查跟踪了解代理为何给出某个回应或使用特定工具。
* <strong>持续改进循环</strong>：可观测性数据是迭代开发流程的基础。通过监控代理在现实环境中的表现，团队可发现改进点、收集数据进行模型微调，并验证变更效果。这样形成反馈循环，在线评估的生产洞察指导离线实验和优化，逐步提升代理性能。
## 关键指标跟踪
为监控和理解代理行为，应跟踪一系列指标和信号。虽然具体指标可能因代理目的而异，但某些指标是普遍重要的。
以下是常见的可观测性工具监控指标：
**延迟：** 代理响应的速度如何？长时间等待会严重影响用户体验。您应通过跟踪代理运行测量任务及各步骤的延迟。例如，所有模型调用共耗时 20 秒的代理可以通过使用更快模型或并行调用模型来加速。
**成本：** 每次代理运行的费用是多少？AI 代理依赖按令牌计费的 LLM 调用或外部 API。频繁使用工具或多次提示可迅速增加成本。例如，若代理为了微小质量提升调用了 LLM 五次，您需要评估成本是否合理，是否可以减少调用次数或选用更便宜的模型。实时监控还可帮助发现异常峰值（如造成过多 API 调用的缺陷）。
**请求错误：** 代理失败的请求有多少？这包括 API 错误或工具调用失败。为使代理在生产中更健壮，您可以设置回退或重试策略。例如，当 LLM 提供商 A 挂掉时，切换到提供商 B 作为备份。
**用户反馈：** 收集用户直接评价提供宝贵洞察。包括明确的评分（👍点赞/👎差评，⭐1-5 星）或文本评论。持续的负面反馈应引起警示，表明代理无法按预期工作。
**隐式用户反馈：** 用户行为即使没有明确评分也提供间接反馈。例如，立即改写问题、重复查询或点击重试按钮。如果您发现用户反复提出相同问题，这往往意味着代理未正常工作。
**准确率：** 代理生成正确或理想输出的频率如何？准确率定义因场景而异（如问题解决正确率、信息检索准确度、用户满意度）。第一步是明确代理的成功标准。您可以通过自动检测、评分或任务完成标签来跟踪准确率。例如，将跟踪标记为“成功”或“失败”。
**自动评估指标：** 也可以设置自动评估。例如，使用 LLM 对代理输出进行评分，判断其是否有帮助、准确等。还有一些开源库支持对代理多个方面评分，如针对检索增强生成代理的 [RAGAS](https://docs.ragas.io/)，或检测有害语言和提示注入的 [LLM Guard](https://llm-guard.com/)。
实践中，多种指标结合使用能更全面反映 AI 代理的健康状态。本章[示例笔记本](https://github.com/microsoft/ai-agents-for-beginners/blob/25b7985f3b2dc37a84f4a7387ccd3c9f0e5b1595/translations/zh-CN/10-ai-agents-production/code_samples/10-expense_claim-demo.ipynb)展示这些指标在实际中的表现，先让我们学习典型评估流程。
## 监控代理
收集跟踪数据需要给代码添加监控埋点。目标是让代理代码能够输出跟踪和指标，供可观测平台捕获、处理和展示。
**OpenTelemetry（OTel）：** [OpenTelemetry](https://opentelemetry.io/) 已成为 LLM 可观测性的行业标准。它提供一套 API、SDK 和工具，用于生成、收集和导出遥测数据。
许多监控库封装现有代理框架，方便将 OpenTelemetry 跨度导出到可观测工具。Microsoft Agent Framework 原生集成了 OpenTelemetry。下面是给 MAF 代理添加监控的示例：
```python
from agent_framework.observability import get_tracer, get_meter
tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("agent_run"):
# 代理执行会被自动跟踪
pass
```
本章节的[示例笔记本](https://github.com/microsoft/ai-agents-for-beginners/blob/25b7985f3b2dc37a84f4a7387ccd3c9f0e5b1595/translations/zh-CN/10-ai-agents-production/code_samples/10-expense_claim-demo.ipynb)将演示如何给 MAF 代理添加监控。
**手动创建跨度：** 虽然监控库提供了良好基础，但有时需要更详细或定制的信息。您可以手动创建跨度以加入自定义应用逻辑。更重要的是，可以给自动或手动创建的跨度添加自定义属性（即标签或元数据），这些属性可包含业务特定数据、中间计算结果或调试分析所需的任何上下文，如 `user_id`、`session_id` 或 `model_version`。
使用 [Langfuse Python SDK](https://langfuse.com/docs/sdk/python/sdk-v3) 手动创建跟踪和跨度的示例：
```python
from langfuse import get_client
langfuse = get_client()
span = langfuse.start_span(name="my-span")
span.end()
```
## 代理评估
可观测性给我们指标，评估则是分析这些数据（及执行测试）以判定 AI 代理表现优劣及改进方向。换句话说，获取跟踪和指标后，如何用它们判断代理并作出决策？
定期评估很重要，因为 AI 代理通常是非确定性的，且可能随时间（通过更新或模型行为漂移）变化——没有评估，就无法知道“智能代理”是否真的做得好，或是否出现回退。
AI 代理评估分为两类：<strong>在线评估</strong>和<strong>离线评估</strong>。两者均有价值且互为补充。我们通常从离线评估开始，这是部署前的最低要求步骤。
### 离线评估
离线评估指在受控环境中使用测试数据集（非实时用户查询）评估代理。您使用已知期望输出或正确行为的精选数据集，并让代理运行这些数据。
例如，若您构建了一个数学文字题代理，可能有一个含 100 道题且答案已知的 [测试数据集](https://huggingface.co/datasets/gsm8k)。离线评估多在开发期间完成，也可纳入 CI/CD 流水线，检查改进或防止回退。其优势是<strong>可重复，且因有标准答案而能获取清晰准确率指标</strong>。您也可模拟用户查询，用自动指标如前所述衡量代理反应与理想答案的差异。
离线评估的主要挑战是确保测试集全面且持续相关——代理可能在固定测试集表现良好，但生产环境遇到截然不同的查询。因此，应不断更新测试集，加入反映真实场景的新边缘案例和示例。混合使用小型“冒烟测试”用例和较大评估集最为有效：小集快速检测，大集提供广泛性能指标。
### 在线评估
在线评估指在真实运行环境，即生产中实际使用时，对代理表现的实时监控和分析。
例如，您可能跟踪成功率、用户满意度分数或其他实时流量指标。在线评估优势在于<strong>捕捉实验室无法预见的情况</strong>——可观察模型随时间漂移（代理效能因输入模式变化下降）并抓住测试数据中未涵盖的意外查询和情况。它提供代理在现实环境中的真实表现。
在线评估通常包括收集隐式与显式用户反馈，如前所述，也可能运行影子测试或 A/B 测试（新代理版本与旧版本并行运行进行对比）。挑战在于为实时交互获得可靠标签或评分较为困难——可能需依赖用户反馈或下游指标（如用户是否点击结果）。
### 两者结合
在线与离线评估并非相互排斥，而是高度互补。在线监控获得的见解（如代理在哪些新查询类型上表现差）可用于丰富和改进离线测试集。相反，离线测试表现良好的代理可以更放心地部署并监控在线表现。
事实上许多团队采用循环模式：
_先做离线评估 -> 部署 -> 在线监控 -> 收集新失败案例 -> 添加入离线数据集 -> 优化代理 -> 重复_
## 常见问题
在部署 AI 代理到生产时，您可能会遇到各种挑战。以下是一些常见问题及潜在解决方案：
| <strong>问题</strong> | <strong>潜在解决方案</strong> |
| ------------- | ------------------ |
| AI 代理任务执行不一致 | - 优化给 AI 代理的提示，确保目标明确。<br>- 识别是否可以将任务拆分为子任务并由多个代理处理。 |
| AI 代理进入连续循环 | - 明确终止条件，确保代理知道何时停止流程。<br>- 对于复杂需要推理和规划的任务，使用专门针对推理的大模型。 |
| AI 代理工具调用表现不佳 | - 在代理系统外测试并验证工具输出。<br>- 优化工具的参数、提示和命名。 |
| 多代理系统表现不稳定 | - 优化给每个代理的提示，确保它们具体且彼此区分。<br>- 构建使用“路由”或控制代理的层级系统，确定哪个代理负责处理。 |
许多此类问题通过启用可观测性能更有效识别。前述跟踪和指标帮助精确定位代理流程中的问题，提高调试和优化效率。
## 成本管理
下面是一些管理将 AI 代理部署到生产环境成本的策略：
**使用更小的模型：** 小型语言模型（SLM）在某些代理用例中表现良好，并且将大幅降低成本。如前所述，构建一个评估系统来确定和比较性能与更大模型的差异，是了解 SLM 在您的用例中表现如何的最佳方式。考虑将 SLM 用于意图分类或参数提取等简单任务，同时将更大模型保留用于复杂推理。
**使用路由器模型：** 一个类似的策略是使用多样化的模型和尺寸。您可以使用 LLM/SLM 或无服务器函数，根据复杂性路由请求到最合适的模型。这也有助于降低成本，同时确保在正确的任务上有良好表现。例如，将简单查询路由到更小、更快的模型，仅在复杂推理任务中使用昂贵的大型模型。
**缓存响应：** 识别常见请求和任务，并在它们通过代理系统之前提供响应，是减少类似请求数量的好方法。您甚至可以实现一个流程，利用更基础的 AI 模型来识别请求与缓存请求的相似度。这个策略可以显著降低常见问答或常见工作流的成本。
## 让我们看看这在实践中的运作方式
在[本节的示例笔记本](https://github.com/microsoft/ai-agents-for-beginners/blob/25b7985f3b2dc37a84f4a7387ccd3c9f0e5b1595/translations/zh-CN/10-ai-agents-production/code_samples/10-expense_claim-demo.ipynb)中，我们将看到如何使用可观测性工具监控和评估我们的代理的示例。
### 关于生产环境中的 AI 代理还有更多问题吗？
加入[Microsoft Foundry Discord](https://discord.com/invite/ATgtXmAS5D)，与其他学习者交流，参加答疑时间，获取您的 AI 代理相关问题的解答。
## 上一课
[元认知设计模式](https://github.com/microsoft/ai-agents-for-beginners/blob/25b7985f3b2dc37a84f4a7387ccd3c9f0e5b1595/translations/zh-CN/09-metacognition/README.md)
## 下一课
[代理协议](https://github.com/microsoft/ai-agents-for-beginners/blob/25b7985f3b2dc37a84f4a7387ccd3c9f0e5b1595/translations/zh-CN/11-agentic-protocols/README.md)
---
<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**免责声明**：
本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。
<!-- CO-OP TRANSLATOR DISCLAIMER END -->
---
## 版权与许可
```text
MIT License
Copyright (c) Microsoft Corporation.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE
```