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

Migrar rastreamentos existentes para o Unity Catalog

O Unity Catalog é o local de armazenamento recomendado para rastreamentos do MLflow. Esta página aborda dois caminhos de migração:

  • Armazenamento de experimentos → Unity Catalog : se os seus rastreamentos estiverem armazenados em um experimento do MLflow (o default), migre-os para o Unity Catalog para ter acesso governado, capacidade de consulta em SQL e sem limite de armazenamento.
  • Legacy Unity Catalog format → current Unity Catalog format : if you configured Unity Catalog trace storage using the older schema-linked format (catalog.schema), migrate to the current table-prefix format (catalog.schema.table_prefix) for faster time-range consultas, richer attribute types, a dedicated tabela de anotações, and support for multiple trace destinations per schema.

Se você estiver começando do zero, sem rastreamentos existentes para migrar, consulte Armazenar rastreamentos no Unity Catalog para configurar um novo experimento diretamente.

Migrar do armazenamento de experimentos para o Unity Catalog​

Esta migração copia rastreamentos, intervalos, avaliações, tags e metadados de um experimento MLflow de origem para tabelas Delta do Unity Catalog. O experimento de origem não é modificado.

nota

The migration does not copy archived or deleted traces, dataset records, labeling sessions, execuções, or non-trace entities.

Requisitos​

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

  • A Databricks SQL warehouse with CAN USE permission. The migration comando runs on the cluster and does not use the warehouse; the warehouse is needed to view migrated traces in the UI.

  • Um cluster do Databricks executando o Databricks Runtime 15.3 ou acima.

  • O pacote databricks-agents Python:

    Bash
    pip install "databricks-agents>=1.10.1"

  • As seguintes permissões:

    • Acesso de leitura ao experimento de origem.
    • USE_CATALOG e USE_SCHEMA no catálogo e no esquema de destino.
    • CREATE TABLE on the destination schema. The migration also creates a _migration_skipped table in the same schema if any traces are skipped.
    • MODIFY e SELECT nas tabelas de destino <prefix>_otel_*. SELECT é obrigatório porque a migração lê as linhas existentes para ignorar os rastreamentos já migrados. ALL_PRIVILEGES não é suficiente — conceda MODIFY e SELECT explicitamente. Consulte Conceder permissões.

Etapa 1: criar um experimento de destino​

Criar um experimento do MLflow vinculado a um local de rastreamento do Unity Catalog. O local do rastreamento é um caminho de três partes (catalog.schema.table_prefix), e a migração grava em quatro tabelas Delta: <prefix>_otel_spans, <prefix>_otel_annotations, <prefix>_otel_logs e <prefix>_otel_metrics.

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

Salve o ID do experimento — você o usará nos passos 2 e 3. Você pode ingerir alguns rastreamentos de teste para verificar se o rastreamento do Unity Catalog funciona antes de prosseguir. Consulte Fazer log de rastreamentos nas tabelas do Unity Catalog.

Etapa 2: Alternar o registro de rastreamento e interromper gravações​

Antes de executar a migração, redirecione o registro de rastreamento para o novo destino e interrompa as gravações no experimento de origem. Isso garante que nenhum rastreamento seja perdido durante a migração.

  1. Interrompa todas as gravações no experimento de origem. Verifique se nenhum notebook, job ou modelo implantado está registrando dados ativamente nele.

  2. Substitua qualquer chamada set_experiment que aponte para o experimento de origem:

    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 das variáveis de ambiente MLFLOW_EXPERIMENT_NAME e MLFLOW_EXPERIMENT_ID, que são usadas por agentes implantados, serviços conteinerizados, configurações de Endpoint de servindo modelo e configurações de IDE ou desenvolvimento local. Para obter detalhes, consulte Visão geral do rastreamento e Exportar rastreios do MLflow para o OpenTelemetry.

Etapa 3: Executar a migração​

Em um Notebook do Databricks no cluster, execute:

Python
from databricks.migrations.migrate_traces_to_uc import run

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

A migração é idempotente — se for interrompida (por exemplo, devido a um tempo limite do cluster), execute o mesmo comando novamente. A execução é retomada de onde parou e ignora as linhas já migradas.

Para migrar apenas rastreamentos criados após um horário específico, passe start_time_ms (milissegundos da época):

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
)

Após a conclusão da migração, o experimento de origem não é modificado e pode ser retido como um backup. Se você usar monitoramento de produção, persista um ID de SQL warehouse no experimento de destino antes do registro dos scorers. Consulte Configurar um SQL warehouse para rastreamentos do Unity Catalog.

Migrar do formato legando do Unity Catalog​

If you configured Unity Catalog trace storage using the older schema-linked format, your traces are stored in fixed-name tables like mlflow_experiment_trace_otel_spans and mlflow_experiment_trace_otel_logs. Esta migração copia intervalos e anotações para o formato atual de prefixo de tabela usando o Spark SQL.

Como identificar se você precisa desta migração : verifique se o seu esquema do Unity Catalog contém tabelas chamadas mlflow_experiment_trace_otel_spans e mlflow_experiment_trace_otel_logs. Se houver, seu experimento usará o formato mais antigo vinculado ao esquema e será um candidato para migração.

The two formats differ as follows:

  • Schema-linked (older format): the experiment's trace destination is a two-part path (catalog.schema). Trace data lives in fixed-name tables. Tags, avaliações e metadados são armazenados como eventos de log na tabela de logs.
  • Prefixo da tabela (formato atual): o destino do rastreamento é um caminho de três partes (catalog.schema.table_prefix). Os dados de rastreamento residem em tabelas com namespaces de prefixo. As anotações têm uma tabela dedicada.

Requisitos​

Os mesmos pré-requisitos compartilhados do primeiro caminho de migração (configuração do UC, SQL warehouse, DBR 15.3+ e pacote databricks-agents). Consulte os requisitos do primeiro caminho para ver a lista completa. Além disso:

  • Na origem : USE_CATALOG, USE_SCHEMA e SELECT no catálogo, no esquema e nas tabelas mlflow_experiment_trace_otel_* de origem.
  • No destination : USE_CATALOG, USE_SCHEMA, MODIFY e SELECT nas tabelas de catálogo, esquema e <table_prefix>_otel_* de destino. SELECT é obrigatório porque a migração lê as linhas existentes para ignorar os dados já migrados.
  • CREATE TABLE no esquema de destino .

Etapa 1: criar um experimento de destino​

Criar um experimento vinculado a um local com prefixo de tabela do Unity Catalog. Para obter detalhes completos da configuração, consulte Criar um experimento com um local de rastreamento do 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"Experiment ID: {experiment.experiment_id}")

Save the experiment ID. Use it to configure your notebooks, jobs, or deployed models to log traces to the new destination.

Etapa 2: Alternar o registro de rastreamento e interromper gravações​

Atualize seus notebooks, jobs ou modelos implantados para registrar rastreamentos no experimento de destino criado na Etapa 1.

importante

Interrompa todas as gravações no experimento de origem antes de executar a migração. Quaisquer rastreamentos gravados nas tabelas de origem durante a migração podem não ser copiados. Verifique se nenhum Notebooks, Jobs ou modelo implantado está registrando rastreamentos ativamente no experimento de origem.

Se quiser fazer uma execução de teste primeiro, você poderá ignorar esta etapa e executar a migração sem alterar suas cargas de trabalho de produção.

Etapa 3: Executar a migração​

Em um Notebook do Databricks no cluster, execute:

Python
from databricks.migrations.v1_to_v2 import V1ToV2SqlMigration

migration = V1ToV2SqlMigration(
    v1_source_schema="<source_catalog>.<source_schema>",
    v2_destination_prefix="<destination_catalog>.<destination_schema>.<table_prefix>",
)
migration.run()

Substitua os espaços reservados:

  • <source_catalog>.<source_schema>: o catálogo e o esquema do Unity Catalog onde suas tabelas de rastreamento de origem estão armazenadas.
  • <destination_catalog>.<destination_schema>.<table_prefix>: o catálogo, o esquema e o prefixo de tabela do Unity Catalog para o destino. Isso deve corresponder ao local configurado na Etapa 1.

A migração é idempotente — se falhar no meio do processo, execute-a novamente. As linhas já migradas são ignoradas automaticamente.

Após a conclusão da migração, as tabelas de origem não são modificadas e podem ser mantidas como backup. Se você usar o monitoramento de produção, persista um ID de SQL warehouse no experimento de destino antes do registro dos scorers. Consulte Configurar um SQL warehouse para rastreamentos do Unity Catalog.

Recursos adicionais​

Nesta página