监视使用代理框架部署的应用

2025-05-14

重要

此功能以 Beta 版本提供。

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

适用于生成式 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 帐户代表。

示例笔记本

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

代理监视示例笔记本

获取笔记本

通过