Pular para o conteúdo principal
Última atualização em

Migrar rastros de experimentos para Unity Catalog

A Databricks recomenda armazenar rastreamentos em tabelas Delta do Unity Catalog. Se você tiver rastreamentos existentes armazenados em um experimento do MLflow, migrá-los para o Unity Catalog é o caminho recomendado: isso remove os limites de armazenamento de rastreamentos, fornece controles de acesso detalhados por meio da governança do Unity Catalog e torna os rastreamentos consultáveis a partir de notebooks, SQL, dashboards do Genie, AI/BI e de qualquer ferramenta baseada em Spark.

A migração copia rastreamentos, intervalos, avaliações, tags e metadados do experimento de origem para as tabelas Unity Catalog . O experimento original não foi modificado.

Se você estiver começando do zero e não tiver rastreamentos existentes para migrar, consulte Armazenar rastreamentos no Unity Catalog para configurar um novo experimento para gravar rastreamentos diretamente no Unity Catalog.

nota

A migração não copia rastreamentos arquivados ou excluídos, registros de dataset , sessões de rótulos, execuções ou entidades que não sejam rastreamentos.

Requisitos​

  • Os pré-requisitos para armazenar rastreamentos no Unity Catalog, incluindo as visualizações de workspace necessárias. Consulte Requisitos.

  • Um Databricks SQL warehouse com permissão CAN USE, usado para fazer view dos rastreamentos migrados na interface de usuário. O comando de migração em si realiza a execução no cluster e não usa o warehouse.

  • Um cluster Databricks executando Databricks Runtime 15.3 ou superior.

  • O pacote Python databricks-agents :

    Bash
    pip install "databricks-agents>=1.10.1"

  • As seguintes permissões:

    • Acesso de leitura ao experimento original.
    • USE_CATALOG e USE_SCHEMA no catálogo e esquema de destino.
    • CREATE TABLE no esquema de destino. O passo 1 cria as quatro tabelas de rastreamento, e a migração cria uma tabela _migration_skipped no mesmo esquema se algum rastro for ignorado.
    • MODIFY e SELECT nas tabelas de destino <prefix>_otel_*. A migração lê as linhas existentes nas tabelas de destino para ignorar os rastreamentos já migrados, portanto, SELECT é necessário além de MODIFY. Conforme observado em Conceder permissões, ALL_PRIVILEGES não é suficiente. Conceda MODIFY e SELECT explicitamente.

o passo 1: Criar um experimento de destino​

O destino é um novo experimento MLflow vinculado a um local de rastreamento Unity Catalog .

A localização do rastreamento é um caminho de três partes (catalog.schema.table_prefix). O prefixo da tabela é aplicado às quatro tabelas Delta que dão suporte ao experimento:

  • <prefix>_otel_spans
  • <prefix>_otel_annotations
  • <prefix>_otel_logs
  • <prefix>_otel_metrics

execute o seguinte para criar o experimento de destino. Para obter detalhes completos sobre a configuração, consulte Configuração: Criar um experimento com um local de rastreamento Unity Catalog.

Python
import mlflow
from mlflow.entities.trace_location import UnityCatalog

experiment = mlflow.set_experiment(
    experiment_name="/Workspace/Users/<user>/<experiment_name>",
    trace_location=UnityCatalog(
        catalog_name="<destination_catalog>",
        schema_name="<destination_schema>",
        table_prefix="<table_prefix>",
    ),
)

print(f"Destination experiment ID: {experiment.experiment_id}")

Guarde o ID do experimento impresso pelo código acima. Você o utiliza nas próximas duas etapas: na etapa 2, para direcionar seus modelos Notebook, Job e de implantação para o novo experimento com suporte do Unity Catalog e, na etapa 3, como o ID do experimento de destino para o comando de migração.

Você pode inserir alguns rastreamentos de teste no novo experimento para verificar se o rastreamento Unity Catalog funciona para o seu fluxo de trabalho antes de prosseguir. Consulte os registros de log das tabelas Unity Catalog para obter exemplos.

o passo 2: Alternar o registro de rastreamento e interromper as gravações no experimento de origem​

Antes de executar a migração, redirecione o registro de rastreamento para o experimento de destino criado na etapa 1 e interrompa as gravações no experimento de origem. Isso garante que novos rastreamentos sejam gravados nas tabelas de destino e que nenhum rastreamento seja perdido durante a execução da migração.

  1. Interrompa todas as gravações no experimento de origem. Quaisquer registros gravados no experimento de origem durante a migração podem não ser copiados. Verifique se nenhum Notebook, Job ou modelo implantado está registrando logs ativamente no experimento de origem.

  2. Substitua qualquer chamada set_experiment existente que aponte para o experimento de origem por uma que aponte para o experimento de destino, seja por nome ou por ID:

    Python
    import mlflow

    # By experiment name
    mlflow.set_experiment(
        experiment_name="/Workspace/Users/<user>/<destination_experiment_name>",
    )

    # Or by experiment ID
    mlflow.set_experiment(experiment_id="<destination_experiment_id>")
nota

A localização do rastreamento também pode ser configurada por meio de outros mecanismos, como as variáveis de ambiente MLFLOW_EXPERIMENT_NAME e MLFLOW_EXPERIMENT_ID , que são usadas por aplicações implantadas, serviços conteinerizados, configurações endpoint de modelos de serviço e configurações de desenvolvimento local ou de IDE. Para obter detalhes sobre como configurar destinos de rastreamento em produção, consulte Implantação de agentes de rastreamento no Databricks e Implantação de agentes de rastreamento fora do Databricks.

o passo 3: execução da migração​

Em um notebook Databricks no cluster, execute o seguinte:

Python
from databricks.migrations.migrate_traces_to_uc import run

run(
    source_experiment_id="<source_experiment_id>",
    target_experiment_id="<destination_experiment_id>",
)

Substitua os marcadores de posição:

  • <source_experiment_id>: O ID do experimento existente que contém os traços que você deseja migrar.
  • <destination_experiment_id>: O ID do experimento do experimento com suporte do Unity Catalog criado na etapa 1.

A migração é idempotente. Caso a execução seja interrompida (por exemplo, devido a um tempo limite do cluster), você poderá executar o mesmo comando novamente sem problemas. A migração é retomada automaticamente de onde parou. As linhas já migradas serão ignoradas.

Para migrar apenas os rastreamentos criados após um horário específico, passe o parâmetro start_time_ms (milissegundos da época). A migração irá incorporar todos os rastreamentos com um horário de solicitação igual ou posterior ao carimbo de data/hora especificado, ignorando aqueles que já foram migrados.

Python
import time

from databricks.migrations.migrate_traces_to_uc import run

one_week_ago_ms = int((time.time() - 7 * 24 * 60 * 60) * 1000)

run(
    source_experiment_id="<source_experiment_id>",
    target_experiment_id="<destination_experiment_id>",
    start_time_ms=one_week_ago_ms,  # Only migrate traces from the last 7 days
)

Assim que a migração for concluída, seus rastreamentos estarão disponíveis no novo experimento de destino. O experimento original não é modificado pela migração e pode ser mantido como backup.

Se você usar monitoramento de produção, persista um ID de SQL Warehouse no experimento de destino antes do registro dos scorers. Consulte Habilitar monitoramento de produção.

Nesta página