Compartilhar via

Gerenciar o ciclo de vida do modelo no Catálogo do Unity

Importante

Este artigo descreve como usar Modelos no Catálogo do Unity como parte do seu fluxo de trabalho de aprendizado de máquina para gerenciar o ciclo de vida completo dos modelos de ML. O Databricks fornece uma versão hospedada do Registro de Modelo do MLflow no Catálogo do Unity. Os modelos no Catálogo do Unity estendem os benefícios do Catálogo do Unity aos modelos de ML, incluindo o controle de acesso centralizado, a auditoria, a linhagem e a descoberta de modelos entre os espaços de trabalho. Os Modelos no Catálogo do Unity são compatíveis com o cliente Python do MLflow de código aberto.

Para obter uma visão geral dos conceitos do Registro de Modelo, consulte MLflow para o ciclo de vida do modelo de ML.

O MLflow 3 faz aprimoramentos significativos no Registro de Modelo do MLflow no Catálogo do Unity, permitindo que seus modelos capturem diretamente dados como parâmetros e métricas e os disponibilizem em todos os workspaces e experimentos. O URI do Registro padrão no MLflow 3 é databricks-uc, o que significa que o Registro de Modelo do MLflow no Catálogo do Unity será usado. Para obter mais detalhes, consulte Introdução aos aprimoramentos do MLflow 3 e do Registro de Modelo com o MLflow 3.

Requisitos

  1. O Catálogo do Unity deve estar habilitado no seu espaço de trabalho. Veja Comece a usar o Unity Catalog para criar um Metastore do Unity Catalog, ativá-lo em um espaço de trabalho e criar um catálogo. Se o Catálogo do Unity não estiver habilitado, use o registro de modelo do espaço de trabalho.

  2. Você deve usar um recurso de computação que tenha acesso ao Catálogo do Unity. Para cargas de trabalho de ML, isso significa que o modo de acesso para a computação deve ser Dedicado (anteriormente usuário único). Para obter mais informações, confira Modos de acesso. Com o Databricks Runtime 15.4 LTS ML e superior, você também pode usar o modo de acesso de grupo dedicado.

  3. Para criar novos modelos registrados, você precisa dos seguintes privilégios:

    • Privilégios USE SCHEMA e USE CATALOG no esquema e no catálogo que o envolve.
    • Privilégios CREATE_MODEL ou CREATE_FUNCTION no esquema. Para conceder privilégios, use a interface do usuário do Catalog Explorer ou o comando SQLGRANT:
    GRANT CREATE_MODEL ON SCHEMA <schema-name> TO <principal>

Observação

Seu espaço de trabalho deve estar vinculado a um metastore do Catálogo Unity que ofereça suporte à herança de privilégios. Isso se aplica a todos os metastores criados após 25 de agosto de 2022. Se estiver executando em um metastore mais antigo, siga os documentos para fazer a atualização.

Instalar e configurar o cliente MLflow para o Catálogo do Unity

Esta seção inclui instruções para instalar e configurar o cliente MLflow para o Catálogo do Unity.

Instalar o cliente Python do MLflow

O suporte para modelos no Catálogo do Unity está incluído no Databricks Runtime 13.2 ML e versões posteriores (Databricks Runtime 15.0 ML e versões posteriores no Azure China).

Você também pode usar os modelos no Catálogo do Unity no Databricks Runtime 11.3 LTS e superior instalando a versão mais recente do cliente Python do MLflow no seu notebook, usando o código a seguir.

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

Configurar o cliente do MLflow para acessar modelos no Catálogo do Unity

Se o catálogo padrão do seu workspace estiver no Catálogo do Unity (em vez de hive_metastore) e você estiver executando um cluster usando o Databricks Runtime 13.3 LTS ou superior (Databricks Runtime 15.0 ou superior nas regiões do Azure China) ou usando o MLflow 3, os modelos serão criados e carregados automaticamente do catálogo padrão.

Para outros espaços de trabalho, o cliente Python do MLflow cria modelos no registro de modelos do espaço de trabalho do Databricks. Para atualizar para modelos no Catálogo do Unity, use o código a seguir em seu notebook para configurar o cliente do MLflow:

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

Para um pequeno número de workspaces onde o catálogo padrão foi configurado como um catálogo no Catálogo Unity antes de janeiro de 2024 e o registro do modelo do workspace foi usado antes de janeiro de 2024, é necessário definir manualmente o catálogo padrão para o Catálogo Unity usando o comando mostrado acima.

Treinar e registrar modelos compatíveis com o Catálogo do Unity

Permissões necessárias: Para criar um novo modelo registrado, você precisa dos privilégios CREATE_MODEL e USE SCHEMA no esquema anexo e do privilégio USE CATALOG no catálogo anexo. Para criar novas versões do modelo em um modelo registrado, você deve ser o proprietário do modelo registrado e ter os privilégios USE SCHEMA e USE CATALOG no esquema e no catálogo que contêm o modelo.

As versões do modelo ML no UC devem ter um modelo de assinatura. Se você ainda não estiver registrando modelos do MLflow com assinaturas em suas cargas de trabalho de treinamento de modelo, pode seguir uma das seguintes opções:

  • Use o Databricks Autologging, que registra automaticamente os modelos com assinaturas para muitas estruturas populares de ML. Confira as estruturas com suporte na documentação do MLflow.
  • Com o MLflow 2.5.0 e superior, você pode especificar um exemplo de entrada na sua mlflow.<flavor>.log_model chamada e a assinatura do modelo é inferida automaticamente. Para obter mais informações, consulte a documentação do MLflow.

Em seguida, passe o nome de três níveis do modelo para as APIs do MLflow, no formato <catalog>.<schema>.<model>.

Os exemplos nesta seção criam e acessam modelos no ml_team esquema do catálogo prod.

Os exemplos de treinamento de modelo nesta seção criam uma nova versão de modelo e a registram no prod catálogo. Usar o prod catálogo não significa necessariamente que a versão do modelo atenda ao tráfego de produção. O catálogo delimitador, o esquema e o modelo registrado da versão do modelo refletem seu ambiente (prod) e as regras de governança associadas (por exemplo, privilégios podem ser configurados para que apenas os administradores possam excluir do prod catálogo), mas não seu status de implantação. Para gerenciar o status da implantação, use aliases de modelo.

Registrar um modelo no Catálogo do Unity usando autologging

Para registrar um modelo, use o método register_model() da API do Cliente MLflow. Veja 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")

Registrar um modelo usando a 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"
)

Registrar um modelo no Catálogo do Unity com uma assinatura inferida automaticamente

O suporte para assinaturas inferidas automaticamente está disponível no MLflow versão 2.5.0 e superior e tem suporte no Databricks Runtime 11.3 LTS ML e superior. Para usar as assinaturas inferidas automaticamente, use o seguinte código para instalar o cliente mais recente do Python do MLflow no seu notebook:

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

O código a seguir mostra um exemplo de uma assinatura inferida automaticamente.

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

Registre um modelo usando a interface de usuário

Siga estas etapas:

  1. Na página de execução do experimento, clique em Registrar modelo no canto superior direito da interface do usuário.

  2. Na caixa de diálogo, selecione Catálogo do Unity e selecione um modelo de destino na lista suspensa.

    Registrar a versão do modelo na caixa de diálogo com o menu suspenso

  3. Clique em Registrar.

    Caixa de diálogo para registrar a versão do modelo com botão

O registro de um modelo pode levar tempo. Para monitorar o progresso, navegue até o modelo de destino no Catálogo do Unity e atualize periodicamente.

Usar aliases de modelo

Aliases de modelo permitem que você atribua uma referência mutável e nomeada a uma versão específica de um modelo registrado. Você pode usar aliases para indicar o status de implantação de uma versão do modelo. Por exemplo, você pode alocar um alias "Champion" na versão do modelo atualmente em produção e direcionar esse alias nas cargas de trabalho que usam o modelo de produção. Em seguida, você pode atualizar o modelo de produção reatribuindo o alias "Champion" para uma versão de modelo diferente.

Definir e excluir aliases nos modelos

Permissões necessárias: Proprietário do modelo registrado, além dos privilégios USE SCHEMA e USE CATALOG no esquema e no catálogo que contêm o modelo.

Você pode definir, atualizar e remover aliases para modelos no Catálogo do Unity usando o Catalog Explorer. Consulte Exibir e gerenciar modelos na interface do usuário.

Para definir, atualizar e excluir aliases usando a API de Cliente do MLflow, consulte os exemplos abaixo:

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

Para obter mais detalhes sobre APIs de cliente de alias, consulte a documentação da API do MLflow.

Versão do modelo de carregamento por alias das cargas de trabalho de inferência

Permissões necessárias: EXECUTE privilégios no modelo registrado, além dos privilégios USE SCHEMA e USE CATALOG privilégios no esquema e no catálogo que contêm o modelo.

As cargas de trabalho de inferência do lote podem fazer referência a uma versão de modelo por alias. O trecho abaixo carrega e aplica a versão do modelo “Champion” para inferência em lote. Se a versão “Champion” for atualizada para fazer referência a uma nova versão do modelo, a carga de trabalho de inferência em lote a pegará automaticamente em sua próxima execução. Isso permite que você desacople as implantações de modelos das cargas de trabalho de inferência em lote.

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)

Os pontos de extremidade de modelagem também podem referenciar uma versão de modelo por alias. Você pode escrever fluxos de trabalho de implantação para obter uma versão do modelo por alias e atualizar um endpoint de serviço de modelo para atender a essa versão, usando a API REST de serviço de modelo. Por exemplo:

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(...)

Carregar a versão do modelo por número de versão para cargas de trabalho de inferência

Você também pode carregar versões de modelos por número de versão:

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)

Compartilhar modelos entre espaços de trabalho

Compartilhar modelos com usuários na mesma região

Caso você tenha os privilégios apropriados, você pode acessar modelos no catálogo Unity de qualquer espaço de trabalho anexado ao metastore que contém o modelo. Por exemplo, você pode acessar os modelos do catálogo prod em um espaço de trabalho de desenvolvimento, para facilitar a comparação de modelos recém-desenvolvidos com a linha de base de produção.

Para colaborar com outros usuários (compartilhar privilégios de gravação) em um modelo registrado criado, você deve conceder a propriedade do modelo a um grupo que contenha a si mesmo e aos usuários com os quais você gostaria de colaborar. Os colaboradores também devem ter os privilégios USE CATALOG e USE SCHEMA no catálogo e no esquema que contém o modelo. Confira Privilégios e objetos protegíveis do Catálogo do Unity para obter detalhes.

Compartilhar modelos com usuários em outra região ou conta

Para compartilhar modelos com usuários em outras regiões ou contas, use o Fluxo de compartilhamento Databricks para Databricks do Delta Sharing. Consulte Adicionar modelos a um compartilhamento (para provedores) e Obter acesso no modelo Databricks para Databricks (para destinatários). Como destinatário, depois de criar um catálogo a partir de um compartilhamento, você acessa modelos nesse catálogo compartilhado da mesma forma que qualquer outro modelo no Catálogo do Unity.

Acompanhar a linhagem de dados de um modelo no Catálogo do Unity

Observação

O suporte para linhagem de tabela para modelo no Catálogo do Unity está disponível no MLflow 2.11.0 e superior.

Ao treinar um modelo em uma tabela no Catálogo do Unity, você pode acompanhar a linhagem do modelo até os conjuntos de dados upstream em que ele foi treinado e avaliado. Para fazer isso, use mlflow.log_input. Isso salva as informações da tabela de entrada com a execução do MLflow que gerou o modelo. A linhagem de dados também é capturada automaticamente nos modelos registrados usando APIs do repositório de recursos. Consulte Governança e linhagem de recursos.

Quando você registra o modelo no Catálogo do Unity, as informações de linhagem são salvas automaticamente e ficam visíveis na guia Linhagem na página de versão do modelo no Gerenciador de Catálogos. Consulte Exibir informações sobre a versão do modelo e a linhagem do modelo.

O código a seguir mostra um exemplo.

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

Controlar o acesso a modelos

No Catálogo do Unity, os modelos registrados são um subtipo do objeto protegível FUNCTION. Para permitir acesso a um modelo registrado no Catálogo do Unity, use GRANT ON FUNCTION. Você também pode usar o Gerenciador de Catálogos para definir a propriedade e as permissões do modelo. Para obter detalhes, consulte Gerenciar privilégios no Catálogo do Unity e no modelo de objeto do Catálogo do Unity.

Você pode configurar permissões de modelo programaticamente usando a Grants REST API. Quando você configura permissões de modelo, defina securable_type como "FUNCTION" nas solicitações da API REST. Por exemplo, use PATCH /api/2.1/unity-catalog/permissions/function/{full_name} para atualizar as permissões de modelo registradas.

Exibir e gerenciar modelos na interface do usuário

Permissões necessárias: para exibir um modelo registrado e suas versões de modelo na interface do usuário, é necessário ter o privilégio EXECUTE no modelo registrado, além dos privilégios USE SCHEMA e USE CATALOG no esquema e no catálogo que contêm o modelo

Você pode exibir e gerenciar modelos registrados e versões de modelo no Catálogo do Unity usando o Catalog Explorer.

Exibir informações do modelo

Para exibir modelos no Gerenciador de Catálogos:

  1. Clique no ícone Dados.Catálogo na barra lateral.

  2. Selecione um recurso de computação na lista suspensa no canto superior direito.

  3. Na árvore do Gerenciador de Catálogos à esquerda, abra um catálogo e selecione um esquema.

  4. Se o esquema contiver modelos, eles aparecerão na árvore em Modelos, conforme mostrado.

    Seção da árvore do gerenciador de catálogos mostrando modelos.

  5. Clique em um modelo para ver mais informações. A página de detalhes do modelo mostra uma lista de versões de modelo com informações adicionais.

    página de detalhes do modelo

Definir aliases de modelo

Para definir um alias de modelo usando a interface do usuário:

  1. Na página de detalhes do modelo, passe o mouse sobre a linha da versão do modelo à qual você deseja adicionar um alias. O botão Adicionar alias é exibido.
  2. Clique em Adicionar alias.
  3. Insira um alias ou selecione um no menu suspenso. Você pode adicionar vários aliases na caixa de diálogo.
  4. Clique em Salvar aliases.

Como adicionar um alias a uma versão de modelo da página de detalhes do modelo.

Para remover um alias:

  1. Passe o mouse sobre a linha da versão do modelo e clique no ícone de lápis ao lado do alias.
  2. Na caixa de diálogo, clique no X próximo ao alias que você deseja remover.
  3. Clique em Salvar aliases.

Como remover um alias de uma versão de modelo na página de detalhes do modelo.

Exibir informações de versão do modelo e linhagem de modelo

Para exibir mais informações sobre uma versão de modelo, clique em seu nome na lista de modelos. A página de versão do modelo é exibida. Esta página inclui um link para executar a origem do MLflow que criou a versão. No MLflow 3, você também pode exibir todos os parâmetros e métricas registrados com o Modelo Registrado correspondente do MLflow.

MLflow 3

página de versão do modelo

MLflow 2.x

página de versão do modelo

Nesta página, você pode exibir a linhagem do modelo da seguinte maneira:

  1. Selecione a guia Linhagem . A barra lateral esquerda mostra os componentes que foram registrados com o modelo.

    Guia Linhagem na página de modelo no Gerenciador de Catálogos

  2. Clique em Ver grafo de linhagem. O grafo de linhagem é exibido. Para obter detalhes sobre como explorar o grafo de linhagem, consulte Capturar e explorar a linhagem.

    tela de linhagem

  3. Para fechar o grafo de linhagem, clique em botão fechar do gráfico de linhagem no canto superior direito.

Renomear um modelo

Permissões necessárias: Proprietário do modelo registrado, privilégio CREATE_MODEL no esquema que contém o modelo registrado e privilégios USE SCHEMA e USE CATALOG no esquema e no catálogo que contêm o modelo.

Para renomear um modelo registrado, use o método de API rename_registered_model() do Cliente MLflow, onde <full-model-name> está o nome completo de 3 níveis do modelo e <new-model-name> é o nome do modelo sem o catálogo ou esquema.

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

Por exemplo, o código a seguir altera o nome do modelo hello_world para hello.

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

Copiar uma versão do modelo

Você pode copiar uma versão de modelo de um modelo para outro no Catálogo do Unity.

Copiar uma versão do modelo usando a interface do usuário

Siga estas etapas:

  1. Na página da versão do modelo, clique em Copiar esta versão no canto superior direito da interface do usuário.

  2. Selecione um modelo de destino na lista suspensa e clique em Copiar.

    Caixa de diálogo Copiar a versão do modelo

A cópia de um modelo pode levar tempo. Para monitorar o progresso, navegue até o modelo de destino no Catálogo do Unity e atualize periodicamente.

Copiar uma versão do modelo usando a API

Para copiar uma versão de modelo, use a API Python copy_model_version() do MLflow:

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

Excluir um modelo ou uma versão do modelo

Permissões necessárias: Proprietário do modelo registrado, além dos privilégios USE SCHEMA e USE CATALOG no esquema e no catálogo que contêm o modelo.

Você pode excluir um modelo registrado ou uma versão de modelo em um modelo registrado usando a interface do usuário ou a API.

Aviso

Você não pode desfazer essa ação. Quando você exclui um modelo, todos os artefatos de modelo armazenados pelo Catálogo do Unity e todos os metadados associados ao modelo registrado são excluídos.

Excluir um modelo ou uma versão do modelo usando a interface do usuário

Para excluir um modelo ou uma versão de modelo no Catálogo do Unity, siga estas etapas.

  1. No Gerenciador de Catálogos, na página do modelo ou na página de versão do modelo, clique no ícone de menu Kebab no canto superior direito.

    Na página do modelo:

    menu kebab da página do modelo com exclusão

    Na página de versão do modelo:

    página da versão do modelo menu kebab com exclusão

  2. Selecione Excluir.

  3. Uma caixa de diálogo de confirmação será exibida. Clique em Excluir para confirmar.

Excluir um modelo ou uma versão do modelo usando a API

Para excluir uma versão do modelo, use o método delete_model_version() da API do Cliente MLflow:

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

Para excluir um modelo, use o método delete_registered_model() da API do Cliente MLflow:

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

Usar tags em modelos

As Marcas são pares de chave-valor associados aos modelos registrados e versões de modelo, permitindo rotulá-los e categorizá-los por função ou status. Por exemplo, você pode aplicar uma marca com chave "task" e valor "question-answering" (exibida na interface do usuário como task:question-answering) aos modelos registrados destinados a tarefas de resposta a perguntas. No nível da versão do modelo, você pode marcar versões em validação de pré-implantação com validation_status:pending e aquelas liberadas para implantação com validation_status:approved.

Permissões necessárias: proprietário de ou tem privilégio APPLY_TAG no modelo registrado, além de privilégios USE SCHEMA e USE CATALOG no esquema e catálogo que contenham o modelo.

Consulte Adicionar e atualizar marcas usando o Explorador de Catálogos para saber como definir e excluir marcas usando a interface do usuário.

Para definir e excluir tags usando a API do Cliente MLflow, consulte os exemplos abaixo.

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

As marcas do modelo e de versão do modelo registrados devem atender às restrições na plataforma.

Para obter mais detalhes sobre APIs de clientes de tags, consulte a documentação da API do MLflow.

Adicione uma descrição (comentários) a um modelo ou uma versão do modelo

Permissões necessárias: Proprietário do modelo registrado, além dos privilégios USE SCHEMA e USE CATALOG no esquema e no catálogo que contêm o modelo.

Você pode incluir uma descrição de texto para qualquer modelo ou versão de modelo no Catálogo do Unity. Por exemplo, você pode incluir uma visão geral do problema ou informações sobre a metodologia e o algoritmo usados.

Para modelos, você também tem a opção de usar comentários gerados por IA. Confira Adicionar comentários gerados por IA a objetos do Catálogo do Unity.

Adicionar uma descrição a um modelo usando a interface do usuário

Para adicionar uma descrição para um modelo, você pode usar comentários gerados por IA ou inserir seus próprios comentários. Edite os comentários gerados por IA conforme necessário.

  • Para adicionar comentários gerados automaticamente, clique no botão Gerar automaticamente.
  • Para adicionar seus próprios comentários, clique em Adicionar. Insira seus comentários na caixa de diálogo e clique em Salvar.

botões de descrição do modelo uc

Adicionar uma descrição a uma versão do modelo usando a interface do usuário

Para adicionar uma descrição a uma versão de modelo no Catálogo do Unity, siga estas etapas:

  1. Na página da versão do modelo, clique no ícone de lápis em Descrição.

    ícone de lápis para adicionar comentários a uma versão do modelo

  2. Insira seus comentários na caixa de diálogo e clique em Salvar.

Adicionar uma descrição a um modelo ou versão de modelo usando a API

Para atualizar uma descrição do modelo registrado, utilize o método da API do cliente do MLflow update_registered_model():

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

Para atualizar a descrição de uma versão do modelo, use o método update_model_version() da API do Cliente MLflow:

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

Listar e pesquisar modelos

Para obter uma lista de modelos registrados no Catálogo do Unity, use a API python search_registered_models() do MLflow:

client=MlflowClient()
client.search_registered_models()

Para pesquisar um nome de modelo específico e obter informações sobre as versões desse modelo, use search_model_versions():

from pprint import pprint

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

Observação

Nem todos os campos e operadores de API de pesquisa têm suporte para modelos no Catálogo do Unity. Confira Limitações para obter detalhes.

Baixar arquivos de modelo (caso de uso avançado)

Na maioria dos casos, para carregar modelos, você deve usar APIs do MLflow como mlflow.pyfunc.load_model ou mlflow.<flavor>.load_model (por exemplo, mlflow.transformers.load_model para modelos HuggingFace).

Em alguns casos, talvez seja necessário baixar arquivos de modelo para depurar o comportamento do modelo ou problemas de carregamento do modelo. Você pode baixar arquivos de modelo usando mlflow.artifacts.download_artifacts, da seguinte maneira:

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)

Promover um modelo entre ambientes

O Databricks recomenda que você implante pipelines de ML como código. Isso elimina a necessidade de promover modelos entre ambientes, pois todos os modelos de produção podem ser produzidos por meio de fluxos de trabalho de treinamentos automatizados em um ambiente de produção.

No entanto, em alguns casos, pode ser muito caro re-treinar os modelos em diversos ambientes. Em vez disso, você pode copiar versões de modelo em modelos registrados no Catálogo do Unity para promovê-las entre ambientes.

Você precisa ter os seguintes privilégios para executar o código de exemplo abaixo:

  • USE CATALOG nos catálogos staging e prod.
  • USE SCHEMA nos esquemas staging.ml_team e prod.ml_team.
  • EXECUTE em staging.ml_team.fraud_detection.

Além disso, você precisa ser o proprietário do modelo registrado prod.ml_team.fraud_detection.

O trecho de código a seguir usa a copy_model_versionAPI do Cliente MLflow, disponível no MLflow versão 2.8.0 e superior.

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)

Depois que a versão do modelo estiver no ambiente de produção, você poderá executar qualquer validação de pré-implantação necessária. Em seguida, marque a versão do modelo para implantação usando aliases.

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

No exemplo acima, somente os usuários que podem fazer leituras no modelo registrado staging.ml_team.fraud_detection e gravações no modelo registrado prod.ml_team.fraud_detection podem promover os modelos de preparo no ambiente de produção. Os mesmos usuários também podem usar aliases para gerenciar as versões de modelo que são implantadas no ambiente de produção. Você não precisa configurar nenhuma outra regra ou política para controlar a promoção e a implantação de modelos.

Personalize esse fluxo para promover a versão do modelo em vários ambientes que correspondem à sua configuração, como dev, qa e prod. O controle de acesso é imposto conforme configurado em cada ambiente.

Bloco de anotações de exemplo

Este notebook de exemplo ilustra como usar modelos em APIs do Catálogo do Unity para gerenciar modelos no Catálogo do Unity, incluindo o registro de modelos e versões de modelo, a adição de descrições, o carregamento e a implantação de modelos, o uso de aliases de modelo e a exclusão de modelos e versões de modelo.

MLflow 3

Modelos no notebook de exemplo do Unity Catalog para MLflow 3

Obter laptop

MLflow 2.x

Modelos no Catálogo do Unity exemplo de notebook

Obter laptop

Migrar modelos e fluxos de trabalho para o Catálogo do Unity

O Databricks recomenda usar os modelos no Catálogo do Unity para governança aprimorada, fácil compartilhamento entre os espaços de trabalho e ambientes e fluxos de trabalho MLOps mais flexíveis. A tabela compara os recursos do Registro de Modelo de Workspace e do Catálogo do Unity.

Recurso Registro do Modelo do Workspace (herdado) Modelos no Catálogo do Unity (recomendado)
Versões de modelo de referência por aliases nomeados Fases do Registro de Modelo: mover versões do modelo para uma das quatro fases fixas para referenciá-las por essa fase. Não é possível renomear ou adicionar fases. Aliases do Registro de Modelo: crie até 10 referências nomeadas personalizadas e reatribuíveis para as versões de modelo para cada modelo registrado.
Criar ambientes controlados por acesso para modelos Fases do Registro de Modelo: use fases em um modelo registrado para denotar o ambiente das suas versões de modelo, com controles de acesso para apenas dois das quatro fases fixas (Staging e Production). Modelos registrados: crie um modelo registrado para cada ambiente em seu fluxo de trabalho do MLOps, utilizando namespaces de três níveis e permissões do Catálogo do Unity para expressar governança.
Promover modelos entre ambientes (modelo de implantação) Use a API do Cliente MLflow transition_model_version_stage() para mover uma versão do modelo para uma fase diferente, potencialmente interrompendo fluxos de trabalho que fazem referência à fase anterior. Use a API do cliente MLflow copy_model_version() para copiar uma versão de modelo de um modelo registrado para outro.
Acessar e compartilhar modelos entre workspaces Exporte e importe manualmente modelos entre workspaces ou configure conexões para registros de modelo remoto usando tokens de acesso pessoal e escopos secretos do workspace. Acesso pronto para uso a modelos em workspaces na mesma conta. Não é necessária nenhuma configuração.
Configurar permissões Defina permissões no nível do workspace. Defina permissões no nível da conta, o que aplica governança consistente entre os espaços de trabalho.
Acessar modelos no marketplace do Databricks Não disponível. Carregue modelos do marketplace do Databricks no metastore do Catálogo do Unity e acesse-os nos workspaces.

Os artigos vinculados abaixo descrevem como migrar fluxos de trabalho (treinamento de modelo e trabalhos de inferência em lote) e modelos do Registro de Modelo de Workspace para o Catálogo do Unity.

Limitações

  • Não há suporte para fases de modelos no Catálogo Unity. O Databricks recomenda usar o namespace de três níveis no Catálogo do Unity para expressar o ambiente em que um modelo está e usar os aliases para promover os modelos para implantação. Confira Promover um modelo entre ambientes para obter detalhes.
  • Não há suporte para os estágios dos modelos no Catálogo do Unity. Consulte as alternativas sugeridas no guia de atualização.
  • Alguns campos e operadores de API de pesquisa não são compatíveis com os modelos no Catálogo do Unity. Isso pode ser mitigado chamando as APIs de pesquisa usando filtros com suporte e verificando os resultados. Estes são alguns exemplos:
    • O parâmetro order_by não é suportado nas APIs de cliente search_model_versions ou search_registered_models.
    • Não há suporte para filtros baseados em marca (tags.mykey = 'myvalue') para search_model_versions ou search_registered_models.
    • Operadores diferentes da igualdade exata (por exemplo, LIKE, ILIKE, !=) não têm suporte para search_model_versions ou search_registered_models.
    • Não há suporte para a pesquisa de modelos registrados por nome (por exemplo, MlflowClient().search_registered_models(filter_string="name='main.default.mymodel'")). Para buscar um modelo registrado específico por nome, use get_registered_model.
  • As notificações por email e os tópicos de discussão de comentários sobre modelos registrados e versões de modelos não são compatíveis com o Catálogo do Unity.
  • Não há suporte para o log de atividades de modelos no Unity Catalog. Para acompanhar a atividade nos modelos no Catálogo do Unity, use os logs de auditoria.
  • search_registered_models pode retornar resultados obsoletos para modelos compartilhados por meio do Compartilhamento Delta. Para garantir os resultados mais recentes, use a CLI ou o SDK do Databricks para listar os modelos em um esquema.