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

2025-06-12

重要

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

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

如需概觀模型註冊的概念，請參閱 ML 模型生命週期的 MLflow。

MLflow 3 可大幅增強 Unity 目錄中的 MLflow 模型登錄，讓您的模型能夠直接擷取參數和計量等數據，並讓所有工作區和實驗都能使用。 MLflow 3 中的預設登錄 URI 為 databricks-uc，這表示將使用 Unity 目錄中的 MLflow 模型登錄。如需詳細資訊，請參閱開始使用 MLflow 3 和 MLflow 3 的模型登錄改進。

需求

必須在工作區中啟用 Unity 目錄。請參閱開始使用 Unity 目錄來建立 Unity 目錄中繼存放區，在工作區中啟用它，並建立目錄。如果未啟用 Unity 目錄，請使用工作區模型登錄。
必須使用可存取 Unity 目錄的計算資源。針對 ML 工作負載，這表示計算的存取模式必須是專用（先前為單一使用者）。如需詳細資訊，請參閱存取模型。透過 Databricks Runtime 15.4 LTS ML 和更新版本，您也可以使用專用群組存取模式。
若要建立新的已註冊模型，您需要下列權限：
- 結構描述及其封入目錄的 USE SCHEMA 和 USE CATALOG 權限。
- CREATE MODEL 或 CREATE FUNCTION 架構的許可權。若要授與許可權，請使用目錄總管 UI 或 SQL GRANT 命令：
```
GRANT CREATE MODEL ON SCHEMA <schema-name> TO <principal>
```

注意

您的工作區必須連結至支援權限繼承的 Unity 目錄中繼存放區。這適用於 2022 年 8 月 25 日之後建立的全部中繼存放區。如果在舊版的元存儲上運行，請參閱文件以便升級。

安裝並設定 Unity 目錄的 MLflow 用戶端

本節包含了安裝及設定 Unity 目錄之 MLflow 用戶端的指示。

安裝 MLflow Python 用戶端

Databricks Runtime 13.2 ML 和更新版本中包含對 Unity Catalog 模型的支援（在 Azure China 中是 Databricks Runtime 15.0 ML 和更新版本）。

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

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

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

如果您的工作區預設目錄位於 Unity 目錄（而非 hive_metastore），而且您是使用 Databricks Runtime 13.3 LTS 或更新版本執行叢集（Azure 中國區域中的 Databricks Runtime 15.0 或更新版本），或使用 MLflow 3，系統會自動在默認目錄中建立和載入模型。

對於其他工作區，MLflow Python 用戶端會在 Databricks 工作區模型登錄中建立模型。若要升級至 Unity 目錄中的模型，請使用筆記本中的下列程式碼來設定 MLflow 用戶端：

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

對於少數工作區，其在 2024 年 1 月之前，預設目錄已設定為 Unity Catalog 中的某個目錄，且已使用工作區模型登錄，您必須使用上述命令，手動將預設目錄設定為 Unity Catalog。

訓練和註冊與 Unity Catalog 相容的模型

必要權限：若要建立新的已註冊模型，您需要封入架構的 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>。

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

本節中的模型訓練範例會建立新的模型版本，並在 prod 目錄中註冊。使用 prod 目錄並不一定表示模型版本正在處理實際運行中的流量。模型版本的編目、架構及已註冊模型反映其環境（prod）和相關的治理規則（例如，可以設定許可權，使只有系統管理員能夠從編目中刪除），但並不反映其部署狀態。若要管理部署狀態，請使用模型別名。

使用自動記錄將模型註冊到 Unity Catalog

若要註冊模型，請使用 MLflow 用戶端 API register_model() 方法。請參閱 mlflow.register_model。

MLflow 3

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,
# and the model version will contain all parameters and metrics
# logged with the corresponding MLflow Logged Model.
logged_model = mlflow.last_logged_model()
mlflow.register_model(logged_model.model_uri, "prod.ml_team.iris_model")

MLflow 2.x

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")

使用 API 註冊模型

MLflow 3

mlflow.register_model(
  "models:/<model_id>", "prod.ml_team.iris_model"
)

MLflow 2.x

mlflow.register_model(
  "runs:/<run_id>/model", "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()

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

MLflow 3

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,
        name="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",
    )

MLflow 2.x

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",
    )

使用 UI 註冊模型

執行下列步驟:

從實驗執行頁面，在 UI 右上角按下註冊模型。
在對話方塊中，選取 [Unity 目錄]，然後從下拉式清單中選取目的地模型。
按下 [註冊]。

註冊模型可能需要一些時間。若要監視進度，請瀏覽至 Unity 目錄中的目的地模型，並定期重新整理。

使用模型別名

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

在模型上設定和刪除別名

必要權限：已註冊模型的擁有者，以及包含該模型的結構描述和目錄的 USE SCHEMA 和 USE CATALOG 權限。

您可以使用目錄總管，在 Unity 目錄中設定、更新和移除模型的別名。請參閱在UI中檢視和管理模型。

要使用 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")

如需別名用戶端 API 的詳細資料，請參閱 MLflow API 文件。

以別名載入模型版本以進行推理工作負載

必要權限：已註冊模型的 EXECUTE 權限，以及包含該模型的結構描述和目錄的 USE SCHEMA 和 USE CATALOG 權限。

批次推論工作負載可根據別名參考模型版本。下列片段會載入並套用「Champion」模型版本以進行批次推斷。如果「Champion」版本更新為參考新的模型版本，批次推理工作負載會在下一次執行時自動採用。這可讓您將模型部署與批次推斷工作負載進行分離。

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 目錄權限和安全物件。

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

追蹤 Unity 目錄中模型的資料譜系

注意

MLflow 2.11.0 和更新版本提供對 Unity Catalog 中資料表與模型之間譜系的支援。

當您在 Unity 目錄的資料表上訓練模型時，您可將模型的譜系追蹤到已訓練和評估的上游資料集。為此，請使用 mlflow.log_input。這會使用產生模型的 MLflow 執行來儲存輸入資料表資訊。資料譜系也會針對使用特徵存放庫 API 所記錄的模型自動擷取。請參閱特徵控管和譜系。

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

下列程式碼為範例。

MLflow 3

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")
    # 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,
        name="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_classifier",
    )

MLflow 2.x

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")
    # 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_classifier",
    )

控制對模型的存取

在 Unity 目錄中，已註冊的模型是 FUNCTION 安全性實體物件的子類型。若要授與 Unity 目錄中註冊之模型的存取權，您可使用 GRANT ON FUNCTION。您也可以使用目錄總管來設定模型擁有權和許可權。如需詳細資訊，請參閱在 Unity 目錄和 Unity 目錄物件模型中管理許可權。

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

在UI中檢視和管理模型

必要權限：若要在 UI 中檢視已註冊的模型及其模型版本，您需要已註冊模型的 EXECUTE 權限，以及包含該模型的結構描述和目錄的 USE SCHEMA 和 USE CATALOG 權限

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

檢視模型資訊

若要在目錄總管中檢視模型：

按一下在側邊欄中點擊目錄。
從右上方的下拉式清單中選取計算資源。
在左側的 [目錄瀏覽器] 樹狀目錄中，開啟目錄並選取結構描述。
如果架構包含任何模型，它們會出現在 [ 模型] 下的樹狀結構中，如下所示。
按兩下模型以查看詳細資訊。模型詳細數據頁面會顯示具有其他資訊的模型版本清單。

設定模型別名

若要使用UI設定模型別名：

在 [模型詳細數據] 頁面上，將滑鼠停留在您要新增別名之模型版本的數據列上。 [ 新增別名] 按鈕隨即出現。
按兩下 [新增別名]。
輸入別名，或從下拉功能表中選取別名。您可以在對話框中新增多個別名。
按兩下 [ 儲存別名]。

如何從模型詳細數據頁面將別名新增至模型版本。

若要移除別名：

將滑鼠停留在模型版本的數據列上，然後按兩下別名旁的鉛筆圖示。
在對話框中，點擊您要移除的別名旁的 X。
按兩下 [ 儲存別名]。

如何在模型詳細數據頁面上從模型版本移除別名。

檢視模型版本資訊和模型譜系

若要檢視模型版本的詳細資訊，請按兩下模型清單中的名稱。模型版本頁面隨即出現。此頁面包含建立版本之 MLflow 來源執行的連結。在 MLflow 3 中，您也可以檢視與對應 MLflow 記錄模型一起記錄的所有參數和計量。

MLflow 3

模型版本頁面

MLflow 2.x

模型版本頁面

您可以從此頁面檢視模型的譜系，如下所示：

選取 [歷程] 索引標籤。左側欄位將顯示記錄在模型中的元件。

的模型頁面上
點選 看譜系圖形。譜系圖形隨即出現。如需探索譜系圖的詳細資訊，請參閱擷取和探索譜系。
若要關閉譜系圖形，請按下右上角譜系圖形的關閉按鈕。

重新命名模型

必要權限：已註冊模型的擁有者、包含已註冊模型的結構描述 CREATE MODEL 權限，以及包含該模型的結構描述和目錄的 USE SCHEMA 和 USE CATALOG 權限。

若要重新命名已註冊的模型，請使用 MLflow 用戶端 API rename_registered_model() 方法，其中 <full-model-name> 是模型的完整 3 層名稱，而 <new-model-name> 是不含目錄或架構的模型名稱。

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

例如，下列程式代碼會將模型 hello_world 的名稱變更為 hello。

client=MlflowClient()
client.rename_registered_model("docs.models.hello_world", "hello")

複製模型版本

您可將模型版本從一個模型複製到 Unity 目錄中的另一個模型。

使用 UI 複製模型版本

執行下列步驟:

從模型版本頁面，按下 UI 右上角的 [複製此版本]。
從下拉式清單中選取目的地模型，然後按下 [複製]。

複製模型可能需要一些時間。若要監視進度，請瀏覽至 Unity 目錄中的目的地模型，並定期重新整理。

使用 API 複製模型版本

若要複製模型版本，請使用 MLflow 的 copy_model_version（） Python API：

client = MlflowClient()
client.copy_model_version(
  "models:/<source-model-name>/<source-model-version>",
  "<destination-model-name>",
)

刪除模型或模型版本

必要權限：已註冊模型的擁有者，以及包含該模型的結構描述和目錄的 USE SCHEMA 和 USE CATALOG 權限。

您可以使用UI或 API，在已註冊的模型中刪除已註冊的模型或模型版本。

警告

您無法復原這個動作。當您刪除模型時，Unity Catalog 儲存的所有模型工件以及與已註冊模型相關的所有元數據都會被刪除。

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

要刪除 Unity 目錄中的模型或模型版本，請遵循下列步驟。

在目錄總管的模型頁面或模型版本頁面上，單擊右上角的

在模型頁面上：

由模型版本頁面開始：
選擇刪除。
確認對話方塊隨即出現。按一下 [刪除] 以確認。

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

若要刪除模型版本，請使用 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>")

在模型上使用標籤

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

必要權限：已註冊模型的擁有者或者擁有 APPLY TAG 權限，再加上該模型所在的結構描述和目錄的 USE SCHEMA 和 USE 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 文件。

將描述 (註解) 新增至模型或模型版本

必要權限：已註冊模型的擁有者，以及包含該模型的結構描述和目錄的 USE SCHEMA 和 USE CATALOG 權限。

您可在 Unity 目錄中包含任何模型或模型版本的文字描述。例如，您可能想要提供問題的概觀，或有關所使用方法和演算法的資訊。

針對模型，您也可選擇使用 AI 產生的註解。請參閱將 AI 產生的批註新增至 Unity Catalog 物件。

使用 UI 新增模型描述

若要新增模型的描述，您可使用 AI 產生的註解，也可輸入自己的註解。您可視需要編輯 AI 產生的註解。

若要新增自動產生的註解，請按下 [AI 產生] 按鈕。
若要新增您自己的註解，請按下 [新增]。在對話方塊中輸入您的註解，然後按下 [儲存]。

uc 模型描述按鈕

使用 UI 將描述添加至模型版本

要將描述新增至 Unity 目錄中的模型版本，請遵循下列步驟：

在模型版本頁面上，按下 [描述] 底下的鉛筆圖示。
在對話方塊中輸入您的註解，然後按下 [儲存]。

使用 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>"
)

列出和搜尋模型

若要在 Unity 目錄中取得已註冊的模型清單，請使用 MLflow 的 search_registered_models（） Python API：

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 目錄中的模型不支援所有搜尋 API 欄位和運算子。如需詳細資訊，請參閱限制。

下載模型檔案 (進階使用案例)

在大部分情況下，若要載入模型，您應該使用 mlflow.pyfunc.load_model 或 mlflow.<flavor>.load_model 之類的 MLflow API (例如，HuggingFace 模型的 mlflow.transformers.load_model)。

在某些情況下，您可能需要下載模型檔案，以偵錯模型行為或模型載入問題。您可使用 mlflow.artifacts.download_artifacts 下載模型檔案，如下所示：

import mlflow
mlflow.set_registry_uri("databricks-uc")
model_uri = f"models:/{model_name}/{version}" # reference model by version or alias
destination_path = "/local_disk0/model"
mlflow.artifacts.download_artifacts(artifact_uri=model_uri, dst_path=destination_path)

跨環境推廣模型

Databricks 建議您將 ML 管線部署為程式碼。不需要跨環境推廣模型，因為所有產品模型都可以透過生產環境中的自動化訓練工作流程來生成。

不過，在某些情況下，重新訓練整個環境模型可能太過昂貴。相反地，你可以在 Unity Catalog 中跨已註冊的模型複製模型版本，以便在不同環境中推廣。

您需要下列權限，才能執行下列範例程式碼：

在 USE CATALOG 和 staging 目錄上的 prod。
USE SCHEMA 基於 staging.ml_team 和 prod.ml_team 結構描述。
EXECUTE 在 staging.ml_team.fraud_detection 上。

此外，您必須是已註冊模型 prod.ml_team.fraud_detection 的擁有者。

下列程式碼片段使用可在 MLflow 2.8.0 版和更新版本中取得的 copy_model_versionMLflow 用戶端 API。

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

client = mlflow.tracking.MlflowClient()
src_model_name = "staging.ml_team.fraud_detection"
src_model_version = "1"
src_model_uri = f"models:/{src_model_name}/{src_model_version}"
dst_model_name = "prod.ml_team.fraud_detection"
copied_model_version = client.copy_model_version(src_model_uri, dst_model_name)

模型版本進入生產環境之後，您可執行任何必要的部署前驗證。然後，您可使用別名來標示要部署的模型版本。

client = mlflow.tracking.MlflowClient()
client.set_registered_model_alias(name="prod.ml_team.fraud_detection", alias="Champion", version=copied_model_version.version)

在上述範例中，只有能夠從 staging.ml_team.fraud_detection 註冊模型讀取並寫入 prod.ml_team.fraud_detection 註冊模型的使用者，才能將暫存模型升階至生產環境。相同的使用者也可使用別名來管理生產環境中部署的模型版本。您不需要設定任何其他規則或原則來管理模型升級和部署。

您可以自訂此流程，以在多個符合您設定的環境中推廣模型版本，例如 dev、qa 和 prod。存取控制會依每個環境中設定的方式執行。

範例筆記本

此範例筆記本說明如何使用 Unity 目錄 API 中的模型來管理 Unity 目錄中的模型，包括註冊模型和模型版本、新增描述、載入和部署模型、使用模型別名，以及刪除模型和模型版本。

MLflow 3

適用於 MLflow 3 的 Unity 目錄範例筆記本中的模型

拿筆記本

MLflow 2.x

Unity Catalog 範例筆記本中的模型

拿筆記本

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

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

能力	工作區模型登錄 (舊版)	Unity 目錄中的模型 (建議)
透過命名別名來參考模型版本	模型登錄階段：將模型版本移至四個固定階段的一個，以依該階段進行參考。無法重新命名或新增階段。	模型登錄別名：為每個已註冊的模型建立最多 10 個自訂名稱並可重新指派的版本參考。
建立模型的存取控制環境	模型登錄階段：在一個已註冊的模型中使用階段來表示其模型版本的環境，僅對四個固定階段 (`Staging` 和 `Production`) 中的兩個進行存取控制。	已註冊的模型：在 MLOps 工作流程中為每個環境建立已註冊的模型，並利用 Unity 目錄的三層命名空間和權限來表示治理。
在不同的環境中推廣模型 (部署模型)	使用 `transition_model_version_stage()` MLflow 用戶端 API 將模型版本移至不同的階段，可能會中斷參考上一個階段的工作流程。	使用 `copy_model_version()` MLflow 用戶端 API，將模型版本從一個已註冊的模型複製到另一個模型。
跨工作區存取和共用模型	在工作區之間手動匯出和匯入模型，或使用個人存取權杖和工作區祕密範圍，設定遠端模型登錄的連線。	在相同帳戶中，跨工作區模型的即時存取。不需要組態。
設定權限	在工作區層級設定權限。	在帳戶層級設定權限，這會在工作區之間套用一致的控管。
存取 Databricks Marketplace 的模型資源	無法使用。	將模型從 Databricks Marketplace 載入 Unity 目錄中繼存放區，並跨工作區存取模型。

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

限制

Unity 目錄中的模型不支援階段。 Databricks 建議使用 Unity 目錄中的三層命名空間來表示模型所處的環境，並使用別名來升級模型以進行部署。如需詳細資訊，請參閱促進模型跨環境應用。
Unity 目錄中的模型不支援 Webhook。請參閱升級指南中的建議替代方案。
Unity 目錄中的模型不支援部分搜尋 API 欄位和運算子。藉由使用支援的篩選條件和掃描結果來呼叫搜尋 API，可減輕此問題。下列是一些範例：
- order_by 參數在 search_model_versions 或 search_registered_models 用戶端 API 中不支援。
- tags.mykey = 'myvalue' 或 search_model_versions 不支援基於標籤的篩選條件 (search_registered_models)。
- 除了完全相等運算子之外（例如 LIKE、ILIKE、!=），search_model_versions 和 search_registered_models 不支援其他運算子。
- 不支援依名稱搜尋已註冊的模型 (例如 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 用戶端

安裝 MLflow Python 用戶端

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

訓練和註冊與 Unity Catalog 相容的模型

使用自動記錄將模型註冊到 Unity Catalog

MLflow 3

MLflow 2.x

使用 API 註冊模型

MLflow 3

MLflow 2.x

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

MLflow 3

MLflow 2.x

使用 UI 註冊模型

使用模型別名

在模型上設定和刪除別名

以別名載入模型版本以進行推理工作負載

依推斷工作負載的版本號碼來載入模型版本

跨工作區共用模型

與相同區域中的使用者共用模型

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

追蹤 Unity 目錄中模型的資料譜系

MLflow 3

MLflow 2.x

控制對模型的存取

在UI中檢視和管理模型

檢視模型資訊

設定模型別名

檢視模型版本資訊和模型譜系

MLflow 3

MLflow 2.x

重新命名模型

複製模型版本

使用 UI 複製模型版本

使用 API 複製模型版本

刪除模型或模型版本

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

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

在模型上使用標籤

將描述 (註解) 新增至模型或模型版本

使用 UI 新增模型描述

使用 UI 將描述添加至模型版本

使用 API 新增模型或模型版本的描述

列出和搜尋模型

下載模型檔案 (進階使用案例)

跨環境推廣模型

範例筆記本

MLflow 3

適用於 MLflow 3 的 Unity 目錄範例筆記本中的模型

MLflow 2.x

Unity Catalog 範例筆記本中的模型

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

限制

意見反應

其他資源