使用 MLflow 記錄計量、參數和檔案

發行項
03/11/2024

適用於：Python SDK azure-ai-ml v2 (目前)

Azure Machine Learning 支援使用 MLflow 追蹤來記錄和追蹤實驗。您可以使用本機電腦或雲端環境中的 MLflow 來記錄模型、計量、參數和成品。

重要

不同於 Azure Machine Learning SDK v1，適用於 Python (v2) 的 Azure Machine Learning SDK 並沒有記錄功能。如果您之前曾使用過 Azure Machine Learning SDK v1，建議您利用 MLflow 來追蹤實驗。如需特定指引，請參閱將記錄從 SDK v1 移轉至 MLflow。

記錄可協助您診斷錯誤和警告，或追蹤參數和模型效能等效能計量。本文會說明如何在下列案例中啟用記錄：

提交作業時記錄計量、參數和模型。
以互動方式定型時，會執行追蹤。
檢視有關定型的診斷資訊。

提示

本文說明如何監視模型定型程序。若您想要從 Azure Machine Learning 監視資源使用量和事件 (例如配額、已完成的定型作業或已完成的模型部署)，請參閱監視 Azure Machine Learning。

必要條件

您必須具有 Azure Machine Learning 工作區。如果您沒有工作區，請參閱建立工作區資源。
您必須已安裝 mlflow 和 azureml-mlflow 套件。若尚未安裝，請使用下列命令在開發環境中加以安裝：
```
pip install mlflow azureml-mlflow
```
如果您正在執行遠端追蹤 (追蹤在 Azure Machine Learning 外部執行的實驗)，請設定 MLflow 來追蹤實驗。如需詳細資訊，請參閱設定 Azure Machine Learning 的 MLflow。
若要使用 MLflow 記錄 Azure Machine Learning 實驗中的計量、參數、成品和模型，只需將 MLflow 匯入指令碼：
```
import mlflow
```

設定實驗

MLflow 會在實驗和執行中組織資訊 (在 Azure Machine Learning 中，執行稱為作業)。取決於您執行程式碼的方式，設定程式碼的方法稍有差異：

以互動方式定型
使用作業定型

以互動方式定型時 (例如在 Jupyter Notebook 中)，請使用下列模式：

建立或設定作用中實驗。
啟動作業。
使用記錄方法來記錄計量和其他資訊。
結束作業。

例如，下列程式碼片段會設定實驗，然後在作業期間記錄：

import mlflow
# Set the experiment
mlflow.set_experiment("mlflow-experiment")

# Start the run
mlflow_run = mlflow.start_run()
# Log metrics or other information
mlflow.log_metric('mymetric', 1)
# End run 
mlflow.end_run()

提示

就技術上來說，您並不需要呼叫 start_run()，因為如果執行不存在，在您呼叫記錄 API 時，就會建立新執行。在這種情況下，您可以使用 mlflow.active_run() 來擷取目前使用的執行。如需詳細資訊，請參閱 mlflow.active_run()。

您也可以使用內容管理員範例：

import mlflow
mlflow.set_experiment("mlflow-experiment")

# Start the run, log metrics, end the run
with mlflow.start_run() as run:
    # Run started when context manager is entered, and ended when context manager exits
    mlflow.log_metric('mymetric', 1)
    mlflow.log_metric('anothermetric',1)
    pass

當您使用 mlflow.start_run 啟動新的執行，指示參數 run_name 可能會很有用，這會轉譯為 Azure Machine Learning 使用者介面中的執行名稱，並協助您更快速地識別執行：

with mlflow.start_run(run_name="iris-classifier-random-forest") as run:
    mlflow.log_metric('mymetric', 1)
    mlflow.log_metric('anothermetric',1)

如需 MLflow 記錄 API 的詳細資訊，請參閱 MLflow 參考。

在 Azure Machine Learning 中執行定型作業時，您不需要在自動啟動執行時呼叫 mlflow.start_run。因此，您可以直接在定型指令碼中使用 mlflow 追蹤功能：

import mlflow

mlflow.autolog()

mlflow.log_metric('mymetric', 1)
mlflow.log_metric('anothermetric',1)

提示

使用 Azure Machine Learning CLI v2 提交作業時，您可以使用作業 YAML 定義中的屬性 experiment_name 來設定實驗名稱。您不必在定型指令碼上設定。如需詳細資訊，請參閱 YAML：顯示名稱、實驗名稱、描述和標籤。

記錄參數

MLflow 支援實驗所使用的記錄參數。參數可以是任何類型，亦可以使用下列語法來加以記錄：

mlflow.log_param("num_epochs", 20)

MLflow 也提供便利方式來記錄多個參數，也就是使用字典來指出所有參數。數個架構亦可以使用字典將參數傳遞至模型，因此這是在實驗中記錄參數的便利方式。

params = {
    "num_epochs": 20,
    "dropout_rate": .6,
    "objective": "binary_crossentropy"
}

mlflow.log_params(params)

記錄計量

計量與參數相反，一律是數值。下表說明如何記錄特定的值類型：

記錄的值	程式碼範例	備註
記錄數字值 (整數或浮點數)	`mlflow.log_metric("my_metric", 1)`
隨時記錄數字值 (整數或浮點數)	`mlflow.log_metric("my_metric", 1, step=1)`	使用參數 `step` 來指出您要記錄計量值的步驟。可以是任何整數。預設值為 0。
記錄布林值	`mlflow.log_metric("my_metric", 0)`	0 = True、1 = False

重要

效能考量：如果您需要記錄多個計量 (或以相同的計量記錄多個值)，請避免在迴圈中呼叫 mlflow.log_metric。藉由記錄計量的批次，可達到更佳效能。使用接受字典的 mlflow.log_metrics 方法，其中包括您想要一次記錄的所有計量，或使用 MLflowClient.log_batch 來接受多個類型的元素以進行記錄。如需範例，請參閱記錄曲線或值的清單。

記錄曲線或值的清單

曲線 (或值的清單) 可以透過多次記錄相同計量來記錄 MLflow。下列範例示範執行的方式：

list_to_log = [1, 2, 3, 2, 1, 2, 3, 2, 1]
from mlflow.entities import Metric
from mlflow.tracking import MlflowClient
import time

client = MlflowClient()
client.log_batch(mlflow.active_run().info.run_id, 
                 metrics=[Metric(key="sample_list", value=val, timestamp=int(time.time() * 1000), step=0) for val in list_to_log])

記錄影像

MLflow 支援兩種記錄映像的方式。這兩種方式都會將指定的映像保存為執行內的成品。

記錄的值	程式碼範例	備註
記錄 numpy 計量或 PIL 影像物件	`mlflow.log_image(img, "figure.png")`	`img` 應該是 `numpy.ndarray` 或 `PIL.Image.Image` 的執行個體。 `figure.png` 是執行內產生的成品名稱。不一定要是現有的檔案。
記錄 matlotlib 繪圖或影像檔案	`mlflow.log_figure(fig, "figure.png")`	`figure.png` 是執行內產生的成品名稱。不一定要是現有的檔案。

記錄檔

一般而言，MLflow 中的檔案稱為成品。您可以在 Mlflow 中以多種方式記錄成品：

記錄的值	程式碼範例	備註
在文字檔中的記錄簡訊	`mlflow.log_text("text string", "notes.txt")`	文字會保存在內部執行名稱為 notes.txt 的文字檔中。
將字典記錄為 JSON 和 YAML 檔案	`mlflow.log_dict(dictionary, "file.yaml"`	`dictionary` 為字典物件，其中涵蓋您要保存為 JSON 或 YAML 檔案的所有結構。
記錄已存在的簡單式檔案	`mlflow.log_artifact("path/to/file.pkl")`	檔案一律記錄在執行的根目錄之中。若已提供 `artifact_path`，則檔案會記錄在資料夾之中，如該參數所示。
記錄現有資料夾中的所有成品	`mlflow.log_artifacts("path/to/folder")`	資料夾結構會複製至執行中，但未包括指定的根資料夾。

提示

當您使用 log_artifact 或 log_model 記錄大型檔案時，可能會在檔案上傳完成之前發生逾時錯誤。考慮藉由調整環境變數 AZUREML_ARTIFACTS_DEFAULT_TIMEOUT 來增加逾時值。預設值為 300 (秒)。

記錄模型

MLflow 引進了模型的概念，可用來封裝指定模型函式所需的所有成品。 MLflow 中的模型一律為具有任意數目檔案的資料夾，取決於用來產生模型的架構。記錄模型的優點是能以單一實體的形式追蹤模型的所有元素，而單一實體可以註冊並且部署。除此之外，MLflow 模型具有無程式碼部署的優點，並可搭配工作室中的負責任 AI 儀表板使用。如需詳細資訊，請參閱從成品到 MLflow 中的模型。

若要從定型執行中儲存模型，請使用您所使用之架構的 log_model() API。例如，mlflow.sklearn.log_model()。如需詳細資訊，請參閱記錄 MLflow 模型。若要將現有的模型移轉至 MLflow，請參閱將自訂模型轉換為 MLflow。

提示

記錄大型模型時，可能會遇到錯誤 Failed to flush the queue within 300 seconds。通常，這表示作業會在模型成品上傳完成之前逾時。考慮藉由調整環境變數 AZUREML_ARTIFACTS_DEFAULT_TIMEOUT 來增加逾時值。

自動記錄

透過 Azure Machine Learning 與 MLflow，使用者可以在將模型定型時自動記錄計量、模型參數與模型成品。每個架構都會決定要為您自動追蹤的內容。支援各種熱門的機器學習程式庫。深入瞭解如何搭配 MLflow 使用自動記錄功能。

若要啟用自動記錄，請在您的定型程式碼前面插入下列程式碼：

mlflow.autolog()

提示

您可以使用 autolog 控制自動記錄的內容。例如，如果您指出 mlflow.autolog(log_models=False)，MLflow 會記錄模型以外的所有項目。當您想要手動記錄模型，但仍想自動記錄計量和參數時，這類控制項會很實用。另請注意，若定型的模型超出特定界限，某些架構可能會停用自動記錄的模型。這類行為取決於所使用的變體，建議您在案例中檢視相關的文件。

使用 MLflow 檢視作業/執行資訊

您可以透過 MLflow.entities.Run 物件來檢視使用 MLflow 記錄的資訊：

import mlflow

run = mlflow.get_run(run_id="<RUN_ID>")

您可以在執行物件的資料欄位中，檢視執行的計量、參數和標籤。

metrics = run.data.metrics
params = run.data.params
tags = run.data.tags

注意

mlflow.get_run 或 mlflow.search_runs 所傳回的計量字典只會傳回給定計量名稱最近記錄的值。例如，如果您記錄名為 iteration 的計量多次，其具有值 1，然後是 2，然後是 3，然後是 4，則在呼叫 run.data.metrics['iteration'] 時僅會傳回 4。

若要取得為特定計量名稱記錄的所有計量，您可以使用 MlFlowClient.get_metric_history()，如從執行中取得參數和計量範例中所述。

提示

MLflow 可以同時從多個執行中擷取計量和參數，允許跨多個試用版進行快速比較。若要深入了解，請參閱使用 MLflow 查詢、比較實驗和執行。

MLflow 可以查詢執行所記錄的任何成品。成品無法使用執行物件本身進行存取，而且應該改用 MLflow 用戶端：

client = mlflow.tracking.MlflowClient()
client.list_artifacts("<RUN_ID>")

此方法會列出執行中記錄的所有成品，但這些成品仍會儲存在成品存放區 (Azure Machine Learning 儲存體) 中。若要下載其中任何一個，請使用 download_artifact 方法：

file_path = client.download_artifacts("<RUN_ID>", path="feature_importance_weight.png")

如需詳細資訊，請參閱取得計量、參數、成品和模型。

在工作室中檢視作業/執行資訊

您可以在 Azure Machine Learning 工作室中瀏覽已完成的作業記錄，包括已記錄的計量。

瀏覽至 [作業] 索引標籤。若要跨 [實驗] 檢視工作區中的所有作業，請選取 [所有作業] 索引標籤。您可以在頂端功能表列中套用 [實驗] 篩選，以向下切入特定實驗的作業。選取感興趣的作業以輸入詳細資料檢視，然後選取 [計量] 索引標籤。

選取記錄的計量，以轉譯右側的圖表。您可以藉由套用平滑、變更色彩或繪製單一圖表上的多個計量來自訂圖表。您也可以視需要調整大小並重新排列配置。建立所需的檢視之後，您可以加以儲存以供日後使用，並使用直接連結與小組成員共用。

檢視並下載診斷記錄

記錄檔是對 Azure Machine Learning 工作負載進行偵錯時不可或缺的資源。在提交定型作業後，請向下切入至特定執行以檢視其記錄和輸出：

瀏覽至 [作業] 索引標籤。
選取特定執行的 runID。
選取頁面頂端的 [輸出和記錄]。
選取 [全部下載]，將所有記錄下載到 zip 資料夾。
您也可以選擇記錄檔並選取 [下載]，以下載個別的記錄檔

user_logs 資料夾

此資料夾包含使用者產生的記錄相關資訊。預設會開啟此資料夾，並選取 std_log.txt 記錄檔。程式碼的記錄 (例如，print 陳述式) 會顯示在 std_log.txt 中。此檔案包含來自控制指令碼和定型指令碼的 stdout 記錄和 stderr 記錄 (每個程序一個)。在大部分情況下，您會在此處監視記錄。

system_logs 資料夾

此資料夾包含 Azure Machine Learning 所產生的記錄，依預設會關閉。系統所產生的記錄會根據執行階段中的作業階段分組到不同的資料夾。

其他資料夾

針對在多個計算叢集上定型的作業，每個 IP 節點都會有記錄。每個節點的結構與單一節點作業相同。另外還有一個存放了整體執行、stderr 和 stdout 記錄的記錄資料夾。

Azure Machine Learning 會在定型期間記錄來自各種來源的資訊，例如 AutoML 或執行定型作業的 Docker 容器。其中有許多記錄並未列載於文件中。如果您遇到問題並連絡 Microsoft 支援服務，他們在進行疑難排解時可能會使用這些記錄。