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

  • Artigo

Importante

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.

As principais características dos modelos no Catálogo Unity incluem:

  • Nomespacing 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 de modelo cronológico (que o experimento MLflow e executa produziu o modelo em um determinado momento).
  • Porção modelo.
  • Controle de versão do modelo.
  • Implantação de modelo por meio de aliases. Por exemplo, marque a versão "Campeão" de um modelo no seu prod catálogo.

Se o catálogo padrão do seu espaço de trabalho 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) estão registrados no Unity Catalog por padrão.

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

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

Requisitos

  1. 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, você ainda poderá usar o registro do modelo de espaço de trabalho clássico.

  2. Seu espaço de trabalho deve ser anexado a um metastore do Unity Catalog que ofereça suporte à herança de privilégios. Isso vale para todos os metastores criados 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 CREATE_MODEL privilégio em um esquema, além dos USE SCHEMA privilégios e USE CATALOG no esquema e seu catálogo anexo. CREATE_MODEL é um novo privilégio de nível de esquema que você pode conceder usando a interface do usuário do Catalog Explorer ou o comando SQL GRANT, conforme mostrado abaixo.

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

Atualize cargas de trabalho de treinamento para o Catálogo Unity

Esta seção inclui instruções para atualizar cargas de trabalho de treinamento existentes para o Catálogo Unity.

Instalar o cliente Python MLflow

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 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 Python MLflow cria modelos no registro do modelo de espaço de trabalho Databricks. Para atualizar para modelos no Unity Catalog, configure o cliente MLflow:

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

Nota

Se o catálogo padrão do seu espaço de trabalho estiver no Catálogo 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), os modelos serão criados e carregados automaticamente a partir do catálogo padrão, sem necessidade de configuração. Não há nenhuma 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 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 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 CREATE_MODEL privilégios e USE SCHEMA no esquema de anexação e USE CATALOG privilégio no catálogo que o anexa. Para criar novas versões de modelo em um modelo registrado, você deve ser o proprietário do modelo registrado e ter USE SCHEMA privilégios USE CATALOG no esquema e catálogo que contém o modelo.

As versões do 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>.

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

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, o esquema e o 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 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 Unity Catalog usando o registro automático

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

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

Controlar a linhagem de dados de um modelo no Unity Catalog

Nota

O suporte para linhagem de tabela a modelo no Unity Catalog está disponível no MLflow 2.11.0 e superior.

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 MLflow que gerou o modelo. A linhagem de dados também é capturada automaticamente para modelos registrados usando APIs de armazenamento de recursos. Consulte Ver linhagem da loja 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 da interface do usuário da versão do modelo no Catalog Explorer.

O código seguinte 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 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.

Controlar o acesso aos modelos

Para obter informações sobre como controlar o acesso a modelos registrados no Unity Catalog, consulte Privilégios do Unity Catalog e objetos protegíveis. Para obter práticas recomendadas sobre como organizar modelos entre catálogos e esquemas, consulte Organizar seus dados.

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.

Implantar e organizar modelos com aliases e tags

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

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.

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.

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, 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. Você pode gerenciar aliases em um modelo registrado na página de detalhes do modelo e configurar aliases para uma versão específica do modelo na página de detalhes da versão do modelo.

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

Definir e excluir tags em modelos

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 Gerenciar tags no Catalog Explorer sobre 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 alias e tags, consulte a documentação da API MLflow.

Modelos de carga para inferência

Consumir versões de modelo por alias em 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.

Você pode escrever cargas de trabalho de inferência em lote que fazem referência a uma versão do 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 "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)

Você também pode escrever fluxos de trabalho de implantação para obter uma versão do modelo por alias e atualizar um ponto de extremidade de serviço de modelo para servir essa versão, usando o modelo que serve a API REST:

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

Consumir versões de modelo por número de versão em 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 prod catálogo 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 USE CATALOG privilégios 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.

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

Pode fornecer informações sobre um modelo ou versão de modelo ao anotá-la. Por exemplo, talvez queira incluir uma descrição geral do problema ou informações sobre a metodologia e o algoritmo utilizados.

Anotar um modelo ou versão de modelo com a IU

Consulte Dados do documento no Gerenciador de Catálogos usando comentários de marcação.

Anotar um modelo ou uma 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 uma descrição da versão do modelo, utilize o método update_model_version() da API do Cliente do MLflow:

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

Mudar o nome de um modelo (apenas API)

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 mudar o nome de um modelo registado, utilize o método rename_registered_model() da API do Cliente do MLflow:

client=MlflowClient()
client.rename_registered_model("<model-name>", "<new-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 do Catalog Explorer ou a API.

Eliminar um modelo ou versão de modelo com a API

Aviso

Não é possível desfazer essa 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.

Eliminar uma versão de modelo

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)

Eliminar um modelo

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

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 um nome de modelo específico e listar seus detalhes de versão usando o search_model_versions() método:

from pprint import pprint

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

Exemplo

Este exemplo ilustra como usar Models no Unity Catalog para criar um aplicativo de aprendizado de máquina.

Exemplo de modelos no Unity Catalog

Migrar fluxos de trabalho 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 espaços de trabalho e ambientes e fluxos de trabalho MLOps mais flexíveis. A tabela compara os recursos do Registro do Modelo de Espaço de Trabalho e do Catálogo Unity.

Funcionalidade Registro de modelo de espaço de trabalho (legado) Modelos no catálogo Unity (recomendado)
Versões de modelo de referência por aliases nomeados Estágios do Registro do Modelo: mova as versões do modelo para um dos quatro estágios fixos para fazer referência a eles por esse estágio. Não é possível renomear ou adicionar estágios. Aliases do Registro do Modelo: crie até 10 referências nomeadas personalizadas e reatribuíveis às versões do modelo para cada modelo registrado.
Crie ambientes de acesso controlado para modelos Estágios do Registro do Modelo: 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 a governança.
Promover modelos entre ambientes (implantar modelo) Use a API do cliente MLflow para mover uma versão do transition_model_version_stage() modelo para um estágio diferente, potencialmente quebrando fluxos de trabalho que fazem referência ao estágio anterior. Use a API do copy_model_version() cliente MLflow para copiar uma versão do modelo de um modelo registrado para outro.
Acessar e compartilhar modelos entre espaços de trabalho Exporte e importe manualmente modelos entre espaços de trabalho ou configure conexões com registros de modelos remotos usando tokens de acesso pessoal e escopos secretos de espaço de trabalho. Acesso imediato a modelos em espaços de trabalho na mesma conta. Nenhuma configuração necessária.
Configurar permissões Defina permissões no nível do espaço de trabalho. Defina permissões no nível da conta, que aplica governança consistente entre espaços de trabalho.
Modelos de acesso no local de marcação Databricks Indisponível. Carregue modelos do mercado Databricks em seu metastore do Unity Catalog e acesse-os em espaços de trabalho.

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

Limitações no suporte ao Catálogo Unity

  • 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 o guia de atualização 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 order_by parâmetro 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, MlflowClient().search_registered_models(filter_string="name='main.default.mymodel'") não é suportada. Para buscar um determinado modelo registrado 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 modelos não são suportados no Catálogo Unity.
  • O log de atividades não é suportado para modelos no Unity Catalog. No entanto, você pode acompanhar a atividade em modelos no Unity Catalog usando logs de auditoria.
  • search_registered_models pode retornar resultados obsoletos para modelos compartilhados por meio do Delta Sharing. Para garantir os resultados mais recentes, use a CLI ou SDK do Databricks para listar os modelos em um esquema.