将自定义模型的服务数据持久化到 Unity Catalog

本页演示如何配置终结点遥测,以便将 OpenTelemetry 日志、跟踪和指标从 自定义模型服务终结点 保存到 Unity 目录表。 使用持久化遥测数据执行根本原因分析、监视终结点运行状况,以及满足标准 SQL 查询的符合性要求。

要求

  • 你的工作区必须启用 Unity Catalog。 默认存储不被支持。

  • 必须对存储日志的目标 Unity Catalog 目录和架构分别具有 USE CATALOG、USE SCHEMA、CREATE TABLE 和 MODIFY 权限。

  • 现有的自定义模型服务端点或代理服务端点,或创建其中一种端点的权限。

  • 工作区必须位于受支持的区域中:

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

步骤 1:设置模型代码

将监控功能添加到您的模型代码中,以收集遥测数据。

  1. 将应用程序日志记录添加到模型。 终结点遥测会自动捕获标准 Python logging 输出。 基本日志记录无需使用 OpenTelemetry SDK 进行instrumentation。

    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
    

    根日志记录级别设置为 WARNING。 请参阅 “故障排除 ”以更改日志记录级别。

  2. (可选)使用 OpenTelemetry 来仪表化自定义指标和追踪。 若要在基本日志记录之外捕获自定义指标和跟踪,请将 OpenTelemetry SDK 工具添加到您的模型中。 展开以下部分,获取演示如何创建计数器、记录范围和附加自定义属性的完整示例。

    方括号图标。 示例:使用 OpenTelemetry 进行自定义指标、跨度和模型日志记录

    注释

    由于模型序列化的限制,为避免错误,您必须在记录日志前将模型写入单独的文件,如下所示使用 %%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())
    
  3. (可选)记录每个请求的自定义数据。 为了持久化每个请求的数据,比如中间分数,每个请求都发送一条OpenTelemetry日志记录。 记录作为表中的 <prefix>_otel_logs 一行存储。

    OpenTelemetry 导出器通过 HTTP 将每条记录发送到端点 pod 中的遥测采集器,收集器再将其传递到 Unity Catalog,超出你的模型进程。 端点为你的模型容器设置 OTEL_EXPORTER_OTLP_ENDPOINT 和 OTEL_EXPORTER_OTLP_PROTOCOL (http/protobuf),所以导出器不需要配置。 用HTTP导出器,不要用gRPC导出器。

    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
    

    要读取记录,请按 event_name 筛选:

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

    对于每个请求的数据,不要从模型代码中调用像 Zerobus Ingest SDK 这样的摄取 SDK。 如果服务缓慢或不可用,这些调用可能会阻塞模型运行。 而 OpenTelemetry 则是你的模型只把记录交给本地采集器,所以缓慢或不可用的接收服务会延迟送达,但不会阻塞请求。 此外,对于在每个请求上发出的记录,请避免使用 Python logging。

  4. 记录并注册模型。

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

步骤 2:准备 Unity Catalog 目标

在创建终结点之前,请确保已准备好一个目录和架构来接收遥测数据。 Azure Databricks 会自动在此架构中创建必要的表(如果它们尚不存在)。

  1. 在目录资源管理器中,导航到要使用的目录和架构(例如)。 my_catalog.observability

  2. 如果你还没有目标模式或目录, 可以创建一个模式 或 目录来存放遥测表。 例如:

    CREATE CATALOG IF NOT EXISTS my_catalog;
    CREATE SCHEMA IF NOT EXISTS my_catalog.observability;
    
  3. 确保启用遥测功能的身份对目标目录和架构拥有 USE CATALOG、USE SCHEMA、CREATE TABLE 和 MODIFY 权限。 这些权限是必要的,以便 Azure Databricks 能够自动创建并写入遥测表。 你也可以 授予这些特权,例如:

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

步骤 3:启用终结点遥测

创建新终结点或将其添加到现有终结点时,可以启用遥测。

新终结点

若要在 UI 中启用遥测数据,请执行以下操作:

  1. 导航到左侧栏中的服务。
  2. 单击“创建服务终结点”。
  3. 展开 “高级”选项,转到 “AI 网关 ”部分,然后选择“ 启用推理表和遥测”。
  4. Unity 目录位置:选择步骤2中准备的目标 目录 和 模式 。
  5. (可选) 表前缀:输入生成的表的前缀。 如果留空,则没有前缀。 表的名称<prefix>_otel_logs<prefix>_otel_spans和<prefix>_otel_metrics。
  6. 完成终结点配置的其余部分(模型选择、计算设置),然后单击“ 创建”。

若要使用 API 执行此操作,请执行以下操作:

方括号图标。 使用 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"
    },
    "inference_table_config": {
      "sampling_fraction": 0.1
    }
  }
}'

inference_table_config.sampling_fraction 是可选的,控制记录在推理表中的请求比例(值介于0和1之间;默认值为1,记录所有请求)。 仅在同一个 table_names 中将其与 telemetry_config 一起设置。 该 sampling_fraction 参数调整所选 table_names 的推理表,并对其本身没有影响。 有关采样行为的详细信息,请参阅 负载采样。

现有端点

注释

更新会触发新的部署。 部署完成后,更改将生效。

若要在 UI 中启用遥测数据,请执行以下操作:

  1. 在“终结点视图”页的 “AI 网关 ”部分中,单击“ 编辑 AI 网关”,然后选择“ 启用推理表和遥测”。
  2. Unity Catalog 位置:选择步骤 2 中准备的目标 目录 和 模式。
  3. (可选) 表前缀:输入生成的表的前缀。 如果留空,则没有前缀。 表的名称<prefix>_otel_logs<prefix>_otel_spans和<prefix>_otel_metrics。
  4. 单击“ 更新”。

步骤 4:验证和查询遥测数据

终结点收到流量后,遥测数据会被传输到配置好的 Unity Catalog 表中。

  1. 转到 目录资源管理器 或 SQL 编辑器。

  2. 找到在配置的架构中命名 <prefix>_otel_logs 的表。

  3. 运行查询以验证数据是否流动:

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

查询遥测数据

以下示例显示了常见查询。

若要查看任何遥测表的完整架构,请运行:

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

使用这些列筛选和关联遥测数据:

  • timestamp
  • severity_text
  • body
  • trace_id
  • span_id
  • attributes —— 一个包含特定事件元数据的映射。

检查过去一小时内的错误

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;

故障排除

日志未显示在表中:根日志记录级别默认为 WARNING,以降低开销。 若要捕获低严重性日志,请更改模型代码中的级别:

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)

局限性

以下限制适用于终结点遥测:

  • 不支持目标表的模式演进。

  • 仅支持托管 Delta 表。 不支持外部存储和默认存储。

  • 表位置必须与工作区位于同一区域。

  • 仅支持包含 ASCII 字母、数字和下划线的表名。

  • 不支持重新创建目标表。

  • 仅支持单可用区(single-az)持久性。

  • 数据投递采用“至少一次”模式。 服务器的确认意味着记录是持久记录,并且位于 Delta 表中。

  • 每个记录必须小于 10 MB。

  • 每个请求必须小于 30 MB。

  • 日志行必须小于 1 MB。

  • 遥测延迟恶化至超过 2500 QPS。

  • 发出日志数秒后,日志会显示在 Unity 目录表中。