创建和管理定制模型

使用任何定制模型的第一步都是创建模型。模型存在后，可以通过查询或更新其元数据和条目，并在不再需要时将其删除，从而管理模型。开始之前，请查看有关定制模型的以下常规用法信息。

定制车型还可以包含您为“实例调整”功能定义的自定义提示。有关按示例调整、自定义提示和说话者模型的更多信息，请参阅了解按示例调整。

定制用法说明

使用定制接口时，请考虑以下准则。

定制模型的所有权

拥有定制模型的 Text to Speech 服务实例是其凭证用于创建该模型的实例。要以任何方式使用定制模型，您必须使用该服务实例的凭证以及定制接口的各种方法。

针对同一 Text to Speech 服务实例获取的所有凭证将共享对为该服务实例创建的所有定制模型的访问权。要限制对定制模型的访问权，请创建单独的服务实例，并仅使用该服务实例的凭证来创建和使用该模型。其他服务实例的凭证无法影响该定制模型。

在凭证之间共享所有权的优点是可以取消一组凭证（例如，如果凭证泄露）。然后，可以为同一服务实例创建新凭证，并仍保留对使用原始凭证创建的定制模型的所有权和访问权。

信息安全

该服务允许您将客户标识与针对定制模型添加或更新的数据相关联。通过使用以下方法来传递 X-Watson-Metadata 头，可以将客户标识与定制词相关联。然后，可以在需要时使用 DELETE /v1/user_data 方法来删除与客户标识关联的数据。

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

此外，如果通过 Text to Speech 控制台删除了 IBM Cloud 服务的实例，那么将自动删除与该服务实例关联的所有数据。这包括所有定制模型和单词/翻译对。这些数据会被自动清除，无论客户标识是否与数据相关联。

有关更多信息，请参阅信息安全。

请求日志记录和数据隐私

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 （可选字符串）

定制模型语言的标识。对于美国英语，缺省值为 en-US。定制模型可与指定语言中可用的任何声音一起使用。例如，为 en-US 语言创建的定制模型可与任何美国英语声音一起使用。但是，不能用于 en-GB 声音。

description （可选字符串）

推荐的新定制车型描述。

请使用与定制模型的语言相匹配的本地化描述。
描述中最多包含128个字符。

以下示例创建了一个名为 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"

此方法将返回包含新模型的全局唯一标识 (GUID) 的 JSON 对象。在用于访问模型的调用（例如，用于查询、修改和使用模型及其词的调用）中，该 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 对象。此方法除了用于修改模型名称和描述外，还可用于在模型中添加或更新词/转换项对。创建模型后，就无法再更改模型的语言。

以下示例将更新定制模型的名称和描述。使用 words 参数发送空的 JSON 数组，以指示模型的条目将保持不变。

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