Migrar traços para o formato de tabela mais recente do Unity Catalog

Se configurou um experimento MLflow para armazenar traços no Unity Catalog durante a versão Beta usando o formato ligado ao esquema (catalog.schema), pode migrar esses traços para o formato de prefixo de tabela (catalog.schema.table_prefix) introduzido com a versão Prévia Pública.

O Databricks recomenda o formato de prefixo de tabela para todas as cargas de trabalho UC trace novas e existentes. Proporciona consultas de intervalo temporal mais rápidas, tipos de atributos mais ricos, uma tabela de anotações dedicada e suporte para múltiplos destinos de traço por esquema.

A migração copia intervalos e anotações (tags, avaliações, metadados) utilizando o Spark SQL.

Identificar experiências que utilizem o formato mais antigo

Experiências que armazenam traços no Catálogo Unity utilizam um de dois formatos:

• Esquema-ligado (usado durante a versão Beta): O destino do rastreio do experimento é um caminho de duas partes (catalog.schema). Os dados de traço são armazenados em tabelas de nomes fixos como mlflow_experiment_trace_otel_spans e mlflow_experiment_trace_otel_logs. Etiquetas, avaliações e metadados são armazenados como eventos de registo na tabela de registos.
• Prefixo de tabela (usado durante a versão de Pré-visualização Pública e subsequentes): O destino de rastreio do experimento é um caminho composto por três partes (catalog.schema.table_prefix). Os dados de traço são armazenados em tabelas com namespace de prefixo, como <table_prefix>_otel_spans, e as anotações possuem uma tabela própria.

Se o seu esquema do Catálogo Unity contiver tabelas nomeadas mlflow_experiment_trace_otel_spans e mlflow_experiment_trace_otel_logs, o seu experimento utiliza o formato mais antigo ligado ao esquema e é elegível para migração.

Pré-requisitos

• Um espaço de trabalho com Unity Catalog.

• Um cluster Azure Databricks a executar Databricks Runtime 15.3 ou superior.

• O pacote databricks-agents Python:

  pip install "databricks-agents>=1.10.0"
  

• As seguintes permissões:

  • USE_CATALOG e USE_SCHEMA no catálogo e esquema de origem.
  • USE_CATALOG, USE_SCHEMA, e MODIFY no catálogo e no esquema de destino.

Passo 1: Criar uma experiência de destino

Crie um experimento associado a uma localização de prefixo de tabela do Unity Catalog. Os registos migrados estão armazenados aqui. Para detalhes completos da configuração, veja Configuração: Criar um experimento com uma localização de rastreio no Unity Catalog.

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

Guarda o ID do experimento. Use-o para configurar os seus notebooks, tarefas ou modelos implementados para registar traços para a nova localização de destino.

Passo 2: Alterar a configuração de registo de traços e parar as operações de escrita na experiência de origem

Atualize os seus cadernos, trabalhos ou modelos implementados para registar traços para o novo experimento criado no Passo 1. Isto garante que os novos registos vão diretamente para as tabelas de destino.

Se quiseres fazer um ensaio a seco primeiro, podes saltar este passo e executar a migração sem mudar as cargas de trabalho de produção.

Passo 3: Executar a migração

Num caderno Azure Databricks no cluster, execute o seguinte:

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 marcadores:

• <source_catalog>.<source_schema>: O catálogo e esquema do Unity Catalog onde estão armazenadas as suas tabelas de traço de origem.
• <destination_catalog>.<destination_schema>.<table_prefix>: O catálogo, esquema e prefixo da tabela do Unity Catalog para o destino. Isto deve corresponder à localização configurada no Passo 1.

A migração é idempotente. Se falhar a meio do processo (por exemplo, devido a um timeout do cluster), podes reexecutá-lo em segurança. As linhas já migradas são saltadas automaticamente.

Uma vez concluída a migração, os seus rastos ficam disponíveis no novo experimento de destino. As tabelas de origem não são modificadas pela migração e podem ser mantidas como backup.