追踪 GenAI 应用（IDE）

2025-06-11

本快速入门帮助你将 GenAI 应用与 MLflow 跟踪集成（如果使用本地 IDE 作为开发环境）。如果使用 Databricks Notebook，请改用 Databricks Notebook 快速入门。

你将实现的目标

在本教程结束时，你将拥有：

GenAI 应用的 MLflow 实验
连接到 MLflow 的本地开发环境
使用 MLflow 跟踪检测的简单 GenAI 应用程序
MLflow 试验中该应用的跟踪

先决条件

Databricks 工作区：访问 Databricks 工作区。

步骤 1：安装 MLflow

在本地 IDE 中工作时，需要使用 Databricks 连接安装 MLflow。

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

步骤 2：创建新的 MLflow 试验

MLflow 试验是 GenAI 应用程序的容器。详细了解试验及其包含在数据模型部分中的内容。

打开 Databricks 工作区
转到机器学习下的左侧边栏中的试验
在“试验”页顶部，单击“新建 GenAI 试验”

实验创建

步骤 3：将环境连接到 MLflow

注释

本快速入门介绍如何使用 Databricks 个人访问令牌。 MLflow 还适用于其他 Databricks 支持的身份验证方法。

使用环境变量

单击“生成 API 密钥”

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

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

使用 .env 文件

单击“生成 API 密钥”

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

DATABRICKS_TOKEN=<databricks-personal-access-token>
DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
MLFLOW_TRACKING_URI=databricks
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()

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

小窍门

Databricks 提供先进和开源的基础 LLM 即时访问权限。若要运行本快速入门，可以：

使用 Databricks 托管的大型语言模型 (LLM)
直接使用来自 LLM 提供程序的自己的 API 密钥
创建外部模型以启用对 LLM 提供程序 API 密钥的受控制访问权限

以下示例快速入门使用 OpenAI SDK 连接到 Databricks 托管 LLM。如果要使用自己的 OpenAI 密钥，请更新行 client = OpenAI(...) 。

如果希望使用 MLflow 支持的其他 20 多个 LLM SDK（Anthropic、Bedrock 等）或 GenAI 创作框架（LangGraph 等），请按照上一步中的 MLflow 实验 UI 中的说明进行操作。

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

在这里，我们使用 @mlflow.trace 修饰器，结合 OpenAI 自动化工具，轻松跟踪任何 Python 应用程序，以捕获对 OpenAI SDK 调用的详细信息。

下面的代码片段使用人类学的 Claude Sonnet LLM。可以从受支持的基础模型列表中选择另一个 LLM。

import mlflow
from openai import OpenAI

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Connect to a Databricks LLM via OpenAI using the same credentials as MLflow
# Alternatively, you can use your own OpenAI credentials here
mlflow_creds = mlflow.utils.databricks_utils.get_databricks_host_creds()
client = OpenAI(
    api_key=mlflow_creds.token,
    base_url=f"{mlflow_creds.host}/serving-endpoints"
)

# 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(
    model="databricks-claude-sonnet-4",  # This example uses a Databricks hosted LLM - you can replace this with any AI Gateway or Model Serving endpoint. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
    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
```

步骤 5：在 MLflow 中查看追踪

返回 MLflow 实验界面
现在，你将在 “跟踪 ”选项卡中看到生成的跟踪
单击跟踪以查看其详细信息

跟踪详细信息

理解追踪的过程

您刚刚创建的跟踪显示：

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

此简单跟踪已提供对应用程序行为的宝贵见解，例如：

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

小窍门

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

后续步骤

继续您的旅程，并参考这些推荐的行动和教程。

评估应用的质量 - 使用 MLflow 评估功能衡量和提高 GenAI 应用的质量
收集人工反馈 - 了解如何从用户和领域专家那里收集反馈
跟踪用户和会话 - 将用户和聊天上下文添加到跟踪

参考指南

浏览本指南中提到的概念和功能的详细文档。

跟踪概念 - 了解 MLflow 跟踪的基础知识
跟踪数据模型 - 了解跟踪、跨度以及 MLflow 如何构建可观测性数据
手动跟踪 API - 探索用于自定义检测的高级跟踪技术

通过