カスタマイズの使用上の注意

カスタマイズ・インターフェースを使用する際には、以下のガイドラインを考慮してください。

カスタム・モデルの作成

新規カスタム・モデルを作成するには、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文字まで入力できます。

次の例では、 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 (Globally Unique Identifier) が含まれた 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": []
}

出力には、モデルの作成時に入力された情報に加え、モデルの所有者の資格情報、モデルの言語、およびモデルの作成時刻と最終変更時刻が含まれます。 この例の 2 つの時刻は、モデルが作成時以降に変更されていないため、同じになっています。

出力には、モデルのカスタム単語をリストする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 時刻が同じになっています。 2 番目のモデルの時刻は異なっており、初期作成時以降に変更されていることを示しています。 この情報には、各モデルに定義されているカスタム項目は含まれません。

カスタム・モデルの更新

カスタム・モデルに関する情報を更新するには、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}"