跳到主要内容

检测您的应用程序

了解如何使用 MLflow Tracing 检测您的 GenAI 应用程序，以捕获并可视化应用程序的执行流程。MLflow 提供了两种主要的追踪实现方法，它们可以独立使用，也可以结合使用以实现全面的可观测性。

先决条件​

本指南需要以下软件包

mlflow>=3.1：具有 GenAI 功能的核心 MLflow 功能。

openai>=1.0.0：仅在运行下面的快速入门示例时需要（如果使用其他 LLM 提供商，请安装其各自的 SDK）

安装所需软件包

pip install --upgrade "mlflow>=3.1" openai>=1.0.0
MLflow 版本推荐

虽然追踪功能在 MLflow 2.15.0+ 版本中可用，但强烈建议安装 MLflow 3 以获取最新的 GenAI 功能，包括扩展的追踪功能、增强的评估能力和改进的 UI。

环境设置​

在运行以下示例之前，请配置您的环境

对于本地开发，请启动 MLflow 追踪服务器

mlflow server --host 127.0.0.1 --port 5000

然后配置您的追踪 URI

import mlflow

mlflow.set_tracking_uri("http://127.0.0.1:5000")
mlflow.set_experiment("my-tracing-experiment")

追踪方法​

MLflow 提供了两种互补的追踪方法

自动追踪：只需添加一行代码 mlflow.<library>.autolog() 即可自动捕获您的应用程序逻辑。自动追踪开箱即用，支持 20 多个受支持的库和框架

手动追踪：专为自定义逻辑和复杂工作流设计，手动追踪让您可以使用高级 API（装饰器和流式上下文管理器）或低级 API 完全控制追踪的内容和方式。

注意

自动追踪和手动追踪可以结合使用。例如，您可以对 OpenAI 的 SDK 使用自动追踪，并使用手动追踪将多个 LLM 调用组合成一个表示应用程序端到端逻辑的单一追踪。

快速入门示例​

自动追踪示例​

只需一行代码即可为您喜欢的库启用自动追踪

import mlflow
from openai import OpenAI
import os

# Set up environment (if not already configured)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# Set up MLflow tracking
mlflow.set_tracking_uri("http://127.0.0.1:5000")
mlflow.set_experiment("auto-tracing-demo")

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

# Your existing code works unchanged
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is MLflow?"}],
    max_tokens=100,
)

print(response.choices[0].message.content)
# Traces are automatically captured and logged!

手动追踪示例​

使用 @mlflow.trace 装饰器来检测您的自定义函数

import mlflow
from mlflow.entities import SpanType
from openai import OpenAI
import os

# Set up environment (if not already configured)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# Set up MLflow tracking
mlflow.set_tracking_uri("http://127.0.0.1:5000")
mlflow.set_experiment("manual-tracing-demo")

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


@mlflow.trace(name="RAG Pipeline", span_type=SpanType.CHAIN)
def answer_question(question: str) -> str:
    """A simple RAG pipeline with manual tracing."""

    # Step 1: Retrieve context (manually traced)
    context = retrieve_context(question)

    # Step 2: Generate answer (automatically traced by OpenAI autolog)
    client = OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Context: {context}"},
            {"role": "user", "content": question},
        ],
        max_tokens=150,
    )

    return response.choices[0].message.content


@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_context(question: str) -> str:
    """Simulate context retrieval."""
    # Simulate retrieval logic
    return f"Relevant context for: {question}"


# Execute the traced pipeline
result = answer_question("What is MLflow Tracing?")
print(result)
提示

通常，我们建议从自动追踪开始，仅当应用程序的逻辑未被准确捕获或您需要更多控制时，才转向手动追踪。

自动追踪​

自动追踪为受支持的库提供零代码可观测性。只需为您使用的库调用 autolog 函数，MLflow 就会自动捕获所有相关操作。

MLflow 支持对 20 多个流行的 GenAI 库进行自动追踪，包括 LLM 提供商（OpenAI、Anthropic、Google Gemini、AWS Bedrock）和框架（LangChain、LangGraph、LlamaIndex、DSPy）。请参阅自动追踪集成处的完整列表。

import mlflow

mlflow.openai.autolog()

您可以通过调用每个 autolog 函数同时启用多个库的自动日志。例如，要启用 OpenAI 和 LangChain 的自动日志，您可以这样做

import mlflow

mlflow.openai.autolog()
mlflow.langchain.autolog()

手动追踪​

手动追踪让您可以精细控制追踪的内容和方式。使用它来检测自定义逻辑、将操作组合成逻辑单元或添加自定义元数据。

装饰器方法是检测函数的理想选择

import mlflow
from mlflow.entities import SpanType


@mlflow.trace(name="Document Processor", span_type=SpanType.CHAIN)
def process_document(document: str, language: str = "en") -> dict:
    """Process a document through multiple steps."""

    # This entire function execution will be traced
    tokens = tokenize(document)
    entities = extract_entities(tokens, language)
    summary = generate_summary(tokens)

    return {"entities": entities, "summary": summary, "token_count": len(tokens)}

Span 类型和属性​

使用 SpanType.CHAIN、SpanType.LLM、SpanType.RETRIEVER、SpanType.EMBEDDING 等 Span 类型以及其他类型，通过适当的分类和元数据来增强您的追踪。使用 span.set_attribute() 添加自定义属性，以捕获有关操作的重要元数据。

在手动追踪指南中了解更多关于手动追踪技术、装饰器、上下文管理器和高级模式的信息。

查看已记录的追踪​

检测完应用程序后，您可以通过多种方式查看和分析您的追踪

记录追踪后，您可以在MLflow UI主实验页面的“追踪”选项卡下查看它们。如果您的追踪是在运行上下文中记录的，此选项卡也可在单独的运行页面中找到。

MLflow Tracking UI

此表格包含有关追踪的高级信息，例如追踪 ID、根 Span 的输入/输出等。在此页面上，您还可以执行一些操作来管理您的追踪

搜索：使用 UI 中的搜索栏，您可以轻松地根据名称、标签或其他元数据过滤您的追踪。查看搜索文档以了解查询字符串格式的详细信息。

Searching traces

删除：UI 支持批量删除追踪。只需选中复选框选择要删除的追踪，然后按“删除”按钮即可。

Deleting traces

编辑标签：您还可以通过 UI 编辑追踪上的键值标签。

Traces tag update

要浏览单个追踪的 Span 数据，只需点击“追踪 ID”或“追踪名称”列中的链接即可打开追踪查看器

Trace Browser

后续步骤​

现在您已经了解了使用 MLflow Tracing 检测应用程序的基础知识，请探索这些详细指南和资源

深化您的追踪知识

自动追踪：探索所有受支持的库和框架，实现一行代码的追踪集成

手动追踪：学习自定义检测和复杂工作流的高级技术

组合方法：结合自动追踪和手动追踪以获得最佳可观测性

提示

推荐学习路径

从自动追踪开始，以获得即时价值，然后添加手动追踪以处理自定义逻辑和工作流。自动追踪和手动追踪的结合使您能够以最小的开销全面观测您的 GenAI 应用程序。