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

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

SDK 的主要領域包括：

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

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

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

穩定與實驗

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

實驗性功能會以 SDK 參考中的附註區段標示，並以 （預覽） 等文字表示，Azure Machine Learning 檔。

工作

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

Workspace 類別是雲端中用來實驗、定型及部署機器學習模型的基礎資源。 它會將您的 Azure 訂用帳戶和資源群組系結至容易取用的物件。

檢視 create Workspace 方法的所有參數 重複使用現有的實例（儲存器、Key Vault、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 筆記本中以互動方式進行實驗，請使用 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，以查看異步執行輸出，因為環境已初始化並定型模型。

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 或私人轉輪檔案將套件新增至環境。 使用 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服務。

Pipeline、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的簡單範例。 如需 腳本的範例，請參閱 子區段 教學課程。

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. 指定工作區、計算和記憶體
2. 使用設定輸入和輸出數據
   1. 數據集，讓現有的 Azure 資料存放區可供使用
   2. PipelineDataset 封裝具類型的表格式數據
   3. PipelineData，用於一個步驟所寫入的中繼檔案或目錄數據，並打算由另一個步驟取用
3. 定義一或多個管線步驟
4. 使用您的工作區和步驟具現化管線
5. 建立您提交管線的實驗
6. 監視實驗結果

此筆記本 是此模式的良好範例。 工作

如需 Azure Machine Learning 管線的詳細資訊，特別是它們與其他管線類型不同的方式，請參閱此 文章。

AutoMLConfig

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

使用 AutoMLConfig 類別來設定自動化機器學習訓練的參數。 自動化機器學習會逐一查看機器學習演算法和超參數設定的許多組合。 然後，它會根據您選擇的精確度計量，尋找最適合的模型。 組態允許指定：

• 工作類型（分類、回歸、預測）
• 每個反覆專案的演算法反覆項目數目和最大時間
• 優化的正確性計量
• 封鎖清單/允許清單的演算法
• 交叉驗證的數目
• 計算目標
• 定型數據

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

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

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 中建置、定型和部署模型。

• 使用左側目錄，查閱此網站上的參考檔中的類別和模組。