共用方式為


安裝及使用 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 機器學習 CLI 是 Azure CLI延伸模組,這是 Azure 平臺的跨平臺命令行介面。 此延伸模組提供使用 Azure 機器學習 的命令。 它可讓您將機器學習活動自動化。 下列清單提供一些您可以使用 CLI 延伸模組執行的範例動作:

  • 執行實驗以建立機器學習模型

  • 註冊機器學習模型以供客戶使用

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

CLI 不是 Azure 機器學習 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 入口網站中工作區的概觀頁面上找到訂用帳戶資訊。

若要選取另一個訂用帳戶來用於 Azure CLI 命令,請執行 az account set -s <subscription> 命令,並指定要切換到的訂用帳戶名稱或識別碼。 如需訂用帳戶選項的詳細資訊,請參閱使用多個 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 環境檔案。 它也包含用來與 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.

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

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 環境的名稱。 請勿以 MicrosoftAzureML 開頭。
version string 環境的版本。
environmentVariables {string: string} 環境變數名稱和值的哈希對應。
python PythonSectionhat 定義要用於目標計算資源的 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 是否要為此 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 服務的金鑰驗證。 tokenAuthEnabledauthEnabled 都無法為 True。 預設值:True
tokenAuthEnabled token_auth_enabled 是否要啟用 Web 服務的權杖驗證。 tokenAuthEnabledauthEnabled 都無法為 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
    }
}

下一步