MLflow 3 em ciência de dados Fabric

Microsoft Fabric dá suporte ao MLflow até a versão 3.1, a plataforma de acompanhamento de machine learning de software livre. Com esse suporte, você pode usar os seguintes recursos para acompanhar e inspecionar cargas de trabalho de IA geradoras e de aprendizado de máquina no Fabric:

  • LoggedModel, introduzido no MLflow 3, como uma entidade de primeira classe que vincula cada modelo à sua execução de origem, código, configuração, parâmetros, métricas e conjuntos de dados.
  • Rastreamentos que capturam prompts, respostas, chamadas de ferramentas, latência e uso de tokens de aplicações com LLMs e IA generativa.

Este artigo explica quais alterações no MLflow 3, como usar os novos recursos no Fabric e como migrar do MLflow 2.x.

GIF animado de um experimento do MLflow 3 no Fabric, mostrando as guias Execuções, Modelos e Rastreios, com os cartões Salvar modelo registrado e Comparar modelos registrados.

Pré-requisitos

  • Um espaço de trabalho atualizado para a experiência mais recente de rastreamento de machine learning. Para verificar a qualificação e a atualização, consulte Atualizar seu sistema de acompanhamento de machine learning.

  • mlflow versão 3.0 ou posterior. Fabric notebooks são fornecidos com o MLflow 2.x por padrão, portanto, você precisa atualizar para o MLflow 3 executando o seguinte comando em seu notebook:

    %pip install "synapseml-mlflow[online-notebook]>=2.0.3" "mlflow-skinny==3.1.0" "opentelemetry-api<=1.40.0"

    O mesmo comando também instala o pacote synapseml-mlflow atualizado para cenários entre espaços de trabalho e fora do Fabric.

O que muda no MLflow 3

Area MLflow 2.x MLflow 3
API de registro de logs do modelo log_model(model, artifact_path="model") log_model(model, name="my_model", params={...}) (o legado artifact_path ainda funciona)
Representação de modelo Artefato anexado a uma execução Entidade LoggedModel de primeira classe vinculada a uma execução
Interface de usuário do experimento Visualização de um único experimento Tipos de experimento de ML vs. tipos de experimento de IA, além de uma seção Modelos Registrados e uma aba Rastreios
Observabilidade de IA generativa Não disponível Rastreamentos de prompts, respostas, chamadas de ferramenta, latência e tokens

O MLflow 3 é retrocompatível com os fluxos de trabalho do MLflow 2.x. Experimentos, execuções e notebooks existentes que usam mlflow>=2 continuam funcionando sem alterações.

Escolher um tipo de experimento

Quando você cria um experimento, a faixa de opções inclui um seletor para o tipo de experimento:

  • Experimento de ML – superfície de acompanhamento clássico para execuções, parâmetros, métricas e LoggedModels. Use esse tipo para fluxos de trabalho de machine learning tradicionais.
  • Experimento de IA — superfície com foco em rastreamento ajustada para cargas de trabalho de IA generativa. A guia Rastreamentos está em destaque, e a visão detalhada da execução enfatiza prompts, chamadas de ferramentas e uso de tokens.

Os experimentos existentes criados antes do MLflow 3 são do tipo experimento de ML por padrão. Você pode alternar tipos da faixa de opções a qualquer momento.

Captura de tela da lista suspensa da faixa de opções do experimento que permite alternar entre o experimento de machine learning e os tipos de experimento de IA.

Comece com um modelo de notebook

Dois modelos de notebook acompanham a versão para você começar com um clique. Quando você abre um experimento que ainda não tem nenhuma execução, a página de experimento vazia apresenta dois cartões de início:

  • Novo modelo de modelo – um exemplo de ElasticNet de ponta a ponta que demonstra a nova API LoggedModel, incluindo params=, get_logged_model()e métricas vinculadas ao LoggedModel e a um conjunto de dados.
  • Novo modelo de rastreamento — abrange @mlflow.trace decoradores, registro automático da OpenAI com credenciais do Fabric, agentes LangChain e o SDK de Agentes da OpenAI.

Selecione um cartão para abrir um notebook pré-configurado com as versões de plug-in do MLflow e a autenticação corretas.

Captura de tela da página vazia do experimento com os cartões iniciais dos modelos New model e New trace destacados.

Registrar um modelo com LoggedModel

No MLflow 3, cada chamada para log_model() cria uma entidade LoggedModel vinculada à execução de origem, aos seus parâmetros, às métricas e aos conjuntos de dados com os quais foi treinado. O exemplo a seguir treina um modelo ElasticNet no conjunto de dados Iris, registra-o como um LoggedModel e vincula as métricas de avaliação de volta a esse LoggedModel e ao conjunto de dados:

import pandas as pd
from sklearn.linear_model import ElasticNet
from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split

import mlflow
import mlflow.sklearn
from mlflow.entities import Dataset

mlflow.set_experiment("mlflow3-logged-model-demo")

def compute_metrics(actual, predicted):
    rmse = mean_squared_error(actual, predicted)
    mae = mean_absolute_error(actual, predicted)
    r2 = r2_score(actual, predicted)
    return rmse, mae, r2

iris = load_iris()
iris_df = pd.DataFrame(data=iris.data, columns=iris.feature_names)
iris_df["quality"] = (iris.target == 2).astype(int)
train_df, test_df = train_test_split(iris_df, test_size=0.2, random_state=42)

with mlflow.start_run() as training_run:
    # Wrap the training data as an MLflow Dataset so metrics can be linked to it.
    train_dataset: Dataset = mlflow.data.from_pandas(train_df, name="train")
    train_x = train_dataset.df.drop(["quality"], axis=1)
    train_y = train_dataset.df[["quality"]]

    lr = ElasticNet(alpha=0.5, l1_ratio=0.5, random_state=42)
    lr.fit(train_x, train_y)

    # Log the model. `params=` attaches hyperparameters directly to the LoggedModel.
    model_info = mlflow.sklearn.log_model(
        sk_model=lr,
        name="elasticnet",
        params={"alpha": 0.5, "l1_ratio": 0.5},
        input_example=train_x,
    )

    # Retrieve the LoggedModel to inspect its identifier and parameters.
    logged_model = mlflow.get_logged_model(model_info.model_id)
    print(logged_model.model_id, logged_model.params)

    # Compute metrics and link them to both the LoggedModel and the training dataset.
    predictions = lr.predict(train_x)
    rmse, mae, r2 = compute_metrics(train_y, predictions)
    mlflow.log_metrics(
        metrics={"rmse": rmse, "r2": r2, "mae": mae},
        model_id=logged_model.model_id,
        dataset=train_dataset,
    )

Após a conclusão da execução, o modelo aparece como um LoggedModel em dois locais:

  • A seção Modelos Registrados na página de experimentos.
  • A aba Modelos registrados na página de detalhes da execução.

Captura de tela de uma página de detalhes de execução com a seção Modelos e rastreamentos realçada, mostrando o LoggedModel vinculado.

Inspecionar um LoggedModel

Selecione um LoggedModel na lista para abrir sua página de detalhes. A página de detalhes mostra:

  • Parâmetros e métricas capturados para o modelo.
  • Link da execução de origem que leva à execução que produziu o modelo.
  • Conjuntos de dados usados durante o treinamento.
  • Ambiente (Python versão, dependências, assinatura).

Captura de tela da guia Modelos na página de experimentos com a lista de modelos registrados realçados.

Comparar modelos registrados

Na seção Modelos Registrados , selecione vários LoggedModels para compará-los usando gráficos de linha internos, gráficos de dispersão e coordenadas paralelas. Você também pode pesquisar, filtrar, classificar e agrupar LoggedModels por métrica, parâmetro, marca ou metadados.

Captura de tela da guia Modelos com vários modelos registrados e o painel de comparação de métricas mostrando gráficos de linhas para RMSE, bagging_fraction e bagging_freq.

Registrar um LoggedModel

Para promover um LoggedModel para um item de modelo do Fabric ML, abra sua página de detalhes e selecione Registrar modelo. Você pode registrá-lo como um novo modelo de ML ou como uma nova versão de um modelo existente. Após o registro, a página de detalhes do LoggedModel mostra um link para o item do modelo registrado.

Capturar rastros de IA generativa

Os rastros capturam a execução de uma aplicação de LLM ou de IA generativa na forma de uma hierarquia de spans. Cada rastreamento mostra entradas, saídas, latência, uso de tokens e quaisquer chamadas de ferramenta ou de função. Use o tipo de experimento de IA para ter a melhor experiência com foco em rastreios.

Rastreie uma função com o decorador @mlflow.trace

Adicione @mlflow.trace a qualquer função para registrar suas entradas, saídas e duração. Use mlflow.update_current_trace() para anexar tags de dentro da função:

import mlflow
import time

mlflow.set_experiment("mlflow3-trace-demo")

@mlflow.trace
def process_user(user_id, action):
    mlflow.update_current_trace(tags={
        "user_id": user_id,
        "action": action,
        "environment": "production",
    })
    time.sleep(1)
    return f"Processed action {action} for user {user_id}"

with mlflow.start_run(run_name="function_call"):
    process_user(user_id=123, action="login")

Quando funções decoradas chamam umas às outras, o MLflow organiza automaticamente os spans de forma aninhada para que você possa visualizar toda a árvore de chamadas na página de detalhes do rastreamento.

Autolog de conclusões de chat da OpenAI

Habilite o registro automático do OpenAI para que cada chamada ao cliente OpenAI seja rastreada automaticamente, sem adicionar decoradores. O exemplo a seguir usa AzureOpenAI com credenciais gerenciadas por Fabric:

import mlflow
from openai import AzureOpenAI
from synapse.ml.fabric.credentials import get_openai_httpx_sync_client

mlflow.openai.autolog()

client = AzureOpenAI(
    api_version="2025-04-01-preview",
    http_client=get_openai_httpx_sync_client(),
)

with mlflow.start_run(run_name="simple_openai_chat") as run:
    response = client.chat.completions.create(
        model="gpt-4.1",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What are the main components of MLflow?"},
        ],
        temperature=0.7,
    )
    print(response.choices[0].message.content)
    print(f"Trace ID: {mlflow.get_last_active_trace_id()}")

Para frameworks de agentes, o MLflow também oferece autologging para LangChain (mlflow.langchain.autolog()) e o SDK de Agentes da OpenAI. O novo modelo de rastreamento inclui exemplos completos e executáveis para ambos, incluindo conversas de chamada de ferramentas de vários turnos.

Exibir rastreamentos

Para visualizar rastreamentos:

  1. Abra um experimento que contém execuções de IA generativas.
  2. Selecione a aba Traços.
  3. Selecione um rastreamento para abrir a visualização Detalhes do rastreamento.

Captura de tela de um rastreamento aberto mostrando detalhes de execução, propriedades e detalhes de rastreamento com entradas e saídas.

A visualização de detalhes do rastreamento mostra:

  • Uma span tree com decomposição hierárquica da solicitação.
  • Entradas, saídas e atributos para cada intervalo.
  • Pares de prompt e resposta para segmentos de LLM (sistema, usuário, assistente).
  • Latência, uso de token e metadados de modelo (nome, versão, parâmetros).
  • Chamadas de ferramenta e função com suas entradas, saídas e IDs de documento.
  • Rastreamentos com falha com tipo de exceção, mensagem e rastreamento de pilha.

A lista de rastreamento mostra a ID de rastreamento, entrada, saída, duração, hora de início e status (Concluído, Com Falha ou Em Execução). Você pode filtrar rastreamentos por usuário, status ou hora de início.

Captura de tela de uma lista de rastreamento aberta mostrando ID de rastreamento, entrada, saída, duração, hora de início e status.

Os rastreios produzidos por uma execução também aparecem na página de detalhes da execução, na guia Rastreios.

Migrar do MLflow 2.x

Você pode adotar o MLflow 3 incrementalmente:

  • Os notebooks existentes continuam sendo executados sem alterações. O parâmetro herdado em artifact_pathlog_model() ainda funciona e produz um LoggedModel.
  • Novos notebooks devem usar o parâmetro name para maior clareza.
  • Cenários entre espaços de trabalho usam o pacote atualizado synapseml-mlflow. Você não precisa mais fixar mlflow-skinny em 2.22.2. Para ver as etapas de instalação, consulte Gerenciar modelos do MLflow em espaços de trabalho e plataformas.

O que ainda não é suportado

A avaliação de IA generativa (mlflow.genai.evaluate()) ainda não está habilitada no Fabric. Está planejado para uma versão futura.

Conteúdo relacionado

  • Last updated on