安裝及使用 CLI （v1）

發行項
01/10/2024

重要

本文中的某些 Azure CLI 命令會使用 azure-cli-mlAzure 機器學習的、或 v1 擴充功能。 v1 延伸模組的支援將於 2025 年 9 月 30 日結束。您將能夠安裝並使用 v1 延伸模組，直到該日期為止。

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

Azure 機器學習 CLI 是 Azure CLI 的延伸模組，這是 Azure 平臺的跨平臺命令行介面。此延伸模組提供使用 Azure 機器學習的命令。它可讓您將機器學習活動自動化。下列清單提供一些您可以使用 CLI 延伸模組執行的範例動作：

執行實驗以建立機器學習模型
註冊機器學習模型以供客戶使用
封裝、部署及追蹤機器學習模型的生命週期

CLI 不是 Azure 機器學習 SDK 的取代專案。這是一個互補工具，可優化來處理適合自動化的高度參數化工作。

必要條件

若要使用 CLI，您必須擁有 Azure 訂用帳戶。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。立即試用免費或付費版本的 Azure 機器學習。
若要從本機環境使用本檔中的 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 機器學習工作區的訂用帳戶相同。您可以流覽工作區的概觀頁面，從 Azure 入口網站找到訂用帳戶標識碼。

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

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

安裝延伸模組

若要安裝 CLI （v1）擴充功能：

az extension add -n azure-cli-ml

更新擴充功能

若要更新機器學習 CLI 擴充功能，請使用下列命令：

az extension update -n azure-cli-ml

拿掉延伸模組

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

az extension remove -n azure-cli-ml

資源管理

下列命令示範如何使用 CLI 來管理 Azure 機器學習所使用的資源。

如果您還沒有資源群組，請建立資源群組：
```
az group create -n myresourcegroup -l westus2
```
建立 Azure 機器學習工作區：
```
az ml workspace create -w myworkspace -g myresourcegroup
```
如需詳細資訊，請參閱 az ml workspace create。
將工作區組態附加至資料夾，以啟用 CLI 內容感知。
```
az ml folder attach -w myworkspace -g myresourcegroup
```
此命令會建立子 .azureml 目錄，其中包含範例 runconfig 和 conda 環境檔案。它也包含config.json用來與 Azure 機器學習工作區通訊的檔案。

如需詳細資訊，請參閱 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 機器學習計算叢集僅支援一個系統指派的身分識別或多個使用者指派的身分識別，而非同時支援兩者。

計算執行個體

管理計算實例。在下列所有範例中，計算實例的名稱是 cpu

建立新的計算實例。
```
az ml computetarget create computeinstance -n cpu -s "STANDARD_D3_V2" -v
```
如需詳細資訊，請參閱 az ml computetarget create computeinstance。
停止計算實例。
```
az ml computetarget computeinstance stop -n cpu -v
```
如需詳細資訊，請參閱 az ml computetarget computeinstance stop。
啟動計算實例。
```
az ml computetarget computeinstance start -n cpu -v
```
如需詳細資訊，請參閱 az ml computetarget computeinstance start。
重新啟動計算實例。
```
az ml computetarget computeinstance restart -n cpu -v
```
如需詳細資訊，請參閱 az ml computetarget computeinstance restart。
刪除計算實例。
```
az ml computetarget delete -n cpu -v
```
如需詳細資訊，請參閱 az ml computetarget delete computeinstance。

執行實驗

開始執行實驗。使用此命令時，請針對 -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.

將這個檔案與執行組態檔一起新增。然後使用：

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

請注意 Runconfig 中的自變數區段，以及 HyperDrive 組態中的參數空間。它們包含要傳遞至定型腳本的命令行自變數。 runconfig 中的值會針對每個反覆項目維持不變，而 HyperDrive 組態中的範圍則會逐一查看。請勿在這兩個檔案中指定相同的自變數。

數據集管理

下列命令示範如何使用 Azure 機器學習中的數據集：

註冊資料集：
```
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 機器學習環境：

建立環境的 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 建立自定義環境組態。最上層物件會鬆散地對應至 Environment Python SDK 中的類別。

{
    "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_variables 類別中的 Environment 變數。

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

ML 管線管理

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

建立機器學習管線：
```
az ml pipeline create -n mypipeline -y mypipeline.yml
```
如需詳細資訊，請參閱 az ml pipeline create。

如需管線 YAML 檔案的詳細資訊，請參閱在 YAML 中定義機器學習管線。
執行管線：
```
az ml run submit-pipeline -n myexperiment -y mypipeline.yml
```
如需詳細資訊，請參閱 az ml run submit-pipeline。

如需管線 YAML 檔案的詳細資訊，請參閱在 YAML 中定義機器學習管線。

排程管線：

az ml pipeline create-schedule -n myschedule -e myexperiment -i mypipelineid -y myschedule.yml

如需詳細資訊，請參閱 az ml pipeline create-schedule。

模型註冊、分析、部署

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

向 Azure 機器學習註冊模型：
```
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`	選擇性。包含要建立映像之所有檔案的資料夾路徑，可讓您輕鬆地存取此資料夾或子資料夾中的任何檔案。您可以從本機電腦上傳整個資料夾作為 Webservice 的相依性。注意：您的entry_script、conda_file和extra_docker_file_steps路徑是source_directory路徑的相對路徑。
`environment`	`environment`	選擇性。 Azure 機器學習環境。

您可以在推斷組態檔中包含 Azure 機器學習環境的完整規格。如果您的工作區中沒有此環境，Azure 機器學習將會建立它。否則，Azure 機器學習會視需要更新環境。下列 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 機器學習環境，並從推斷組態檔中移除「環境」金鑰。針對環境名稱使用 -e，針對環境版本使用 --ev。如果您未指定 --ev，則會使用最新版本。以下是推斷組態檔的範例：

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

下列命令示範如何使用先前的推斷組態檔來部署模型（名為 myInferenceConfig.json）。

它也使用最新版的現有 Azure 機器學習環境（名為 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`	是否要為此 Web 服務啟用 SSL。預設為 False。
`appInsightsEnabled`	`enable_app_insights`	是否要為此 Web 服務啟用 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`	要用於此 Webservice 的主要驗證金鑰
`secondaryKey`	`secondary_key`	要用於此 Webservice 的次要驗證金鑰
`gpuCores`	`gpu_cores`	要配置給此 Webservice 的 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'）和連字元（'-'）個字元。第一個和最後一個字元不能是連字元。