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

Migrar tabelas de rastreamento legadas do Unity Catalog para o formato de prefixo de tabela

Se você configurou um experimento do MLflow para armazenar rastreamentos no Unity Catalog usando o formato antigo vinculado ao esquema (catalog.schema), migre esses rastreamentos para o formato atual de prefixo de tabela (catalog.schema.table_prefix).

A Databricks recomenda o formato de prefixo de tabela para todas as cargas de trabalho de rastreamento UC, novas e existentes. Ele oferece consultas de intervalo de tempo mais rápidas, tipos de atributos mais ricos, uma tabela de anotações dedicada e suporte para vários destinos de rastreamento por esquema.

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

Identifique experimentos que utilizam o formato antigo.​

Os experimentos que armazenam rastros no Unity Catalog usam um dos dois formatos a seguir:

  • Vinculado ao esquema (formato antigo): O destino do rastreamento do experimento é um caminho de duas partes (catalog.schema). Os dados de rastreamento são armazenados em tabelas com nome fixo, como mlflow_experiment_trace_otel_spans e mlflow_experiment_trace_otel_logs. Tags, avaliações e metadados são armazenados como eventos de log na tabela Logs.
  • Prefixo da tabela (formato atual): o destino do rastreamento do experimento é um caminho de três partes (catalog.schema.table_prefix). Os dados de rastreamento são armazenados em tabelas com prefixo de namespace como <table_prefix>_otel_spans, e as anotações têm uma tabela dedicada.

Se o seu esquema Unity Catalog contiver tabelas com os nomes mlflow_experiment_trace_otel_spans e mlflow_experiment_trace_otel_logs, o seu experimento usa o formato vinculado ao esquema mais antigo e é elegível para migração.

Pré-requisitos​

  • Um workspace compatível com o Catálogo Unity.

  • Um cluster Databricks executando Databricks Runtime 15.3 ou superior.

  • O pacote Python databricks-agents :

    Bash
    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 esquema de destino .

o passo 1: Criar um experimento de destino​

Crie um experimento vinculado a um local com prefixo de tabela Unity Catalog . Os rastros migrados são armazenados aqui. 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"Experiment ID: {experiment.experiment_id}")

Salve o ID do experimento. Utilize-o para configurar seus modelos de Notebook, Job ou Implant para log rastreamentos no novo destino.

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

Atualize seus modelos de Notebook, Job ou Implant para log rastreamentos do novo experimento criado na etapa 1. Isso garante que os novos rastreamentos sejam enviados diretamente para as tabelas de destino.

importante

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

Se você quiser fazer uma execução a seco primeiro, pode pular esta etapa e executar a migração sem alterar suas cargas de trabalho de produção.

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

Em um notebook Databricks no cluster, execute o seguinte:

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 marcadores de posição:

  • <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 Unity Catalog , o esquema e o prefixo da tabela para o destino. Isso deve corresponder à localização configurada na etapa 1.

A migração é idempotente. Se a operação falhar durante o processo (por exemplo, devido a um tempo limite do cluster), você pode executá-la novamente sem problemas. As linhas já migradas são ignoradas automaticamente.

Assim que a migração for concluída, seus rastreamentos estarão 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.

Nesta página