跟踪常见问题

入门和基本用法

问：我如何开始使用 MLflow Tracing？

最简单的入门方法是使用支持库的自动追踪

import mlflow
import openai

# Enable automatic tracing for OpenAI
mlflow.openai.autolog()

# Your existing code now generates traces automatically
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello!"}]
)

对于自定义代码，使用 @mlflow.trace 装饰器

@mlflow.trace
def my_function(input_data):
    # Your logic here
    return "processed result"

问：MLflow Tracing 自动支持哪些库？

MLflow 为 20 多个流行库提供自动追踪 (autolog)。请参阅自动追踪集成处的完整列表。

问：我可以为自定义库或不支持的框架添加追踪吗？

是的，您可以使用手动追踪 API 为任何 Python 代码添加追踪

函数的装饰器

@mlflow.trace(name="Custom Operation")
def my_custom_function():
    return "result"

代码块的上下文管理器

with mlflow.start_span(name="Custom Processing") as span:
    result = custom_processing()
    span.set_outputs({"result": result})

第三方库的函数封装

traced_function = mlflow.trace(third_party_function)

用户界面和 Jupyter 集成

问：我可以直接在 Jupyter 笔记本中查看追踪吗？

是的！Jupyter 集成在 MLflow 2.20 及以上版本中可用。当以下情况发生时，追踪 UI 会自动显示在笔记本中

单元格代码生成追踪
您调用 mlflow.search_traces()
您显示追踪对象

import mlflow

# Set tracking URI to your MLflow server
mlflow.set_tracking_uri("https://:5000")


@mlflow.trace
def my_function():
    return "Hello World"


# Trace UI will appear automatically in the notebook
my_function()

要控制显示

# Disable notebook display
mlflow.tracing.disable_notebook_display()

# Enable notebook display
mlflow.tracing.enable_notebook_display()

问：如何自定义 UI 中的请求和响应预览？

您可以使用 mlflow.update_current_trace() 自定义追踪列表的“请求”和“响应”列中显示的内容

@mlflow.trace
def predict(messages: list[dict]) -> str:
    # Customize the request preview for long message histories
    custom_preview = f'{messages[0]["content"][:10]} ... {messages[-1]["content"][:10]}'
    mlflow.update_current_trace(request_preview=custom_preview)

    # Your model logic here
    result = process_messages(messages)

    # Customize response preview
    mlflow.update_current_trace(response_preview=f"Result: {result[:50]}...")
    return result

标签和元数据

问：如何向追踪添加标签？

根据您设置标签的时间，有几种方法可以添加标签

执行期间（针对活动追踪）

@mlflow.trace
def my_func(x):
    mlflow.update_current_trace(tags={"user_id": "123", "session": "abc"})
    return x + 1

完成后（针对已完成的追踪）

from mlflow.client import MlflowClient

client = MlflowClient()
client.set_trace_tag(trace_id="trace_id", key="tag_key", value="tag_value")

通过 MLflow UI：在追踪视图中点击标签旁边的铅笔图标以直接编辑它们。

问：我应该使用哪些标准 MLflow 标签？

MLflow 为常见用例提供了标准标签

mlflow.trace.user：将追踪与特定用户关联
mlflow.trace.session：将多轮对话中的追踪分组

mlflow.update_current_trace(
    tags={
        "mlflow.trace.user": "user-123",
        "mlflow.trace.session": "session-abc-456",
        "environment": "production",
        "app_version": "1.0.0",
    }
)

生产和性能

问：我可以在生产应用程序中使用 MLflow Tracing 吗？

是的，MLflow Tracing 稳定且设计用于生产环境。

在生产环境中使用 MLflow Tracing 时，我们建议使用 MLflow Tracing SDK (mlflow-tracing) 来检测您的代码/模型/代理，它具有最少的依赖项和更小的安装占用空间。该 SDK 旨在完美适用于需要高效轻量级追踪解决方案的生产环境。请参阅生产监控部分了解更多详情。

问：如何启用异步追踪日志记录？

异步日志记录可以显著减少性能开销（典型工作负载约 80%）

import mlflow

# Enable async logging
mlflow.config.enable_async_logging()

# Traces will be logged asynchronously
with mlflow.start_span(name="foo") as span:
    span.set_inputs({"a": 1})
    span.set_outputs({"b": 2})

# Manually flush if needed
mlflow.flush_trace_async_logging()

配置选项

您可以使用以下环境变量配置异步日志记录的详细行为

环境变量	描述	默认值
`MLFLOW_ASYNC_TRACE_LOGGING_MAX_WORKERS`	最大工作线程数	`10`
`MLFLOW_ASYNC_TRACE_LOGGING_MAX_QUEUE_SIZE`	最大排队追踪数	`1000`
`MLFLOW_ASYNC_TRACE_LOGGING_RETRY_TIMEOUT`	重试超时（秒）	`500`

故障排除

问：我无法在 MLflow UI 中打开我的追踪。我该怎么办？

追踪可能无法在 MLflow UI 中查看有多种可能的原因

追踪尚未完成：如果追踪仍在收集，MLflow 无法在 UI 中显示 span。确保所有 span 都已使用“OK”或“ERROR”状态正确结束。
浏览器缓存已过时：当您将 MLflow 升级到新版本时，浏览器缓存可能包含过时数据，并阻止 UI 正确显示追踪。清除浏览器缓存 (Shift+F5) 并刷新页面。
MLflow 服务器连接：确保您的 MLflow 追踪服务器正在运行且可访问
```
mlflow ui --host 0.0.0.0 --port 5000
```
实验权限：验证您是否拥有访问包含追踪的实验的权限。

问：模型执行卡住了，我的追踪一直处于“进行中”状态。

有时模型或代理会卡在长时间运行的操作或无限循环中，导致追踪卡在“进行中”状态。

为了防止这种情况，您可以使用 MLFLOW_TRACE_TIMEOUT_SECONDS 环境变量为追踪设置超时。如果追踪超出超时，MLflow 将自动以 ERROR 状态停止追踪并将其导出到后端，以便您可以分析 span 以识别问题。默认情况下，未设置超时。

注意

超时仅适用于 MLflow 追踪。即使追踪停止，主程序、模型或代理也将继续运行。

例如，以下代码将超时设置为 5 秒，并模拟 MLflow 如何处理长时间运行的操作

import mlflow
import os
import time

# Set the timeout to 5 seconds for demonstration purposes
os.environ["MLFLOW_TRACE_TIMEOUT_SECONDS"] = "5"


# Simulate a long-running operation
@mlflow.trace
def long_running():
    for _ in range(10):
        child()


@mlflow.trace
def child():
    time.sleep(1)


long_running()

注意

MLflow 在后台线程中监视追踪执行时间和过期时间。默认情况下，此检查每秒执行一次，资源消耗可忽略不计。如果您想调整间隔，可以设置 MLFLOW_TRACE_TIMEOUT_CHECK_INTERVAL_SECONDS 环境变量。

问：我的追踪没有出现在 MLflow UI 中。可能出了什么问题？

有几个问题可能导致追踪不显示

追踪 URI 未设置：确保您的追踪 URI 已配置

import mlflow

mlflow.set_tracking_uri("https://:5000")  # or your server URL

实验未设置：确保您正在记录到正确的实验

mlflow.set_experiment("my-tracing-experiment")

追踪已禁用：检查追踪是否已启用

print(mlflow.tracing.is_tracing_enabled())  # Should return True

自动日志未调用：对于支持的库，请确保在使用前调用自动日志

mlflow.openai.autolog()  # Call before using OpenAI

多线程和并发

问：当进行多线程处理时，我的追踪会分成多个追踪。如何将它们合并为一个追踪？

由于 MLflow Tracing 依赖于 Python ContextVar，每个线程默认都有自己的追踪上下文，但通过一些额外步骤，可以为多线程应用程序生成单个追踪。

这是一个快速示例

import contextvars
import mlflow
from concurrent.futures import ThreadPoolExecutor


@mlflow.trace
def worker_function(data):
    # Worker logic here
    return process_data(data)


@mlflow.trace
def main_function(data_list):
    with ThreadPoolExecutor() as executor:
        futures = []
        for data in data_list:
            # Copy context to worker thread
            ctx = contextvars.copy_context()
            futures.append(executor.submit(ctx.run, worker_function, data))

        results = [future.result() for future in futures]
    return results

问：MLflow Tracing 是否适用于 async/await 代码？

是的，MLflow Tracing 支持异步函数。@mlflow.trace 装饰器可以与异步函数无缝协作

import asyncio
import mlflow


@mlflow.trace
async def async_function(query: str):
    # Async operations are traced normally
    result = await some_async_operation(query)
    return result


# Usage
asyncio.run(async_function("test query"))

配置和控制

问：如何临时禁用追踪？

要禁用追踪，mlflow.tracing.disable() API 将停止从 MLflow 内部收集追踪数据，并且不会向 MLflow Tracking 服务记录任何有关追踪的数据。

要启用追踪（如果曾临时禁用），mlflow.tracing.enable() API 将重新启用已检测模型的追踪功能。

import mlflow

# Disable tracing
mlflow.tracing.disable()


# Your traced functions won't generate traces
@mlflow.trace
def my_function():
    return "No trace generated"


my_function()

# Re-enable tracing
mlflow.tracing.enable()

# Now traces will be generated again
my_function()  # This will generate a trace

问：我可以在不修改代码的情况下启用/禁用应用程序的追踪吗？

是的，您可以使用环境变量和全局配置

环境变量：设置 MLFLOW_TRACING_ENABLED=false 以禁用所有追踪

export MLFLOW_TRACING_ENABLED=false
python your_app.py  # No traces will be generated

条件追踪：使用编程控制

import mlflow
import os

# Only trace in development
if os.getenv("ENVIRONMENT") == "development":
    mlflow.openai.autolog()

MLflow 运行集成

问：如何将追踪与 MLflow 运行关联起来？

如果追踪是在运行上下文中生成的，它将自动与该运行关联

import mlflow

# Create and activate an experiment
mlflow.set_experiment("Run Associated Tracing")

# Start a new MLflow Run
with mlflow.start_run() as run:
    # Traces created here are associated with the run
    with mlflow.start_span(name="Run Span") as parent_span:
        parent_span.set_inputs({"input": "a"})
        parent_span.set_outputs({"response": "b"})

然后您可以检索特定运行的追踪

# Retrieve traces associated with a specific Run
traces = mlflow.search_traces(run_id=run.info.run_id)
print(traces)

数据管理

问：如何删除追踪？

您可以使用 mlflow.client.MlflowClient.delete_traces() 方法删除追踪

from mlflow.client import MlflowClient
import time

client = MlflowClient()

# Get the current timestamp in milliseconds
current_time = int(time.time() * 1000)

# Delete traces older than a specific timestamp
deleted_count = client.delete_traces(
    experiment_id="1", max_timestamp_millis=current_time, max_traces=10
)

提示

删除追踪是一个不可逆转的过程。请确保 delete_traces API 中提供的设置符合预期的删除范围。

阅读更多关于追踪删除的信息。

问：我的追踪存储在哪里？

追踪存储在您的 MLflow 追踪后端

本地文件系统：在本地使用 mlflow ui 时，追踪存储在 mlruns 目录中

远程追踪服务器：使用远程 MLflow 服务器时，追踪存储在配置的后端（数据库 + 工件存储）

数据库：追踪元数据存储在 MLflow 追踪数据库中

工件存储：大型追踪数据可能存储在工件存储中（文件系统、S3 等）

集成与兼容性

问：MLflow Tracing 是否与其他可观察性工具兼容？

是的，MLflow Tracing 基于 OpenTelemetry 标准构建，可以与其他可观察性工具集成

OpenTelemetry 导出：将追踪导出到 OTLP 兼容系统

自定义导出器：为您的可观察性堆栈构建自定义集成

标准格式：使用行业标准追踪格式以实现互操作性

有关生产监控，请参阅生产追踪以获取集成模式。

问：我可以创建自定义手动追踪和 span 吗？

是的，MLflow 提供了全面的手动追踪功能。有关使用装饰器、上下文管理器和低级 API 手动创建追踪和 span 的详细信息，请参阅手动追踪指南。

获取帮助

问：我在哪里可以找到更多帮助或报告问题？

文档：从 MLflow Tracing 文档开始

GitHub 问题：在 MLflow GitHub 报告错误或请求功能

社区：加入 MLflow Slack 社区的讨论

Stack Overflow：搜索或提问带有 mlflow 标签的问题

Databricks 支持：对于托管 MLflow 功能，请联系 Databricks 支持

对于此处未涵盖的其他问题或议题，请查阅 MLflow 文档或联系社区。

入门和基本用法​

问：我如何开始使用 MLflow Tracing？​

问：MLflow Tracing 自动支持哪些库？​

问：我可以为自定义库或不支持的框架添加追踪吗？​

用户界面和 Jupyter 集成​

问：我可以直接在 Jupyter 笔记本中查看追踪吗？​

问：如何自定义 UI 中的请求和响应预览？​

标签和元数据​

问：如何向追踪添加标签？​

问：我应该使用哪些标准 MLflow 标签？​

生产和性能​

问：我可以在生产应用程序中使用 MLflow Tracing 吗？​

问：如何启用异步追踪日志记录？​

故障排除​

问：我无法在 MLflow UI 中打开我的追踪。我该怎么办？​

问：模型执行卡住了，我的追踪一直处于“进行中”状态。​

问：我的追踪没有出现在 MLflow UI 中。可能出了什么问题？​

多线程和并发​

问：当进行多线程处理时，我的追踪会分成多个追踪。如何将它们合并为一个追踪？​

问：MLflow Tracing 是否适用于 async/await 代码？​

配置和控制​

问：如何临时禁用追踪？​

问：我可以在不修改代码的情况下启用/禁用应用程序的追踪吗？​

MLflow 运行集成​

问：如何将追踪与 MLflow 运行关联起来？​

数据管理​

问：如何删除追踪？​

问：我的追踪存储在哪里？​

集成与兼容性​

问：MLflow Tracing 是否与其他可观察性工具兼容？​

问：我可以创建自定义手动追踪和 span 吗？​

获取帮助​

问：我在哪里可以找到更多帮助或报告问题？​