Manter o modelo personalizado que fornece dados para o Catálogo do Unity

Esta página mostra como configurar a telemetria de ponto de extremidade para persistir logs, rastreamentos e métricas do OpenTelemetry de seus pontos de extremidade do serviço de modelo do Unity Catalog. Utilize os dados de telemetria persistentes e armazenados para realizar a análise de causa raiz, monitorar a saúde do ponto final e atender aos requisitos de conformidade com consultas SQL padronizadas.

Requisitos

O seu workspace precisa estar habilitado para o Unity Catalog. Não há suporte para o armazenamento padrão (Arclight).
Você deve ter permissões USE CATALOG, USE SCHEMA, CREATE TABLE e MODIFY no catálogo do Unity Catalog e no esquema de destino em que os logs são armazenados.
Um ponto de extremidade do serviço de modelo personalizado existente ou ponto de extremidade do serviço de agente, ou permissões para criar um.
Seu workspace deve estar em uma região com suporte:
- canadacentral
- westus
- westus2
- southcentralus
- eastus
- eastus2
- centralus
- northcentralus
- swedencentral
- westeurope
- northeurope
- uksouth
- australiaeast
- southeastasia

Etapa 1: Instrumentar o código do modelo

Adicione instrumentação ao código do modelo para capturar a telemetria.

Adicione o registro em log do aplicativo ao seu modelo. A telemetria de endpoints captura automaticamente a saída padrão do Python logging. Nenhuma instrumentação do SDK do OpenTelemetry é necessária para registro em log básico.

import logging

class MyCustomModel(mlflow.pyfunc.PythonModel):
    def predict(self, context, model_input):
        # This log will be persisted to the <prefix>_otel_logs table
        logging.warning("Received inference request")

        try:
            # Your model logic here
            result = model_input * 2
            return result
        except Exception as e:
            # Error logs are also captured with severity 'ERROR'
            logging.error(f"Inference failed: {e}")
            raise e

O nível de log raiz é definido como WARNING. Consulte Resolução de Problemas para alterar o nível de registro de log.

(Opcional) Instrumentar métricas e rastreamentos personalizados com o OpenTelemetry. Para capturar métricas e rastreamentos personalizados além do log básico, adicione a instrumentação do SDK do OpenTelemetry ao seu modelo. Expanda a seção a seguir para obter um exemplo completo que mostra como criar contadores, intervalos de registros e anexar atributos personalizados.

Exemplo: Métricas personalizadas, intervalos e registro em log de modelo com OpenTelemetry

Observação

Devido a limitações na serialização de modelo, você deve salvar seu modelo em um arquivo separado antes de registrar o log para evitar erros, como mostrado abaixo usando %%writefile return_input_model.py.

%%writefile return_input_model.py
import os

import mlflow
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.metrics import get_meter, set_meter_provider
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import get_tracer, set_tracer_provider

# highlight-start
# ---- OTel initialization (per-worker) ----
resource = Resource.create({
    "worker.pid": str(os.getpid()),
})

otlp_trace_exporter = OTLPSpanExporter()
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(BatchSpanProcessor(otlp_trace_exporter))
set_tracer_provider(tracer_provider)

otlp_metric_exporter = OTLPMetricExporter()
metric_reader = PeriodicExportingMetricReader(otlp_metric_exporter)
meter_provider = MeterProvider(metric_readers=[metric_reader], resource=resource)
set_meter_provider(meter_provider)

_tracer = get_tracer(__name__)
_meter = get_meter(__name__)
_prediction_counter = _meter.create_counter(
    name="prediction_count",
    description="Number of predictions made",
    unit="1"
)
# highlight-end


class ReturnInputModel(mlflow.pyfunc.PythonModel):
    def load_context(self, context):
        # highlight-start
        self.tracer = _tracer
        self.prediction_counter = _prediction_counter
        # highlight-end

    def predict(self, context, model_input):
        # highlight-next-line
        with self.tracer.start_as_current_span("ReturnInputModel.predict") as span:
            # highlight-next-line
            span.set_attribute("input_shape", str(model_input.shape))
            # highlight-next-line
            span.set_attribute("input_columns", str(list(model_input.columns)))
            # highlight-next-line
            self.prediction_counter.add(1)
            return model_input

mlflow.models.set_model(ReturnInputModel())

Registre e faça log do modelo.

import pandas as pd
import mlflow
from mlflow.models import infer_signature

# Prepare tabular input/output for signature (pyfunc expects DataFrame)
input_df = pd.DataFrame({"inputs": ["hello world"]})
output_df = input_df.copy()  # model returns input unchanged

# Log the model with OpenTelemetry dependencies (using code-based logging to avoid serialization issues)
with mlflow.start_run():
    signature = infer_signature(input_df, output_df)

    model_info = mlflow.pyfunc.log_model(
        name="model",
        python_model="return_input_model.py",
        signature=signature,
        input_example=input_df,
        pip_requirements=[
            "mlflow==3.1",
            # highlight-next-line
            "opentelemetry-sdk",
            # highlight-next-line
            "opentelemetry-exporter-otlp-proto-http",
        ],
    )

# Register with express deployment environment packing
# Use Unity Catalog name: catalog.schema.model_name
registered = mlflow.register_model(
    model_info.model_uri,
    MODEL_NAME,
    env_pack="databricks_model_serving"
)

Etapa 2: Configurar o destino do Unity Catalog

Antes de criar seu ponto de extremidade, confirme se você tem um catálogo e um esquema prontos para receber os dados de telemetria. O Azure Databricks criará automaticamente as tabelas necessárias nesse esquema se elas ainda não existirem.

No Catalog Explorer, navegue até o catálogo e o esquema que você deseja usar (por exemplo, my_catalog.observability).

Etapa 3: Habilitar a telemetria do ponto de extremidade

Você pode habilitar a telemetria ao criar um novo ponto de extremidade ou adicioná-lo a um existente.

Novo ponto de extremidade

Para habilitar a telemetria na interface do usuário:

Navegue até Serviço na barra lateral esquerda.
Clique em Criar endpoint de serviço.
Expanda opções avançadas, vá para a seção Gateway de IA e selecione Habilitar tabelas de inferência e telemetria.
Local do Catálogo do Unity: selecione o catálogo de destino e o esquema preparados na etapa 2.
(Opcional) Prefixo da tabela: insira um prefixo para as tabelas geradas. Se deixado em branco, não haverá nenhum prefixo. As tabelas são nomeadas <prefix>_otel_logs, <prefix>_otel_spanse <prefix>_otel_metrics.
Conclua o restante da configuração do ponto de extremidade (seleção de modelo, configurações de computação) e clique em Criar.

Para fazer isso com a API:

Habilitar a telemetria usando a API

curl -X POST -H "Authorization: Bearer <your-token>" \
https://<workspace-url>/api/2.0/serving-endpoints \
-d '{
  "name": "my-custom-logging-endpoint",
  "config": {
    "served_entities": [
      {
        "name": "my-model",
        "entity_name": "my-model",
        "entity_version": "1",
        "workload_size": "Small",
        "scale_to_zero_enabled": true
      }
    ]
  },
  "telemetry_config": {
    "table_names": {
      "logs_table": "my_catalog.observability.custom_endpoint_logs",
      "metrics_table": "my_catalog.observability.custom_endpoint_metrics",
      "traces_table": "my_catalog.observability.custom_endpoint_spans"
    }
  }
}'

Ponto de extremidade existente

Observação

A atualização dispara uma nova implantação. As alterações entrarão em vigor quando a implantação for concluída.

Para habilitar a telemetria na interface do usuário:

Na página de visualização do endpoint, na seção Gateway de IA, clique em Editar Gateway de IA e selecione Ativar tabelas de inferência e telemetria.
Local do Catálogo do Unity: selecione o catálogo de destino e o esquema preparados na etapa 2.
(Opcional) Prefixo da tabela: insira um prefixo para as tabelas geradas. Se deixado em branco, não haverá nenhum prefixo. As tabelas são nomeadas <prefix>_otel_logs, <prefix>_otel_spanse <prefix>_otel_metrics.
Clique em Atualizar.

Etapa 4: Verificar e consultar dados de telemetria

Depois que o ponto de extremidade recebe tráfego, os dados de telemetria são enviados para as tabelas configuradas no Unity Catalog.

Acesse o Gerenciador de Catálogos ou o Editor do SQL.
Localize a tabela nomeada <prefix>_otel_logs no esquema configurado.

Execute uma consulta para verificar se os dados estão fluindo:

SELECT * FROM <catalog>.<schema>.<prefix>_otel_logs
LIMIT 10;

Consultar dados de telemetria

Os exemplos a seguir mostram consultas comuns.

Para exibir o esquema completo de qualquer tabela de telemetria, execute:

DESCRIBE TABLE <catalog>.<schema>.<prefix>_otel_logs;

Use estas colunas para filtrar e correlacionar dados de telemetria:

timestamp
severity_text
body
trace_id
span_id
attributes — um mapa que contém metadados específicos do evento.

Verificar se há erros na última hora

SELECT
  timestamp,
  severity_text,
  body,
  attributes
FROM <catalog>.<schema>.<prefix>_otel_logs
WHERE
  severity_text = 'ERROR'
  AND timestamp > current_timestamp() - INTERVAL 1 HOUR
ORDER BY timestamp DESC;

Solução de problemas

Logs não estão aparecendo na tabela: o nível de registro em log raiz é definido como padrão WARNING para reduzir a sobrecarga. Para capturar logs de gravidade inferior, altere o nível no código do modelo:

class MyModel(mlflow.pyfunc.PythonModel):
    def load_context(self, context):
        root = logging.getLogger()
        root.setLevel(logging.DEBUG)
        for handler in root.handlers:
            handler.setLevel(logging.DEBUG)

Limitações

Os seguintes limites se aplicam à telemetria do ponto de extremidade:

Não há suporte para a evolução do esquema na tabela de destino.
Há suporte apenas para tabelas Delta gerenciadas. Não há suporte para armazenamento externo e armazenamento padrão do Arclight.
O local da tabela deve estar na mesma região que seu workspace.
Há suporte apenas para nomes de tabela com letras ASCII, dígitos e sublinhados.
A recriação de uma tabela de destino não é compatível.
Apenas a durabilidade de zona de disponibilidade única (single-az) é compatível.
A entrega é pelo menos uma. Uma confirmação do servidor significa que o registro é durável e está na tabela Delta.
Os registros devem ter menos de 10 MB cada.
As solicitações devem ter menos de 30 MB cada.
As linhas de log devem ter menos de 1 MB cada.
A latência de telemetria degrada além de 2500 QPS.
Os logs aparecem na tabela do Unity Catalog alguns segundos depois de serem emitidos.

Comentários

Esta página foi útil?

Last updated on 2026-07-06