共用方式為

使用 API 建立監視器

  • 發行項

此頁面描述如何使用 Databricks SDK 在 Databricks 中建立監視器，並描述 API 呼叫中使用的所有參數。 您也可以使用 REST API 來建立和管理監視器。 如需參考資訊，請參閱 Lakehouse 監視 SDK 參考和 REST API 參考。

您可以在 Unity Catalog 中註冊的任何受管或外部 Delta 資料表上建立監視器。 在任何資料表的 Unity Catalog 中繼存放區中只能建立單一監視器。

需求

Lakehouse Monitoring API 建置於 databricks-sdk 0.28.0 和更高版本中。 若要使用最新版本的 API，請在筆記本的開頭使用下列命令來安裝 Python 用戶端：

%pip install "databricks-sdk>=0.28.0"

若要進行驗證以在您的環境中使用 Databricks SDK，請參閱驗證。

設定檔類型

當您建立監視器時，可以選取下列其中一種設定檔類型：TimeSeries、InferenceLog 或 Snapshot。 本節簡短說明每個選項。 如需詳細資訊，請參閱 API 參考或 REST API 參考。

注意

  • 當您第一次建立時間序列或推斷設定檔時，監視器只會分析其建立前 30 天的資料。 建立監視器之後，就會處理所有新資料。
  • 具體化檢視和串流資料表上定義的監視器不支援累加處理。

提示

針對 TimeSeries 和 Inference 設定檔，最佳做法是在您的資料表上啟用變更資料摘要 (CDF)。 啟用 CDF 時，只會處理新附加的資料，而不是每次重新整理時重新處理整個資料表。 這使得執行更加有效，並在跨許多資料表擴展監視時降低成本。

TimeSeries 設定檔

TimeSeries 設定檔會比較跨時間範圍的資料分佈。 對於 TimeSeries 設定檔，必須提供下列內容：

  • 時間戳記資料行 (timestamp_col)。 時間戳記資料行資料類型必須是 TIMESTAMP，或是可以使用 to_timestamp PySpark 函數轉換為時間戳記的類型。
  • 用來計算計量的 granularities 集合。 可用的粒度為 「5 分鐘」、“30 分鐘”、“1 小時”、“1 天”、“1 周”、“2 周”、“3 周”、“4 周”、“1 個月”、“1 年”。
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"])
)

InferenceLog 設定檔

InferenceLog 設定檔類似於 TimeSeries 設定檔，但也包含模型品質計量。 對於 InferenceLog 設定檔，需要以下參數：

參數 描述
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION 或 MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col 包含模型預測值的資料行。
timestamp_col 包含推斷要求時間戳記的資料行。
model_id_col 包含用於預測之模型 ID 的資料行。
granularities 決定如何在時段之間分割資料。 可能的值：「5 分鐘」、“30 分鐘”、“1 小時”、“1 天”、“1 周”、“2 周”、“3 周”、“4 周”、“1 個月”、“1 年”。

另外還有選擇性參數：

選擇性參數 描述
label_col 包含模型預測之基礎真相的資料行。 
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorInferenceLog, MonitorInferenceLogProblemType

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  inference_log=MonitorInferenceLog(
        problem_type=MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION,
        prediction_col="preds",
        timestamp_col="ts",
        granularities=["30 minutes", "1 day"],
        model_id_col="model_ver",
        label_col="label", # optional
  )
)

對於 InferenceLog 設定檔，會根據不同的 model_id_col 值自動建立配量。

Snapshot 設定檔

與 TimeSeries 相反，Snapshot 設定檔會監視資料表的全部內容如何隨時間變更。 針對資料表中的所有資料計算計量，並在每次重新整理監視器時監視資料表狀態。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorSnapshot

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  snapshot=MonitorSnapshot()
)

重新整理和檢視監視結果

若要重新整理計量資料表，請使用 run_refresh。 例如：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.run_refresh(
    table_name=f"{catalog}.{schema}.{table_name}"
)

當您從筆記本呼叫 run_refresh 時，會建立或更新監視計量資料表。 此計算會在無伺服器計算上執行，而不是在筆記本所連結的叢集上執行。 您可以在更新監視器統計資料時，繼續在筆記本中執行命令。

如需計量資料表中所儲存統計資料的相關資訊，請參閱監視計量資料表。計量資料表是 Unity Catalog 資料表。 您可以在筆記本或 SQL 查詢總管中查詢它們，並在目錄總管中檢視它們。

若要顯示與監視器相關聯的所有重新整理的歷程記錄，請使用 list_refreshes。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.list_refreshes(
    table_name=f"{catalog}.{schema}.{table_name}"
)

若要取得已排入佇列、執行中或完成的特定執行狀態，請使用 get_refresh。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.get_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id = run_info.refresh_id
)

若要取消已排入佇列或正在執行的重新整理，請使用 cancel_refresh。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.cancel_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id=run_info.refresh_id
)

檢視監視設定

您可以使用 API get_monitor 來檢閱監視設定。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.get(f"{catalog}.{schema}.{table_name}")

排程

若要設定監視以按排程執行，請使用 create_monitor 的 schedule 參數：

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorCronSchedule

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  schedule=MonitorCronSchedule(
        quartz_cron_expression="0 0 12 * * ?", # schedules a refresh every day at 12 noon
        timezone_id="PST",
    )
)

如需詳細資訊，請參閱 Cron 運算式。

通知

若要設定監視的通知，請使用 create_monitor 的 notifications 參數：

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorNotifications, MonitorDestination

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  notifications=MonitorNotifications(
        # Notify the given email when a monitoring refresh fails or times out.
        on_failure=MonitorDestination(
            email_addresses=["your_email@domain.com"]
        )
    )
)

每個事件類型最多支援 5 個電子郵件地址 (例如，「on_failure」)。

控制計量資料表的存取

監視器所建立的計量資料表和儀表板是由建立監視器的使用者所擁有。 您可以使用 Unity Catalog 權限來控制計量資料表的存取權。 若要在工作區內共用儀表板，請使用儀表板右上角的 [共用] 按鈕。

刪除監視器

若要刪除監視器：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.delete(table_name=f"{catalog}.{schema}.{table_name}")

此命令不會刪除監視器所建立的設定檔資料表和儀表板。 您必須在單獨的步驟中刪除這些資產，或者可以將它們儲存在不同位置。

筆記本範例

下列範例筆記本說明如何建立監視器、重新整理監視器，以及檢查它所建立的計量資料表。

筆記本範例：時間序列設定檔

此筆記本說明如何建立 TimeSeries 類型監視器。

TimeSeries Lakehouse 監視器範例筆記本

取得筆記本

筆記本範例：推斷設定檔 (迴歸)

此筆記本說明如何建立迴歸問題的 InferenceLog 類型監視器。

推斷 Lakehouse 監視器迴歸範例筆記本

取得筆記本

筆記本範例：推斷設定檔 (分類)

此筆記本說明如何建立分類問題的 InferenceLog 類型監視器。

推斷 Lakehouse 監視器分類範例筆記本

取得筆記本

筆記本範例：快照設定檔

此筆記本說明如何建立 Snapshot 類型監視器。

Snapshot Lakehouse 監視器範例筆記本

取得筆記本