快速入門：GenAI 的 MLflow 追蹤（本機 IDE）

如果您使用本機開發環境，例如 IDE （VS Code、PyCharm、Cursor 或其他） 或本機裝載的筆記本環境 （Jupyter 或其他） ，本快速入門可協助您將 GenAI 應用程式與 MLflow 追蹤 整合。 如果您使用 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 應用程式的容器。 在 概念部分進一步了解實驗。

1. 開啟 Databricks 工作區
2. 在左側提要欄位的 [AI/ML] 底下，按兩下 [ 實驗]。
3. 在 [實驗] 頁面頂端，按一下 [GenAI 應用程式和代理程式]
4. 按一下左上角的資訊圖示 [ ，以取得實驗 ID 和路徑。 您稍後將使用這些。

步驟 3：將您的環境連線到 MLflow

下列程式碼片段示範如何使用 Databricks 個人存取權杖來設定驗證。 MLflow 也適用於其他 Databricks 支援的驗證方法。

使用環境變數

1. 在您的 MLflow 實驗中，單擊 >本機記錄追蹤> 單擊 產生 API 金鑰。

2. 在終端機中複製並執行產生的程序代碼。

   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 檔案

1. 在您的 MLflow 實驗中，單擊 >本機記錄追蹤> 單擊 產生 API 金鑰。

2. 將產生的程式代碼複製到 .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>
   

3. 安裝 python-dotenv 套件

   pip install python-dotenv
   

4. 在您的程式代碼中載入環境變數

   # At the beginning of your Python script
   from dotenv import load_dotenv
   
   # Load environment variables from .env file
   load_dotenv()
   

步驟 4：建立及檢測您的應用程式

建立啟用追蹤的 GenAI 應用程式。

1. 在項目目錄中建立名為 的 app.py Python 檔案。

2. 初始化 OpenAI 用戶端，以連接到由 Databricks 或 OpenAI 裝載的 LLM。

   Databricks 託管的 LLM

   使用 MLflow 取得連線到 Databricks 裝載的 LLM 的 OpenAI 用戶端。 從 可用的基礎模型中選取模型。

   import mlflow
   from databricks.sdk import WorkspaceClient
   
   # Enable MLflow's autologging to instrument your application with Tracing
   mlflow.openai.autolog()
   
   # Set up MLflow tracking to Databricks
   mlflow.set_tracking_uri("databricks")
   mlflow.set_experiment("/Shared/docs-demo")
   
   # Create an OpenAI client that is connected to Databricks-hosted LLMs
   w = WorkspaceClient()
   client = w.serving_endpoints.get_open_ai_client()
   
   # Select an LLM
   model_name = "databricks-claude-sonnet-4"
   

   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()
   
   # Set up MLflow tracking to Databricks
   mlflow.set_tracking_uri("databricks")
   mlflow.set_experiment("/Shared/docs-demo")
   
   # Create an OpenAI client connected to OpenAI SDKs
   client = openai.OpenAI()
   
   # Select an LLM
   model_name = "gpt-4o-mini"
   

3. 定義並執行您的應用程式：

   使用 @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(
           model=model_name,  # 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)
   

4. 執行應用程式

   python app.py
   

如需如何將追蹤新增至應用程式，請參閱 追蹤檢測指南 和 20+ 程式庫整合。

步驟 5：在 MLflow 中檢視追蹤

1. 流覽回 MLflow 實驗 UI。
2. 您現在將在 [追蹤] 索引標籤中看到產生的追蹤。
3. 按一下痕跡以檢視其詳細資料。

瞭解追蹤資訊

您剛建立的追蹤記錄顯示如下內容：

• 根跨度：代表 my_app(...) 函數的輸入
  • 子範圍：表示 OpenAI 的完成請求
• 屬性：包含模型名稱、令牌計數和計時資訊等元數據
• 輸入：傳送至模型的訊息
• 輸出：從模型接收的回應

這個簡單的追蹤已經提供您應用程式行為的寶貴見解，例如：

• 被問及的內容
• 產生了什麼回應？
• 請求所耗時間
• 使用了多少代幣（影響成本）

針對更複雜的應用程式，例如RAG系統或多步驟代理程式，MLflow追蹤會藉由顯示每個元件和步驟的內部工作來提供更多價值。

指南和參考

如需本指南中概念和功能的詳細資訊，請參閱：

• MLflow 追蹤指南 - 從這裡開始，深入瞭解 MLflow 追蹤
• MLflow 追蹤整合 - 20+ 個具有自動追蹤整合的程式庫
• 追蹤概念 - 瞭解 MLflow 追蹤的基本概念