使用第 1 版將模型部署至 Azure Kubernetes Service 叢集

發行項
03/13/2024

重要

本文說明如何使用 Azure 機器學習 CLI （v1）和 Azure 機器學習 SDK for Python （v1）來部署模型。如需第 2 版的建議方法，請參閱使用線上端點來部署和評分機器學習模型。

了解如何使用 Azure Machine Learning 在 Azure Kubernetes Service (AKS) 上將模型部署為 Web 服務。 AKS 適用於大規模生產環境部署。如果您需要下列一或多個功能，請使用 AKS：

快速回應時間
已部署服務的自動調整
Logging
模型資料收集
驗證
TLS 終止
硬體加速選項，例如 GPU 和可現場程式化閘道陣列 (FPGA)

部署至 AKS 時，您會部署到連線至工作區的 AKS 叢集。如需將 AKS 叢集連線至工作區的相關資訊，請參閱建立和連結 Azure Kubernetes Service 叢集。

重要

建議您先在本機進行偵錯，再部署至 Web 服務。如需詳細資訊，請參閱使用本機模型部署進行疑難解答。

您也可以參閱在 GitHub 上部署至本機筆記本。

注意

Azure Machine Learning 端點 (v2) 提供經過改良且更簡單的部署體驗。端點同時支援即時和 Batch 推斷案例。端點會提供整合介面，以叫用和管理跨計算類型的模型部署。請參閱什麼是 Azure Machine Learning 端點？。

必要條件

Azure Machine Learning 工作區。如需詳細資訊，請參閱建立 Azure Machine Learning 工作區。
在您的工作區中登錄的機器學習模型。如果您沒有已註冊的模型，請參閱將機器學習模型部署至 Azure。
適用於 Machine Learning 服務的 Azure CLI 延伸模組 (第 1 版)、Azure Machine Learning Python SDK 或 Azure Machine Learning Visual Studio Code 擴充功能。

重要

本文中的 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。
本文中的 Python 程式碼片段會假設已設定下列變數：
- ws - 設為您的工作區。
- model - 設為您已註冊的模型。
- inference_config - 設為模型的推斷設定。
如需設定這些變數的詳細資訊，請參閱部署模型的方式和位置。
本文中的 CLI 代碼段假設您已建立 inferenceconfig.json 檔。如需建立此文件的詳細資訊，請參閱將機器學習模型部署至 Azure。
線上到工作區的 AKS 叢集。如需詳細資訊，請參閱建立和連結 Azure Kubernetes Service 叢集。
- 如果您想要將模型部署到 GPU 節點或 FPGA 節點（或任何特定產品），則必須建立具有特定產品的叢集。不支援在現有的叢集中建立次要節點集區，並在次要節點集區中部署模型。

瞭解部署程式

Kubernetes 和 Azure 機器學習都使用部署一詞。部署在這兩個內容中有不同的意義。在 Kubernetes 中，部署是具有宣告式 YAML 檔案指定的具體實體。 Kubernetes 部署具有定義的生命週期和與其他 Kubernetes 實體的具體關聯性，例如 Pods 和 ReplicaSets。您可以從位於什麼是 Kubernetes？的文件和影片了解 Kubernetes。

在 Azure 機器學習中，部署在更一般意義上的可用和清除項目資源。 Azure Machine Learning 認為屬於部署一部分的步驟為：

壓縮項目資料夾中的檔案，忽略 .amlignore 或 .gitignore 中指定的檔案
相應增加計算叢集（與 Kubernetes 相關）
建置或下載 dockerfile 至計算節點（與 Kubernetes 相關）
1. 系統會計算下列雜湊：
  - 基礎映像
  - 自訂 Docker 步驟 (請參閱使用自訂 Docker 基礎映像部署模型)
  - conda 定義 YAML (請參閱在 Azure Machine Learning 中建立及使用軟體環境)
2. 系統會使用此雜湊作為工作區 Azure Container Registry (ACR) 查閱中的索引鍵
3. 如果找不到，它會在全域 ACR 中尋找相符專案
4. 如果找不到，系統會建置快取並推送至工作區 ACR 的新映射
將壓縮的專案檔案下載至計算節點上的暫存儲存體
解壓縮專案檔
執行 python <entry script> <arguments> 的計算節點
將記錄、模型檔案和其他寫入 ./output 的檔案儲存至與工作區相關聯的記憶體帳戶
相應減少計算，包括移除暫存記憶體（與 Kubernetes 相關）

Azure Machine Learning 路由器

將傳入推斷要求路由至部署的服務的前端元件 (azureml-fe) 會視需要自動調整。 azureml-fe 的調整是根據 AKS 叢集用途和大小 (節點數目)。建立或連結 AKS 叢集時，會設定叢集目的和節點。每個叢集都有一個 azureml-fe 服務，可能會在多個 Pod 上執行。

重要

使用設定為dev-test的叢集時，會停用自我調整程式。即使是 FastProd/DenseProd 叢集，Self-Scaler 也僅在遙測顯示需要時才會啟用。

注意

要求承載上限為 100 MB。

Azureml-fe 會擴大 (垂直) 以使用更多核心，及擴增 (水平) 以使用更多的 Pod。進行擴大的決策時，會使用路由傳入推斷要求所耗費的時間。如果此時間超過閾值，就會發生擴大。如果路由傳入要求的時間持續超過閾值，則會發生擴增。

進行縮減和縮小時，會使用 CPU 使用量。如果符合 CPU 使用量閾值，則前端會先相應減少。如果 CPU 使用量下降到縮小閾值，就會發生縮小作業。只有在有足夠的叢集資源可用時，才會相應增加和相應放大。

相應增加或相應減少時，會重新啟動 azureml-fe Pod 以套用 cpu/記憶體變更。重新啟動不會影響推斷要求。

了解 AKS 推斷叢集的連線需求

當 Azure 機器學習建立或連結 AKS 叢集時，AKS 叢集會使用下列兩個網路模型的其中一個來部署：

Kubenet 網路：網路資源通常會建立並設定為部署 AKS 叢集。
Azure 容器網路介面（CNI）網路功能：AKS 叢集已連線到現有的虛擬網路資源和組態。

針對 Kubenet 網路功能，會為 Azure Machine Learning 服務建立並正確設定網路。針對 CNI 網路功能，您需要了解連線需求，並確保 AKS 推斷的 DNS 解析和輸出連線。例如，您可能使用防火牆來封鎖網路流量。

下圖顯示 AKS 推斷的連線需求。黑色箭號代表實際的通訊，而藍色箭號代表網域名稱。您可能需要將這些主機的專案新增至防火牆或自定義 DNS 伺服器。

Diagram that shows connectivity requirements for AKS inferencing.

如需一般 AKS 連線需求，請參閱使用 AKS 中的 Azure 防火牆限制網路流量。

如需在防火牆後方存取 Azure Machine Learning 服務，請參閱設定輸入和輸出網路流量。

整體 DNS 解析需求

現有虛擬網路內的 DNS 解析位於您的控制之下。例如，防火牆或自訂 DNS 伺服器。下列主機必須可連線：

主機名稱	使用對象
`<cluster>.hcp.<region>.azmk8s.io`	AKS API 伺服器
`mcr.microsoft.com`	Microsoft Container Registry (MCR)
`<ACR name>.azurecr.io`	您的 Azure Container Registry (ACR)
`<account>.table.core.windows.net`	Azure 儲存體帳戶 (資料表儲存體)
`<account>.blob.core.windows.net`	Azure 儲存體帳戶 (Blob 儲存體)
`api.azureml.ms`	Microsoft Entra 驗證
`ingest-vienna<region>.kusto.windows.net`	用於上傳遙測的 Kusto 端點
`<leaf-domain-label + auto-generated suffix>.<region>.cloudapp.azure.com`	如果您使用 Azure 機器學習自動產生端點功能變數名稱。如果您使用自訂網域名稱，則不需要此項目。

依時間順序連線性需求

在 AKS 建立或連結的程序中，會將 Azure Machine Learning 路由器 (azureml-fe) 部署至 AKS 叢集。為了部署 Azure Machine Learning 路由器，AKS 節點應能夠：

解析 AKS API 伺服器的 DNS
解析 MCR 的 DNS，以便下載適用於 Azure Machine Learning 路由器的 Docker 映像
從 MCR 下載映像，其中需要輸出連線

在部署 azureml-fe 之後，它會嘗試啟動，這需要您：

解析 AKS API 伺服器的 DNS
查詢 AKS API 伺服器以探索其本身的其他執行個體 (這是多 Pod 服務)
連線至其本身的其他執行個體

一旦啟動 azureml-fe，需要下列項目，連線才能正常運作：

連線 Azure 儲存體，以下載動態設定
解析 Microsoft Entra 驗證伺服器的 DNS api.azureml.ms ，並在部署的服務使用 Microsoft Entra 驗證時與其通訊。
查詢 AKS API 伺服器以探索部署的模型
與已部署的模型 Pod 通訊

在模型部署期間，針對成功的模型部署，AKS 節點應該能夠：

解析客戶的 ACR DNS
從客戶的 ACR 下載映像
解析儲存模型所在 Azure Blob 的 DNS
從 Azure Blob 下載模型

部署模型並啟動服務之後，azureml-fe 會自動使用 AKS API 探索模型，並準備好將要求路由傳送至該模型。它必須能夠與模型 Pod 通訊。

注意

如果已部署的模型需要任何連線能力（例如查詢外部資料庫或其他 REST 服務，或下載 BLOB），則應該啟用這些服務的 DNS 解析和輸出通訊。

部署到 AKS

若要將模型部署至 AKS，請建立 描述所需計算資源的部署組態 。例如，核心和記憶體的數目。您也需要推斷設定，其中描述裝載模型和 Web 服務所需的環境。如需建立推斷設定的詳細資訊，請參閱部署模型的方式和位置。

注意

要部署的模型數目限制為每個部署 (每個容器) 1,000 個模型。

適用於：Python SDK azureml v1

from azureml.core.webservice import AksWebservice, Webservice
from azureml.core.model import Model
from azureml.core.compute import AksCompute

aks_target = AksCompute(ws,"myaks")
# If deploying to a cluster configured for dev/test, ensure that it was created with enough
# cores and memory to handle this deployment configuration. Note that memory is also used by
# things such as dependencies and AML components.
deployment_config = AksWebservice.deploy_configuration(cpu_cores = 1, memory_gb = 1)
service = Model.deploy(ws, "myservice", [model], inference_config, deployment_config, aks_target)
service.wait_for_deployment(show_output = True)
print(service.state)
print(service.get_logs())

如需此範例中所使用的類別、方法和參數的詳細資訊，請參閱下列參考文件：

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

若要使用 CLI 進行部署，請使用下列命令。將 myaks 取代為 AKS 計算目標的名稱。將 mymodel:1 取代為已註冊模型的名稱和版本。將 myservice 取代為要提供此服務的名稱：

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

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
    }
}

如需詳細資訊，請參閱 az ml 模型部署參考。

自動調整規模

適用於：Python SDK azureml v1

為 Azure Machine Learning 模型部署處理自動調整的元件是 azureml-fe，也就是智慧型要求路由器。由於所有推斷要求都會經過，因此其具有自動調整已部署模型所需的數據。

重要

請勿針對模型部署啟用 Kubernetes Horizontal Pod 自動調整程式（HPA）。這樣做會導致兩個自動調整元件彼此競爭。 Azureml-fe 的設計可自動調整 Azure ML 部署的模型，其中的 HPA 必須從一般計量 (例如 CPU 使用量或自訂計量設定) 猜測或估計模型使用率。
Azureml-fe 無法調整 AKS 叢集中的節點數目，因為這可能會導致非預期的成本增加。相反地，它會在實體叢集界限內調整模型的複本數目。如果您需要調整叢集內的節點數目，您可以手動調整叢集或設定 AKS 叢集自動調整程式。

您可以藉由設定 autoscale_target_utilization、autoscale_min_replicas 和 autoscale_max_replicas 來控制 AKS Web 服務的自動調整。下列範例示範如何啟用自動調整：

aks_config = AksWebservice.deploy_configuration(autoscale_enabled=True, 
                                                autoscale_target_utilization=30,
                                                autoscale_min_replicas=1,
                                                autoscale_max_replicas=4)

相應增加或減少的決定是以目前容器復本的使用率為基礎。忙碌中 (處理要求) 的複本數目除以目前複本的總數即為目前的使用率。如果此數目超過 autoscale_target_utilization，則會建立更多複本。如果低於此數目，即會減少複本。依預設，目標使用率為 70%。

新增複本的決策是積極且快速 (大約 1 秒)。移除複本的決策是保守 (大約 1 分鐘)。

您可以使用下列程式碼來計算所需的複本：

from math import ceil
# target requests per second
targetRps = 20
# time to process the request (in seconds)
reqTime = 10
# Maximum requests per container
maxReqPerContainer = 1
# target_utilization. 70% in this example
targetUtilization = .7

concurrentRequests = targetRps * reqTime / targetUtilization

# Number of container replicas
replicas = ceil(concurrentRequests / maxReqPerContainer)

如需設定 autoscale_target_utilization、autoscale_max_replicas 和 autoscale_min_replicas 的詳細資訊，請參閱 AksWebservice 模組參考。

Web 服務驗證

部署到 Azure Kubernetes Service 時，預設會啟用金鑰型驗證。您也可以啟用權杖型驗證。權杖型驗證要求用戶端使用 Microsoft Entra 帳戶來要求驗證權杖，其會用來對已部署的服務提出要求。

若要停用驗證，請在建立部署設定時設定 auth_enabled=False 參數。下列範例會使用 SDK 停用驗證：

deployment_config = AksWebservice.deploy_configuration(cpu_cores=1, memory_gb=1, auth_enabled=False)

如需從用戶端應用程式進行驗證的詳細資訊，請參閱取用部署為 Web 服務的 Azure Machine Learning 模型。

使用金鑰驗證

如果啟用金鑰驗證，則可以使用 get_keys 方法來擷取主要和次要驗證金鑰：

primary, secondary = service.get_keys()
print(primary)

重要

如果您需要重新產生金鑰，請使用 service.regen_key。

使用權杖驗證

若要啟用權杖驗證，請在建立或更新部署時設定 token_auth_enabled=True 參數。下列範例會使用 SDK 啟用權杖驗證：

deployment_config = AksWebservice.deploy_configuration(cpu_cores=1, memory_gb=1, token_auth_enabled=True)

如果已啟用權杖驗證，則可以使用 get_token 方法來擷取 JWT 權杖，以及該權杖的到期時間：

token, refresh_by = service.get_token()
print(token)

重要

您必須在令牌的時間之後要求新的令牌 refresh_by 。

Microsoft 強烈建議您在與 AKS 叢集相同的區域中建立 Azure 機器學習工作區。若要使用令牌進行驗證，Web 服務會呼叫 Azure 機器學習工作區建立所在的區域。如果您的工作區區域無法使用，即使您的叢集位於與工作區不同的區域，您也無法擷取 Web 服務的令牌。這實際上會導致令牌型驗證無法使用，直到您的工作區區域再次可用為止。此外，叢集區域與工作區區域之間的距離越大，擷取令牌所需的時間越長。

若要取得權杖，您必須使用 Azure Machine Learning SDK 或 az ml service get-access-token 命令。

弱點掃描

適用於雲端的 Microsoft Defender 提供跨混合式雲端工作負載的整合式安全性管理與進階威脅保護。您應允許適用於雲端的 Microsoft Defender 掃描您的資源，並遵循其建議。如需詳細資訊，請參閱適用於容器的 Microsoft Defender 中的容器安全性。