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

Este artigo descreve como usar modelos no catálogo Unity como parte do 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 MLflow Model Registry no Unity Catalog. Os modelos no Unity Catalog estendem os benefícios do Unity Catalog aos modelos de ML, incluindo controle de acesso centralizado, auditoria, linhagem e descoberta de modelos em espaços de trabalho. Models in Unity Catalog é compatível com o cliente Python MLflow de código aberto.

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

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

Requisitos

• O Catálogo Unity deve estar habilitado em seu espaço de trabalho. Consulte Introdução ao uso do Unity Catalog para criar um Unity Catalog Metastore, habilitá-lo em um espaço de trabalho e criar um catálogo. Se o Unity Catalog não estiver habilitado, use o registro do modelo de espaço de trabalho.

• Você deve usar um recurso de computação que tenha acesso ao Catálogo Unity. Para cargas de trabalho de ML, isso significa que o modo de acesso da computação deve ser Dedicado (anteriormente usuário único). Para obter mais informações, consulte 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.

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

  • USE SCHEMA e USE CATALOG privilégios no esquema e o catálogo que o contém.
  • CREATE MODEL ou CREATE FUNCTION privilégio 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>
  

• Se você tiver problemas de autorização ao tentar registrar um modelo, tente definir a variável MLFLOW_USE_DATABRICKS_SDK_MODEL_ARTIFACTS_REPO_FOR_UC de ambiente como True. Inclua uma célula no seu bloco de notas com o seguinte código:

  import os
  os.environ['MLFLOW_USE_DATABRICKS_SDK_MODEL_ARTIFACTS_REPO_FOR_UC'] = 'True'
  

  Essa abordagem não pode ser usada para modelos compartilhados com o Delta Sharing que usam armazenamento padrão.

Instalar e configurar o cliente MLflow para o Unity Catalog

Esta seção inclui instruções para instalar e configurar o cliente MLflow para o Unity Catalog.

Instalar o cliente Python MLflow

O suporte para modelos no Unity Catalog está incluído no Databricks Runtime 13.2 ML e superior (Databricks Runtime 15.0 ML e superior no Azure China).

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

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

Configurar o cliente MLflow para acessar modelos no Unity Catalog

Se o catálogo padrão do seu espaço de trabalho estiver no Unity Catalog (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 a partir do catálogo padrão.

Para outros espaços de trabalho, o cliente Python MLflow cria modelos no registro do modelo de espaço de trabalho Databricks. Para atualizar para modelos no Unity Catalog, use o seguinte código em seus blocos de anotações para configurar o cliente MLflow:

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

Para um pequeno número de espaços de trabalho em que o catálogo padrão foi configurado para um catálogo no Unity Catalog antes de janeiro de 2024 e o registro do modelo de espaço de trabalho foi usado antes de janeiro de 2024, você deve definir manualmente o catálogo padrão como Unity Catalog usando o comando mostrado acima.

Treine e registre modelos compatíveis com o Unity Catalog

Permissões necessárias: para criar um novo modelo registado, necessita dos privilégios CREATE MODEL e USE SCHEMA no esquema envolvente, e do privilégio USE CATALOG no catálogo envolvente. Para criar novas versões de modelo em um modelo registrado, você deve ser o proprietário do modelo registrado e ter privilégios de USE SCHEMA e USE CATALOG no esquema e catálogo que contém o modelo.

Se você tiver problemas de autorização ao tentar registrar um modelo, tente definir a variável MLFLOW_USE_DATABRICKS_SDK_MODEL_ARTIFACTS_REPO_FOR_UC de ambiente como True. Essa abordagem não pode ser usada para modelos compartilhados com o Delta Sharing que usam armazenamento padrão. Consulte Requisitos.

As novas versões de modelo de ML na UC devem ter uma assinatura de modelo. Se você ainda não estiver registrando modelos MLflow com assinaturas em suas cargas de trabalho de treinamento de modelo, poderá:

• Use o registro automático do Databricks, que registra automaticamente modelos com assinaturas para muitas estruturas de ML populares. Consulte as estruturas suportadas nos documentos MLflow.
• Com o MLflow 2.5.0 e superior, você pode especificar um exemplo de entrada em sua mlflow.<flavor>.log_model chamada e a assinatura do modelo é automaticamente inferida. Para obter mais informações, consulte a documentação do MLflow.

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

As versões de modelo que não têm assinaturas têm certas limitações. Para obter uma lista dessas limitações e para adicionar ou atualizar uma assinatura para uma versão de modelo existente, consulte Adicionar ou atualizar uma assinatura para uma versão de modelo existente.

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

Os exemplos de treinamento de modelo nesta seção criam uma nova versão do modelo e a registram no catálogo prod. 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, o esquema e o modelo registado da versão do modelo refletem o seu ambiente (prod) e as regras de governança associadas (por exemplo, os privilégios podem ser configurados para que somente os administradores possam excluir do catálogo prod), mas não o seu estado de implementação. Para gerenciar o status da implantação, use aliases de modelo.

Registrar um modelo no Unity Catalog usando o registro automático

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

Registar um modelo com 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 Unity Catalog com assinatura inferida automaticamente

O suporte para assinaturas inferidas automaticamente está disponível no MLflow versão 2.5.0 e superior, e é suportado no Databricks Runtime 11.3 LTS ML e superior. Para usar assinaturas inferidas automaticamente, use o código a seguir para instalar o cliente Python MLflow mais recente em seu bloco de anotações:

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

O código a seguir mostra um exemplo de uma assinatura automaticamente inferida. Observe que usar registered_model_namelog_model() na chamada registra o modelo no Unity Catalog, portanto, você deve fornecer o nome completo de três níveis do modelo no formato <catalog>.<schema>.<model>.

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,
        # Use three-level name to register model in Unity Catalog.
        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,
        # Use three-level name to register model in Unity Catalog.
        registered_model_name="prod.ml_team.iris_model",
    )

Registrar um modelo usando a interface do usuário

Siga estes passos:

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 Unity Catalog e selecione um modelo de destino na lista suspensa.

   Janela de diálogo de registo da versão do modelo com menu suspenso

3. Clique em Registrar.

   

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

Adicionar ou atualizar uma assinatura para uma versão de modelo existente

As versões de modelo que não têm assinaturas têm as seguintes limitações:

• Se uma assinatura for fornecida, as entradas do modelo serão verificadas na inferência e um erro será relatado se as entradas não corresponderem à assinatura. Sem uma assinatura, não há imposição automática de entrada, e os modelos precisam ser capazes de lidar com entradas inesperadas.
• Usar uma versão de modelo com funções de IA requer fornecer um esquema na chamada de função.
• O uso de uma versão de modelo com o Model Serving não gera automaticamente exemplos de entrada.

Para adicionar ou atualizar uma assinatura de versão do modelo, consulte a documentação do MLflow.

Usar pseudónimos de modelo

Os aliases de modelo permitem atribuir 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 "Campeão" para a versão do modelo atualmente em produção e direcionar esse alias em cargas de trabalho que usam o modelo de produção. Em seguida, você pode atualizar o modelo de produção reatribuindo o alias "Campeão" a uma versão diferente do modelo.

Definir e excluir aliases em modelos

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

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

Para definir, atualizar e excluir aliases usando a API do cliente 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 MLflow.

Carregar versão do modelo por meio de alias para cargas de trabalho de inferência

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

As cargas de trabalho de inferência em lote podem fazer referência a uma versão do modelo por alcunha. O trecho abaixo carrega e aplica a versão do modelo "Campeão" 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 implantações de modelo de suas 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 endpoints de um modelo também podem fazer referência a uma versão do modelo por meio de um alias. Você pode criar fluxos de trabalho de implantação para obter uma versão do modelo por alias e atualizar um ponto de extremidade de serviço para servir essa versão, usando a API REST de serviço de modelos. 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 versão do modelo por número de versão para cargas de trabalho de inferência

Você também pode carregar versões do modelo 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)

Partilhar modelos entre áreas de trabalho

Compartilhar modelos com usuários na mesma região

Contanto que você tenha os privilégios apropriados, você pode acessar modelos no Unity Catalog a partir de qualquer espaço de trabalho anexado ao metastore que contém o modelo. Por exemplo, você pode acessar modelos do catálogo de 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 que você criou, você deve conceder a propriedade do modelo a um grupo que contenha você mesmo e os usuários com quem você gostaria de colaborar. Os colaboradores também devem ter os privilégios de USE CATALOG e USE SCHEMA no catálogo e esquema que contém o modelo. Consulte Privilégios do catálogo Unity e objetos protegíveis 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 Delta Sharing Databricks-to-Databricks. Consulte Adicionar modelos a um compartilhamento (para provedores) e Obter acesso no modelo Databricks-to-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 Unity Catalog.

Rastrear a linhagem de dados de um modelo no Unity Catalog

Ao treinar um modelo em uma tabela no Unity Catalog, você pode rastrear a linhagem do modelo para o(s) conjunto(s) 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 para modelos registados usando APIs de feature store. Consulte Governança e linhagem de funcionalidades.

Quando você registra o modelo no Catálogo 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 Catalog Explorer. Consulte Exibir informações sobre a versão do modelo e a linhagem do modelo.

O código seguinte 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,
        # Use three-level name to register model in Unity Catalog.
        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,
        # Use three-level name to register model in Unity Catalog.
        registered_model_name="prod.ml_team.iris_classifier",
    )

Controlar o acesso aos modelos

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

Você pode configurar permissões de modelo programaticamente usando a API REST do Grants. Ao configurar permissões de modelo, defina securable_type como "FUNCTION" em solicitações de API REST. Por exemplo, use PATCH /api/2.1/unity-catalog/permissions/function/{full_name} para atualizar permissões de modelo registrado.

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, você precisa de EXECUTE privilégios no modelo registrado, além USE SCHEMAUSE CATALOG de privilégios no esquema e no catálogo que contém o modelo

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

Ver informações do modelo

Para exibir modelos no Gerenciador de Catálogos:

1. Clique no Catálogo na barra lateral.

2. Selecione um recurso de computação a partir da lista suspensa localizada no canto superior direito.

3. Na árvore do Catalog Explorer à esquerda, abra um catálogo e selecione um esquema.

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

   

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

   

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 apelido ou selecione um no menu suspenso. Você pode adicionar vários aliases na caixa de diálogo.
4. Clique em Salvar aliases.

Para remover um alias:

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

Ver informações sobre a versão do modelo e a linhagem do modelo

Para exibir mais informações sobre uma versão do modelo, clique em seu nome na lista de modelos. A página da versão do modelo é exibida. Esta página inclui um link para a execução original 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 MLflow correspondente.

MLflow 3

MLflow 2.x

Nesta página, você pode visualizar 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.

   

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

   

3. Para fechar o gráfico de linhagem, clique no no canto superior direito.

Renomear um modelo

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

Para renomear um modelo registrado, use o método MLflow Client API rename_registered_model() , onde <full-model-name> é 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 do modelo de um modelo para outro no Catálogo Unity.

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

Siga estes passos:

1. Na página 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.

   

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

Copiar uma versão do modelo usando a API

Para copiar uma versão do 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>",
)

Eliminar um modelo ou versão de modelo

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

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

Eliminar uma versão do modelo ou modelo usando a interface de utilizador

Para excluir um modelo ou uma versão do modelo no Unity Catalog, siga estas etapas.

1. No Catalog Explorer, na página do modelo ou na página da versão do modelo, clique no no canto superior direito.

   Na página do modelo:

   

   Na página da versão do modelo:

   

2. Selecione Excluir.

3. É apresentado um diálogo de confirmação. Clique em Excluir para confirmar.

Eliminar uma versão de modelo ou modelo usando a API

Para eliminar uma versão de modelo, utilize o método delete_model_version() da API do Cliente do 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 eliminar um modelo, utilize o método delete_registered_model() da API do Cliente do MLflow:

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

Usar tags em modelos

As tags são pares chave-valor que você associa a modelos registrados e versões de modelos, permitindo que você os rotule e categorize por função ou status. Por exemplo, você pode aplicar uma tag com chave "task" e valor "question-answering" (exibido na interface do usuário como task:question-answering) a modelos registrados destinados a tarefas de resposta a perguntas. No nível da versão do modelo, você pode marcar as versões que estão passando pela validação pré-implantação com validation_status:pending e as liberadas para implantação com validation_status:approved.

Permissões necessárias: Proprietário ou com APPLY TAG privilégio no modelo registrado, além USE SCHEMA de privilégios USE CATALOG no esquema e no catálogo que contém o modelo.

Consulte Aplicar tags a objetos protegíveis do Unity Catalog para saber como definir e excluir tags 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")

Tanto o modelo registrado quanto as tags de versão do modelo devem atender às restrições de toda a plataforma.

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

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

Permissões necessárias: Proprietário do modelo registrado, mais USE SCHEMA e USE CATALOG privilégios no esquema e 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 Unity. Por exemplo, você pode fornecer 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. Consulte Adicionar comentários gerados por IA a objetos do Catálogo 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. Você pode editar comentários gerados por IA conforme necessário.

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

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 do modelo no Unity Catalog, siga estas etapas:

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

   

2. Introduza os seus comentários na caixa de diálogo e clique em Guardar.

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

Para atualizar uma descrição de modelo registrado, use o método MLflow Client API update_registered_model():

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

Para atualizar a descrição da versão de um modelo, use o método update_model_version() da API Client do MLflow.

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

Lista e modelos de pesquisa

Para obter uma lista de modelos registrados no Unity Catalog, use a API Python search_registered_models() do MLflow:

mlflow.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

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

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

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

Em alguns casos, pode ser 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 forma:

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)

Promova um modelo em todos os ambientes

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

No entanto, em alguns casos, pode ser muito caro reeducar os modelos em diferentes ambientes. Em vez disso, você pode copiar versões de modelos entre modelos registrados no Unity Catalog para promovê-los em todos os ambientes.

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

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

Além disso, você deve ser o proprietário do modelo prod.ml_team.fraud_detectionregistrado.

O trecho de código a seguir usa a API do copy_model_versioncliente 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 pré-implantação necessária. Em seguida, você pode marcar 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, apenas os utilizadores que podem ler do modelo registado staging.ml_team.fraud_detection e escrever no modelo registado prod.ml_team.fraud_detection podem promover modelos de ensaio para o ambiente de produção. Os mesmos usuários também podem usar aliases para gerenciar quais versões de modelo são implantadas no ambiente de produção. Não é necessário configurar outras regras ou políticas para governar a promoção e a implantação do modelo.

Você pode personalizar esse fluxo para promover a versão do modelo em vários ambientes que correspondam à sua configuração, como dev, qae prod. O controle de acesso é imposto conforme configurado em cada ambiente.

Exemplo de bloco de notas

Este bloco de anotações de exemplo ilustra como usar Modelos nas APIs do Unity Catalog para gerenciar modelos no Unity Catalog, incluindo o registro de modelos e versões de modelos, 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 modelos.

MLflow 3

Modelos no bloco de anotações de exemplo do Unity Catalog para MLflow 3

Obter caderno

MLflow 2.x

Modelos no bloco de anotações de exemplo do Unity Catalog

Obter caderno

Limitações

• Os estágios não são suportados para modelos no Unity Catalog. O Databricks recomenda o uso do namespace de três níveis no Unity Catalog para expressar o ambiente em que um modelo está e o uso de aliases para promover modelos para implantação. Consulte Promover um modelo entre ambientes para obter detalhes.
• Webhooks não são suportados para modelos no Unity Catalog. Consulte as alternativas sugeridas no guia de atualização.
• Alguns campos e operadores de API de pesquisa não são suportados para modelos no Unity Catalog. Isso pode ser atenuado chamando as APIs de pesquisa usando filtros suportados e verificando os resultados. Seguem-se alguns exemplos:
  • O parâmetro order_by não é suportado nas APIs de cliente search_model_versions ou search_registered_models.
  • Filtros baseados em tags (tags.mykey = 'myvalue') não são suportados para search_model_versions ou search_registered_models.
  • Operadores diferentes da igualdade exata (por exemplo, LIKE, ILIKE, !=) não são suportados para search_model_versions ou search_registered_models.
  • A pesquisa de modelos registados pelo nome (por exemplo, search_registered_models(filter_string="name='main.default.mymodel'") não é suportada. Para buscar um determinado modelo registrado pelo nome, use get_registered_model.
• As notificações por e-mail e os tópicos de discussão de comentários sobre modelos registados e as suas versões não são suportados no Catálogo Unity.
• O log de atividades não é suportado para modelos no Unity Catalog. Para monitorizar a atividade em modelos no Unity Catalog, utilize logs de auditoria.
• search_registered_models pode retornar resultados obsoletos para modelos compartilhados por meio do Delta Sharing. Para garantir os resultados mais recentes, utilize a CLI do Databricks ou o SDK para listar os modelos em um esquema.