Speichern Sie benutzerdefinierte Modelldienstdaten dauerhaft im Unity-Katalog.

Auf dieser Seite wird gezeigt, wie Sie die Endpunkttelemetrie so konfigurieren, dass OpenTelemetry-Protokolle, Ablaufverfolgungen und Metriken aus Ihrem benutzerdefinierten Modell gespeichert werden, das Endpunkte für Unity-Katalogtabellen bedient. Verwenden Sie die gespeicherten Telemetriedaten, um Die Ursachenanalyse durchzuführen, endpunktintegrität zu überwachen und die Complianceanforderungen mit standardmäßigen SQL-Abfragen zu erfüllen.

Anforderungen

  • Ihr Arbeitsbereich muss für Unity Catalog aktiviert sein. Standardspeicher wird nicht unterstützt.

  • Sie müssen über USE CATALOG, USE SCHEMA, CREATE TABLE und MODIFY Berechtigungen für den Ziel-Unity-Katalog und das Schema verfügen, in dem die Protokolle gespeichert sind.

  • Ein vorhandener benutzerdefinierter Modellbereitstellungs Endpunkt oder Agent-Bereitstellungsendpunkt oder Berechtigungen zum Erstellen solcher Endpunkte.

  • Ihr Arbeitsbereich muss sich in einer unterstützten Region befinden:

    • canadacentral
    • westus
    • westus2
    • southcentralus
    • eastus
    • eastus2
    • centralus
    • northcentralus
    • swedencentral
    • westeurope
    • northeurope
    • uksouth
    • australiaeast
    • southeastasia

Schritt 1: Einrichten des Modellcodes

Fügen Sie dem Modellcode Instrumentierung hinzu, um Telemetrie zu erfassen.

  1. Fügen Sie Ihrem Modell Anwendungsprotokollierung hinzu. Endpunkt-Telemetrie erfasst automatisch die standardmäßige Python-Ausgabe logging . Für die grundlegende Protokollierung ist keine OpenTelemetry SDK-Instrumentierung erforderlich.

    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
    

    Die Stammprotokollierungsebene ist auf WARNING gesetzt. Informationen zum Ändern der Protokollierungsebene finden Sie unter "Problembehandlung ".

  2. (Optional) Instrumentieren Sie benutzerdefinierte Metriken und Traces mit OpenTelemetry. Um benutzerdefinierte Metriken und Ablaufverfolgungen über die grundlegende Protokollierung hinaus zu erfassen, fügen Sie Ihrem Modell die OpenTelemetry SDK-Instrumentierung hinzu. Erweitern Sie den folgenden Abschnitt für ein vollständiges Beispiel, in dem gezeigt wird, wie Zähler, Datensatzspannen und benutzerdefinierte Attribute erstellt werden.

    Symbol für eckige Klammern. Beispiel: Benutzerdefinierte Metriken, Spans und Modellprotokollierung mit OpenTelemetry

    Hinweis

    Aufgrund von Einschränkungen bei der Modellserialisierung müssen Sie Ihr Modell mit %%writefile return_input_model.py in eine separate Datei schreiben, bevor Sie es protokollieren, um Fehler zu vermeiden, wie unten gezeigt.

    %%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())
    
  3. (Optional) Protokollieren Sie benutzerdefinierte Daten pro Anfrage. Um Ihre eigenen Daten für jede Anfrage, wie z. B. Zwischenwerte, zu speichern, geben Sie pro Anfrage einen OpenTelemetrie-Protokolleintrag aus. Der Datensatz wird als eine einzige Zeile in der <prefix>_otel_logs Tabelle gespeichert.

    Der OpenTelemetrie-Exporter sendet jeden Datensatz über HTTP an den Telemetrie-Sammler im Pod des Endpunkts, der ihn außerhalb Ihres Modellprozesses an den Unity-Katalog liefert. Der Endpunkt setzt OTEL_EXPORTER_OTLP_ENDPOINT und OTEL_EXPORTER_OTLP_PROTOCOL (http/protobuf) für deinen Modellcontainer, sodass der Exporter keine Konfiguration benötigt. Benutze den HTTP-Exporter, nicht den gRPC-Exporter.

    import json
    
    from opentelemetry._logs import LogRecord
    from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
    from opentelemetry.sdk._logs import LoggerProvider
    from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
    
    logger_provider = LoggerProvider()
    logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
    _record_logger = logger_provider.get_logger(__name__)
    
    
    class MyCustomModel(mlflow.pyfunc.PythonModel):
        def predict(self, context, model_input):
            scores = {"model_score": 0.82, "lookup_hits": 3}
    
            # A JSON string body is much cheaper to encode than a nested dict
            _record_logger.emit(
                LogRecord(
                    event_name="prediction_details",
                    body=json.dumps(scores),
                    attributes={"model_version": "1"},
                )
            )
            return model_input
    

    Um die Datensätze zu lesen, filtern Sie auf event_name:

    SELECT timestamp, body, attributes
    FROM <catalog>.<schema>.<prefix>_otel_logs
    WHERE event_name = 'prediction_details';
    

    Für Daten pro Anfrage rufen Sie kein Ingestion SDK, wie das Zerobus Ingest SDK, aus Ihrem Modellcode auf. Wenn der Dienst langsam oder nicht verfügbar ist, können diese Anrufe dein Modell blockieren. Bei OpenTelemetry übergibt dein Modell den Datensatz nur an den lokalen Sammler, sodass ein langsamer oder nicht verfügbarer Ingestion-Service die Lieferung verzögert, aber keine Anfragen blockiert. Vermeide auch Python logging für Protokolleinträge, die du bei jeder Anfrage ausgibst.

  4. Protokollieren und registrieren Sie das Modell.

    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>=1.37.0",
                # highlight-next-line
                "opentelemetry-exporter-otlp-proto-http>=1.37.0",
            ],
        )
    
    # Use Unity Catalog name: catalog.schema.model_name
    registered = mlflow.register_model(
        model_info.model_uri,
        MODEL_NAME,
    )
    

Schritt 2: Vorbereiten des Unity-Katalogziels

Stellen Sie vor dem Erstellen Ihres Endpunkts sicher, dass Sie über einen Katalog und ein Schema verfügen, um die Telemetriedaten zu empfangen. Azure Databricks erstellt automatisch die erforderlichen Tabellen in diesem Schema, wenn sie noch nicht vorhanden sind.

  1. Navigieren Sie im Katalog-Explorer zu dem Katalog und Schema, das Sie verwenden möchten (z. B. my_catalog.observability).

  2. Wenn Sie noch kein Zielschema oder Katalog haben, erstellen Sie ein Schema oder einen Katalog), um die Telemetrietabellen zu speichern. Beispiel:

    CREATE CATALOG IF NOT EXISTS my_catalog;
    CREATE SCHEMA IF NOT EXISTS my_catalog.observability;
    
  3. Stellen Sie sicher, dass die Identität, die die Telemetrie aktiviert, über die Berechtigungen USE CATALOG, USE SCHEMA, CREATE TABLE und MODIFY für den Zielkatalog und das Zielschema verfügt. Diese Privilegien sind erforderlich, damit Azure Databricks automatisch die Telemetrietabellen erstellen und schreiben kann. Sie können die Privilegien auch gewähren, zum Beispiel:

    GRANT USE CATALOG ON CATALOG my_catalog TO `<principal>`;
    GRANT USE SCHEMA, CREATE TABLE, MODIFY ON SCHEMA my_catalog.observability TO `<principal>`;
    

Schritt 3: Aktivieren der Endpunkt-Telemetrie

Sie können Telemetrie aktivieren, wenn Sie einen neuen Endpunkt erstellen oder zu einem bestehenden hinzufügen.

Neuer Endpunkt

So aktivieren Sie Telemetrie auf der Benutzeroberfläche:

  1. Navigieren Sie in der linken Randleiste zu "Dienen ".
  2. Klicken Sie auf "Bereitstellungsendpunkt erstellen".
  3. Erweitern Sie erweiterte Optionen, wechseln Sie zum Abschnitt "AI-Gateway ", und wählen Sie " Rückschlusstabellen und Telemetrie aktivieren" aus.
  4. Unity Catalog-Speicherort: Wählen Sie den in Schritt 2 vorbereiteten Zielkatalog und das Schema aus.
  5. (Optional) Tabellenpräfix: Geben Sie ein Präfix für die generierten Tabellen ein. Wenn sie leer gelassen wird, gibt es kein Präfix. Die Tabellen sind benannt <prefix>_otel_logs, <prefix>_otel_spansund <prefix>_otel_metrics.
  6. Schließen Sie den Rest der Endpunktkonfiguration (Modellauswahl, Computeeinstellungen) ab, und klicken Sie auf "Erstellen".

Gehen Sie dazu mit der API wie folgt vor:

Symbol für eckige Klammern. Telemetrie über die API aktivieren
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 ist optional und steuert den Anteil der Anfragen, die in der Inferenztabelle protokolliert werden (ein Wert zwischen 0 und 1; standardmäßig ist 1, was alle Anfragen protokolliert). Legen Sie sie nur zusammen mit table_names im selben telemetry_config fest. Der sampling_fraction Parameter passt die von ihm ausgewählte table_names Ableitungstabelle an und hat keine auswirkungen auf sich selbst. Ausführliche Informationen zum Samplingverhalten finden Sie unter Payload-Sampling.

Vorhandener Endpunkt

Hinweis

Durch das Aktualisieren wird eine neue Bereitstellung ausgelöst. Änderungen werden wirksam, sobald die Bereitstellung abgeschlossen ist.

So aktivieren Sie Telemetrie auf der Benutzeroberfläche:

  1. Klicken Sie auf der Seite "Endpunktansicht" im Abschnitt "AI-Gateway" auf "KI-Gateway bearbeiten", und wählen Sie dann "Rückschlusstabellen und Telemetrie aktivieren" aus.
  2. Unity-Katalogstandort: Wählen Sie den in Schritt 2 vorbereiteten Zielkatalog und das Schema aus.
  3. (Optional) Tabellenpräfix: Geben Sie ein Präfix für die generierten Tabellen ein. Wenn sie leer gelassen wird, gibt es kein Präfix. Die Tabellen sind benannt <prefix>_otel_logs, <prefix>_otel_spansund <prefix>_otel_metrics.
  4. Klicke auf Aktualisieren.

Schritt 4: Überprüfen und Abfragen von Telemetriedaten

Nachdem der Endpunkt Datenverkehr empfängt, werden Telemetriedatenströme an die konfigurierten Unity-Katalogtabellen gesendet.

  1. Wechseln Sie zum Katalog-Explorer oder zum SQL-Editor.

  2. Suchen Sie die Tabelle, die im konfigurierten Schema benannt ist <prefix>_otel_logs .

  3. Führen Sie eine Abfrage aus, um zu überprüfen, ob Daten fließen:

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

Telemetriedaten abfragen

Die folgenden Beispiele zeigen allgemeine Abfragen.

Führen Sie Folgendes aus, um das vollständige Schema einer telemetrietabelle anzuzeigen:

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

Verwenden Sie diese Spalten, um Telemetriedaten zu filtern und zu korrelieren:

  • timestamp
  • severity_text
  • body
  • trace_id
  • span_id
  • attributes — eine Map, die ereignisspezifische Metadaten enthält.

Nach Fehlern in der letzten Stunde prüfen

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;

Problembehandlung

Logs erscheinen nicht in der Tabelle: Das Root-Logging-Level ist standardmäßig auf WARNING gesetzt, um den Overhead zu reduzieren. Zum Erfassen von Protokollen mit niedrigerem Schweregrad ändern Sie die Ebene im Modellcode:

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)

Einschränkungen

Die folgenden Grenzwerte gelten für Endpunkttelemetrie:

  • Änderungen am Schema in der Zieltabelle werden nicht unterstützt.

  • Nur verwaltete Delta-Tabellen werden unterstützt. Externer Speicher und Standardspeicher werden nicht unterstützt.

  • Die Tabellenposition muss sich in derselben Region wie Ihr Arbeitsbereich befinden.

  • Es werden nur Tabellennamen mit ASCII-Buchstaben, Ziffern und Unterstrichen unterstützt.

  • Das Erneute Erstellen einer Zieltabelle wird nicht unterstützt.

  • Es wird nur Einzelverfügbarkeitszonen-Dauerhaftigkeit (Single-AZ) unterstützt.

  • Die Lieferung erfolgt mindestens einmal. Eine Bestätigung vom Server bedeutet, dass der Datensatz dauerhaft gespeichert und in der Delta-Tabelle ist.

  • Datensätze müssen jeweils kleiner als 10 MB sein.

  • Anforderungen müssen jeweils kleiner als 30 MB sein.

  • Protokollzeilen müssen jeweils kleiner als 1 MB sein.

  • Die Telemetrielatenz verschlechtert sich jenseits von 2500 QPS.

  • Protokolle werden einige Sekunden nachdem sie ausgegeben wurden in der Unity-Katalog-Tabelle angezeigt.