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.

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

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

• Um data warehouseDatabricks SQL. 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-west-2

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

  Bash

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

Configuração: Crie tabelas UC e vincule um experimento.

Crie as tabelas Unity Catalog para armazenar os rastreamentos. Em seguida, vincule o esquema Unity Catalog que contém as tabelas a um experimento MLflow para gravar seus rastreamentos nas tabelas por default:

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"

import os
import mlflow
from mlflow.exceptions import MlflowException
from mlflow.entities import UCSchemaLocation
from mlflow.tracing.enablement import set_experiment_trace_location

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

if experiment := mlflow.get_experiment_by_name(experiment_name):
    experiment_id = experiment.experiment_id
else:
    experiment_id = mlflow.create_experiment(name=experiment_name)
print(f"Experiment ID: {experiment_id}")

# To link an experiment to a trace location
result = set_experiment_trace_location(
    location=UCSchemaLocation(catalog_name=catalog_name, schema_name=schema_name),
    experiment_id=experiment_id,
)
print(result.full_otel_spans_table_name)

Verificar tabelas

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

• mlflow_experiment_trace_otel_logs
• mlflow_experiment_trace_otel_metrics
• mlflow_experiment_trace_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 mlflow_experiment_trace_<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 destino do rastreamento. A forma de fazer isso depende da origem dos rastros.

MLflow SDK

O catálogo e o esquema podem ser especificados usando a API Python mlflow.tracing.set_destination ou definindo a variável de ambiente MLFLOW_TRACING_DESTINATION .

Python

import mlflow

mlflow.set_tracking_uri("databricks")

# Specify the name of the catalog and schema to use for storing Traces
catalog_name = "<UC_CATALOG_NAME>"
schema_name = "<UC_SCHEMA_NAME>"

# Option 1: Use the `set_destination` API to configure the catalog and schema for
# storing MLflow Traces
from mlflow.entities import UCSchemaLocation
mlflow.tracing.set_destination(
    destination=UCSchemaLocation(
        catalog_name=catalog_name,
        schema_name=schema_name,
    )
)

# Option 2: Use the `MLFLOW_TRACING_DESTINATION` environment variable to configure the
# catalog and schema for storing MLflow Traces
import os
os.environ["MLFLOW_TRACING_DESTINATION"] = f"{catalog_name}.{schema_name}"

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

test(100)

Databricks App

Um aplicativo Databricks em execução mlflow >= 3.5.0 pode gravar rastreamentos no Unity Catalog, desde que a entidade de serviço do aplicativo Databricks tenha acesso às tabelas Unity Catalog .

Para conceder à entidade de serviço do seu aplicativo Databricks acesso às tabelas Unity Catalog para ingestão de rastreamento:

1. Encontre o nome da entidade de serviço do seu aplicativo na tab Autorização do aplicativo.

2. Conceda à entidade de serviço MODIFY e SELECT acesso às tabelas logs e spans .

3. Atualize o código do seu aplicativo Databricks para definir o catálogo e o esquema para ingestão de rastreamento:

   Python

   import mlflow
   
   mlflow.set_tracking_uri("databricks")
   # Specify the name of the catalog and schema to use for storing Traces
   catalog_name = "<UC_CATALOG_NAME>"
   schema_name = "<UC_SCHEMA_NAME>"
   
   # Option 1: Use the `set_destination` API to configure the catalog and schema for
   # storing MLflow Traces
   from mlflow.entities import UCSchemaLocation
   mlflow.tracing.set_destination(
       destination=UCSchemaLocation(
           catalog_name=catalog_name,
           schema_name=schema_name,
       )
   )
   
   # Option 2: Use the `MLFLOW_TRACING_DESTINATION` environment variable to configure the
   # catalog and schema for storing MLflow Traces
   import os
   os.environ["MLFLOW_TRACING_DESTINATION"] = f"{catalog_name}.{schema_name}"
   
   # Create and ingest an example trace using the `@mlflow.trace` decorator
   @mlflow.trace
   def test(x):
       return x + 1
   
   test(100)

4. implantou o aplicativo Databricks .

Model Serving endpoint

Para gravar rastreamentos de um endpoint Databricks servindo modelo em tabelas Unity Catalog , você deve configurar um token de acesso pessoal (PAT).

1. Conceda a um usuário ou entidade de serviço MODIFY e SELECT acesso às tabelas logs e spans .
2. Gere um PAT para o usuário ou entidade de serviço.
3. Adicione o PAT à variável de configuração do ambiente doDatabricks modelo endpoint, especificando DATABRICKS_TOKEN como o nome da variável de ambiente.
4. Adicione o local de rastreamento para gravar como uma string "{catalog}.{schema}" na variável de configuração de ambiente doDatabricks instalado modelo endpoint com MLFLOW_TRACING_DESTINATION como o nome da variável de ambiente:

Python

import mlflow
import os

mlflow.set_tracking_uri("databricks")

# Specify the name of the catalog and schema to use for storing Traces
catalog_name = "<UC_CATALOG_NAME>"
schema_name = "<UC_SCHEMA_NAME>"

# Option 1: Use the `set_destination` API to configure the catalog and schema for
# storing MLflow Traces
from mlflow.entities import UCSchemaLocation
mlflow.tracing.set_destination(
    destination=UCSchemaLocation(
        catalog_name=catalog_name,
        schema_name=schema_name,
    )
)

# Option 2: Use the `MLFLOW_TRACING_DESTINATION` environment variable to configure the
# catalog and schema for storing MLflow Traces
os.environ["MLFLOW_TRACING_DESTINATION"] = f"{catalog_name}.{schema_name}"

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

test(100)

3rd party OTEL client

Uma das vantagens de armazenar rastreamentos no formato OTEL é a possibilidade de gravar nas tabelas Unity Catalog usando clientes de terceiros que suportam OTEL. Os rastreamentos escritos dessa forma aparecerão em um experimento do MLflow vinculado à tabela, desde que possuam um intervalo raiz. O exemplo a seguir mostra os exportadores OTLP do OpenTelemetry.

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Span exporter configuration
otlp_trace_exporter = OTLPSpanExporter(
    # Databricks hosted OTLP traces collector endpoint
    endpoint="https://myworkspace.databricks.com/api/2.0/otel/v1/traces",
    headers={
        "content-type": "application/x-protobuf",
        "X-Databricks-UC-Table-Name": "cat.sch.mlflow_experiment_trace_otel_spans",
        "Authorization: Bearer MY_API_TOKEN"
    },
)

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.

   

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.

5. Você também pode selecionar um esquema diferente. Ao selecionar um esquema alternativo, certifique-se de que ele já contenha tabelas OpenTelemetry. O menu suspenso não cria as tabelas.

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.

Desvincular um esquema Unity Catalog

Para desvincular um esquema Unity Catalog de um experimento MLflow , clique no dropdown "Storage UC Schema" na interface do usuário do experimento MLflow e selecione "Unlink schema" .

Os registros ainda estarão presentes no esquema Unity Catalog , e o esquema poderá ser vinculado novamente ao experimento MLflow a qualquer momento.

Limitações

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

• 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.

• Ao conectar um experimento do MLflow a um esquema do Unity Catalog, somente os rastreamentos armazenados no esquema do Unity Catalog vinculado ao experimento ficam acessíveis. Os rastros preexistentes no experimento se tornarão inacessíveis para buscas a partir de clientes MLflow com Python >= 3.5.0. e a partir da interface do usuário do MLflow. Esses registros permanecem armazenados no experimento, mas não podem ser visualizados ou pesquisados enquanto o experimento estiver vinculado ao Unity Catalog.

  Desvincular o esquema do experimento MLflow restaura o acesso aos rastreamentos preexistentes.

• Limite de taxa de transferência de ingestão de 200 consultas por segundo (QPS)

Próximos passos

• Consultar rastreamentos MLflow usando SQL MLflow Databricks SQL