Özel modelin verilerini Unity Kataloğu'na kalıcı olarak kaydetme

Bu sayfada, özel model sunum uç noktalarınızdan gelen OpenTelemetry günlüklerini, izlerini ve metriklerini Unity Catalog tablolarına kalıcı olarak depolamak için uç nokta telemetrisinin nasıl yapılandırılacağı gösterilmektedir. Kök neden analizi gerçekleştirmek, uç nokta durumunu izlemek ve standart SQL sorguları ile uyumluluk gereksinimlerini karşılamak için kalıcı telemetri verilerini kullanın.

Gereksinimler

Unity Kataloğu için çalışma alanınızın etkinleştirilmesi gerekir. Varsayılan depolama (Arclight) desteklenmez.
Günlüklerin depolandığı hedef Unity Kataloğu kataloğu ve şemasında USE CATALOG, USE SCHEMA, CREATE TABLE ve MODIFY izinlerine sahip olmanız gerekir.
Uç noktaya hizmet veren mevcut bir özel model veya uç noktaya hizmet veren aracı ya da oluşturma izinleri.
Çalışma alanınız desteklenen bir bölgede olmalıdır:
- canadacentral
- westus
- westus2
- southcentralus
- eastus
- eastus2
- centralus
- northcentralus
- swedencentral
- westeurope
- northeurope
- uksouth
- australiaeast
- southeastasia

1. Adım: Model kodunuzu enstrümante etme

Model kodunuza telemetri veri toplama araçları ekleyin.

Modelinize uygulama günlüğü ekleyin. Uç nokta telemetrisi standart Python logging çıkışını otomatik olarak yakalar. Temel günlük kaydı için OpenTelemetry SDK enjeksiyonu gerekmez.

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

Kök günlük düzeyi WARNING olarak ayarlanır. Günlük düzeyini değiştirmek için, Sorun Giderme bölümüne bakın.

(İsteğe bağlı) OpenTelemetry ile özelleştirilmiş metrikler ve izler aracılığıyla enstrümantasyon yapın. Temel günlüğün ötesinde özel ölçümleri ve izleri yakalamak için modelinize OpenTelemetry SDK araçlarını ekleyin. Sayaç oluşturma, kayıt yayılma alanları ve özel özniteliklerin nasıl eklendiğini gösteren eksiksiz bir örnek için aşağıdaki bölümü genişletin.

Örnek: OpenTelemetry ile özel ölçümler, yayılma alanları ve model günlüğü

Uyarı

Model serileştirmedeki sınırlamalar nedeniyle, hatalardan kaçınmak için modelinizi ayrı bir dosyaya kaydetmeniz gerekir. Bu işlem aşağıda %%writefile return_input_model.py kullanılarak gösterilmiştir.

%%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())

Modeli günlük kayıt yapın ve kaydedin.

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

2. Adım: Unity Kataloğu hedefini hazırlama

Uç noktanızı oluşturmadan önce, telemetri verilerini almaya hazır bir kataloğunuz ve şemanız olduğundan emin olun. Azure Databricks, henüz mevcut olmayan gerekli tabloları bu şemada otomatik olarak oluşturur.

Katalog Gezgini'nde, kullanmak istediğiniz kataloğa ve şemaya gidin (örneğin, my_catalog.observability).
Eğer zaten bir hedef şemanız veya kataloğunuz yoksa, telemetri tablolarını tutmak için bir şema veya katalog oluşturun. Örneğin:
```
CREATE CATALOG IF NOT EXISTS my_catalog;
CREATE SCHEMA IF NOT EXISTS my_catalog.observability;
```
Kimlik etkinleştiren telemetri cihazının hedef katalog ve şema üzerinde , USE CATALOG, USE SCHEMA, ve CREATE TABLE ayrıcalıklarına sahip MODIFYolduğundan emin olun. Bu ayrıcalıklar, Azure Databricks'in telemetri tablolarını otomatik olarak oluşturup yazabilmesi için gereklidir. Ayrıca , ayrıcalıkları verebilirsiniz, örneğin:
```
GRANT USE CATALOG ON CATALOG my_catalog TO `<principal>`;
GRANT USE SCHEMA, CREATE TABLE, MODIFY ON SCHEMA my_catalog.observability TO `<principal>`;
```

3. Adım: Uç nokta telemetrisini etkinleştirme

Yeni bir uç nokta oluştururken telemetriyi etkinleştirebilir veya mevcut bir uç noktaya ekleyebilirsiniz.

Yeni uç nokta

Kullanıcı arabiriminde telemetriyi etkinleştirmek için:

Sol kenar çubuğunda Hizmet Verme'ye gidin.
Sunum uç noktası oluştur'a tıklayın.
Gelişmiş seçenekler'i genişletin, AI Gateway bölümüne gidin ve Çıkarım tablolarını ve telemetriyi etkinleştir'i seçin.
Unity Kataloğu konumu: 2. adımda hazırlanan hedef Kataloğu ve Şemayı seçin.
(İsteğe bağlı) Tablo ön eki: Oluşturulan tablolar için bir ön ek girin. Boş bırakılırsa ön ek olmaz. Tablolar , <prefix>_otel_logsve <prefix>_otel_spansolarak adlandırılır<prefix>_otel_metrics.
Uç nokta yapılandırmasının geri kalanını (Model seçimi, İşlem ayarları) tamamlayın ve Oluştur'a tıklayın.

Bunu API ile yapmak için:

API kullanarak telemetriyi etkinleştirme

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"
    },
    "inference_table_config": {
      "sampling_fraction": 0.1
    }
  }
}'

inference_table_config.sampling_fraction isteğe bağlıdır ve çıkarım tablosuna günlüğe kaydedilen isteklerin oranını belirler (0 ile 1 arasında bir değer; varsayılan değer 1'dir ve tüm isteklerin günlüğe kaydedilmesini sağlar). Bunu yalnızca aynı table_names içinde telemetry_config ile birlikte ayarlayın. sampling_fraction parametresi, table_names tarafından seçilen çıkarım tablosunu ayarlar ve tek başına hiçbir etkisi yoktur. Örnekleme davranışı hakkında ayrıntılı bilgi için bkz. Yük örnekleme.

Mevcut uç nokta

Uyarı

Güncelleştirme yeni bir dağıtımı tetikler. Dağıtım tamamlandıktan sonra değişiklikler geçerli olur.

Kullanıcı arabiriminde telemetriyi etkinleştirmek için:

Uç nokta görünümü sayfasındaki AI Gateway bölümünde AI Ağ GeçidiniDüzenle'ye tıklayın, ardından Çıkarım tablolarını ve telemetrisini etkinleştir'i seçin.
Unity Kataloğu konumu: 2. adımda hazırlanan hedef Kataloğu ve Şemayı seçin.
(İsteğe bağlı) Tablo ön eki: Oluşturulan tablolar için bir ön ek girin. Boş bırakılırsa ön ek olmaz. Tablolar , <prefix>_otel_logsve <prefix>_otel_spansolarak adlandırılır<prefix>_otel_metrics.
Güncelleştir'itıklayın.

4. Adım: Telemetri verilerini doğrulama ve sorgulama

Uç nokta trafiği aldıktan sonra, telemetri verileri yapılandırılmış Unity Kataloğu tablolarına akışla aktarılır.

Katalog Gezgini'ne veya SQL Düzenleyicisi'ne gidin.
Yapılandırılan şemanızda adlı <prefix>_otel_logs tabloyu bulun.
Verilerin aktığını doğrulamak için bir sorgu çalıştırın:
```
SELECT * FROM <catalog>.<schema>.<prefix>_otel_logs
LIMIT 10;
```

Telemetri verilerini sorgulama

Aşağıdaki örneklerde yaygın sorgular gösterilmektedir.

Herhangi bir telemetri tablosunun tam şemasını görüntülemek için şunu çalıştırın:

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

Telemetri verilerini filtrelemek ve ilişkilendirmek için şu sütunları kullanın:

timestamp
severity_text
body
trace_id
span_id
attributes — olaya özgü meta verileri içeren bir harita.

Son bir saat içindeki hataları denetleme

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;

Sorun giderme

Günlükler tabloda görünmüyor: Ek yükü azaltmak için WARNING kök günlük düzeyi varsayılan olarak olarak kullanılır. Daha düşük önem derecesindeki günlükleri yakalamak için model kodunuzdaki düzeyi değiştirin:

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)

Sınırlamalar

Uç nokta telemetrisi için aşağıdaki sınırlar geçerlidir:

Hedef tablodaki şema evrimi desteklenmez.
Yalnızca yönetilen Delta tabloları desteklenir. Dış depolama alanı ve Arclight varsayılan depolaması desteklenmez.
Tablo konumu çalışma alanınızla aynı bölgede olmalıdır.
Yalnızca ASCII harf, rakam ve alt çizgi içeren tablo adları desteklenir.
Hedef tabloyu yeniden oluşturmak desteklenmez.
Yalnızca tek kullanılabilirlik alanı (single-az) dayanıklılığı desteklenir.
Teslimat en az bir kez yapılır. Sunucudan alınan bir onay, kaydın dayanıklı ve Delta tablosunda olduğu anlamına gelir.
Kayıtların her birinin 10 MB'tan az olması gerekir.
İsteklerin her birinin 30 MB'tan az olması gerekir.
Log satırlarının her birinin 1 MB'tan az olması gerekir.
Telemetri gecikme süresi 2500 QPS'nin ötesine düşer.
Günlükler, Unity Kataloğu tablosunda gönderildikten birkaç saniye sonra görüntülenir.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-31