入门：本地 IDE 中 GenAI 的 MLflow 跟踪

如果使用的是 IDE（VS Code、PyCharm、Cursor 或其他）或本地托管的笔记本环境（例如 Jupyter），本快速入门可帮助你将 GenAI 应用与 MLflow 跟踪集成。如果使用 Databricks 笔记本，请参阅 Databricks 笔记本快速入门。

本教程将指导你完成以下操作：

在您的 Azure Databricks 工作区中创建 MLflow 实验
将本地开发环境与实验连接起来
在你的机器上本地运行一个简单的生成式人工智能应用
查看上传到您的 Azure Databricks 工作区的追踪数据

trace

先决条件

访问Azure Databricks工作区。

步骤 1：安装 MLflow

使用 Databricks 连接安装 MLflow：

pip install --upgrade "mlflow[databricks]>=3.1" openai

步骤 2：创建新的 MLflow 试验

MLflow 试验是 GenAI 应用程序的容器。有关详细信息，请参阅试验。

打开 Azure Databricks 工作区。
在左侧边栏中的 “AI/ML”下，单击“ 试验”。
在“试验”页顶部，单击 GenAI 应用和代理。
若要获取试验 ID 和路径，请单击左上角的信息。你会在后续步骤中使用这些值。

步骤 3：将环境连接到 MLflow

以下代码片段演示如何使用Azure Databricks个人访问令牌（PAT）设置身份验证。 MLflow 还适用于其他 Databricks 支持的身份验证方法。

使用环境变量

在 MLflow 试验中，单击 >本地>日志跟踪生成 API 密钥。

在终端中复制并运行生成的代码。

export DATABRICKS_TOKEN=<databricks-personal-access-token>
export DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
export MLFLOW_TRACKING_URI=databricks
export MLFLOW_REGISTRY_URI=databricks-uc
export MLFLOW_EXPERIMENT_ID=<experiment-id>

使用 .env 文件

在 MLflow 试验中，单击 >本地>日志跟踪生成 API 密钥。

将生成的代码复制到 .env 项目根目录中的文件。

DATABRICKS_TOKEN=<databricks-personal-access-token>
DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
MLFLOW_TRACKING_URI=databricks
MLFLOW_REGISTRY_URI=databricks-uc
MLFLOW_EXPERIMENT_ID=<experiment-id>

安装 python-dotenv 包。
```
pip install python-dotenv
```

在代码中加载环境变量：

# At the beginning of your Python script
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

Note

当身份验证信息来自 DATABRICKS_TOKEN（而不是来自上述 ~/.databrickscfg 环境变量）时，MLFLOW_TRACKING_URI=databricks 会读取 DEFAULT 配置文件。如果你使用 databricks auth login 进行了身份验证，它会创建一个以你的工作区主机命名而不是以 DEFAULT 命名的配置文件，请使用以下两个选项之一：

与其他环境变量一起设置 DATABRICKS_CONFIG_PROFILE=<your-profile-name> 。跑 databricks auth profiles 去列出个人资料名称。
或者用 MLFLOW_TRACKING_URI=databricks://<your-profile-name> 代替 databricks。

步骤3b（推荐）：启用Unity Catalog跟踪存储

上述步骤使用的是托管式实验后端，这是获得第一条追踪数据的最快方式，但会将每个实验的追踪数据上限设为 100,000 条。对于可扩展、受控且无跟踪限制的存储，Azure Databricks 建议将实验绑定到 Unity Catalog 的跟踪位置。

将以下内容添加到终端环境（与步骤3中的变量一起）：

export MLFLOW_TRACING_SQL_WAREHOUSE_ID=<warehouse-id>

在第四步创建 app.py 时，在任何追踪调用前，在顶部添加以下内容：

import mlflow
from mlflow.entities.trace_location import UnityCatalog

mlflow.set_experiment(
    experiment_id="<experiment-id>",  # the ID you copied in Step 2
    trace_location=UnityCatalog(
        catalog_name="<UC_CATALOG_NAME>",
        schema_name="<UC_SCHEMA_NAME>",
        table_prefix="<UC_TABLE_PREFIX>",
    ),
)

步骤 4：创建和检测应用程序

创建启用追踪功能的 GenAI 应用。代码完全运行在你的本地机器上，并将追踪上传到Azure Databricks工作区中的MLflow实验。

创建在项目目录中命名 app.py 的 Python 文件。

初始化 OpenAI 客户端以连接到由 Databricks 托管的 LLM 或者由 OpenAI 托管的 LLM。

OpenAI 托管的 LLM

使用本地 OpenAI SDK 连接到由 OpenAI 托管的模型。从可用的 OpenAI 模型中选择一个模型。

import mlflow
import os
import openai

# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

# Traces are written to the experiment set by MLFLOW_EXPERIMENT_ID and the
# tracking server set by MLFLOW_TRACKING_URI, both configured in the previous step

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-5"

定义并运行应用程序：

@mlflow.trace使用修饰器可以轻松跟踪任何 Python 函数，并结合 OpenAI 自动检测来捕获对 OpenAI SDK 调用的详细信息。

# Use the trace decorator to capture the application's entry point
@mlflow.trace
def my_app(input: str):
    # This call is automatically instrumented by `mlflow.openai.autolog()`
    response = client.chat.completions.create(
        # Uses a Databricks-hosted LLM by default. To use an AI Gateway, Model Serving endpoint, or your own OpenAI credentials, replace `model_name` with a valid model such as `gpt-5`.
        model=model_name,
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant.",
            },
            {
                "role": "user",
                "content": input,
            },
        ],
    )
    return response.choices[0].message.content

result = my_app(input="What is MLflow?")
print(result)

运行应用程序：
```
python app.py
```
这段代码在本地运行： app.py 文件存储在你的机器上，步骤3的环境变量告诉MLflow客户端在哪里上传跟踪数据。要更改提示符或代理逻辑，编辑本地文件并重新运行。

有关向应用添加跟踪的详细信息，请参阅向应用程序添加跟踪：自动和手动跟踪和 MLflow 跟踪集成（超过 20 个库集成）。

步骤 5：在 MLflow 中查看跟踪

当 Azure Databricks 界面中出现追踪时，说明你的代码是在笔记本上运行，并通过 HTTPS 传输。

返回你在步骤2中选择的MLflow实验。
生成的跟踪将显示在“ 跟踪 ”选项卡中。
点击跟踪以查看其详细信息。

跟踪详细信息

了解跟踪

新的跟踪记录显示：

根范围：表示my_app(...)函数的输入
- 子范围：表示 OpenAI 完成请求
属性：包含模型名称、令牌计数和计时信息等元数据
输入：发送到模型的消息
输出：从模型接收的响应

即使是此最小的跟踪图面也提供了有关应用程序行为的有用信息，包括：

有人问什么
生成了什么响应？
请求花费的时间
使用了多少个令牌（影响成本）

对于更复杂的应用程序（如 RAG 系统或多步骤代理），MLflow 跟踪通过揭示每个组件和步骤的内部工作来提供更多价值。

指南和参考

有关本指南中的概念和功能的详细信息，请参阅：

MLflow 跟踪 - GenAI 可观测性 - 从此处开始深入了解 MLflow 跟踪。
MLflow 跟踪集成 - 包含自动跟踪集成的 20 多个库。
跟踪概念 - 了解 MLflow 跟踪的基础知识。

Last updated on 2026-08-26