什麼是適用於 Python 的 Azure Machine Learning SDK？

發行項
05/30/2023

資料科學家和 AI 開發人員可使用 Azure Machine Learning 服務搭配適用於 Python 的 Azure Machine Learning SDK，來建置及執行機器學習工作流程。您可以在任何 Python 環境 (包括 Jupyter Notebook、Visual Studio Code 或您慣用的 Python IDE) 中與該服務互動。

SDK 的主要領域包括：

探索、準備及管理在機器學習實驗中使用之資料集的生命週期。
管理用來對您的機器學習實驗進行監視、記錄及組織的雲端資源。
在本機或使用雲端資源 (包括 GPU 加速模型訓練) 定型模型。
使用自動化機器學習，此服務可接受組態參數和訓練資料。它會自動逐一查看演算法和超參數設定，以找出執行預測的最佳模型。
部署 Web 服務，將您已定型的模型轉換成可在任何應用程式中使用的 RESTful 服務。

如需如何開始使用的逐步解說，請試著進行教學課程。

以下各節將概述 SDK 中一些最重要的類別，及其使用時的常見設計模式。若要取得 SDK，請參閱安裝指南。

穩定與實驗版本

適用於 Python 的 Azure Machine Learning SDK 會在同一個 SDK 中提供穩定和實驗性功能。

功能/功能狀態	Description
穩定功能	生產就緒對於大部分的使用案例和生產環境，建議使用這些功能。其比實驗性功能更新頻率更低。
實驗性功能	發展這些功能是新開發的功能，& 可能尚未準備好或完全測試生產環境的更新。雖然此功能通常可以運作，但可能會納入一些中斷性變更。實驗性功能可用來消除 SDK 中斷的錯誤，而且只會在測試期間接收更新。實驗性功能也稱為處於預覽狀態的功能。如名稱所示，實驗性 (預覽) 功能適用於實驗，且不會被視為無 Bug 或穩定。因此，我們只建議將實驗性功能提供給想要嘗試早期功能版本和更新，而且想要回報錯誤和問題的進階使用者。

功能/功能狀態

Description

穩定功能

生產就緒

對於大部分的使用案例和生產環境，建議使用這些功能。其比實驗性功能更新頻率更低。

實驗性功能

發展

這些功能是新開發的功能，& 可能尚未準備好或完全測試生產環境的更新。雖然此功能通常可以運作，但可能會納入一些中斷性變更。實驗性功能可用來消除 SDK 中斷的錯誤，而且只會在測試期間接收更新。實驗性功能也稱為 處於預覽狀態的功能。

如名稱所示，實驗性 (預覽) 功能適用於實驗， 且不會被視為無 Bug 或穩定。因此，我們只建議將實驗性功能提供給想要嘗試早期功能版本和更新，而且想要回報錯誤和問題的進階使用者。

實驗性功能會以 SDK 參考中的附註一節標示，並以文字表示，例如 ， (預覽) 整個 Azure Machine Learning 檔。

工作區

命名空間：azureml.core.workspace.Workspace

Workspace 類別是您在雲端中用來實驗、定型及部署機器學習模型的基礎資源。此類別可將您的 Azure 訂用帳戶和資源群組與容易使用的物件結合。

檢視建立 Workspace 方法的所有參數，以重複使用現有的實例 (記憶體、金鑰保存庫、App-Insights 和 Azure Container Registry-ACR) ，以及修改其他設定，例如私人端點組態和計算目標。

請使用下列程式碼匯入類別並建立新的工作區。如果您已有要用於工作區的既有 Azure 資源群組，請將 create_resource_group 設定為 False。某些功能可能會提示您提供 Azure 驗證認證。

from azureml.core import Workspace
ws = Workspace.create(name='myworkspace',
                      subscription_id='<azure-subscription-id>',
                      resource_group='myresourcegroup',
                      create_resource_group=True,
                      location='eastus2'
                     )

您可以在多個環境中使用相同的工作區，只要先將其寫入至組態 JSON 檔案即可。這會儲存您的訂用帳戶、資源和工作區名稱資料。

ws.write_config(path="./file-path", file_name="ws_config.json")

藉由讀取組態檔來載入您的工作區。

from azureml.core import Workspace
ws_other_environment = Workspace.from_config(path="./file-path/ws_config.json")

或者，使用靜態 get() 方法載入現有的工作區，而不使用組態檔。

from azureml.core import Workspace
ws = Workspace.get(name="myworkspace", subscription_id='<azure-subscription-id>', resource_group='myresourcegroup')

變數 ws 代表下列程式碼範例中的 Workspace 物件。

實驗

命名空間：azureml.core.experiment.Experiment

Experiment 類別是另一個基本雲端資源，代表試用 (個別的模型執行) 的集合。下列程式碼會依名稱從 Workspace 內擷取 Experiment 物件；如果名稱不存在，則會建立新的 Experiment 物件。

from azureml.core.experiment import Experiment
experiment = Experiment(workspace=ws, name='test-experiment')

執行下列程式碼，以取得包含在 Workspace 中的所有 Experiment 物件的清單。

list_experiments = Experiment.list(ws)

使用 get_runs 函式，從 Experiment 擷取 Run 物件 (試用) 的清單。下列程式碼會擷取執行，並列印每個執行識別碼。

list_runs = experiment.get_runs()
for run in list_runs:
    print(run.id)

有兩種方式可執行實驗試用。如果您是在 Jupyter Notebook 中以互動方式進行實驗，請使用 start_logging 函式。如果您要從標準 Python 環境中提交實驗，請使用 submit 函式。這兩個函式都會傳回 Run 物件。 experiment 變數代表下列程式碼範例中的 Experiment 物件。

執行

命名空間：azureml.core.run.Run

執行代表實驗的單一試用。 Run 是一個物件，用來監視試用的非同步執行、儲存試用的輸出、分析結果，以及存取產生的成品。您可以在實驗程式碼內使用 Run，將計量和成品記錄到「執行歷程記錄」服務。功能包括：

儲存及擷取計量和資料。
使用標籤和子階層以便查閱過去的執行。
註冊已儲存的模型檔案以進行部署。
儲存、修改和擷取執行的屬性。

藉由提交具有執行組態物件的 Experiment 物件，來建立 Run 物件。使用 tags 參數，將自訂類別和標籤連結至您的執行。您稍後可以從 Experiment 輕鬆地加以找出並擷取。

tags = {"prod": "phase-1-model-tests"}
run = experiment.submit(config=your_config_object, tags=tags)

使用靜態 list 函式，從 Experiment 取得所有 Run 物件的清單。指定 tags 參數，以依據您先前建立的標籤進行篩選。

from azureml.core.run import Run
filtered_list_runs = Run.list(experiment, tags=tags)

使用 get_details 函式擷取執行的詳細輸出。

run_details = run.get_details()

此函式的輸出是包含下列項目的字典：

回合識別碼
狀態
開始和結束時間
計算目標 (本機與雲端)
執行時所使用的相依性和版本
訓練特有的資料 (視模型類型而有所不同)

如需更多關於如何設定和監視執行的範例，請參閱操作說明。

模型

命名空間：azureml.core.model.Model

Model 類別可用來處理機器學習模型的雲端表示法。「方法」可協助您在本機開發環境與雲端中的 Workspace 物件之間傳輸模型。

您可以使用模型註冊，在您位於 Azure 雲端的工作區中儲存模型和控制模型版本。已註冊的模型是透過名稱和版本來識別。每次註冊與現有模型名稱相同的模型時，登錄都會遞加版本。 Azure Machine Learning 支援任何可透過 Python 3 載入的模型，而不只是 Azure Machine Learning 模型。

下列範例說明如何使用 scikit-learn 建置簡單的本機分類模型、在 Workspace 中註冊模型，以及從雲端下載模型。

建立簡單的分類器 clf，以根據年齡預測客戶流失。然後，將模型傾印到相同目錄中的 .pkl 檔案。

from sklearn import svm
import joblib
import numpy as np

# customer ages
X_train = np.array([50, 17, 35, 23, 28, 40, 31, 29, 19, 62])
X_train = X_train.reshape(-1, 1)
# churn y/n
y_train = ["yes", "no", "no", "no", "yes", "yes", "yes", "no", "no", "yes"]

clf = svm.SVC(gamma=0.001, C=100.)
clf.fit(X_train, y_train)

joblib.dump(value=clf, filename="churn-model.pkl")

使用 register 函式，在您的工作區中註冊模型。指定本機模型路徑和模型名稱。多次註冊相同的名稱，將會建立新的版本。

from azureml.core.model import Model

model = Model.register(workspace=ws, model_path="churn-model.pkl", model_name="churn-model-test")

現在，您已在工作區中註冊模型，接著即可輕鬆管理、下載和組織您的模型。若要從 Workspace 擷取模型 (例如，在另一個環境中) 物件，請使用類別建構函式，並指定模型名稱和任何選用參數。然後，使用 download 函式下載模型，包括雲端資料夾結構。

from azureml.core.model import Model
import os

model = Model(workspace=ws, name="churn-model-test")
model.download(target_dir=os.getcwd())

使用 delete 函式，從 Workspace 移除模型。

model.delete()

在註冊模型之後，將模型部署為 Web 服務將是簡單的程序。首先，您應建立並註冊映像。此步驟會設定 Python 環境及其相依性，以及用來定義 Web 服務要求和回應格式的指令碼。建立映像後，您應建置部署組態，以設定計算目標的 CPU 核心和記憶體參數。然後，您應連結映像。

ComputeTarget、RunConfiguration 和 ScriptRunConfig

命名空間：azureml.core.compute.ComputeTarget
命名空間：azureml.core.runconfig.RunConfiguration
命名空間：azureml.core.script_run_config.ScriptRunConfig

ComputeTarget 類別是用來建立和管理計算目標的抽象父類別。計算目標代表您可用來定型機器學習模型的多種資源。計算目標可以是本機電腦或雲端資源，例如 Azure Machine Learning Compute、Azure HDInsight 或遠端虛擬機器。

請使用計算目標以利用強大的虛擬機器來進行模型定型，並設定持續性計算目標或暫時的執行階段叫用目標。如需設定和管理計算目標的完整指南，請參閱操作說明。

下列程式碼顯示設定 AmlCompute (ComputeTarget 的子類別) 目標的簡單範例。此目標會在您的 Workspace 物件中建立執行階段遠端計算資源。在提交作業時，此資源會自動調整。在執行完成後，資源就會自動刪除。

重複使用簡單的 scikit-learn 流失模型，並在目前的目錄中將其建置為專屬的檔案 train.py。在檔案結尾處，建立名為 outputs 的新目錄。此步驟會在雲端 (您的工作區) 中建立一個目錄，用以儲存 joblib.dump() 所序列化的定型模型。

# train.py

from sklearn import svm
import numpy as np
import joblib
import os

# customer ages
X_train = np.array([50, 17, 35, 23, 28, 40, 31, 29, 19, 62])
X_train = X_train.reshape(-1, 1)
# churn y/n
y_train = ["yes", "no", "no", "no", "yes", "yes", "yes", "no", "no", "yes"]

clf = svm.SVC(gamma=0.001, C=100.)
clf.fit(X_train, y_train)

os.makedirs("outputs", exist_ok=True)
joblib.dump(value=clf, filename="outputs/churn-model.pkl")

接著，您應建立計算目標，方法是將 RunConfiguration 物件具現化，並設定類型和大小。此範例使用最小的資源大小 (1 個 CPU 核心，3.5 GB 的記憶體)。 list_vms 變數會列出支援的虛擬機器及其大小。

from azureml.core.runconfig import RunConfiguration
from azureml.core.compute import AmlCompute
list_vms = AmlCompute.supported_vmsizes(workspace=ws)

compute_config = RunConfiguration()
compute_config.target = "amlcompute"
compute_config.amlcompute.vm_size = "STANDARD_D1_V2"

使用 CondaDependencies 類別，為遠端計算資源的 Python 環境建立相依性。 train.py 檔案會使用必須安裝在環境中的 scikit-learn 和 numpy。您也可以指定相依性的版本。請使用 dependencies 物件在 compute_config 中設定環境。

from azureml.core.conda_dependencies import CondaDependencies

dependencies = CondaDependencies()
dependencies.add_pip_package("scikit-learn")
dependencies.add_pip_package("numpy==1.15.4")
compute_config.environment.python.conda_dependencies = dependencies

現在您已準備就緒，可提交實驗。請使用 ScriptRunConfig 類別來連結計算目標組態，並指定訓練指令碼 train.py 的路徑/檔案。藉由指定 submit() 函式的 config 參數來提交實驗。在產生的執行上呼叫 wait_for_completion，以在初始化環境和定型模型時查看非同步執行輸出。

警告

以下是在參數中使用 ScriptRunConfig 時，特定字元的限制：

"、$、 ;和 \ 字元會由後端逸出，因為它們被視為用來分隔bash命令的保留字元。
在 Windows 上執行本機執行時，會(逸出、)、%、<^!>、、 &和 | 字元。

from azureml.core.experiment import Experiment
from azureml.core import ScriptRunConfig

script_run_config = ScriptRunConfig(source_directory=os.getcwd(), script="train.py", run_config=compute_config)
experiment = Experiment(workspace=ws, name="compute_target_test")
run = experiment.submit(config=script_run_config)
run.wait_for_completion(show_output=True)

執行完成後，您的工作區中就會有已定型的模型檔案 churn-model.pkl。

環境

命名空間：azureml.core.environment

Azure Machine Learning 環境會針對您的訓練和評分指令碼指定 Python 套件、環境變數和軟體設定。除了 Python 以外，您也可以為環境設定 PySpark、Docker 和 R。環境會在內部產生 Docker 映像，以在計算目標上執行訓練和評分程序。這些環境是在您 Machine Learning 工作區內已設定版本的受控實體，可在各種計算目標和計算類型之間啟用可重現、可稽核且可攜帶的機器學習工作流程。

您可以使用 Environment 物件來執行下列動作：

開發您的訓練指令碼。
在 Azure Machine Learning Compute 中重複使用相同的環境，以進行大規模的模型訓練。
使用相同環境部署您的模型，無須繫結至特定計算類型。

下列程式碼會從 SDK 匯入 Environment 類別，並將環境物件具現化。

from azureml.core.environment import Environment
Environment(name="myenv")

使用 Conda、pip 或私人的 Wheel 檔案，將套件新增至環境。藉由使用 CondaDependency 類別來指定每個套件相依性，以將其新增至環境的 PythonSection。

下列範例會對環境新增項目。其中會新增 1.17.0 版的 numpy。也會將 pillow 套件新增至環境 (myenv)。此範例會分別使用 add_conda_package() 方法和 add_pip_package() 方法。

from azureml.core.environment import Environment
from azureml.core.conda_dependencies import CondaDependencies

myenv = Environment(name="myenv")
conda_dep = CondaDependencies()

# Installs numpy version 1.17.0 conda package
conda_dep.add_conda_package("numpy==1.17.0")

# Installs pillow package
conda_dep.add_pip_package("pillow")

# Adds dependencies to PythonSection of myenv
myenv.python.conda_dependencies=conda_dep

若要提交訓練回合，您需要將您的環境、計算目標和訓練 Python 指令碼結合為回合組態。此組態是用於提交回合的包裝函式物件。

提交訓練回合後，建立新環境可能需要幾分鐘的時間。持續時間視所需相依性的大小而定。服務會快取環境。因此只要環境定義維持不變，您就只會遇到一次完整的安裝時間。

下列範例會示範如何使用 ScriptRunConfig 作為包裝函式物件。

from azureml.core import ScriptRunConfig, Experiment
from azureml.core.environment import Environment

exp = Experiment(name="myexp", workspace = ws)
# Instantiate environment
myenv = Environment(name="myenv")

# Add training script to run config
runconfig = ScriptRunConfig(source_directory=".", script="train.py")

# Attach compute target to run config
runconfig.run_config.target = "local"

# Attach environment to run config
runconfig.run_config.environment = myenv

# Submit run 
run = exp.submit(runconfig)

如果您在提交回合之前未在回合組態中指定環境，則會為您建立預設環境。

請參閱模型部署一節，以使用環境來部署 Web 服務。

管線、PythonScriptStep

命名空間：azureml.pipeline.core.pipeline.Pipeline
命名空間：azureml.pipeline.steps.python_script_step.PythonScriptStep

Azure Machine Learning 管線是完整機器學習工作的自動化工作流程。子工作會封裝成管線內的一系列步驟。 Azure Machine Learning 管線可以十分簡約，例如，一個呼叫 Python 指令碼的步驟。管線包含以下幾方面的功能：

資料準備，包括匯入、驗證和清除、改寫和轉換、正規化以及暫存
訓練組態，包括參數化引數、檔案路徑，以及記錄/報告組態
有效而重複地定型和驗證，其中可能包括指定特定的資料子集、不同的硬體計算資源、分散式處理和進度監視
部署，包括版本控制、調整、佈建和存取控制
將管線發佈至 REST 端點，以從任何 HTTP 程式庫重複執行

PythonScriptStep 是在計算目標上執行 Python 指令碼的基本內建步驟。它會將指令碼名稱和其他選用參數 (例如引數) 用於指令碼、計算目標、輸入和輸出。下列程式碼是 PythonScriptStep 的簡單範例。如需 train.py 指令碼的範例，請參閱教學課程小節。

from azureml.pipeline.steps import PythonScriptStep

train_step = PythonScriptStep(
    script_name="train.py",
    arguments=["--input", blob_input_data, "--output", output_data1],
    inputs=[blob_input_data],
    outputs=[output_data1],
    compute_target=compute_target,
    source_directory=project_folder
)

建立至少一個步驟之後，您可以將步驟連結在一起，並發佈為簡單的自動化管線。

from azureml.pipeline.core import Pipeline

pipeline = Pipeline(workspace=ws, steps=[train_step])
pipeline_run = experiment.submit(pipeline)

如需建置管線工作流程的完整範例，請遵循進階教學課程。

建立和使用管線的模式

Azure Machine Learning 管線會與 Azure Machine Learning 工作區相關聯，而管線步驟會與該工作區中可用的計算目標相關聯。如需詳細資訊，請參閱這篇工作區相關文章或這些計算目標相關說明。

管線步驟的常見模式如下：

指定工作區、計算和儲存體
使用下列項目設定您的輸入和輸出資料
1. 資料集，可讓現有的 Azure 資料存放區可供使用
2. PipelineDataset，可封裝具類型的表格式資料
3. PipelineData ，可用於以一個步驟撰寫，而要供另一個步驟使用的中繼檔案或目錄資料
定義一或多個管線步驟
使用您的工作區和步驟將管線具現化
建立您要對其提交管線的實驗
監視實驗結果

此 Notebook 是這個模式的理想範例。作業

如需 Azure Machine Learning 管線的詳細資訊 (尤其是它們與其他管線類型有何不同)，請參閱這篇文章。

AutoMLConfig

命名空間：azureml.train.automl.automlconfig.AutoMLConfig

使用 AutoMLConfig 類別可設定將機器學習訓練自動化的參數。自動化機器學習會逐一查看機器學習演算法和超參數設定的多種組合。接著，它會根據您選擇的精確度計量，找出最適合的模型。在設定時可以指定：

工作類型 (分類、迴歸、預測)
演算法反覆運算次數和每次反覆運算的時間上限
要最佳化的精確度計量
封鎖清單/允許清單的演算法
交叉驗證次數
計算目標
訓練資料

注意

請在您的安裝中使用 automl 額外項目，以使用自動化機器學習。

如需設定自動化機器學習實驗的詳細指南和範例，請參閱教學課程操作說明。

下列程式碼說明如何建置分類模型的自動化機器學習組態物件，並在您提交實驗時加以使用。

from azureml.train.automl import AutoMLConfig

automl_config = AutoMLConfig(task="classification",
                             X=your_training_features,
                             y=your_training_labels,
                             iterations=30,
                             iteration_timeout_minutes=5,
                             primary_metric="AUC_weighted",
                             n_cross_validations=5
                            )

使用 automl_config 物件提交實驗。

from azureml.core.experiment import Experiment

experiment = Experiment(ws, "automl_test_experiment")
run = experiment.submit(config=automl_config, show_output=True)

在您提交實驗之後，輸出會顯示每個反覆運算完成時的定型精確度。執行完成後，會傳回 AutoMLRun 物件 (延伸 Run 類別)。請使用 get_output() 函式傳回 Model 物件，以取得最適合的模型。

best_model = run.get_output()
y_predict = best_model.predict(X_test)

模型部署

命名空間：azureml.core.model.InferenceConfig
命名空間：azureml.core.webservice.webservice.Webservice

InferenceConfig 類別會用在組態設定中，用來描述裝載模型和 Web 服務所需的環境。

Webservice 是一個抽象父類別，可用來建立和部署模型的 Web 服務。如需有關準備模型部署和部署 Web 服務的詳細指南，請參閱此操作說明。

您可以在將模型部署為 Web 服務時使用環境。環境會啟用可重現的連線工作流程，讓您可以在訓練計算和推斷計算中使用相同程式庫來部署模型。就內部而言，環境會實作為 Docker 映像。您可以使用 Microsoft 提供的映像，或使用您自己的自訂 Docker 映像。如果您先前已針對部署使用 ContainerImage 類別，請參閱 DockerSection 類別，以使用環境來完成類似的工作流程。

若要部署 Web 服務，請在您的部署物件中結合環境、推斷計算、評分指令碼和已註冊的模型 (deploy())。

下列範例假設您已經使用環境 (myenv) 來完成訓練回合，並想要將該模型部署到 Azure 容器執行個體。

from azureml.core.model import InferenceConfig, Model
from azureml.core.webservice import AciWebservice, Webservice

# Register the model to deploy
model = run.register_model(model_name = "mymodel", model_path = "outputs/model.pkl")

# Combine scoring script & environment in Inference configuration
inference_config = InferenceConfig(entry_script="score.py",
                                   environment=myenv)

# Set deployment configuration
deployment_config = AciWebservice.deploy_configuration(cpu_cores = 1,
                                                       memory_gb = 1)

# Define the model, inference, & deployment configuration and web service name and location to deploy
service = Model.deploy(workspace = ws,
                       name = "my_web_service",
                       models = [model],
                       inference_config = inference_config,
                       deployment_config = deployment_config)

此範例會建立 Azure 容器執行個體 Web 服務，這是小規模測試和快速部署的最佳選擇。若要將模型部署為生產規模 Web 服務，請使用 Azure Kubernetes Service (AKS)。如需詳細資訊，請參閱 AksCompute 類別。

資料集

命名空間：azureml.core.dataset.Dataset
命名空間：azureml.data.file_dataset.FileDataset
命名空間：azureml.data.tabular_dataset.TabularDataset

Dataset 類別是用來在 Azure Machine Learning 中探索及管理資料的基礎資源。您可以使用摘要統計資料來探索資料，並將資料集儲存至 AML 工作區，以取得版本控制和重現性功能。模型在定型期間可輕易取用資料集。如需詳細的使用範例，請參閱操作指南。

TabularDataset 會以表格式格式呈現在剖析的檔案或檔案清單後建立的資料。
FileDataset 會參考資料存放區或公用 URL 中的單一或多個檔案。

下列範例說明如何建立指向資料存放區中單一路徑的 TabularDataset。

from azureml.core import Dataset

dataset = Dataset.Tabular.from_delimited_files(path = [(datastore, 'train-dataset/tabular/iris.csv')])
dataset.take(3).to_pandas_dataframe()

下列範例說明如何建立參考多個檔案 URL 的 FileDataset。

from azureml.core.dataset import Dataset

url_paths = [
            'http://yann.lecun.com/exdb/mnist/train-images-idx3-ubyte.gz',
            'http://yann.lecun.com/exdb/mnist/train-labels-idx1-ubyte.gz',
            'http://yann.lecun.com/exdb/mnist/t10k-images-idx3-ubyte.gz',
            'http://yann.lecun.com/exdb/mnist/t10k-labels-idx1-ubyte.gz'
            ]
dataset = Dataset.File.from_files(path=url_paths)

後續步驟

請嘗試下列步驟，了解如何使用適用於 Python 的 Azure Machine Learning SDK：

遵循教學課程，以了解如何在 Python 中建置、定型和部署模型。
使用左側的目錄，在此網站上查閱參考文件中的類別和模組。