建立及管理自訂模型

使用任何自訂模型的第一步是建立它。 一旦它存在,您就可以藉由查詢或更新其 meta 資料和項目來管理模型,如果不再需要,也可以將它刪除。 開始之前,請檢閱有關自訂模型的下列一般用法資訊。

自訂作業的使用注意事項

使用自訂作業介面時,請考量下列準則。

自訂模型的所有權

自訂模型是由將其認證用來建立此模型的 Text to Speech 服務實例所擁有。 要以任何方式使用自訂模型,您必須使用該服務實例的認證以及自訂作業介面的各種方法。

針對相同 Text to Speech 服務實例取得的所有認證將共用對為該服務實例建立的所有自訂模型的存取權。 若要限制對自訂模型的存取,請建立個別服務實例,並且只使用該服務實例的認證來建立及使用模型。 其他服務實例的認證無法影響自訂模型。

在認證之間共用所有權的優點是,您可以取消一組認證(例如,如果認證遭洩露的話)。 然後,您可以為相同的服務實例建立新的認證,並仍保留對使用原始認證建立之自訂模型的所有權和存取權。

資訊安全

服務容許您建立客戶 ID 與針對自訂模型新增或更新之資料的關聯。 您可以使用下列方法傳遞 X-Watson-Metadata 標頭,以建立客戶 ID 與自訂字組的關聯。 必要的話,您可以使用 DELETE /v1/user_data 方法來刪除與客戶 ID 相關聯的資料。

  • POST /v1/customizations/{customization_id}
  • POST /v1/customizations/{customization_id}/words
  • PUT /v1/customizations/{customization_id}/words/{word}

此外,如果您從 Text to Speech 主控台刪除 IBM Cloud 服務實例,則會自動刪除與該服務實例相關聯的所有資料。 這包括所有自訂模型和單字/翻譯對。 此資料會自動清除,而不論客戶 ID 是否與資料相關聯。

如需相關資訊,請參閱資訊安全。

要求記載和資料隱私權

IBM Cloud

服務如何處理自訂作業介面呼叫的要求記載,取決於要求:

  • 該服務不會記錄用於建立自訂模型的資料(單詞和翻譯)。 使用自訂作業介面來管理自訂模型中的字組和轉換時,您不需要設定 X-Watson-Learning-Opt-Out 要求標頭。 您的訓練資料絕不會用來改善服務的基礎模型。
  • 服務會 在搭配使用自訂模型與合成要求時記載資料。 您可以在帳戶層級選擇退出請求記錄,或者將 X-Watson-Learning-Opt-Out 請求標頭設為 true。

如需相關資訊,請參閱要求記載。

建立自訂模型

若要建立新的自訂模型,請使用 POST /v1/customizations 方法。 新模型在剛建立時一律是空的。 您必須使用其他方法,將字組/轉換配對移入其中。 如果新的自訂模型是使用某個服務實例的認證建立的,則該模型由該服務實例所擁有。 如需相關資訊,請參閱自訂模型的所有權。

您可以使用 POST /v1/customizations 要求的內文,將下列屬性當作 JSON 物件來傳遞:

name (必填字串)
新自訂模型的使用者定義名稱。 使用與自訂模型語言相符的本地化名稱,並描述模型的領域,例如 Medical custom model 或 Legal custom model。
  • 名稱中最多包含 256 個字元。
  • 請勿在名稱中使用反斜線、斜線、冒號、等號、括號或問號。
  • 使用您擁有的所有自訂模型中唯一的名稱。
language (可選字串)
自訂模型的語言 ID。 預設值為 en-US,表示美式英文。 自訂模型可搭配以指定語言提供的任何語音使用。 例如,為 en-US 語言建立的自訂模型可以與任何美式英文的語音一起使用。 不過,它不能與 en-GB 語音一起使用。
description (可選字串)
新訂製模型的建議說明。
  • 請使用符合自訂模型語言的本地化說明。
  • 描述中最多包含 128 個字元。

以下範例建立一個新的 US English 自訂模型,命名為 Test。 所需的 Content-Type 標頭將輸入類型識別為:application/json。

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test\", \"language\":\"en-US\", \"description\":\"Customization test\"}" \
"{url}/v1/customizations"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test\", \"language\":\"en-US\", \"description\":\"Customization test\"}" \
"{url}/v1/customizations"

此方法會傳回 JSON 物件,其中包含新模型的廣域唯一 ID (GUID)。 GUID 用來作為各呼叫中的 customization_id 參數以存取模型,例如用於查詢、修改及使用模型及其字組的呼叫。

{
  "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97"
}

查詢自訂模型

若要查詢現有自訂模型的相關資訊,請使用 GET /v1/customizations/{customization_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}"

此方法會將其結果傳回為下列格式的 JSON 物件:

{
  "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97",
  "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
  "created": "2016-07-15T18:12:31.743Z",
  "name": "Test",
  "language": "en-US",
  "description": "Customization test",
  "last_modified": "2016-07-15T18:12:31.743Z",
  "words": [],
  "prompts": []
}

輸出中除了包含在建立模型時輸入的資訊外,還包含模型擁有者的認證、模型的語言,以及建立模型和前次修改模型的時間。 因為模型自建立之後尚未經過修改,所以範例中的兩個時間相同。

輸出還包括列出模型自訂字詞的 words 陣列,以及列出模型自訂提示的 prompts 陣列。 由於模型尚未更新,範例中的陣列是空的。

查詢所有自訂模型

若要查看您擁有之所有自訂模型的相關資訊,請使用 GET /v1/customizations 方法:

IBM Cloud

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

IBM Cloud Pak for Data IBM Software Hub

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

此方法會傳回一個 JSON 陣列,其中包括要求者所擁有之每個自訂模型的物件。 擁有者的認證會顯示在 owner 欄位中。

{
  "customizations": [
    {
      "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97",
      "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-07-15T19:15:17.926Z",
      "name": "Test",
      "language": "en-US",
      "description": "Customization test",
      "last_modified": "2016-07-15T19:15:17.926Z"
    },
    {
      "customization_id": "63f5807f-a4f2-5766-914e-7abb1a84fe97",
      "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-07-15T18:12:31.743Z",
      "name": "Test Two",
      "language": "en-US",
      "description": "Second customization test",
      "last_modified": "2016-07-15T18:23:50.912Z"
    }
  ]
}

第一個模型的 created 及 last_modified 時間相同,因為它尚未經過更新。 第二個模型的時間不同,指出它自起始建立之後已變更過。 此資訊不包括針對模型定義的自訂項目。

更新自訂模型

若要更新自訂模型的相關資訊,請使用 POST /v1/customizations/{customization_id} 方法。 您可以將更新項目指定為 JSON 物件。 除了修改其名稱及說明之外,您也可以使用此方法來新增或更新模型中的字組/轉換配對。 建立模型的語言之後,即無法進行變更。

下列範例更新自訂模型的名稱和說明。 空的 JSON 陣列會與 words 參數一起傳送,指出模型的項目將維持不變。

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test Update\", \"description\":\"Customization test update\", \"words\":[]}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test Update\", \"description\":\"Customization test update\", \"words\":[]}" \
"{url}/v1/customizations/{customization_id}"

如需更新模型中字組的相關資訊,請參閱將多個字組新增至自訂模型。

刪除自訂模型

若要捨棄您不再需要的自訂模型,請使用 DELETE /v1/customizations/{customization_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}"