部署模型

發行項
10/16/2024

一旦滿意模型的效能，就可以部署模型，然後在模型中從表達查詢預測。模型部署後則可透過預測 API 使用。

必要條件

成功建立的專案
標記的表達和成功定型的模型
已檢閱模型效能來判斷模型的表現。

部署模型

檢閱模型的效能並確定其適合用於環境之後，您必須將模型指派給部署，才能查詢。將模型指派給部署時，可透過預測 API 使用該模型。建議建立名稱為 production 的部署，以便指派目前為止建置的最佳模型，並在系統中使用。您可建立名稱為 staging 的另一個部署，可將目前處理中的模型指派給該部署，以便進行測試。您的專案中最多可有 10 個部署。

Language Studio
REST API

若要從 Language Studio 內部署您的模型：

從左側功能表中，選取 [部署模型]。
選取 [新增部署] 以啟動 [新增部署] 精靈。
選取 [建立新的部署] 以建立新的部署，並從下方的下拉式清單中指派定型的模型。否則，您可以選取 [覆寫現有的部署名稱]，以有效地取代現有部署所使用的模型。

注意

覆寫現有的部署不需要變更預測 API 呼叫，但您取得的結果將會以新指派的模型為基礎。
從 [模型] 下拉式清單中選取定型的模型。
選取 [部署] 以啟動部署作業。
部署成功之後，在其旁邊會出現到期日。部署到期表示部署的模型無法再用於預測，通常發生於訓練組態到期的十二個月後。

提交部署作業

使用下列 URL、標頭和 JSON 本文來建立 PUT 要求，以開始部署交談語言理解模型。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}

預留位置	值	範例
`{ENDPOINT}`	用於驗證 API 要求的端點。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	專案名稱。此值區分大小寫。	`myProject`
`{DEPLOYMENT-NAME}`	部署的名稱。此值區分大小寫。	`staging`
`{API-VERSION}`	您正在呼叫的 API 版本。	`2023-04-01`

標頭

使用下列標頭來驗證您的要求。

機碼	值
`Ocp-Apim-Subscription-Key`	資源的金鑰。用於驗證 API 要求。

要求本文

{
  "trainedModelLabel": "{MODEL-NAME}",
}

機碼	預留位置	值	範例
trainedModelLabel	`{MODEL-NAME}`	模型名稱會指派給您的部署。您只能指派成功定型的模型。此值區分大小寫。	`myModel`

傳送 API 要求之後，您會收到表示成功的 202 回應。在回應標頭中，擷取 operation-location 值。其格式如下：

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

您可以使用此 URL 來取得部署作業狀態。

取得部署作業狀態

當您傳送成功的部署要求時，檢查作業狀態的完整要求 URL (包括端點、專案名稱和作業識別碼) 會包含在回應的 operation-location 標頭中。

使用下列 GET 要求來取得部署作業的狀態。以您自己的值取代預留位置值。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

預留位置	值	範例
`{ENDPOINT}`	用於驗證 API 要求的端點。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	專案名稱。此值區分大小寫。	`myProject`
`{DEPLOYMENT-NAME}`	部署的名稱。此值區分大小寫。	`staging`
`{JOB-ID}`	用來尋找模型定型狀態的識別碼。	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	您正在呼叫的 API 版本。	`2023-04-01`

標頭

使用下列標頭來驗證您的要求。

機碼	值
`Ocp-Apim-Subscription-Key`	資源的金鑰。用於驗證 API 要求。

回應本文

傳送要求之後，您會收到下列回應。持續輪詢此端點，直到狀態參數變更為「成功」為止。

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

交換部署

指派給一個部署的模型測試完畢之後，可以再將其指派給另一個部署。交換部署牽涉到：

將指派給第一個部署的模型指派給第二個部署。
將指派給第二個部署的模型指派給第一個部署。

想要將指派給 staging 的模型指派給 production 時，可依此來交換 production 和 staging 部署。

Language Studio
REST API

若要從 Language Studio 內交換部署

在 [部署模型] 頁面中，選取您想要交換的兩個部署，然後選取頂端功能表中的 [交換部署]。
從出現的視窗中，選取要交換的部署名稱。

使用下列 URL、標頭和 JSON 本文來建立 POST 要求，以啟動交換部署工作。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/:swap?api-version={API-VERSION}

預留位置	值	範例
`{ENDPOINT}`	用於驗證 API 要求的端點。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	專案名稱。此值區分大小寫。	`myProject`
`{API-VERSION}`	您正在呼叫的 API 版本。	`2023-04-01`

標頭

使用下列標頭來驗證您的要求。

機碼	值
`Ocp-Apim-Subscription-Key`	資源的金鑰。用於驗證 API 要求。

要求本文

{
  "firstDeploymentName": "{FIRST-DEPLOYMENT-NAME}",
  "secondDeploymentName": "{SECOND-DEPLOYMENT-NAME}"
}

機碼	預留位置	值	範例
firstDeploymentName	`{FIRST-DEPLOYMENT-NAME}`	第一個部署的名稱。此值區分大小寫。	`production`
secondDeploymentName	`{SECOND-DEPLOYMENT-NAME}`	第二個部署的名稱。此值區分大小寫。	`staging`

傳送 API 要求之後，您會收到表示成功的 202 回應。

若要從 Language Studio 中刪除部署，請選取 [部署模型] 頁面。然後選取要刪除的部署，並選取頂端功能表中的 [刪除部署]

使用下列 URL、標頭和 JSON 本文來建立 DELETE 要求，以刪除交談語言理解部署。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

預留位置	值	範例
`{ENDPOINT}`	用於驗證 API 要求的端點。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	專案名稱。此值區分大小寫。	`myProject`
`{DEPLOYMENT-NAME}`	部署的名稱。此值區分大小寫。	`staging`
`{API-VERSION}`	您正在呼叫的 API 版本。	`2023-04-01`

標頭

使用下列標頭來驗證您的要求。

機碼	值
`Ocp-Apim-Subscription-Key`	資源的金鑰。用於驗證 API 要求。

傳送 API 要求後，您將會收到 202 回應指示已成功，這表示您的部署已刪除。

指派部署資源

您可以指派在不同區域的不同語言資源，將專案部署至多個區域。

Language Studio
REST API

若要在 Language Studio 中指派其他區域中的部署資源，方法如下：

請確定您已為自己指派用來建立專案資源的認知服務語言擁有者。
前往 Language Studio 的 [部署模型] 頁面。
選取 [區域] 索引標籤。
選取 [新增部署資源]。
選取另一個區域的語言資源。

您現在已準備好將專案部署至已指派資源的區域。

以程式設計的方式指派部署資源需要 Microsoft Entra 驗證**。您想將資源指派至多區域部署的專案時，可使用 Microsoft Entra ID 確認您具有該資源的存取權。若要在進行 REST API 呼叫時，以程式設計方式使用 Microsoft Entra 驗證，請參閱 Azure AI 服務驗證文件。

指派資源

使用下列 URL、標頭和 JSON 本文來提交 POST 要求，以指派部署資源。

要求 URL

建立 API 要求時，請使用下列 URL。請以您自己的值取代下列預留位置值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/resources/:assign?api-version={API-VERSION}

預留位置	值	範例
`{ENDPOINT}`	用於驗證 API 要求的端點。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	專案名稱。此值區分大小寫。	`myProject`
`{API-VERSION}`	您所呼叫 API 的版本。	`2022-10-01-preview`

標題

使用 Microsoft Entra 驗證驗證此 API。

本文

使用下列範例 JSON 作為本文。

{
  "resourcesMetadata": [
    {
      "azureResourceId": "{AZURE-RESOURCE-ID}",
      "customDomain": "{CUSTOM-DOMAIN}",
      "region": "{REGION-CODE}"
    }
  ]
}

機碼	預留位置	值	範例
`azureResourceId`	`{AZURE-RESOURCE-ID}`	您要指派的完整資源識別碼路徑。請前往 Azure 入口網站，在該資源的 [屬性] 索引標籤底下，於 [資源識別碼] 欄位中取得相關資料。	`/subscriptions/12345678-0000-0000-0000-0000abcd1234/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource`
`customDomain`	`{CUSTOM-DOMAIN}`	您想指派之資源的自訂子網域。請前往 Azure 入口網站，在該資源的 [金鑰和端點] 索引標籤底下，於 URL `https://<your-custom-subdomain>.cognitiveservices.azure.com/` 的 [端點] 欄位中取得相關資料	`contosoresource`
`region`	`{REGION-CODE}`	區域代碼，指定您想指派之資源的區域。請前往 Azure 入口網站，在該資源的 [金鑰和端點] 索引標籤底下，於 [位置/區域] 欄位中取得相關資料。	`eastus`

取得指派資源狀態

使用下列 GET 要求，取得指派部署資源工作的狀態。請以您自己的值取代下列預留位置值。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/resources/assign/jobs/{JOB-ID}?api-version={API-VERSION}

預留位置	值	範例
`{ENDPOINT}`	用於驗證 API 要求的端點。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	專案名稱。此值區分大小寫。	`myProject`
`{JOB-ID}`	取得指派部署狀態所需的工作識別碼。在回應您指派部署資源要求的 API `operation-location` 標頭值中，會顯示此識別碼。	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	您所呼叫 API 的版本。	`2022-10-01-preview`

標頭

使用下列標頭來驗證您的要求。

機碼	值
`Ocp-Apim-Subscription-Key`	資源的金鑰。用於驗證 API 要求。

回應本文

傳送要求之後，您會收到下列回應。持續輪詢此端點，直到狀態參數變更為「成功」為止。

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

取消指派部署資源

從專案取消指派或移除部署資源時，您也會刪除已部署至該資源區域的所有部署。

Language Studio
REST API

若要使用 Language Studio 來取消指派或移除其他區域的部署資源，方法如下：

前往 [部署模型] 頁面中的 [區域] 索引標籤。
選取您要取消指派的資源。
選取 [移除指派] 按鈕。
在顯示的視窗中，鍵入您想移除的資源名稱。

取消指派資源

使用下列 URL、標頭和 JSON 本文來提交 POST 要求，以從您的專案取消指派或移除部署資源。

要求 URL

建立 API 要求時，請使用下列 URL。請以您自己的值取代下列預留位置值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/resources/:unassign?api-version={API-VERSION}

預留位置	值	範例
`{ENDPOINT}`	用於驗證 API 要求的端點。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	專案名稱。此值區分大小寫。	`myProject`
`{API-VERSION}`	您所呼叫 API 的版本。	`2022-10-01-preview`

標頭

使用下列標頭來驗證您的要求。

機碼	值
`Ocp-Apim-Subscription-Key`	資源的金鑰。用於驗證 API 要求。

本文

使用下列範例 JSON 作為本文。

{
  "assignedResourceIds": [
    "{AZURE-RESOURCE-ID}"
  ]
}

機碼	預留位置	值	範例
`assignedResourceIds`	`{AZURE-RESOURCE-ID}`	您要取消指派的完整資源識別碼路徑。請前往 Azure 入口網站，在該資源的 [屬性] 索引標籤底下，取得 [資源識別碼] 欄位中的資料。	`/subscriptions/d73a1925-0000-0000-0000-0000c5fe888e/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource`

取得取消指派資源狀態

使用下列 GET 要求，取得取消指派部署資源工作的狀態。請以您自己的值取代下列預留位置值。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/resources/unassign/jobs/{JOB-ID}?api-version={API-VERSION}

預留位置	值	範例
`{ENDPOINT}`	用於驗證 API 要求的端點。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	專案名稱。此值區分大小寫。	`myProject`
`{JOB-ID}`	取得指派部署狀態所需的工作識別碼。在回應您取消指派部署資源要求的 API `operation-location` 標頭值中，會顯示此識別碼。	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	您所呼叫 API 的版本。	`2022-10-01-preview`

標頭

使用下列標頭來驗證您的要求。

機碼	值
`Ocp-Apim-Subscription-Key`	資源的金鑰。用於驗證 API 要求。

回應本文

傳送要求之後，您會收到下列回應。持續輪詢此端點，直到狀態參數變更為「成功」為止。

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

下一步

使用預測 API 來查詢模型

共用方式為

部署模型

必要條件

部署模型

提交部署作業

要求 URL

標頭

要求本文

取得部署作業狀態

要求 URL

標頭

回應本文

交換部署

要求 URL

標頭

要求本文

刪除部署

要求 URL

標頭

指派部署資源

指派資源

要求 URL

標題

本文

取得指派資源狀態

要求 URL

標頭

回應本文

取消指派部署資源

取消指派資源

要求 URL

標頭

本文

取得取消指派資源狀態

要求 URL

標頭

回應本文

下一步

意見反應

其他資源