Registre e registre modelos Gerencie os estágios do ciclo de vida do modelo Evite atualizações em modelos registrados usando tags de recursos

Registre automaticamente modelos de SageMaker IA com o SageMaker Model Registry

Quando você registra um modelo MLflow, a SageMaker AI cria automaticamente um Grupo de Pacotes de Modelos e uma versão de Pacote de Modelos correspondentes no Registro de SageMaker Modelos. Isso permite que você:

Registre modelos do MLFlow SDK ou da interface do usuário do MLflow.
Anexe uma especificação de inferência para permitir a implantação direta em endpoints de SageMaker IA.
Registre as métricas de avaliação que estão incluídas como um cartão modelo no pacote de modelos.
Gerencie estágios do ciclo de vida do modelo (preparação, produção) e status (pendente, ativo) por meio de aliases MLflow.
Controle as transições do ciclo de vida e o registro com chaves de condição do IAM e políticas baseadas em tags de recursos.

nota

A sincronização do Model Registry é um recurso opcional. Para habilitá-lo, chame a UpdateMlflowApp API UpdateMlflowTrackingServer or com a sincronização do Model Registry ativada.

Registre e registre modelos

Esta seção aborda como preparar um modelo para registro, registrá-lo no Registro de SageMaker Modelos e visualizá-lo no Studio.

Permissões obrigatórias do IAM

O servidor de rastreamento MLflow ou a função de serviço MLflow App IAM deve ter as seguintes permissões para registrar modelos:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sagemaker:CreateModelPackageGroup",
                "sagemaker:DescribeModelPackageGroup",
                "sagemaker:CreateModelPackage",
                "sagemaker:UpdateModelPackage",
                "sagemaker:AddTags",
                "sagemaker:CreateAction",
                "sagemaker:AddAssociation"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:ListBucket"
            ],
            "Resource": "*"
        }
    ]
}

Para obter mais informações sobre como configurar funções do IAM para aplicativos MLflow, consulteConfigurar permissões do IAM para aplicativos MLflow.

Prepare um modelo para registro

Antes de registrar um modelo, você o registra durante uma corrida de treinamento. Opcionalmente, você pode anexar uma especificação de inferência e métricas de avaliação, que são transferidas para o SageMaker AI Model Package após o registro.

Registre um modelo

Use o SDK do MLflow para registrar um modelo durante uma execução de treinamento:


import mlflow
from sklearn.datasets import make_regression
from sklearn.ensemble import RandomForestRegressor
from mlflow.models import infer_signature

mlflow.set_tracking_uri(arn)
mlflow.set_experiment("my-experiment")

params = {"n_estimators": 3, "random_state": 42}
X, y = make_regression(n_features=4, n_informative=2, random_state=0, shuffle=False)

with mlflow.start_run() as run:
    model = RandomForestRegressor(**params).fit(X, y)
    signature = infer_signature(X, model.predict(X))
    mlflow.log_params(params)
    model_info = mlflow.sklearn.log_model(
        model, name="sklearn-model", signature=signature, input_example=X[:3]
    )

Registrar uma especificação de inferência (opcional)

Uma especificação de inferência define a imagem do contêiner e os tipos de instância necessários para implantar seu modelo. Quando anexada a um modelo registrado antes do registro, a especificação de inferência é incluída automaticamente no pacote de modelos de SageMaker IA. Isso permite a implantação direta em um endpoint de SageMaker IA a partir do Registro de Modelos sem configuração adicional.

Use sagemaker_mlflow.log_inference_specification() para anexar uma especificação de inferência:


import sagemaker_mlflow

# Get the logged model's artifact location
logged_model = mlflow.MlflowClient().get_logged_model(model_info.model_id)

inference_spec = {
    "Containers": [{
        "Image": "763104351884.dkr.ecr.us-west-2.amazonaws.com/pytorch-inference:2.0.0-cpu-py310",
        "ModelDataSource": {
            "S3DataSource": {
                "S3Uri": logged_model.artifact_location + "/",
                "S3DataType": "S3Prefix",
                "CompressionType": "None",
            }
        },
    }],
    "SupportedRealtimeInferenceInstanceTypes": ["ml.m5.xlarge"],
}
sagemaker_mlflow.log_inference_specification(
    model_info.model_id,
    inference_specification=inference_spec
)

nota

A especificação de inferência deve seguir o mesmo esquema do InferenceSpecification parâmetro da API de SageMaker IACreateModelPackage. Para obter mais informações, consulte InferenceSpecification na Referência da API SageMaker AI.

Após o registro, a especificação de inferência é armazenada como um sagemaker_inference_specification.json artefato junto com seu modelo:

Artefato de especificação de inferência na interface do usuário do MLflow.

Métricas de avaliação de registros (opcional)

As métricas de avaliação fornecem um resumo padronizado do desempenho do seu modelo. Quando registrados antes do registro, os resultados da avaliação são incluídos no SageMaker AI Model Package como um cartão modelo, tornando as métricas visíveis no SageMaker AI Model Registry and Studio. Para obter mais informações sobre placas modelo, consulte Esquema da placa modelo.

Use sagemaker_mlflow.evaluate() para registrar métricas de avaliação:


import sagemaker_mlflow
import pandas as pd

eval_df = pd.DataFrame(X, columns=["f1", "f2", "f3"])
eval_df["target"] = y
dataset = mlflow.data.from_pandas(
    eval_df, source="s3://my-bucket/eval.csv", name="eval_set", targets="target"
)
sagemaker_mlflow.evaluate(model_info, data=dataset, model_type="regressor")

Após o registro, o grupo de avaliação é armazenado como um artefato junto com seu modelo:

Artefato do grupo de avaliação na interface do usuário do MLflow.

Registre modelos usando o SDK

Use mlflow.register_model() para registrar um SageMaker modelo no Registro de Modelos. Isso cria automaticamente um Grupo de Pacotes Modelo (se não existir) e uma versão do Pacote Modelo em SageMaker AI.


model_uri = f"runs:/{run.info.run_id}/sklearn-model"
mv = mlflow.register_model(model_uri, "MyRegisteredModel")

print(f"Name: {mv.name}")
print(f"Version: {mv.version}")

Você também pode usar create_registered_model para criar o Grupo de Pacotes de Modelos antes de registrar as versões:


from mlflow import MlflowClient

client = MlflowClient()
client.create_registered_model("MyRegisteredModel", tags={"team": "ml-platform"})

Após o registro, a versão do modelo é marcada com o SageMaker AI Model Package ARN. Você pode recuperá-lo da seguinte forma:


mv = client.get_model_version("MyRegisteredModel", mv.version)
sm_arn = mv.tags["sagemaker.model_package_arn"]
print(f"SageMaker Model Package ARN: {sm_arn}")

nota

Não use espaços no nome do modelo. Embora o MLflow ofereça suporte a nomes de modelos com espaços, o SageMaker AI Model Package não. O processo de registro falhará se você usar espaços no nome do modelo.

Registrar modelos usando a interface do usuário do MLflow

Você pode registrar um modelo no Registro de SageMaker Modelos diretamente na interface do usuário do MLflow. No menu Modelos, escolha Criar modelo. Os modelos criados dessa forma são adicionados automaticamente ao Registro de SageMaker Modelos.

Criação de registro de modelo na interface do usuário do MLflow.

Depois de registrar um modelo durante o acompanhamento do experimento, navegue até a página de execução na interface do usuário do MLflow. Escolha o painel Artefatos e escolha Registrar modelo para registrar a versão do modelo no MLFlow e SageMaker no Registro de modelos.

Registre uma versão do modelo na página de execução do MLflow.

Exibir modelos registrados no Studio

No Studio, escolha Modelos no painel de navegação esquerdo para ver seus modelos registrados. Para obter mais informações sobre como começar a usar o Studio, consulte Iniciar o Amazon SageMaker Studio.

A página de versão do Model Package no Studio exibe métricas de treinamento e conjuntos de dados que foram sincronizados do MLflow:

Visão geral da versão do Model Package mostrando métricas de treinamento no Studio.

A guia Trem também mostra a localização do conjunto de dados de treinamento e o caminho do artefato do modelo:

Conjuntos de dados de treinamento e artefatos de modelo no Studio.

Se você registrou uma especificação de inferência, a seção Contêiner mostra a imagem do contêiner, a localização dos dados do modelo e os tipos de instância compatíveis. O estágio Implantação mostra Aprovado, indicando que o modelo está pronto para implantação:

Contêineres de especificação de inferência e tipos de instância no Studio.

Se você registrou métricas de avaliação, a guia Avaliar exibe métricas de desempenho, como pontuação, erro médio absoluto e raiz do erro quadrático médio:

A guia Avaliar também mostra a localização do conjunto de dados de avaliação:

Conjunto de dados de avaliação no Studio.

A guia Linhagem mostra a relação entre o experimento MLflow, a versão do modelo, a imagem do contêiner e o Grupo de Pacotes do Modelo:

Gráfico de linhagem do modelo mostrando a associação do experimento MLflow no Studio.

Limitações

Não use espaços nos nomes dos modelos. SageMaker O AI Model Package não oferece suporte a espaços e o registro falha.
Se a função não tiver s3:GetObject permissão nos caminhos do artefato, a especificação de inferência e os artefatos de avaliação serão ignorados silenciosamente. O pacote modelo ainda está criado, mas sem dados de inferência ou avaliação.
Se a função estiver ausente sagemaker:CreateAction ousagemaker:AddAssociation, as associações de linhagem entre o modelo MLflow e o SageMaker AI Model Package serão ignoradas silenciosamente. Isso não afeta o registro ou o gerenciamento do ciclo de vida.
Definir um estágio e status do ciclo de vida não ativa o botão Implantar no Studio. Para ativar a implantação com um clique a partir da interface do usuário, você deve definir separadamente o status de aprovação do pacote modelo para Approved usar a API SageMaker AI.
As alterações nas permissões da função de serviço IAM do aplicativo MLflow podem levar até 15 minutos para entrar em vigor.

Gerencie os estágios do ciclo de vida do modelo

Depois de registrar um modelo, você pode gerenciar seu estágio e status do ciclo de vida no SageMaker AI Model Registry definindo aliases de versão do modelo MLflow. Quando você define um alias usando a convenção de nomenclatura do ciclo de vida, o ciclo de vida correspondente do pacote SageMaker AI Model é atualizado automaticamente. Para obter mais informações sobre os estágios do ciclo de vida do modelo, consulte Modelos de estágios no Registro de Modelos.

Permissões do IAM para gerenciamento do ciclo de vida

O servidor de rastreamento MLflow ou a função de serviço MLflow App IAM requer sagemaker:UpdateModelPackage permissão para gerenciar os estágios do ciclo de vida. Essa ação já está incluída nas permissões básicas de registro descritas acima.

Restrinja as transições do ciclo de vida

Você pode usar as chaves de condição do IAM para controlar quais transições de ciclo de vida uma função pode realizar:

sagemaker:ModelLifeCycle/stage— O estágio do ciclo de vida que está sendo definido. Valores:staging,production.
sagemaker:ModelLifeCycle/stageStatus— O status do ciclo de vida que está sendo definido. Valores:pending,active.

Exemplo: negar promoções de produção


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "sagemaker:UpdateModelPackage",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "sagemaker:ModelLifeCycle/stage": "production"
                }
            }
        }
    ]
}

Exemplo: Permitir somente staging/pending transições


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sagemaker:UpdateModelPackage",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "sagemaker:ModelLifeCycle/stage": "staging",
                    "sagemaker:ModelLifeCycle/stageStatus": "pending"
                }
            }
        }
    ]
}

Quando uma transição do ciclo de vida é negada pela política do IAM, a operação do alias MLflow falha e retorna um erro ao chamador.

Para obter mais informações sobre o ciclo de vida do modelo no SageMaker AI Model Registry, consulte Implantar um modelo a partir do registro.

Defina estágios do ciclo de vida usando o SDK

Use o seguinte formato de alias para definir o estágio e o status do ciclo de vida:


sagemakerlifecycle-stage-status

Estágios suportados:staging, production

Status suportados:pending, active

nota

Os valores de estágio e status devem estar em minúsculas. Os aliases MLFlow suportam apenas caracteres minúsculos, portanto, valores como Production ou Active não são válidos.


import mlflow

mlflow.set_tracking_uri(arn)
client = mlflow.MlflowClient()

# Set lifecycle to staging/pending
client.set_registered_model_alias("MyRegisteredModel", "sagemakerlifecycle-staging-pending", version)

# Promote to production/active
client.set_registered_model_alias("MyRegisteredModel", "sagemakerlifecycle-production-active", version)

Você pode verificar o estado do ciclo de vida descrevendo o pacote de modelos de SageMaker IA:


import boto3

sm = boto3.client("sagemaker")
mv = client.get_model_version("MyRegisteredModel", version)
sm_arn = mv.tags["sagemaker.model_package_arn"]

desc = sm.describe_model_package(ModelPackageName=sm_arn)
print(desc["ModelLifeCycle"]["Stage"])       # "staging"
print(desc["ModelLifeCycle"]["StageStatus"]) # "pending"

Defina os estágios do ciclo de vida usando a interface do usuário do MLflow

Na interface do usuário do MLflow, navegue até a página da versão do modelo. Em Aliases, adicione um alias usando o sagemakerlifecycle-stage-status formato. O ciclo de vida do SageMaker AI Model Package é atualizado automaticamente quando o alias é salvo.

Definindo um alias de ciclo de vida na interface do usuário do MLFlow.

Veja os estágios do ciclo de vida no Studio

No Studio, navegue até Modelos e selecione uma versão do pacote de modelos. O estágio e o status do ciclo de vida são exibidos na guia Detalhes em Ciclo de vida do modelo.

Estágio e status do ciclo de vida do modelo no Studio.

Evite atualizações em modelos registrados usando tags de recursos

Você pode usar condições baseadas em tags de recursos do IAM para evitar que o servidor de rastreamento MLflow ou a função do aplicativo MLFlow modifique grupos de pacotes de modelos específicos ou versões de pacotes de modelos. Isso permite que você impeça que modelos individuais sejam atualizados por meio do MLflow após atingirem um determinado estado.

Por exemplo, a política a seguir é UpdateModelPackage negada em qualquer pacote modelo que tenha a tag: locked=true


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "sagemaker:UpdateModelPackage",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/locked": "true"
                }
            }
        }
    ]
}

Quando essa política é anexada ao servidor de rastreamento ou à função do aplicativo MLflow, qualquer tentativa de atualizar o ciclo de vida de um pacote modelo marcado do MLflow falha com um erro de acesso negado.

Da mesma forma, você pode restringir CreateModelPackage um grupo de pacotes de modelos para evitar que novas versões sejam registradas:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "sagemaker:CreateModelPackage",
            "Resource": "arn:aws:sagemaker:region:account:model-package-group/group-name/*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/frozen": "true"
                }
            }
        }
    ]
}

nota

As condições baseadas em tags de recursos dependem de tags aplicadas ao SageMaker AI Model Package Group ou ao recurso Model Package (não ao modelo MLflow). Você pode aplicar essas tags por meio do console de SageMaker IA, CLI ou SDK. Tag-based as condições podem levar até 15 minutos para se propagar após a aplicação de uma etiqueta.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Métricas de log

Implantar modelos