管理自訂語言模型

自訂作業介面包含 POST /v1/customizations 方法，用來建立自訂語言模型。此介面也包含 POST /v1/customizations/train 方法，根據其 words 資源中的最新資料來訓練自訂模型。如需相關資訊，請參閱：

此介面也包括列出自訂語言模型資訊、將自訂模型重設為初始狀態、升級自訂模型以及刪除自訂模型的方法。服務正在處理對自訂模型的其他作業（包括將資源新增至模型）時，無法訓練、重設、升級或刪除該模型。

列出自訂語言模型

自訂作業介面提供兩種方法來列出指定認證所擁有之自訂語言模型的相關資訊：

GET /v1/customizations 方法會列出所有自訂語言模型的資訊，如果您指定 language 參數，則會列出指定語言的所有自訂語言模型的資訊。如果指定語言，請使用基本機型名稱中的語言識別碼，例如 en-US 代表美國英文機型。
GET /v1/customizations/{customization_id} 方法，列出指定自訂語言模型的相關資訊。您可以使用此方法來輪詢服務關於訓練要求或是新增字組要求的狀態。

這兩種方法會傳回自訂模型的下列相關資訊：

customization_id 可識別自訂模型的「廣域唯一 ID (GUID)」。 GUID 用來在介面的方法中識別模型。
created 是建立自訂模型的日期和時間，以世界標準時間 (UTC) 表示。
updated 是前次修改自訂模型的日期和時間，以世界標準時間 (UTC) 表示。
language 是自訂模型的語言。該值與基本機型名稱中的語言識別碼相符。例如，en-US 為美國英語語言模型。
dialect 是自訂模型的語言方言，這不一定與前一代西班牙文模型的自訂模型語言相符。如需詳細資訊，請參閱「建立自訂語言模型」中 dialect 欄位的說明。
owner 識別擁有該自訂模型之服務實例的認證。
name 是自訂模型的名稱。
description 顯示自訂模型的說明（如果已在建立時提供的話）。
base_model 指出已為其建立自訂模型的語言模型名稱。
versions 提供自訂模型的可用版本清單。陣列的每一個元素都指出可搭配使用自訂模型的基礎模型版本。只有在自訂模型升級到其基本模型的新版本時，才會存在多個版本。否則，只會顯示單一版本。如需相關資訊，請參閱列出自訂模型的版本資訊。

此方法也會傳回 status 欄位，指出自訂模型的狀態：

pending 指出已建立模型。它正在等待加入有效的訓練資料 (語料庫、字詞或語法)，或是等待服務完成分析已加入的資料。
ready 指出模型包含有效的資料，且已準備好進行訓練。如果模型包含有效和無效資源的組合，則除非您將 strict 查詢參數設定為 false，否則模型訓練會失敗。如需相關資訊，請參閱訓練失敗。
training 表示正在使用資料訓練模型。
available 表示模型已經過訓練，並備妥可與辨識要求搭配使用。
upgrading 指出模型正在升級中。
failed 指出模型的訓練失敗。請檢查模型 words 資源中的字組，以判定有哪些錯誤導致無法訓練模型。

此外，輸出還包括一個 progress 欄位，顯示自訂模型的訓練狀態。如果您使用 POST /v1/customizations/{customization_id}/train 方法成功訓練模型，則此欄位的值為 100。如果模型沒有完全訓練好，available，該欄位的值為 0。

監控自訂模型的訓練或升級時，請輪詢 status 欄位的值，而不是 progress 欄位的值。如果操作因任何原因失敗，status 欄位的值會改變，以反映失敗情況； progress 欄位的值仍為 0。

列出所有自訂語言模型範例

下列範例包含 language 查詢參數，用於列出指定認證擁有的所有美式英文自訂語言模型：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations?language=en-US"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations?language=en-US"

認證擁有兩個這類模型。第一個模型正在等待資料，或是正在由服務處理中。第二個模型已完全訓練過，可以使用。兩款客製化機型都是基於前一代機型；第一款客製化機型有兩種可用版本。

{
  "customizations": [
    {
      "customization_id": "74f4807e-b5ff-4866-824e-6bba1a84fe96",
      "created": "2016-06-01T14:21:26.894Z",
      "updated": "2020-01-18T18:42:25.324Z",
      "language": "en-US",
      "dialect": "en-US",
      "versions": [
        "en-US_BroadbandModel.v2018-07-31",
        "en-US_BroadbandModel.v2020-01-16"
      ],
      "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
      "name": "Example model",
      "description": "Example custom language model",
      "base_model_name": "en-US_BroadbandModel",
      "status": "pending",
      "progress": 0
    },
    {
      "customization_id": "8391f918-3b76-e109-763c-b7732fae4829",
      "created": "2017-12-02T18:51:37.291Z",
      "updated": "2017-12-02T20:02:10.624Z",
      "language": "en-US",
      "dialect": "en-US",
      "versions": [
        "en-US_BroadbandModel.v2017-11-15"
      ],
      "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
      "name": "Example model two",
      "description": "Example custom language model two",
      "base_model_name": "en-US_BroadbandModel",
      "status": "available",
      "progress": 100
    }
  ]
}

列出特定的自訂語言模型範例

下列範例會傳回具有指定自訂作業 ID 之自訂模型的相關資訊：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"

回應會重複上一個範例中的資訊：

{
  "customization_id": "74f4807e-b5ff-4866-824e-6bba1a84fe96",
  "created": "2016-06-01T14:21:26.894Z",
  "updated": "2020-01-18T18:42:25.324Z",
  "language": "en-US",
  "dialect": "en-US",
  "versions": [
    "en-US_BroadbandModel.v2018-07-31",
    "en-US_BroadbandModel.v2020-01-16"
  ],
  "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
  "name": "Example model",
  "description": "Example custom language model",
  "base_model_name": "en-US_BroadbandModel",
  "status": "pending",
  "progress": 0
}

重設自訂語言模型

使用 POST /v1/customizations/{customization_id}/reset 方法來重設自訂模型。重設模型會移除模型中的所有語料庫和字組，並將模型起始設定為其建立時的狀態。此方法不會刪除模型本身或 meta 資料，例如其名稱和語言。不過，當您重設模型時，其 words 資源是空的，必須藉由新增語料庫和字組來予以重建。

重設自訂語言模型範例

下列範例會重設具有指定自訂作業 ID 的自訂模型：

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}/reset"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}/reset"

刪除自訂語言模型

使用 DELETE /v1/customizations/{customization_id} 方法來刪除不再需要的自訂語言模型。此方法會刪除與自訂模型和模型本身相關聯的所有語料庫和字組。使用此方法時請小心：刪除模型之後，即無法收回自訂模型及其資料。

刪除自訂語言模型範例

下列範例會刪除具有指定自訂作業 ID 的自訂模型：

IBM Cloud

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"