Gerencie o ciclo de vida do modelo no Unity Catalog

Importante

Este artigo descreve como usar modelos no Unity Catalog como parte de seu workflow do machine learning para gerenciar todo o ciclo de vida dos modelos de ML. 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 no workspace. Os modelos no Unity Catalog são compatíveis com o cliente MLflow Python de código aberto.

key recursos dos modelos no Unity Catalog incluem:

  • Espaçamento entre nomes e governança para modelos, para que você possa agrupar e governar modelos no nível de ambiente, projeto ou equipe ("Conceder aos cientistas de dados acesso somente leitura aos modelos de produção").

  • Linhagem do modelo cronológico (qual experimento e execução do MLflow produziu o modelo em um determinado momento).

  • Servir modelo.

  • Versionamento de modelo.

  • Implementação de modelo por meio de aliases. Por exemplo, marque a versão “Campeã” de um modelo em seu catálogo prod .

Se o workspace default catálogo do seu estiver configurado para um catálogo no Unity Catalog, os modelos registrados usando APIs MLflow, como mlflow.<model-type>.log_model(..., registered_model_name) ou ,mlflow.register_model(model_uri, name) serão registrados Unity Catalog defaultno por .

Este artigo inclui instruções para os modelos na interface de usuário e na API do Unity Catalog.

Para obter uma visão geral dos conceitos do Model Registry, consulte Gerenciamento do ciclo de vida de ML usando MLflow.

Requisitos

  1. Unity Catalog deve estar habilitado em seu workspace. Consulte Começar a usar o Unity Catalog para criar um metastore de catálogo do Unity, habilitá-lo em um espaço de trabalho e criar um catálogo. Se Unity Catalog não estiver habilitado, você ainda poderá usar o espaço de trabalho clássico registro de modelo.

  2. Seu workspace deve estar conectado a um metastore do Unity Catalog que ofereça suporte à herança de privilégios. Isso vale para todas as metastores criadas após 25 de agosto de 2022. Se estiver sendo executado em um metastore mais antigo, siga os documentos para atualizar.

  3. Você deve ter acesso para executar comandos em um cluster com acesso ao Unity Catalog.

  4. Para criar novos modelos registrados, você precisa do privilégio CREATE_MODEL em um esquema, além dos privilégios USE SCHEMA e USE CATALOG no esquema e em seu catálogo anexo. CREATE_MODEL é um novo privilégio em nível de esquema que você pode conceder usando a UI do Catalog Explorer ou o comando SQL GRANT, conforme mostrado abaixo.

    GRANT CREATE_MODEL ON SCHEMA <schema-name> TO <principal>

Atualize as cargas de trabalho de treinamento para o Unity Catalog

Esta seção contém instruções para atualizar cargas de trabalho de treinamento existentes para o Unity Catalog.

Instale o cliente MLflow Python

O suporte para modelos no Unity Catalog está incluído no Databricks Runtime 13.2 MLe acima.

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

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

Configurar o cliente MLflow para acessar modelos no Unity Catalog

Por padrão, o cliente MLflow Python cria modelos no modelo de registro do workspace do Databricks. Para atualizar para modelos no Unity Catalog, configure o cliente MLflow:

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

Observação

Se workspace o catálogo padrão do seu estiver no Unity Catalog (em vez de hive_metastore) e você estiver executando clusters usando o Databricks Runtime 13.3 LTS ou acima, os modelos serão criados e carregados automaticamente no catálogo padrão, sem necessidade de configuração. Não há alteração no comportamento para outras versões do Databricks Runtime. Um pequeno número de espaços de trabalho em que o catálogo default foi configurado para um catálogo no Unity Catalog antes de janeiro de 2024 e o workspace registro de modelo foi usado antes de janeiro de 2024 estão isentos desse comportamento.

Treinar e registrar modelos compatíveis com o Unity Catalog

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

As versões do modelo ML no UC devem ter uma assinatura de modelo. Se você ainda não está registrando modelos MLflow com assinaturas em suas cargas de trabalho de treinamento de modelos, você pode optar por:

  • Use o autologging do Databricks, que modela automaticamente o log com assinaturas para muitas estruturas de ML populares. Consulte as estruturas suportadas na documentação do MLflow.

  • Com o MLflow 2.5.0e acima, você pode especificar um exemplo de entrada na sua chamada mlflow.<flavor>.log_model, 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>.

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

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

Registrar um modelo no Unity Catalog usando autologging 

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

Registre um modelo no Unity Catalog com assinatura inferida automaticamente

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

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

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

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

Rastrear a linhagem de dados de um modelo no Unity Catalog

Observação

O suporte à tabela para modelar a linhagem no Unity Catalog está disponível no MLflow 2.11.0 e acima.

Ao ensinar um modelo em uma tabela no Unity Catalog, o senhor pode rastrear a linhagem do modelo até o(s) dataset(s) upstream em que ele foi treinado e avaliado. Para fazer isso, use mlflow.logs. 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 registros de modelos usando APIs de repositório de recursos. Consulte view repositório de recursos lineage.

Quando o senhor registra o modelo no Unity Catalog, as informações de linhagem são salvas automaticamente e ficam visíveis no Lineage tab da interface do usuário da versão do modelo no Catalog Explorer.

O código a seguir mostra um exemplo.

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

Exibir modelos na UI

Permissões necessárias: para visualizar um modelo registrado e suas versões de modelo na UI, você precisa de privilégio EXECUTE no modelo registrado, além de privilégios USE SCHEMA e USE CATALOG no esquema e catálogo que contém o modelo

Você pode view e gerenciar modelos registrados e versões de modelos no Unity Catalog usando o Catalog Explorer.

Controlar o acesso aos modelos

Para obter informações sobre como controlar o acesso a modelos registrados no Unity Catalog, consulte Privilégios e objetos protegíveisUnity Catalog . Para obter as melhores práticas de organização de modelos em catálogos e esquemas, consulte Organize seus dados.

Você pode configurar as permissões do modelo de forma programática utilizando a API REST do Grants. Ao configurar permissões de modelo, configure securable_type com "FUNCTION" em pedidos da API REST. Por exemplo, utilize o PATCH /api/2.1/unity-catalog/permissions/function/{full_name} para atualizar as permissões de modelo registradas.

implantar e organizar modelos com aliases e tags

Aliases e tags de modelo ajudam a organizar e gerenciar modelos no Unity Catalog.

Os aliases de modelo permitem atribuir uma referência nomeada e mutável a uma versão específica de um modelo registrado. Você pode usar aliases para indicar o status de implementação de uma versão de modelo. Por exemplo, você poderia alocar um alias “Champion” 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. Você pode então atualizar o modelo de produção reatribuindo o alias “Champion” a uma versão de modelo diferente.

Tags são valores- keypar que você associa a modelos registrados e versões de modelos, permitindo rotulá-los e categorizá-los por função ou status. Por exemplo, você pode aplicar tags com key "task" e valor "question-answering" (exibido na UI como task:question-answering) a modelos registrados destinados a tarefas de resposta a perguntas. No nível da versão do modelo, você pode tags versões que passam por validação de pré-implantação com validation_status:pending e aquelas liberadas para implantação com validation_status:approved.

Consulte as seções a seguir para saber como usar aliases e tags.

Definir e excluir aliases em modelos

Permissões necessárias: proprietário do modelo registrado, além de 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 de modelos no Unity Catalog usando o Catalog Explorer. Você pode gerenciar aliases em um modelo registrado na página de detalhes do modelo e configurar aliases para uma versão de modelo específica na página de detalhes da versão do modelo.

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

Definir e excluir tags em modelos

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

Consulte gerenciar tags no Catalog Explorer para saber como configurar e excluir tags usando a UI.

Para definir e excluir tags usando a API do cliente MLflow, veja 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 clientes de tags e alias, consulte a documentação da API MLflow.

Carregar modelos para inferência

Faça uso de versões de modelos através de alias em cargas de trabalho de inferência

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

Você pode escrever cargas de trabalho de inferência em lote que referenciam uma versão de modelo por alias. Por exemplo, o trecho abaixo carrega e aplica a versão do modelo "Campeão" para inferência em lote.Se a versão "Campeão" for atualizada para fazer referência a uma nova versão do modelo, a carga de trabalho de inferência em lote a captura automaticamente em sua próxima execução.Isso permite dissociar implantações de modelo 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)

Você também pode escrever o fluxo de trabalho de implantação para obter uma versão do modelo por alias e atualizar um endpoint de servidor de modelo para atender a essa versão, usando a API REST de servidor de modelo:

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

Faça uso de versões de modelo por número de versão em cargas de trabalho de inferência

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

Compartilhe modelos entre workspaces

Compartilhe modelos com usuários da mesma região

Desde que tenha os privilégios adequados, o senhor pode acessar os modelos em Unity Catalog de qualquer workspace que esteja anexado ao metastore que contém o modelo. Por exemplo, o senhor pode acessar modelos do catálogo prod em um dev workspace, 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, é necessário conceder a propriedade do modelo a um grupo que contenha você e os usuários com os quais gostaria de colaborar. Os colaboradores também devem ter os USE SCHEMA privilégios USE CATALOG e no catálogo e no esquema que contém o modelo. Para obter detalhes, consulte Privilégios e objetos protegíveis do Unity Catalog.

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

Para compartilhar modelos com usuários de 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, o senhor acessa os modelos desse catálogo compartilhado da mesma forma que qualquer outro modelo no Unity Catalog.

Anotar um modelo ou uma versão de modelo

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

Você pode fornecer informações sobre um modelo ou versão do modelo anotá-lo. Por exemplo, convém incluir uma visão geral do problema ou informações sobre a metodologia e o algoritmo usados.

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

Consulte Dados do documento no Catalog Explorer usando comentários de redução.

Anote um modelo ou versão do modelo usando a API

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

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 API do cliente MLflow update_model_version():

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

Renomear um modelo (somente API)

Permissões exigidas: proprietário do modelo registrado, privilégio do CREATE_MODEL no esquema contendo o modelo registrado e privilégios do USE SCHEMA e USE CATALOG no esquema e catálogo contendo o modelo.

Para renomear um modelo registrado, use o método MLflow Client API rename_registered_model():

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

Excluir um modelo ou versão do modelo

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

É possível excluir um modelo registrado ou uma versão de modelo dentro de um modelo registrado usando a UI do Catalog Explorer ou a API.

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

Aviso

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

Excluir uma versão do modelo

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)

Excluir um modelo

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

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

Lista e modelos de pesquisa

Você pode listar modelos registrados no Unity Catalog com a API Python search_registered_models() do MLflow:

client=MlflowClient()
client.search_registered_models()

Você também pode pesquisar o nome de um modelo específico e listar os detalhes da versão usando o método search_model_versions() :

from pprint import pprint

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

Exemplo

"Este exemplo ilustra como usar Modelos no Unity Catalog para criar uma aplicação de machine learning.

Exemplo de modelos no Unity Catalog

Migrar workflows e modelos para o Unity Catalog

A Databricks recomenda o uso de modelos no Unity Catalog para melhorar a governança, facilitar o compartilhamento entre workspace e ambientes e fluxo de trabalho de MLOps mais flexível. A tabela compara os recursos do Workspace Model Registry e do Unity Catalog.

Capacidade

Workspace Model Registry (legado)

Modelos no Unity Catalog (recomendado)

Versões de modelo de referência por aliases nomeados

Estágios Model Registry : mova as versões do modelo para um dos quatro estágios fixos para referenciá-las nesse estágio. Não é possível renomear ou adicionar estágios.

Aliases Model Registry : crie até 10 referências nomeadas personalizadas e reatribuíveis para versões de modelo para cada modelo registrado.

Crie ambientes com acesso controlado para modelos

Estágios Model Registry : Use estágios dentro de um modelo registrado para denotar o ambiente de suas versões de modelo, com controles de acesso para apenas dois dos quatro estágios fixos (Staging e Production).

Modelos registrados: crie um modelo registrado para cada ambiente em seu fluxo de trabalho MLOps, utilizando namespaces de três níveis e permissões do Unity Catalog para expressar governança.

Promover modelos em todos os ambientes (modelo implantado)

Use a transition_model_version_stage() API MLflow Client para mover uma versão do modelo para um estágio diferente, potencialmente interrompendo o fluxo de trabalho que faz referência ao estágio anterior.

Use a copy_model_version() API MLflow Client para copiar uma versão de modelo de um modelo registrado para outro.

Acesse e compartilhe modelos no workspace

Exporte e importe modelos manualmente no workspace ou configure conexões com registros de modelos remotos usando pessoal access token e workspace Secret Scope.

Acesso imediato a modelos no workspace na mesma account. Nenhuma configuração necessária.

Configurar permissões

Defina permissões no nível do workspace .

Defina permissões no nível da account , o que aplica governança consistente em todo workspace.

Acessar modelos no markplace do Databricks

Indisponível.

Carregue modelos do marketplace Databricks em seu metastore do Unity Catalog e acesse-os no workspace.

Os artigos vinculados abaixo descrevem como migrar fluxo de trabalho (treinamento de modelo e Job de inferência de lotes) e modelos do Workspace Model Registry para o Unity Catalog.

Limitações no suporte do Unity Catalog

  • Os estágios não são suportados para modelos no Unity Catalog. A 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 o guia de upgrade para obter detalhes.

  • Os webhooks não são compatíveis com os modelos do Unity Catalog. Veja as alternativas sugeridas no guia de upgrade.

  • Alguns campos e operadores da API de pesquisa não são compatíveis com modelos no Unity Catalog. Isso pode ser mitigado chamando-se as APIs de pesquisa com filtros compatíveis e examinando os resultados. Veja a seguir alguns exemplos:

    • O parâmetro order_by não é suportado pelas 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 de igualdade exata (por exemplo, LIKE, ILIKE, !=) não são suportados em search_model_versions ou search_registered_models.

    • A pesquisa de modelos registrados por nome (por exemplo, não MlflowClient().search_registered_models(filter_string="name='main.default.mymodel'") é suportada). Para buscar um modelo registrado específico pelo nome, use get_registered_model.

  • Notificações por e-mail e tópicos de discussão de comentários em modelos registrados e versões de modelo não são suportados no Catálogo Unity.

  • Os logs de atividades não são compatíveis com modelos no Unity Catalog. No entanto, você pode rastrear atividades em modelos no Unity Catalog usando logs de auditoria.

  • search_registered_models pode retornar resultados desatualizados para modelos compartilhados por meio do Delta Sharing. Para garantir os resultados mais recentes, use a CLI ou o SDK da Databricks para listar os modelos em um esquema.