监视使用 Agent Framework 部署的应用（旧版）

2025-06-11

重要

此功能以 Beta 版本提供。

重要

本页介绍<0.22 与 MLflow <2.x 的代理评估。 Databricks 建议使用与代理评估 >1.0集成的 MLflow 3。代理评估 SDK 方法现在通过 mlflow SDK 公开。

本页介绍如何为使用马赛克 AI 代理框架部署的生成式 AI 应用设置监视。有关使用监视（例如结果架构、查看结果、使用 UI、添加警报和管理监视器）的一般信息，请参阅什么是 Lakehouse Monitoring for generative AI？（旧版）

适用于生成式 AI 的湖屋监视可帮助你使用 Mosaic AI 代理评估 AI 判定来跟踪运营指标（如数据量、延迟、错误和成本）以及质量指标（如正确性和准则遵守情况）。

监视的工作原理：

工作原理概述

监视用户界面：

适用于生成式 AI 的湖屋监视 UI 主图

要求

在 Databricks 笔记本中安装 databricks-agents SDK 。

%pip install databricks-agents>=0.22.0
dbutils.library.restartPython()

必须启用无服务器作业。
LLM 法官指标要求启用合作伙伴支持的 AI 辅助功能。无论此设置如何，都支持其他指标，例如延迟。
终结点创建者（部署代理的用户）必须具有 CREATE VOLUME 所选架构的权限，才能在部署时存储推理表。这可确保可以在架构中创建相关的评估和日志记录表。请参阅 “启用和禁用推理表”。

局限性

重要

最长可能需要经过 2 小时才能通过监视 UI 获取跟踪。
跟踪显示在监视 UI 中之后，质量指标可能需要经过额外 15 分钟才能进行计算。

有关详细信息，请参阅 “监视执行和计划”。

如果需要较低的延迟，请联系 Databricks 帐户代表。

设置监视

如果通过部署agents.deploy，则会自动设置基本监视。这包括：

请求量跟踪
延迟指标
错误日志记录

此自动监视不包括特定的评估指标（如准则遵循或安全性），但提供必要的遥测来跟踪代理的使用情况和性能。

小提示

若要在监视器中包含最终用户 👍 / 👎 反馈，请参阅提供有关已部署代理（实验性）的反馈，获取有关如何将反馈附加到推理表的说明。

配置代理监视指标

若要将评估指标添加到自动监视，请使用 update_monitor 以下方法：

重要

监视必须附加到 MLflow 试验。每个实验只能有一个附加的监视器（对于单个终结点）。默认情况下，update_monitor 和 create_monitor 使用笔记本的 MLflow 试验。若要覆盖此行为然后选择其他实验，请使用 experiment_id 参数。

from databricks.agents.monitoring import update_monitor, AssessmentsSuiteConfig, BuiltinJudge, GuidelinesJudge

monitor = update_monitor(
    endpoint_name = "model-serving-endpoint-name",
    assessments_config = AssessmentsSuiteConfig(
        sample=1.0,  # Sample 100% of requests
        assessments=[
            # Builtin judges: "safety", "groundedness", "relevance_to_query", "chunk_relevance"
            BuiltinJudge(name='safety'),  # or {'name': 'safety'}
            BuiltinJudge(name='groundedness', sample_rate=0.4), # or {'name': 'groundedness', 'sample_rate': 0.4}
            BuiltinJudge(name='relevance_to_query'), # or {'name': 'relevance_to_query'}
            BuiltinJudge(name='chunk_relevance'), # or {'name': 'chunk_relevance'}
            # Create custom judges with the guidelines judge.
            GuidelinesJudge(guidelines={
              "english": ["The response must be in English"],
              "clarity": ["The response must be clear, coherent, and concise"],
            }),
        ],
    )
)

对于没有部署自动监控的代理，您可以使用 create_monitor 方法设置监控。

from databricks.agents.monitoring import create_monitor, AssessmentsSuiteConfig, BuiltinJudge, GuidelinesJudge

monitor = create_monitor(
    endpoint_name = "model-serving-endpoint-name",
    assessments_config = AssessmentsSuiteConfig(
        sample=1.0,  # Sample 100% of requests
        assessments=[
            # Builtin judges: "safety", "groundedness", "relevance_to_query", "chunk_relevance"
            BuiltinJudge(name='safety'),  # or {'name': 'safety'}
            BuiltinJudge(name='groundedness', sample_rate=0.4), # or {'name': 'groundedness', 'sample_rate': 0.4}
            BuiltinJudge(name='relevance_to_query'), # or {'name': 'relevance_to_query'}
            BuiltinJudge(name='chunk_relevance'), # or {'name': 'chunk_relevance'}
            # Create custom judges with the guidelines judge.
            GuidelinesJudge(guidelines={
              "english": ["The response must be in English"],
              "clarity": ["The response must be clear, coherent, and concise"],
            }),
        ],
    )
)

这两种方法采用以下输入：

endpoint_name: str - 要监视的模型服务终结点的名称。
assessments_config: AssessmentsSuiteConfig | dict - 用于监视器计算的评估的配置。支持以下参数：
- [Optional] sample: float - 全局采样率，即用于计算评估的请求比例（介于 0 和 1 之间）。默认为 1.0（所有流量的计算评估）。
- [Optional] paused: bool - 监视器是否暂停。
- [Optional] assessments: list[BuiltinJudge | GuidelinesJudge] 评估列表，包括内置评估标准或准则评估标准。
[Optional] experiment_id：将显示监视结果的 MLflow 试验。如果未指定，监视器将使用最初记录了代理的同一试验。

BuiltinJudge 采用下列参数：

name: str - 支持监测的内置法官之一：“安全”、“稳重性”、“查询相关性”、“片段相关性”。有关内置法官的更多详细信息，请参阅内置法官。
[Optional] sample_rate: float - 计算此评估请求的比例（范围在 0 到 1 之间）。默认为全局采样率。

GuidelinesJudge 采用下列参数：

guidelines: dict[str, list[str]] - 一个字典，其中包含用于对请求/响应进行断言的指南名称和纯文本指南。有关准则的更多详细信息，请参阅 “遵循准则”。
[Optional] sample_rate: float - 在 0 和 1 之间的计算准则请求的比例。默认为全局采样率。

有关更多详细信息，请参阅 Python SDK 文档。

创建监视器后，你将在单元格输出中看到一个指向监视 UI 的链接。可以在此 UI 中查看评估结果，并存储在 monitor.evaluated_traces_table其中。若要查看已评估的行，请运行：

display(spark.table(monitor.evaluated_traces_table).filter("evaluation_status != 'skipped'"))

监视执行和调度

重要

最长可能需要经过 2 小时才能通过监视 UI 获取跟踪。
跟踪显示在监视 UI 中之后，质量指标可能需要额外 30 分钟才能进行计算。

创建监视器时，它会启动一个作业，该作业评估过去 30 天内向终结点发出的请求示例。此初始评估可能需要几个小时才能完成，具体取决于请求量和采样率。

向终结点发出请求时，会发生以下情况：

请求及其 MLflow 追踪数据将写入推理表（15 - 30 分钟）。
计划作业将推理表解压缩到两个单独的表中： request_log包含请求和跟踪，以及 assessment_logs包含用户反馈（作业每小时运行一次）。
监视作业将评估指定的请求示例（作业每 15 分钟运行一次）。

这些步骤结合使用意味着请求最多可能需要 2.5 小时才能显示在监视 UI 中。

监视器由 Databricks 工作流提供支持。若要手动触发监视器的刷新（步骤 3），请查找具有名称 [<endpoint_name>] Agent Monitoring Job 的工作流，然后单击“ 立即运行”。

如果需要较低的延迟，请联系 Databricks 帐户代表。

示例笔记本

以下示例记录并部署一个简单的代理，然后启用监视。

代理监视示例笔记本

获取笔记本

通过