将生产跟踪链接到应用版本

跟踪应用程序版本指南介绍了如何在开发过程中跟踪LoggedModel应用程序版本。

部署到 LoggedModel 生产环境时，需要将生成的跟踪与特定版本关联，以进行监控和调试。 本指南演示如何将部署配置为在生产跟踪中包含版本信息。

先决条件

1. 对于 Databricks 模型服务外部的生产部署，请安装 mlflow-tracing 包：

   pip install --upgrade "mlflow-tracing>=3.1.0"
   

   此包专门针对生产环境进行优化，提供：

   • 为更快、更精简的部署提供最少的依赖项
   • 高容量跟踪的性能优化

   注释

   生产跟踪需要 MLflow 3。 由于性能限制和生产用途缺少功能，生产部署不支持 MLflow 2.x。

2. 请按照 设置环境快速指南 创建 MLflow 试验。

环境变量配置

1. 导航到 “版本 ”选项卡以获取 LoggedModel ID。 在 CI/CD 管道中，您可以使用如下所示的方法生成一个新的LoggedModel，该方法为create_external_model()。 我们建议使用

import mlflow
import subprocess

# Define your application and its version identifier
app_name = "customer_support_agent"

# Get current git commit hash for versioning
try:
    git_commit = (
        subprocess.check_output(["git", "rev-parse", "HEAD"])
        .decode("ascii")
        .strip()[:8]
    )
    version_identifier = f"git-{git_commit}"
except subprocess.CalledProcessError:
    version_identifier = "local-dev"  # Fallback if not in a git repo

logged_model_name = f"{app_name}-{version_identifier}"

# Create a new LoggedModel
model = mlflow.create_external_model(name=logged_model_name)

2. 将 LoggedModel 生产环境配置中的 MLFLOW_ACTIVE_MODEL_ID ID 添加到环境变量中，并与快速入门设置中的标准 MLflow 跟踪变量一起使用。

# Standard MLflow tracing configuration
export DATABRICKS_HOST="https://your-workspace.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"
export MLFLOW_TRACKING_URI=databricks
# Either use MLFLOW_EXPERIMENT_NAME or MLFLOW_EXPERIMENT_ID
export MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

# Add LoggedModel version tracking by specifying your LoggedModel ID
# Ensure this matches a LoggedModel in your MLFlow Experiment
export MLFLOW_ACTIVE_MODEL_ID="customer_support_agent-git-98207f02"

自动追踪链接

应用程序代码与开发期间完全相同：

import mlflow
from fastapi import FastAPI, Request

app = FastAPI()

@mlflow.trace
def process_message(message: str) -> str:
    # Your actual application logic here
    # This is just a placeholder
    return f"Processed: {message}"

@app.post("/chat")
def handle_chat(request: Request, message: str):
    # Your traces are automatically linked to the LoggedModel
    # specified in MLFLOW_ACTIVE_MODEL_ID

    # Your application logic here
    response = process_message(message)
    return {"response": response}

若要向跟踪添加其他上下文（例如用户 ID、会话 ID 或自定义元数据），请参阅在生产跟踪指南中 向生产跟踪添加上下文 。

部署示例

码头工人

使用 Docker 进行部署时，请通过容器配置传递所有必要的环境变量：

# Dockerfile
FROM python:3.9-slim

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application code
COPY . /app
WORKDIR /app

# Declare required environment variables (no defaults)
ENV DATABRICKS_HOST
ENV DATABRICKS_TOKEN
ENV MLFLOW_TRACKING_URI
ENV MLFLOW_EXPERIMENT_NAME
ENV MLFLOW_ACTIVE_MODEL_ID

CMD ["python", "app.py"]

使用环境变量运行容器：

docker run -d \
  -e DATABRICKS_HOST="https://your-workspace.databricks.com" \
  -e DATABRICKS_TOKEN="your-databricks-token" \
  -e MLFLOW_TRACKING_URI=databricks \
  -e MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app" \
  -e MLFLOW_ACTIVE_MODEL_ID="customer_support_agent-git-98207f02" \
  -e APP_VERSION="1.0.0" \
  your-app:latest

Kubernetes （简体中文）

请使用 ConfigMaps 和 Secrets 来管理 Kubernetes 部署中的配置：

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: mlflow-config
data:
  DATABRICKS_HOST: 'https://your-workspace.databricks.com'
  MLFLOW_TRACKING_URI: 'databricks'
  MLFLOW_EXPERIMENT_NAME: '/Shared/production-genai-app'
  MLFLOW_ACTIVE_MODEL_ID: 'customer_support_agent-git-98207f02'

---
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: databricks-secrets
type: Opaque
stringData:
  DATABRICKS_TOKEN: 'your-databricks-token'

---
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: genai-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: genai-app
  template:
    metadata:
      labels:
        app: genai-app
    spec:
      containers:
        - name: app
          image: your-app:latest
          ports:
            - containerPort: 8000
          envFrom:
            - configMapRef:
                name: mlflow-config
            - secretRef:
                name: databricks-secrets
          env:
            - name: APP_VERSION
              value: '1.0.0'
          resources:
            requests:
              memory: '256Mi'
              cpu: '250m'
            limits:
              memory: '512Mi'
              cpu: '500m'

查询 Version-Specific 跟踪

部署后，可以在 MLflow 跟踪 UI 中查看跟踪，也可以按 SDK 中的模型版本查询跟踪：

import mlflow

# Get the experiment ID
experiment = client.get_experiment_by_name("/Shared/production-genai-app")

# Find all traces from a specific model version
traces = mlflow.search_traces(
    experiment_ids=[experiment.experiment_id],
    model_id="customer_support_agent-git-98207f02",
)

# View the results
print(f"Found {len(traces)} traces for this model version")

Databricks 模型服务中的跟踪链接

当你使用代理框架将 LoggedModel 部署到 Databricks 模型服务并且在开发环境中安装 MLflow 3 时，跟踪链接会自动配置。

若要查看 Databricks 模型服务端点的跟踪，请按照以下步骤操作：

1. 导航到您调用时处于活动状态的 MLflow 试验 agents.deploy()
2. 单击“ 跟踪 ”选项卡以查看跟踪
3. 所有跟踪都自动链接到提供请求的特定模型版本

唯一的要求是应用程序代码使用 MLflow 跟踪（通过自动记录或手动检测）。@mlflow.trace

后续步骤

有关完整的生产跟踪设置，包括 Databricks 模型服务外部部署的身份验证、监视和反馈收集，请参阅 生产可观测性与跟踪。