跟踪常见问题

入门和基本用法

问：如何开始使用 MLflow Tracing？

最简单的方法是对受支持的库进行自动跟踪

python

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 装饰器

python

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

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

MLflow 为 40 多个流行库提供自动跟踪（autolog）。请在 自动跟踪集成中查看完整列表。

用户界面和 Jupyter 集成

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

是的！MLflow 2.20 及更高版本中提供了 Jupyter 集成。当出现以下情况时，跟踪 UI 会自动显示在笔记本中

1. 单元格代码生成跟踪
2. 您调用 mlflow.search_traces()
3. 您显示一个跟踪对象

python

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

控制显示

python

# Disable notebook display
mlflow.tracing.disable_notebook_display()

# Enable notebook display
mlflow.tracing.enable_notebook_display()

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

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

python

@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 Tracing 吗？

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

在生产环境中使用 MLflow Tracing 时，我们建议使用 MLflow Tracing SDK (mlflow-tracing) 以最少的依赖项和较小的安装占地面积来检测您的代码/模型/代理。该 SDK 专为需要高效轻量级跟踪解决方案的生产环境而设计。有关更多详细信息，请参阅 生产监控 部分。

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

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

python

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 的自动跟踪集成捕获了有助于调试和评估模型/代理的丰富信息。然而，这会增加跟踪大小的成本。例如，您可能不想记录 RAG 应用程序中检索到的所有文档文本。

MLflow 支持插入自定义后处理钩子，在导出到后端之前应用于跟踪数据。这允许您通过删除不必要的数据或应用安全防护措施（如屏蔽敏感数据）来减小跟踪大小。

要注册自定义钩子，请使用 mlflow.tracing.configure API。例如，以下代码会过滤掉检索器跨度输出中的文档内容，以减小跟踪大小

python

import mlflow
from mlflow.entities.span import Span, SpanType


# Define a custom hook that takes a span as input and mutates it in-place.
def filter_retrieval_output(span: Span):
    """Filter out the document contents from the retriever span output and only keep the document ids."""
    if span.span_type == SpanType.RETRIEVAL:
        documents = span.outputs.get("documents")
        document_ids = [doc.id for doc in documents]
        span.set_outputs({"document_ids": document_ids})


# Register the hook
mlflow.tracing.configure(span_processors=[filter_retrieval_output])

# Any traces created after the configuration will be filtered by the hook.
...

有关钩子 API 和示例的更多详细信息，请参阅 安全屏蔽敏感数据 指南。

问：我可以在单个应用程序中将跟踪记录到不同的实验中吗？

是的，您可以在单个应用程序中将跟踪记录到不同的实验中。默认情况下，MLflow 会记录到通过 mlflow.set_experiment API 或 MLFLOW_EXPERIMENT_ID 环境变量设置的当前活动实验。

但是，您可能希望从单个应用程序动态地将跟踪路由到不同的实验。例如，您的应用程序服务器可能会暴露两个端点，每个端点服务于不同的模型。切换活动实验不起作用，因为活动实验是全局定义的，并且不隔离到每个线程或异步上下文。

因此，MLflow 提供了两种切换目标实验以记录跟踪的方法

可选 1. 在启动手动跟踪时设置 trace_destination 参数

trace_destination 参数已添加到 MLflow 3.3 中的 @mlflow.trace 装饰器和 mlflow.start_span API 中，允许您为每个跟踪明确指定目标实验。

python

import mlflow
from mlflow.entities.trace_location import MlflowExperimentLocation


@mlflow.trace(trace_destination=MlflowExperimentLocation(experiment_id="1234"))
def math_agent(request: Request):
    # Your model logic here
    ...

请注意，trace_destination 参数仅在设置为跟踪的根跨度时才有效。如果它设置为子跨度，MLflow 将忽略它并打印警告。

选项 2. 使用带有 context_local=True 的 mlflow.tracing.set_destination

mlflow.tracing.set_destination() API 是专门用于设置跟踪目标的 API，同时绕过了 mlflow.set_experiment 的开销。context_local 参数允许您为每个异步任务或线程设置目标，从而在并发应用程序中提供隔离。当您使用自动跟踪且不使用手动跟踪 API 时，此选项很有用。

python

import mlflow
from mlflow.entities.trace_location import MlflowExperimentLocation


@app.get("/math-agent")
def math_agent(request: Request):
    # The API is super low-overhead, so you can call it inside the request handler.
    mlflow.tracing.set_destination(MlflowExperimentLocation(experiment_id="1234"))

    # Your model logic here
    with mlflow.start_span(name="math-agent") as span:
        ...


@app.get("/chat-agent")
def chat_agent(request: Request):
    mlflow.tracing.set_destination(MlflowExperimentLocation(experiment_id="5678"))

    # Your model logic here
    with mlflow.start_span(name="chat-agent") as span:
        ...

故障排除

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

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

1. 跟踪尚未完成：如果跟踪仍在收集过程中，MLflow 无法在 UI 中显示跨度。确保所有跨度都以“OK”或“ERROR”状态正确结束。

2. 浏览器缓存过时：当您将 MLflow 升级到新版本时，浏览器缓存可能包含过时数据，并阻止 UI 正确显示跟踪。请清除浏览器缓存（Shift+F5）并刷新页面。

3. MLflow 服务器连接：确保您的 MLflow 跟踪服务器正在运行且可访问

   bash

   mlflow server --host 0.0.0.0 --port 5000

4. 实验权限：验证您是否有权访问包含跟踪的实验。

问：模型执行卡住，我的跟踪永远处于“进行中”。

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

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

注意

超时仅适用于 MLflow 跟踪。即使跟踪被中止，主程序、模型或代理仍将继续运行。

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

python

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

python

import mlflow

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

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

python

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

未调用 Autolog：对于受支持的库，请确保在使用前调用了 autolog

python

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

多线程和并发

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

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

这是一个快速示例

python

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 装饰器可以与异步函数无缝协作

python

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 跟踪服务记录任何有关跟踪的数据。

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

python

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 以禁用所有跟踪

bash

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

条件跟踪：使用程序化控制

python

import mlflow
import os

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

MLflow 运行集成

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

如果在运行上下文内生成跟踪，它将自动与该运行相关联

python

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

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

python

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

数据管理

问：如何删除跟踪？

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

python

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 server 时，跟踪存储在 mlruns 目录中

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

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

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

集成和兼容性

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

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

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

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

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

有关生产监控，请参阅 生产跟踪 以了解集成模式。

问：我可以创建自定义手动跟踪和跨度吗？

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

获取帮助

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

文档：从 MLflow 跟踪文档开始

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

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

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

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

---

对于此处未涵盖的额外问题或问题，请查看 MLflow 文档 或联系社区。