在 Unity 目錄中管理模型生命週期

發行項
04/12/2024

重要

本文記載 Unity 目錄中的模型，Databricks 建議用來控管和部署模型。如果您的工作區未針對 Unity 目錄啟用，則此頁面上的功能無法使用。相反地，請參閱使用工作區模型登錄管理模型生命週期。如需如何將工作區模型登錄升級至 Unity 目錄的指引，請參閱將工作流程和模型移轉至 Unity 目錄。
Unity 目錄中的模型無法在 Azure Government 區域中使用。

本文說明如何在 Unity 目錄中使用模型作為機器學習工作流程的一部分，以管理 ML 模型的完整生命週期。 Databricks 提供 Unity 目錄中裝載的 MLflow 模型登錄版本。 Unity 目錄中的模型會將 Unity 目錄的優點延伸到 ML 模型，包括跨工作區的集中式訪問控制、稽核、譜系和模型探索。 Unity 目錄中的模型與開放原始碼 MLflow Python 用戶端相容。

Unity 目錄中模型的主要功能包括：

模型的名稱和控管，因此您可以在環境、專案或小組層級分組和管理模型（「授與數據科學家唯讀存取生產模型」）。
時間模型譜系（MLflow 實驗和執行會在指定時間產生模型）。
模型服務。
模型版本控制。
透過別名進行模型部署。例如，在目錄內 prod 標記模型的「冠軍」版本。

如果您的工作區的預設目錄已設定為 Unity 目錄中的目錄，則使用 MLflow API 註冊的模型，例如 mlflow.<model-type>.log_model(..., registered_model_name) 或 mlflow.register_model(model_uri, name) 預設會註冊至 Unity 目錄。

本文包含 Unity 目錄 UI 和 API 中模型的指示。

如需模型登錄概念的概觀，請參閱使用 MLflow 的 ML 生命週期管理。

需求

您的工作區中必須啟用 Unity 目錄。請參閱開始使用 Unity 目錄來建立 Unity 目錄中繼存放區、在工作區中啟用它，以及建立目錄。如果未啟用 Unity 目錄，您仍然可以使用傳統工作區模型登錄。
您的工作區必須附加至支援許可權繼承的 Unity 目錄中繼存放區。這適用於 2022 年 8 月 25 日之後建立的所有中繼存放區。如果在較舊的中繼存放區上執行，請遵循文件升級。
您必須具有存取 Unity 目錄的叢集上執行命令的存取權。
若要建立新的已註冊模型，除了架構及其封入目錄的和 USE CATALOG 許可權之外，USE SCHEMA您還需要CREATE_MODEL架構的許可權。 CREATE_MODEL 是您可以使用目錄總管 UI 或 SQL GRANT 命令授與的新架構層級許可權，如下所示。
```
GRANT CREATE_MODEL ON SCHEMA <schema-name> TO <principal>
```

將訓練工作負載升級至 Unity 目錄

本節包含將現有定型工作負載升級至 Unity 目錄的指示。

安裝 MLflow Python 用戶端

您也可以使用下列程序代碼，在 Databricks Runtime 11.3 LTS 和更新版本中的 Unity 目錄中使用模型，方法是在筆記本中安裝最新版本的 MLflow Python 用戶端。

%pip install --upgrade "mlflow-skinny[databricks]"
dbutils.library.restartPython()

設定 MLflow 用戶端以存取 Unity 目錄中的模型

根據預設，MLflow Python 用戶端會在 Databricks 工作區模型登錄中建立模型。若要升級至 Unity 目錄中的模型，請設定 MLflow 用戶端：

import mlflow
mlflow.set_registry_uri("databricks-uc")

注意

如果您的工作區默認目錄位於 Unity 目錄（而非 hive_metastore），而且您執行的是使用 Azure 中國地區 Databricks Runtime 13.3 LTS 或更新版本（Databricks Runtime 15.0 或更新版本）的叢集，則模型會自動在預設目錄中建立並載入，且不需要設定。其他 Databricks Runtime 版本的行為沒有變更。少數工作區，其中預設目錄在 2024 年 1 月之前設定為 Unity 目錄中的目錄，而工作區模型登錄是在 2024 年 1 月之前使用，則會豁免此行為。

定型和註冊 Unity 目錄相容模型

必要許可權：若要建立新的已註冊模型，您需要 CREATE_MODEL 封入架構的和 USE SCHEMA 許可權，以及 USE CATALOG 封入目錄的許可權。若要在已註冊的模型下建立新的模型版本，您必須是已註冊模型的擁有者，而且擁有 USE SCHEMA 包含模型的架構和目錄和 USE CATALOG 許可權。

UC 中的 ML 模型版本必須具有模型簽章。如果您尚未在模型定型工作負載中使用簽章記錄 MLflow 模型，則可以：

使用 Databricks 自動記錄，其會自動記錄具有許多熱門 ML 架構簽章的模型。請參閱 MLflow 檔中支援的架構。
透過 MLflow 2.5.0 和更新版本，您可以在呼叫中 mlflow.<flavor>.log_model 指定輸入範例，並自動推斷模型簽章。如需詳細資訊，請參閱 MLflow 檔。

然後，將模型的三層名稱傳遞至 MLflow API，格式為 <catalog>.<schema>.<model>。

本節中的範例會在目錄下的prod架構中ml_team建立和存取模型。

本節中的模型定型範例會建立新的模型版本，並在目錄中註冊。prod prod使用目錄不一定表示模型版本提供生產流量。模型版本的封入目錄、架構和已註冊的模型會反映其環境（prod）和相關聯的治理規則（例如，可以設定許可權，讓只有系統管理員可以從類別目錄刪除），但無法刪除 prod 其部署狀態。若要管理部署狀態，請使用模型別名。

使用自動記錄向 Unity 目錄註冊模型

from sklearn import datasets
from sklearn.ensemble import RandomForestClassifier

# Train a sklearn model on the iris dataset
X, y = datasets.load_iris(return_X_y=True, as_frame=True)
clf = RandomForestClassifier(max_depth=7)
clf.fit(X, y)

# Note that the UC model name follows the pattern
# <catalog_name>.<schema_name>.<model_name>, corresponding to
# the catalog, schema, and registered model name
# in Unity Catalog under which to create the version
# The registered model will be created if it doesn't already exist
autolog_run = mlflow.last_active_run()
model_uri = "runs:/{}/model".format(autolog_run.info.run_id)
mlflow.register_model(model_uri, "prod.ml_team.iris_model")

使用自動推斷的簽章向 Unity 目錄註冊模型

MLflow 2.5.0 版和更新版本提供自動推斷簽章的支援，且在 Databricks Runtime 11.3 LTS ML 和更新版本中支援。若要使用自動推斷的簽章，請使用下列程式代碼在筆記本中安裝最新的 MLflow Python 用戶端：

%pip install --upgrade "mlflow-skinny[databricks]"
dbutils.library.restartPython()

下列程式代碼顯示自動推斷簽章的範例。

from sklearn import datasets
from sklearn.ensemble import RandomForestClassifier

with mlflow.start_run():
    # Train a sklearn model on the iris dataset
    X, y = datasets.load_iris(return_X_y=True, as_frame=True)
    clf = RandomForestClassifier(max_depth=7)
    clf.fit(X, y)
    # Take the first row of the training dataset as the model input example.
    input_example = X.iloc[[0]]
    # Log the model and register it as a new version in UC.
    mlflow.sklearn.log_model(
        sk_model=clf,
        artifact_path="model",
        # The signature is automatically inferred from the input example and its predicted output.
        input_example=input_example,
        registered_model_name="prod.ml_team.iris_model",
    )

追蹤 Unity 目錄中模型的數據譜系

注意

MLflow 2.11.0 和更新版本提供對 Unity 目錄中模型譜系的數據表支援。

當您在 Unity 目錄的數據表上定型模型時，您可以將模型的譜系追蹤到已定型和評估的上游數據集。若要這樣做，請使用 mlflow.log_input。這會使用產生模型的 MLflow 執行來儲存輸入數據表資訊。數據譜系也會針對使用功能存放區 API 記錄的模型自動擷取。請參閱檢視功能存放區歷程。

當您將模型註冊至 Unity 目錄時，歷程資訊會自動儲存，而且會顯示在目錄總管中模型版本 UI 的 [譜系] 索引卷標中。

下列程式碼為範例。

import mlflow
import pandas as pd
import pyspark.pandas as ps
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestRegressor

# Write a table to Unity Catalog
iris = load_iris()
iris_df = pd.DataFrame(iris.data, columns=iris.feature_names)
iris_df.rename(
  columns = {
    'sepal length (cm)':'sepal_length',
    'sepal width (cm)':'sepal_width',
    'petal length (cm)':'petal_length',
    'petal width (cm)':'petal_width'},
  inplace = True
)
iris_df['species'] = iris.target
ps.from_pandas(iris_df).to_table("prod.ml_team.iris", mode="overwrite")

# Load a Unity Catalog table, train a model, and log the input table
dataset = mlflow.data.load_delta(table_name="prod.ml_team.iris", version="0")
pd_df = dataset.df.toPandas()
X = pd_df.drop("species", axis=1)
y = pd_df["species"]
with mlflow.start_run():
    clf = RandomForestRegressor(n_estimators=100)
    clf.fit(X, y)
    mlflow.log_input(dataset, "training")

在UI中檢視模型

需要的許可權：若要在UI中檢視已註冊的模型及其模型版本，您需要EXECUTE已註冊模型的許可權，以及USE SCHEMAUSE CATALOG包含模型之架構和目錄的許可權

您可以使用目錄總管，在 Unity 目錄中檢視和管理已註冊的模型和模型版本。

控制模型的存取

如需控制 Unity 目錄中註冊之模型存取權的相關信息，請參閱 Unity 目錄許可權和安全性實體物件。如需跨目錄和架構組織模型的最佳作法，請參閱組織您的數據。

您可以使用授與 REST API 以程式設計方式設定模型許可權。設定模型權限時，請在 REST API 要求中會設定為 securable_type"FUNCTION" 。例如，使用 PATCH /api/2.1/unity-catalog/permissions/function/{full_name} 來更新已註冊的模型許可權。

使用別名和標籤部署及組織模型

模型別名和標籤可協助您在 Unity 目錄中組織和管理模型。

模型別名可讓您將具名的可變動參考指派給已註冊模型的特定版本。您可以使用別名來指出模型版本的部署狀態。例如，您可以將「冠軍」別名配置給目前處於生產環境的模型版本，並在使用生產模型的工作負載中將此別名設為目標。接著，您可以將「冠軍」別名重新指派給不同的模型版本，以更新生產模型。

卷標是與已註冊的模型和模型版本相關聯的索引鍵/值組，可讓您依據函式或狀態來標記和分類它們。例如，您可以套用索引鍵 "task" 和值 "question-answering" 標籤（如 UI task:question-answering所示）套用至用於回答問題工作的已註冊模型。在模型版本層級，您可以使用標記 validation_status:pending 進行預先部署驗證的版本，以及使用清除以進行部署 validation_status:approved的版本。

如需如何使用別名和標記，請參閱下列各節。

在模型上設定和刪除別名

必要許可權：已註冊模型的擁有者，以及 USE SCHEMA 包含模型的架構和 USE CATALOG 目錄的許可權。

您可以使用目錄總管，在 Unity 目錄中設定、更新和移除模型的別名。您可以在模型詳細數據頁面中跨已註冊的模型管理別名，並在模型版本詳細數據頁面中設定特定模型版本的別名。

若要使用 MLflow 用戶端 API 來設定、更新和刪除別名，請參閱下列範例：

from mlflow import MlflowClient
client = MlflowClient()

# create "Champion" alias for version 1 of model "prod.ml_team.iris_model"
client.set_registered_model_alias("prod.ml_team.iris_model", "Champion", 1)

# reassign the "Champion" alias to version 2
client.set_registered_model_alias("prod.ml_team.iris_model", "Champion", 2)

# get a model version by alias
client.get_model_version_by_alias("prod.ml_team.iris_model", "Champion")

# delete the alias
client.delete_registered_model_alias("prod.ml_team.iris_model", "Champion")

在模型上設定和刪除標籤

必要許可權：已註冊模型的擁有者或擁有APPLY_TAG許可權，以及USE SCHEMAUSE CATALOG包含模型的架構和目錄的許可權。

請參閱在目錄總管中管理標籤，瞭解如何使用UI來設定和刪除標籤。

若要使用 MLflow 用戶端 API 來設定和刪除標籤，請參閱下列範例：

from mlflow import MlflowClient
client = MlflowClient()

# Set registered model tag
client.set_registered_model_tag("prod.ml_team.iris_model", "task", "classification")

# Delete registered model tag
client.delete_registered_model_tag("prod.ml_team.iris_model", "task")

# Set model version tag
client.set_model_version_tag("prod.ml_team.iris_model", "1", "validation_status", "approved")

# Delete model version tag
client.delete_model_version_tag("prod.ml_team.iris_model", "1", "validation_status")

已註冊的模型和模型版本標籤都必須符合整個平台的條件約束。

如需別名和標記用戶端 API 的詳細資訊，請參閱 MLflow API 檔。

載入用於推斷的模型

依別名推斷工作負載取用模型版本

需要的許可權：EXECUTE已註冊模型的許可權，以及USE SCHEMAUSE CATALOG包含模型的架構和目錄的許可權。

您可以撰寫批次推斷工作負載，以依別名參考模型版本。例如，下列代碼段會載入並套用「冠軍」模型版本以進行批次推斷。如果「冠軍」版本更新為參考新的模型版本，批次推斷工作負載就會在下一次執行時自動挑選。這可讓您將模型部署與批次推斷工作負載分離。

import mlflow.pyfunc
model_version_uri = "models:/prod.ml_team.iris_model@Champion"
champion_version = mlflow.pyfunc.load_model(model_version_uri)
champion_version.predict(test_x)

您也可以撰寫部署工作流程，以依別名取得模型版本，並使用服務 REST API 的模型來更新服務端點的模型來提供該版本：

import mlflow
import requests
client = mlflow.tracking.MlflowClient()
champion_version = client.get_model_version_by_alias("prod.ml_team.iris_model", "Champion")
# Invoke the model serving REST API to update endpoint to serve the current "Champion" version
model_name = champion_version.name
model_version = champion_version.version
requests.request(...)

依推斷工作負載的版本號碼取用模型版本

您也可以依版本號碼載入模型版本：

import mlflow.pyfunc
# Load version 1 of the model "prod.ml_team.iris_model"
model_version_uri = "models:/prod.ml_team.iris_model/1"
first_version = mlflow.pyfunc.load_model(model_version_uri)
first_version.predict(test_x)

只要您擁有適當的許可權，就可以從連結至包含模型的中繼存放區的任何工作區存取 Unity 目錄中的模型。例如，您可以從開發工作區中的目錄存取模型 prod ，以利比較新開發的模型與生產基準。

若要與其他使用者共同作業（共用寫入許可權）在您建立的已註冊模型上，您必須將模型的擁有權授與包含您自己和您想要共同作業的使用者群組。共同作業者也必須在包含模型的目錄和架構上擁有 USE CATALOG 和 USE SCHEMA 許可權。如需詳細資訊，請參閱 Unity 目錄許可權和安全性實體物件。

若要與其他區域或帳戶中的用戶共用模型，請使用 Delta Sharing Databricks-to-Databricks 共用流程。請參閱將模型新增至共用（適用於提供者）和取得 Databricks 模型（適用於收件者）中的存取權。身為收件者，從共用建立目錄之後，您會以與 Unity 目錄中任何其他模型相同的方式存取該共享目錄中的模型。

標註模型或模型版本

必要許可權：已註冊模型的擁有者，以及 USE SCHEMA 包含模型的架構和 USE CATALOG 目錄的許可權。

您可以標註模型或模型版本的相關信息。例如，您可能想要包含問題的概觀，或所使用方法和演算法的相關信息。

使用UI標註模型或模型版本

請參閱使用 Markdown 批注在目錄總管中的文件數據。

使用 API 標註模型或模型版本

若要更新已註冊的模型描述，請使用 MLflow 用戶端 API update_registered_model() 方法：

client = MlflowClient()
client.update_registered_model(
  name="<model-name>",
  description="<description>"
)

若要更新模型版本描述，請使用 MLflow 用戶端 API update_model_version() 方法：

client = MlflowClient()
client.update_model_version(
  name="<model-name>",
  version=<model-version>,
  description="<description>"
)

重新命名模型（僅限 API）

需要的許可權：已註冊模型的擁有者、CREATE_MODEL包含已註冊模型的架構許可權，以及USE SCHEMAUSE CATALOG包含模型的架構和目錄的許可權。

若要重新命名已註冊的模型，請使用 MLflow 用戶端 API rename_registered_model() 方法：

client=MlflowClient()
client.rename_registered_model("<model-name>", "<new-model-name>")

刪除模型或模型版本

必要許可權：已註冊模型的擁有者，以及 USE SCHEMA 包含模型的架構和 USE CATALOG 目錄的許可權。

您可以使用目錄總管 UI 或 API，刪除已註冊的模型或模型版本。

使用 API 刪除模型版本或模型

警告

您無法恢復這個動作。當您刪除模型時，會刪除 Unity 目錄所儲存的所有模型成品，以及與已註冊模型相關聯的所有元數據。

刪除模型版本

若要刪除模型版本，請使用 MLflow 用戶端 API delete_model_version() 方法：

# Delete versions 1,2, and 3 of the model
client = MlflowClient()
versions=[1, 2, 3]
for version in versions:
  client.delete_model_version(name="<model-name>", version=version)

刪除模型

若要刪除模型，請使用 MLflow 用戶端 API delete_registered_model() 方法：

client = MlflowClient()
client.delete_registered_model(name="<model-name>")

清單和搜尋模型

您可以使用 MLflow 的 search_registered_models（） Python API，在 Unity 目錄中列出已註冊的模型：

client=MlflowClient()
client.search_registered_models()

您也可以使用 search_model_versions() 方法來搜尋特定模型名稱，並列出其版本詳細資料：

from pprint import pprint

client=MlflowClient()
[pprint(mv) for mv in client.search_model_versions("name='<model-name>'")]

範例

此範例說明如何使用 Unity 目錄中的模型來建置機器學習應用程式。

Unity 目錄範例中的模型

將工作流程和模型遷移至 Unity 目錄

Databricks 建議使用 Unity 目錄中的模型來改善治理、輕鬆地跨工作區和環境共用，以及更有彈性的 MLOps 工作流程。數據表會比較工作區模型登錄和 Unity 目錄的功能。

功能	工作區模型登錄（舊版）	Unity 目錄中的模型（建議）
依具名別名參考模型版本	模型登錄階段：將模型版本移至四個固定階段的其中一個，以依該階段參考它們。無法重新命名或新增階段。	模型登錄別名：為每個已註冊的模型建立最多 10 個自定義和可重新指派的具名參考。
建立模型的訪問控制環境	模型登錄階段：在一個已註冊的模型中使用階段來表示其模型版本的環境，且四個固定階段中只有兩個的訪問控制（`Staging` 和 `Production`）。	已註冊的模型：在 MLOps 工作流程中為每個環境建立已註冊的模型，並利用 Unity 目錄的三層命名空間和許可權來表示治理。
跨環境升級模型（部署模型）	`transition_model_version_stage()`使用 MLflow 用戶端 API 將模型版本移至不同的階段，可能會中斷參考上一個階段的工作流程。	`copy_model_version()`使用 MLflow 用戶端 API，將模型版本從一個已註冊的模型複製到另一個模型。
跨工作區存取和共用模型	在工作區之間手動匯出和匯入模型，或使用個人存取令牌和工作區秘密範圍設定遠端模型登錄的連線。	跨相同帳戶中工作區的模型存取現用。不需要設定。
設定權限	在工作區層級設定許可權。	在帳戶層級設定許可權，這會在工作區之間套用一致的控管。
存取 Databricks Markplace 中的模型	無法。	將模型從 Databricks 市集載入 Unity 目錄中繼存放區，並跨工作區存取模型。

以下連結的文章說明如何將工作流程（模型定型和批次推斷作業）和模型從工作區模型登錄移轉至 Unity 目錄。

Unity 目錄支援的限制

Unity 目錄中的模型不支持階段。 Databricks 建議使用 Unity 目錄中的三層命名空間來表示模型位於的環境，並使用別名來升級模型以進行部署。如需詳細資訊，請參閱升級指南。
Unity 目錄中的模型不支援 Webhook。請參閱升級指南中的建議替代方案。
Unity 目錄中的模型不支援某些搜尋 API 欄位和運算元。藉由使用支援的篩選條件和掃描結果來呼叫搜尋 API，即可減輕此問題。以下是一些範例：
- order_by search_model_versions 或 search_registered_models 用戶端 API 不支援參數。
- 或search_registered_models不支援search_model_versions以標記為基礎的篩選條件。tags.mykey = 'myvalue'。
- 或不支援search_model_versionssearch_registered_models完全相等的運算子（例如、!=LIKEILIKE 、。
- 不支援依名稱搜尋已註冊的模型（例如 MlflowClient().search_registered_models(filter_string="name='main.default.mymodel'") 。若要依名稱擷取特定的已註冊模型，請使用 get_registered_model。
Unity 目錄中不支援已註冊模型和模型版本的電子郵件通知和批注討論線程。
Unity 目錄中的模型不支援活動記錄。不過，您可以使用稽核記錄來追蹤 Unity 目錄中模型的活動。
search_registered_models 可能會針對透過 Delta Sharing 共用的模型傳回過時的結果。若要確保最新的結果，請使用 Databricks CLI 或 SDK 來列出架構中的模型。

在 Unity 目錄中管理模型生命週期

需求

將訓練工作負載升級至 Unity 目錄

安裝 MLflow Python 用戶端

設定 MLflow 用戶端以存取 Unity 目錄中的模型

定型和註冊 Unity 目錄相容模型

使用自動記錄向 Unity 目錄註冊模型

使用自動推斷的簽章向 Unity 目錄註冊模型

追蹤 Unity 目錄中模型的數據譜系

在UI中檢視模型

控制模型的存取

使用別名和標籤部署及組織模型

在模型上設定和刪除別名

在模型上設定和刪除標籤

載入用於推斷的模型

依別名推斷工作負載取用模型版本

依推斷工作負載的版本號碼取用模型版本

標註模型或模型版本

使用UI標註模型或模型版本

使用 API 標註模型或模型版本

重新命名模型（僅限 API）

刪除模型或模型版本

使用 API 刪除模型版本或模型

刪除模型版本

刪除模型

清單和搜尋模型

範例

將工作流程和模型遷移至 Unity 目錄

Unity 目錄支援的限制

意見反應

意見反應

其他資源

在 Unity 目錄中管理模型生命週期

需求

將訓練工作負載升級至 Unity 目錄

安裝 MLflow Python 用戶端

設定 MLflow 用戶端以存取 Unity 目錄中的模型

定型和註冊 Unity 目錄相容模型

使用自動記錄向 Unity 目錄註冊模型

使用自動推斷的簽章向 Unity 目錄註冊模型

追蹤 Unity 目錄中模型的數據譜系

在UI中檢視模型

控制模型的存取

使用別名和標籤部署及組織模型

在模型上設定和刪除別名

在模型上設定和刪除標籤

載入用於推斷的模型

依別名推斷工作負載取用模型版本

依推斷工作負載的版本號碼取用模型版本

跨工作區共用模型

與相同區域中的用戶共用模型

與其他區域或帳戶中的用戶共用模型

標註模型或模型版本

使用UI標註模型或模型版本

使用 API 標註模型或模型版本

重新命名模型（僅限 API）

刪除模型或模型版本

使用 API 刪除模型版本或模型

刪除模型版本

刪除模型

清單和搜尋模型

範例

將工作流程和模型遷移至 Unity 目錄

Unity 目錄支援的限制

意見反應

意見反應

其他資源