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

Armazene os rastreamentos MLflow no Unity Catalog

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

O Databricks oferece suporte ao armazenamento de rastreamentos do MLflow em tabelas do Unity Catalog usando um formato compatível com OpenTelemetry (OTEL). Por default, MLflow armazena rastreamentos organizados por experimentos no serviço do plano de controle MLflow . No entanto, armazenar rastros no Unity Catalog usando o formato OTEL oferece os seguintes benefícios:

  • O controle de acesso é gerenciado por meio do esquema Unity Catalog e das permissões de tabela, em vez de ACLs em nível de experimento. Usuários com acesso às tabelas Unity Catalog podem view todos os rastreamentos armazenados nessas tabelas, independentemente do experimento ao qual os rastreamentos pertencem.

  • Os IDs de rastreamento usam o formato URI em vez do formato tr-<UUID> , melhorando a compatibilidade com sistemas externos.

  • Armazene um número ilimitado de rastreamentos em tabelas Delta, permitindo a retenção e análise de dados de rastreamento a longo prazo. Consulte Considerações sobre desempenho.

  • Consulte dados de rastreamento diretamente usando SQL por meio de um data warehouse Databricks SQL , possibilitando análises avançadas e relatórios personalizados.

  • O formato OTEL garante compatibilidade com outros clientes e ferramentas OpenTelemetry.

Pré-requisitos​

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

  • Certifique-se de que a pré-visualização "OpenTelemetry on Databricks" esteja ativada. Veja as prévias do Gerenciador Databricks.

  • Permissões para criar catálogos e esquemas no Unity Catalog.

  • Um data warehouseDatabricks SQL com CAN USE permissões. Guarde o ID do armazém para referência futura.

  • Embora este recurso esteja em versão Beta, seu workspace deve estar em uma das seguintes regiões:

    • us-east-1
    • us-east-2
    • us-west-2
    • ca-central-1
    • ap-southeast-1
    • ap-southeast-2
    • ap-northeast-1
    • ap-northeast-2
    • ap-south-1
    • eu-central-1
    • eu-west-1
    • eu-west-2
    • sa-east-1

  • A biblioteca MLflow para Python, versão 3.11.0 ou posterior, deve estar instalada em seu ambiente:

    Bash
    pip install mlflow[databricks]>=3.11.0 --upgrade --force-reinstall

Configuração: Crie um experimento com um local de rastreamento Unity Catalog​

Execute o seguinte código para criar e vincular um experimento a um local de rastreamento Unity Catalog :

Python
# Example values for the placeholders below:
# MLFLOW_TRACING_SQL_WAREHOUSE_ID: "abc123def456" (found in SQL warehouse URL)
# experiment_name: "/Users/user@company.com/traces"
# catalog_name: "main" or "my_catalog"
# schema_name: "mlflow_traces" or "production_traces"
# table_prefix: "my_otel"

import os
import mlflow
from mlflow.entities.trace_location import UnityCatalog

mlflow.set_tracking_uri("databricks")

# Specify the ID of a SQL warehouse you have access to.
os.environ["MLFLOW_TRACING_SQL_WAREHOUSE_ID"] = "<SQL_WAREHOUSE_ID>"
# Specify the name of the MLflow Experiment to use for viewing traces in the UI.
experiment_name = "<MLFLOW_EXPERIMENT_NAME>"
# Specify the name of the Catalog to use for storing traces.
catalog_name = "<UC_CATALOG_NAME>"
# Specify the name of the Schema to use for storing traces.
schema_name = "<UC_SCHEMA_NAME>"
# Specify the name of the prefix appended to every table storing trace data.
table_prefix = "<UC_TABLE_PREFIX>"

# mlflow.set_experiment is an upsert operation
experiment = mlflow.set_experiment(
    experiment_name=experiment_name,
    trace_location=UnityCatalog(
        catalog_name=catalog_name,
        schema_name=schema_name,
        table_prefix=table_prefix,  # defaults to experiment id if not provided
    ),
)

print(f"Experiment ID: {experiment.experiment_id}")
print(experiment.trace_location.full_otel_spans_table_name)

Você também pode usar mlflow.create_experiment com o mesmo parâmetro trace_location . Ao contrário de set_experiment, create_experiment não define o experimento ativo, portanto você deve chamar set_experiment posteriormente para garantir que os rastreamentos sejam roteados para o local correto:

Python
experiment_id = mlflow.create_experiment(
    name=experiment_name,
    trace_location=UnityCatalog(
        catalog_name=catalog_name,
        schema_name=schema_name,
        table_prefix=table_prefix,
    ),
)

# trace_location is optional here since
# the experiment is already bound to the UC trace location above.
mlflow.set_experiment(experiment_id=experiment_id)

Depois de associar um experimento a um local de rastreamento UC, você não poderá reatribuir o experimento a um local de rastreamento UC diferente. No entanto, vários experimentos podem compartilhar a mesma localização de traço UC.

Verificar tabelas​

Após executar o código de configuração, quatro novas tabelas do Unity Catalog ficarão visíveis no esquema da interface do usuário do Catalog Explorer:

  • <table_prefix>_otel_annotations
  • <table_prefix>_otel_logs
  • <table_prefix>_otel_metrics
  • <table_prefix>_otel_spans

Conceder permissões​

As seguintes permissões são necessárias para que um usuário ou entidade de serviço Databricks possa ler ou gravar rastreamentos MLflow nas tabelas Unity Catalog :

  1. Permissões USE_CATALOG no catálogo.
  2. Permissões USE_SCHEMA no esquema.
  3. Permissões MODIFY e SELECT em cada uma das tabelas <table_prefix>_<type> .
nota

ALL_PRIVILEGES Não é suficiente para acessar as tabelas de rastreamento Unity Catalog . Você deve conceder explicitamente as permissões MODIFY e SELECT .

rastreia logs nas tabelas Unity Catalog​

Após criar as tabelas, você pode gravar rastreamentos nelas a partir de várias fontes, especificando o local do rastreamento. A forma de fazer isso depende da origem dos rastros.

O local de rastreamento do Unity Catalog pode ser especificado usando a API Python mlflow.set_experiment ou definindo a variável de ambiente MLFLOW_TRACING_DESTINATION .

Python
import mlflow

from mlflow.entities.trace_location import UnityCatalog

mlflow.set_tracking_uri("databricks")

# Specify the catalog, schema, and table prefix to use for storing Traces
catalog_name = "<UC_CATALOG_NAME>"
schema_name = "<UC_SCHEMA_NAME>"
table_prefix = "<UC_TABLE_PREFIX>"

# Option 1: Use the `set_experiment` API
# For existing experiments, it is not necessary to specify `trace_location`. MLflow
# retrieves the UC trace location bound to the experiment and routes traces to
# that location.
mlflow.set_experiment(
    experiment_name="...",
    trace_location=UnityCatalog(
        catalog_name=catalog_name,
        schema_name=schema_name,
        table_prefix=table_prefix,
    ),  # optional for existing experiments
)

# Option 2: Use the `MLFLOW_TRACING_DESTINATION` environment variable
import os

os.environ["MLFLOW_TRACING_DESTINATION"] = f"{catalog_name}.{schema_name}.{table_prefix}"

# Create and ingest an example trace using the `@mlflow.trace` decorator
@mlflow.trace
def test(x):
    return x + 1

test(100)

visualizar rastros na interface do usuário​

Visualize os rastros armazenados no formato OTEL da mesma forma que view outros rastros:

  1. Na sua área de trabalho, acesse Experimentos .

  2. Encontre o experimento em que seus registros são logaritmos. Por exemplo, o experimento definido por mlflow.set_experiment("/Shared/my-genai-app-traces").

  3. Clique tab "Rastreamentos " para ver uma lista de todos os registros de rastreamento desse experimento.

    Visualização da lista de rastreamento

  4. Se você armazenou seus rastreamentos em uma tabela Unity Catalog, Databricks recupera os rastreamentos usando um SQL warehouse. Selecione um SQL warehouse no menu suspenso.

Para obter mais informações sobre como usar a interface do usuário para pesquisar rastreamentos, consulte Visualizar rastreamentos na interface do usuário Databricks MLflow.

Ativar o monitoramento da produção​

Para usar o monitoramento de produção com rastreamentos armazenados no Unity Catalog, você deve configurar um ID SQL warehouse para o experimento. O terceiro trabalho requer essa configuração para executar consultas de pontuação nas tabelas Unity Catalog .

Defina o ID SQL warehouse usando set_databricks_monitoring_sql_warehouse_id():

Python
from mlflow.tracing import set_databricks_monitoring_sql_warehouse_id

# Set the SQL warehouse ID for monitoring
set_databricks_monitoring_sql_warehouse_id(
    sql_warehouse_id="<SQL_WAREHOUSE_ID>",
    experiment_id="<EXPERIMENT_ID>"  # Optional, uses active experiment if not specified
)

Alternativamente, você pode definir a variável de ambiente MLFLOW_TRACING_SQL_WAREHOUSE_ID antes de iniciar o monitoramento.

Se você pular esta etapa, o monitoramento Job falhará com um erro indicando que a tag de experimento mlflow.monitoring.sqlWarehouseId está faltando.

Para configurar o monitoramento de rastreamentos do Unity Catalog , você precisa das seguintes permissões em nível workspace :

  • CAN USE permissão no SQL warehouse
  • CAN EDIT permissão para o experimento MLflow
  • Permissão para monitoramento do trabalho (concedida automaticamente ao cadastrar o primeiro avaliador)

O monitoramento da execução do Job é feito sob a identidade do usuário que primeiro registrou um avaliador no experimento. As permissões deste usuário determinam a que o trabalho de monitoramento pode acessar.

Limitações​

  • A ingestão de rastreamentos é limitada a 200 rastreamentos por segundo por workspace e 100 MB por segundo por tabela.

  • Um experimento só pode ser vinculado a um local de rastreamento Unity Catalog no momento da criação do experimento.

  • Os rastros armazenados no Unity Catalog não são compatíveis com o Assistente de Conhecimento ou o Agente Supervisor.

  • O desempenho da interface do usuário pode ser afetado quando mais de 2 TB de dados de rastreamento são armazenados na tabela. Consulte Considerações sobre desempenho.

  • A exclusão de rastreamentos individuais não é compatível com rastreamentos armazenados no Unity Catalog. Para remover os vestígios, você deve excluir linhas diretamente das tabelas subjacentes do Unity Catalog usando SQL. Isso difere dos rastros de experimentos, que podem ser excluídos usando a interface do usuário ou a API do MLflow.

  • O servidorMLflow MCP não suporta a interação com rastreamentos armazenados no Unity Catalog.

Próximos passos​