安裝 & 使用 CLI (v1)

  • 發行項

適用於：Azure CLI ml 延伸模組 v1

重要

本文中的 Azure CLI 命令需要azure-cli-ml 或 v1，Azure Machine Learning 的擴充功能。 v1 擴充功能的支援將於 2025 年 9 月 30 日終止。 您將能安裝並使用 v1 擴充功能，直到該日期為止。

建議您在 2025 年 9 月 30 日之前轉換至 ml 或 v2 擴充功能。 如需有關 v2 擴充功能的詳細資訊，請參閱 Azure ML CLI 擴充功能和 Python SDK v2。

Azure Machine Learning CLI 是 Azure CLI 的擴充功能，而 Azure CLI 是 Azure 平台的跨平台命令列介面。 此擴充功能提供命令，供您使用 Azure Machine Learning， 讓您能夠自動化機器學習活動。 下列清單提供一些可透過 CLI 擴充功能執行的一些範例動作：

  • 執行實驗來建立機器學習服務模型

  • 註冊供客戶使用的機器學習服務模型

  • 封裝、部署和追蹤機器學習模型的生命週期

CLI 不是 Azure Machine Learning SDK 的取代項目。 它是已經過最佳化處理的補充工具，可處理適合自動化的高度參數化工作。

必要條件

  • 若要使用 CLI，您必須擁有 Azure 訂用帳戶。 如果您沒有 Azure 訂用帳戶，請在開始前先建立免費帳戶。 立即試用免費或付費版本的 Azure Machine Learning。

  • 若要從您的本機環境使用本文件中的 CLI 命令，您需要 Azure CLI。

    如果您使用 Azure Cloud Shell，則可透過瀏覽器存取 CLI，並存留在雲端。

完整參考文件

尋找適用於 Azure CLI 的 azure-cli-ml 擴充功能完整參考文件。

將 CLI 連接至您的 Azure 訂用帳戶

重要

如果您是使用 Azure Cloud Shell，則可以跳過本節。 Cloud Shell 會使用您登入 Azure 訂閱的帳戶，自動驗證您的身分。

您可藉由數種方式透過 CLI 向您的 Azure 訂用帳戶進行驗證。 最基本的方式是使用瀏覽器，以互動方式進行驗證。 若要以互動方式進行驗證，請開啟命令列或終端機，並使用下列命令：

az login

如果 CLI 可以開啟預設瀏覽器，它會執行這項操作，並載入登入頁面。 否則，您需要開啟瀏覽器，並遵循命令列上的指示。 這些指示需要瀏覽至 https://aka.ms/devicelogin，並輸入授權碼。

提示

登入之後，您會看到一份與 Azure 帳戶相關聯的訂用帳戶清單。 具有 isDefault: true 的訂用帳戶資訊是目前針對 Azure CLI 命令啟用的訂用帳戶。 此訂用帳戶必須是包含 Azure Machine Learning 工作區的相同訂用帳戶。 您可從 Azure 入口網站瀏覽工作區的概觀頁面來尋找訂用帳戶識別碼。 您也可以使用 SDK，從工作區物件取得訂用帳戶識別碼。 例如： Workspace.from_config().subscription_id 。

若要選取另一個訂用帳戶，請使用 az account set -s <subscription name or ID> 命令並指定訂用帳戶名稱或識別碼以進行切換。 如需訂用帳戶選取的詳細資訊，請參閱使用多個 Azure 訂用帳戶。

如需其他驗證方法，請參閱使用 Azure CLI 登入。

安裝延伸模組

若要安裝 CLI (v1) 擴充功能：

az extension add -n azure-cli-ml

更新擴充功能

若要更新 Machine Learning CLI 擴充功能，請使用下列命令：

az extension update -n azure-cli-ml

移除擴充功能

若要移除 CLI 擴充功能，請使用下列命令：

az extension remove -n azure-cli-ml

資源管理

下列命令示範如何使用 CLI 來管理 Azure Machine Learning 所使用的資源。

  • 如果您還沒有，請建立資源群組：

    az group create -n myresourcegroup -l westus2

  • 建立 Azure Machine Learning 工作區：

    az ml workspace create -w myworkspace -g myresourcegroup

    如需詳細資訊，請參閱 az ml workspace create。

  • 將工作區設定連結至資料夾，以啟用 CLI 內容感知。

    az ml folder attach -w myworkspace -g myresourcegroup

    此命令會建立一個 .azureml 子目錄，其中包含範例 runconfig 和 conda 環境檔案。 它也包含用來與 Azure Machine Learning 工作區通訊的 config.json 檔案。

    如需詳細資訊，請參閱 az ml folder attach。

  • 連結 Azure Blob 容器做為資料存放區。

    az ml datastore attach-blob  -n datastorename -a accountname -c containername

    如需詳細資訊，請參閱 az ml datastore attach-blob。

  • 上傳檔案到資料存放區。

    az ml datastore upload  -n datastorename -p sourcepath

    如需詳細資訊，請參閱 az ml datastore upload。

  • 連結 AKS 叢集做為計算目標。

    az ml computetarget attach aks -n myaks -i myaksresourceid -g myresourcegroup -w myworkspace

    如需詳細資訊，請參閱 az ml computetarget attach aks

計算叢集

  • 建立新的受控計算叢集。

    az ml computetarget create amlcompute -n cpu --min-nodes 1 --max-nodes 1 -s STANDARD_D3_V2

  • 使用受控識別建立新的受控計算叢集

    • 使用者指派的受控識別

      az ml computetarget create amlcompute --name cpu-cluster --vm-size Standard_NC6 --max-nodes 5 --assign-identity '/subscriptions/<subcription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user_assigned_identity>'

    • 系統指派的受控識別

      az ml computetarget create amlcompute --name cpu-cluster --vm-size Standard_NC6 --max-nodes 5 --assign-identity '[system]'

  • 將受控識別新增至現有的叢集：

    • 使用者指派的受控識別

      az ml computetarget amlcompute identity assign --name cpu-cluster '/subscriptions/<subcription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user_assigned_identity>'

    • 系統指派的受控識別

      az ml computetarget amlcompute identity assign --name cpu-cluster '[system]'

如需詳細資訊，請參閱 az ml computetarget create amlcompute。

注意

Azure Machine Learning 計算叢集僅支援一個系統指派的身分識別，或多個使用者指派的身分識別，無法同時支援兩者。

計算執行個體

管理計算執行個體。 在下列所有範例中，計算執行個體的名稱為 cpu

執行實驗

  • 開始您的實驗回合。 使用此命令時，請對應 -c 參數指定 runconfig 檔案的名稱 (如果您是在檔案系統中查看，則為 *.runconfig 前面的文字)。

    az ml run submit-script -c sklearn -e testexperiment train.py

    提示

    az ml folder attach 命令會建立一個 .azureml 子目錄，其中包含兩個範例 runconfig 檔案。

    如果您有使用程式設計方式建立執行設定物件的 Python 指令碼，則可以使用 RunConfig.save() 以將其儲存為 runconfig 檔案。

    您可以在此 JSON 檔案中找到完整的 runconfig 結構描述。 此結構描述是透過每個物件的 description 索引鍵自行記錄。 此外，有一些列舉的可能值，以及結尾的範本程式碼片段。

    如需詳細資訊，請參閱 az ml run submit-script。

  • 檢視實驗清單：

    az ml experiment list

    如需詳細資訊，請參閱 az ml experiment list。

HyperDrive 回合

您可以搭配使用 HyperDrive 與 Azure CLI 來執行參數微調回合。 首先，以下列格式建立 HyperDrive 組態檔。 如需超參數微調參數的詳細資訊，請參閱為您的模型調整超參數一文。

# hdconfig.yml
sampling: 
    type: random # Supported options: Random, Grid, Bayesian
    parameter_space: # specify a name|expression|values tuple for each parameter.
    - name: --penalty # The name of a script parameter to generate values for.
      expression: choice # supported options: choice, randint, uniform, quniform, loguniform, qloguniform, normal, qnormal, lognormal, qlognormal
      values: [0.5, 1, 1.5] # The list of values, the number of values is dependent on the expression specified.
policy: 
    type: BanditPolicy # Supported options: BanditPolicy, MedianStoppingPolicy, TruncationSelectionPolicy, NoTerminationPolicy
    evaluation_interval: 1 # Policy properties are policy specific. See the above link for policy specific parameter details.
    slack_factor: 0.2
primary_metric_name: Accuracy # The metric used when evaluating the policy
primary_metric_goal: Maximize # Maximize|Minimize
max_total_runs: 8 # The maximum number of runs to generate
max_concurrent_runs: 2 # The number of runs that can run concurrently.
max_duration_minutes: 100 # The maximum length of time to run the experiment before cancelling.

連同回合組態檔一起新增此檔案。 然後，使用下列命令提交 HyperDrive 回合：

az ml run submit-hyperdrive -e <experiment> -c <runconfig> --hyperdrive-configuration-name <hdconfig> my_train.py

請注意 runconfig 中的 arguments 區段，以及 HyperDrive config 中的 parameter space。其包含要傳遞至定型指令碼的命令列引數。 runconfig 中的值會在每次反覆運算時維持不變，而 HyperDrive config 中的範圍則會遭到反覆處理。 請勿在這兩個檔案中指定相同的引數。

資料集管理

下列命令示範如何使用 Azure Machine Learning 中的資料集：

  • 註冊資料集：

    az ml dataset register -f mydataset.json

    如需用於定義資料集的 JSON 檔案格式相關資訊，請使用 az ml dataset register --show-template。

    如需詳細資訊，請參閱 az ml dataset register。

  • 列出工作區中的所有資料集：

    az ml dataset list

    如需詳細資訊，請參閱 az ml dataset list。

  • 取得資料集的詳細資料：

    az ml dataset show -n dataset-name

    如需詳細資訊，請參閱 az ml dataset show。

  • 取消註冊資料集：

    az ml dataset unregister -n dataset-name

    如需詳細資訊，請參閱 az ml dataset unregister。

環境管理

下列命令示範如何為您的工作區建立、註冊和列出 Azure Machine Learning 環境：

  • 為環境建立 Scaffolding 檔案：

    az ml environment scaffold -n myenv -d myenvdirectory

    如需詳細資訊，請參閱 az ml environment scaffold。

  • 註冊環境：

    az ml environment register -d myenvdirectory

    如需詳細資訊，請參閱 az ml environment register。

  • 列出註冊的環境：

    az ml environment list

    如需詳細資訊，請參閱 az ml environment list。

  • 下載註冊的環境：

    az ml environment download -n myenv -d downloaddirectory

    如需詳細資訊，請參閱 az ml environment download。

環境設定結構描述

如果您使用 az ml environment scaffold 命令，它會產生可修改的範本 azureml_environment.json 檔案，並使用 CLI 來建立自訂環境設定。 最上層物件會鬆散地對應至 Python SDK 中的 Environment 類別。

{
    "name": "testenv",
    "version": null,
    "environmentVariables": {
        "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
    },
    "python": {
        "userManagedDependencies": false,
        "interpreterPath": "python",
        "condaDependenciesFile": null,
        "baseCondaEnvironment": null
    },
    "docker": {
        "enabled": false,
        "baseImage": "mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210615.v1",
        "baseDockerfile": null,
        "sharedVolumes": true,
        "shmSize": "2g",
        "arguments": [],
        "baseImageRegistry": {
            "address": null,
            "username": null,
            "password": null
        }
    },
    "spark": {
        "repositories": [],
        "packages": [],
        "precachePackages": true
    },
    "databricks": {
        "mavenLibraries": [],
        "pypiLibraries": [],
        "rcranLibraries": [],
        "jarLibraries": [],
        "eggLibraries": []
    },
    "inferencingStackVersion": null
}

下表詳細說明 JSON 檔案中的每個最上層欄位、其類型，以及描述。 如果物件類型已連結至 Python SDK 的類別，則每個 JSON 欄位與 Python 類別中的公用變數名稱之間會有一個鬆散的 1:1 比對。 在某些情況下，欄位可能會對應至建構函式引數，而不是類別變數。 例如，environmentVariables 欄位會對應至 Environment 類別中的 environment_variables 變數。

JSON 欄位 類型 描述
name string 環境的名稱。 名稱開頭請勿使用 Microsoft 或 AzureML。
version string 環境的版本。
environmentVariables {string: string} 環境變數名稱和值的雜湊對應。
python PythonSection 定義目標計算資源上使用的 Python 環境和解譯器。
docker DockerSection 定義設定，以自訂根據環境規格建立的 Docker 映像。
spark SparkSection 此區段可設定 Spark 設定。 只有當架構設為 PySpark 時，才會使用它。
databricks DatabricksSection 設定 Databricks 程式庫相依性。
inferencingStackVersion string 指定新增至映像的推斷堆疊版本。 若要避免新增推斷堆疊，請將此欄位保留 null。 有效值："latest"。

ML 管線管理

下列命令示範如何使用機器學習管線：

模型註冊、分析、部署

下列命令示範如何註冊定型的模型，然後將它部署為生產服務：

  • 向 Azure Machine Learning 註冊模型：

    az ml model register -n mymodel -p sklearn_regression_model.pkl

    如需詳細資訊，請參閱 az ml model register。

  • 選擇性分析您的模型，以取得最佳的 CPU 和記憶體以供部署使用。

    az ml model profile -n myprofile -m mymodel:1 --ic inferenceconfig.json -d "{\"data\": [[1,2,3,4,5,6,7,8,9,10],[10,9,8,7,6,5,4,3,2,1]]}" -t myprofileresult.json

    如需詳細資訊，請參閱 az ml model profile。

  • 將您的模型部署至 AKS

    az ml model deploy -n myservice -m mymodel:1 --ic inferenceconfig.json --dc deploymentconfig.json --ct akscomputetarget

    如需關於推斷設定檔結構描述的詳細資訊，請參閱推斷設定結構描述。

    如需關於部署設定檔結構描述的詳細資訊，請參閱部署設定結構描述。

    如需詳細資訊，請參閱 az ml model deploy。

推斷設定結構描述

inferenceconfig.json 文件中的項目會對應至 InferenceConfig 類別的參數。 下表描述 JSON 文件中的實體之間的對應以及方法的參數：

JSON 實體 方法參數 描述
entryScript entry_script 本機檔案的路徑，其中包含要為映像執行的程式碼。
sourceDirectory source_directory 選擇性。 資料夾的路徑，其中包含要建立映像的所有檔案，讓您可以在此資料夾或子資料夾中輕鬆存取任何檔案。 您可以從本機電腦上傳整個資料夾，作為 Web 服務的相依性。 注意：entry_script、conda_file 和 extra_docker_file_steps 路徑是 source_directory 路徑的相對路徑。
environment environment 選擇性。 Azure Machine Learning 環境。

您可以在推斷設定檔中包含 Azure Machine Learning 環境的完整規格。 如果工作區中不存在此環境，則 Azure Machine Learning 會加以建立。 否則，Azure Machine Learning 將視需要更新環境。 下列 JSON 是一個範例：

{
    "entryScript": "score.py",
    "environment": {
        "docker": {
            "arguments": [],
            "baseDockerfile": null,
            "baseImage": "mcr.microsoft.com/azureml/intelmpi2018.3-ubuntu18.04",
            "enabled": false,
            "sharedVolumes": true,
            "shmSize": null
        },
        "environmentVariables": {
            "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
        },
        "name": "my-deploy-env",
        "python": {
            "baseCondaEnvironment": null,
            "condaDependencies": {
                "channels": [
                    "conda-forge"
                ],
                "dependencies": [
                    "python=3.7",
                    {
                        "pip": [
                            "azureml-defaults",
                            "azureml-telemetry",
                            "scikit-learn==0.22.1",
                            "inference-schema[numpy-support]"
                        ]
                    }
                ],
                "name": "project_environment"
            },
            "condaDependenciesFile": null,
            "interpreterPath": "python",
            "userManagedDependencies": false
        },
        "version": "1"
    }
}

您也可以在不同的 CLI 參數中使用現有的 Azure Machine Learning 環境，並從推斷設定檔中移除「環境」金鑰。 針對環境名稱使用 -e，並針對環境版本使用 --ev。 如果您未指定--ev，則會使用最新版本。 以下是推斷設定檔的範例：

{
    "entryScript": "score.py",
    "sourceDirectory": null
}

下列命令示範如何使用先前的推斷設定檔 (名為 myInferenceConfig.json) 來部署模型。

其也會使用現有 Azure Machine Learning 環境 (名為 AzureML-Minimal) 的最新版本。

az ml model deploy -m mymodel:1 --ic myInferenceConfig.json -e AzureML-Minimal --dc deploymentconfig.json

部署設定結構描述

本地部署設定結構描述

deploymentconfig.json 文件中的項目會對應至 LocalWebservice.deploy_configuration 的參數。 下表描述 JSON 文件中的實體之間的對應以及方法的參數：

JSON 實體 方法參數 描述
computeType NA 計算目標。 若為本機目標，該值必須為 local。
port port 本機連接埠上公開服務的 HTTP 端點。

此 JSON 是與 CLI 搭配使用的範例部署設定：

{
    "computeType": "local",
    "port": 32267
}

將此 JSON 儲存為稱為 deploymentconfig.json 的檔案。

Azure 容器執行個體部署設定結構描述

deploymentconfig.json 文件中的專案會對應至 AciWebservice.deploy_configuration 的參數。 下表描述 JSON 文件中的實體之間的對應以及方法的參數：

JSON 實體 方法參數 描述
computeType NA 計算目標。 若為 ACI，則值必須為 ACI。
containerResourceRequirements NA CPU 和記憶體實體的容器。
  cpu cpu_cores 要配置的 CPU 核心數目。 依預設，0.1
  memoryInGB memory_gb 要為此 Web 服務配置的記憶體 (GB) 數量。 預設值，0.5
location location 要作為部署此 Webservice 的 Azure 區域。 如果未指定，則將會使用工作區位置。 如需可用區域的詳細資訊，請參閱：ACI 區域
authEnabled auth_enabled 是否要啟用此 Webservice 的驗證。 預設為 False
sslEnabled ssl_enabled 是否要為此 Webservice 啟用 SSL。 預設為 False。
appInsightsEnabled enable_app_insights 是否要為此 Webservice 啟用 AppInsights。 預設為 False
sslCertificate ssl_cert_pem_file 若已啟用 SSL，則需要憑證檔案
sslKey ssl_key_pem_file 啟用 SSL 時所需的金鑰檔案
cname ssl_cname 如果 SSL 已啟用，則為 cname
dnsNameLabel dns_name_label 評分端點的 DNS 名稱標籤。 若未指定，就會為評分端點產生唯一的 DNS 名稱標籤。

下列 JSON 是與 CLI 搭配使用的範例部署設定：

{
    "computeType": "aci",
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    },
    "authEnabled": true,
    "sslEnabled": false,
    "appInsightsEnabled": false
}

Azure Kubernetes Service 部署設定結構描述

deploymentconfig.json 文件中的專案會對應至 AksWebservice.deploy_configuration 的參數。 下表描述 JSON 文件中的實體之間的對應以及方法的參數：

JSON 實體 方法參數 描述
computeType NA 計算目標。 若為 AKS，則值必須為 aks。
autoScaler NA 包含自動調整的組態元素。 請參閱自動調整資料表。
  autoscaleEnabled autoscale_enabled 是否為 Web 服務啟用自動調整。 如果 numReplicas = 0，則為 True：否則為 False。
  minReplicas autoscale_min_replicas 自動調整此 Web 服務時，要使用的容器數目下限。 預設值：1。
  maxReplicas autoscale_max_replicas 自動調整此 Web 服務時，要使用的容器數目上限。 預設值：10。
  refreshPeriodInSeconds autoscale_refresh_seconds 自動調整器嘗試調整此 Web 服務的頻率。 預設值：1。
  targetUtilization autoscale_target_utilization 自動調整器應嘗試為此 Web 服務維持的目標使用率 (以百分比為單位，最高 100)。 預設值：70。
dataCollection NA 包含資料收集的組態元素。
  storageEnabled collect_model_data 是否要啟用 Web 服務的模型資料收集。 預設值：False。
authEnabled auth_enabled 是否要啟用 Web 服務的金鑰驗證。 tokenAuthEnabled 和 authEnabled 都無法為 True。 預設值：True。
tokenAuthEnabled token_auth_enabled 是否要啟用 Web 服務的權杖驗證。 tokenAuthEnabled 和 authEnabled 都無法為 True。 預設值：False。
containerResourceRequirements NA CPU 和記憶體實體的容器。
  cpu cpu_cores 要為此 Web 服務配置的 CPU 核心數目。 依預設，0.1
  memoryInGB memory_gb 要為此 Web 服務配置的記憶體 (GB) 數量。 預設值，0.5
appInsightsEnabled enable_app_insights 是否要啟用 Web 服務的 Application Insights 記錄。 預設值：False。
scoringTimeoutMs scoring_timeout_ms 要對 Web 服務評分呼叫強制套用的逾時毫秒數。 預設值：60000。
maxConcurrentRequestsPerContainer replica_max_concurrent_requests 此 Web 服務每個節點的並行要求數上限。 預設值：1。
maxQueueWaitMs max_request_wait_time 在傳回 503 錯誤之前，要求會停留在該佇列中的時間上限 (以毫秒為單位)。 預設值：500。
numReplicas num_replicas 要為此 Web 服務配置的容器數目。 無預設值。 如果未設定此參數，則預設會啟用自動調整程式。
keys NA 包含金鑰的組態元素。
  primaryKey primary_key 用於此 Web 服務的主要驗證金鑰
  secondaryKey secondary_key 用於此 Web 服務的次要驗證金鑰
gpuCores gpu_cores 要為此 Web 服務配置的 GPU 核心數 (每個容器複本)。 預設值為 1。 僅支援整數值。
livenessProbeRequirements NA 包含活躍度探查需求的組態元素。
  periodSeconds period_seconds 執行活躍度探查的頻率 (以秒為單位)。 預設值為 10 秒。 最小值為 1。
  initialDelaySeconds initial_delay_seconds 在起始活躍度探查之前，容器啟動後的秒數。 預設值為 310
  timeoutSeconds timeout_seconds 活躍度探查逾時之前所經過的秒數。預設值為 2 秒。 最小值為 1。
  successThreshold success_threshold 失敗之後，會將活躍度探查的最小連續成功次數視為成功。 預設值為 1。 最小值為 1。
  failureThreshold failure_threshold 當 Pod 啟動且活躍度探查失敗時，Kubernetes 會在放棄之前先嘗試使用 failureThreshold 時間。 預設值為 3。 最小值為 1。
namespace namespace Web 服務部署所在的 Kubernetes 命名空間。 最多 63 個小寫英數字元 ('a'-'z，'0'-'9') 和連字號 ('-') 字元。 第一個和最後一個字元不可以是連字號。

下列 JSON 是與 CLI 搭配使用的範例部署設定：

{
    "computeType": "aks",
    "autoScaler":
    {
        "autoscaleEnabled": true,
        "minReplicas": 1,
        "maxReplicas": 3,
        "refreshPeriodInSeconds": 1,
        "targetUtilization": 70
    },
    "dataCollection":
    {
        "storageEnabled": true
    },
    "authEnabled": true,
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    }
}

後續步驟