カスタム言語モデルの管理

カスタマイズ・インターフェースには、カスタム言語モデルを作成するための POST /v1/customizations メソッドが含まれます。このインターフェースには、単語リソースの最新データに関してカスタム・モデルをトレーニングするための POST /v1/customizations/train メソッドも含まれます。詳しくは、以下を参照してください

このインターフェースには、カスタム言語モデルに関する情報をリストするメソッド、カスタム・モデルを初期状態にリセットするメソッド、カスタム・モデルをアップグレードするメソッド、およびカスタム・モデルを削除するメソッドも含まれています。サービスがカスタム・モデルに対する別の操作 (モデルへのリソースの追加など) を処理している間は、そのカスタム・モデルのトレーニング、リセット、アップグレード、および削除は実行できません。

カスタム言語モデルのリスト

カスタマイズ・インターフェースには、指定の資格情報により所有されるカスタム言語モデルに関する情報をリストするメソッドが 2 つあります。

GET /v1/customizations メソッドは、すべてのカスタム言語モデルに関する情報、またはlanguage パラメーターを指定した場合は、指定された言語のすべてのカスタム言語モデルに関する情報をリストします。言語を指定する場合は、基本モデルの名前からの言語 ID を使用します。例えば、米国英語モデルの場合は en-US です。
GET /v1/customizations/{customization_id} メソッドは、指定のカスタム言語モデルに関する情報をリストします。このメソッドを使用してサービスをポーリングし、トレーニング要求のステータスまたは新規単語の追加要求のステータスを調べます。

どちらのメソッドも、カスタム・モデルに関する以下の情報を返します。

customization_id は、カスタム・モデルの GUID (Globally Unique Identifier) を識別します。 GUID は、インターフェースのメソッドでモデルを識別するために使用されます。
created は、カスタム・モデルが作成された日時 (協定世界時、UTC) です。
updated は、カスタム・モデルが変更された日時 (協定世界時、UTC) です。
language は、カスタム・モデルの言語です。この値は、基本モデルの名前からの言語 ID と一致します。例えば、米国英語言語モデルの場合は en-US です。
dialect は、カスタム・モデルの言語の方言です。これは、前世代のスペイン語モデルのカスタム・モデルの言語と必ずしも一致するわけではありません。詳しくは、カスタム言語モデルの作成の dialect フィールドの説明を参照してください。
owner は、カスタム・モデルを所有するサービス・インスタンスの資格情報を識別します。
name は、カスタム・モデルの名前です。
description は、カスタム・モデルの説明を示します (モデルの作成時に指定されている場合)。
base_model は、カスタム言語モデルを作成する際に使用された言語モデルの名前を意味します。
versions は、カスタム・モデルの使用可能なバージョンのリストを示します。配列の各要素は、カスタム・モデルで使用できる基本モデルのバージョンを意味します。複数のバージョンが存在するのは、カスタム・モデルがその基本モデルの新規バージョンにアップグレードされた場合のみです。それ以外の場合は、1 つのバージョンのみが表示されます。詳しくは、カスタム・モデルのバージョン情報の表示を参照してください。

メソッドは、カスタム・モデルの状態を示す status フィールドも返します。

pending は、モデルが作成されたことを意味します。有効なトレーニング・データ (コーパス、単語、または文法) が追加されるか、サービスが追加されたデータの分析を終了するのを待機しています。
ready は、モデルに有効なデータが取り込まれ、モデルのトレーニングを開始できる状態になっていることを意味します。モデルに有効なリソースと無効なリソースが混在しており、strict 照会パラメーターが false に設定されていない場合は、モデルのトレーニングは失敗します。詳しくは、トレーニングの失敗を参照してください。
training は、モデルがデータに関して、トレーニング中であることを意味します。
available は、モデルのトレーニングが完了し、モデルが認識要求で使用可能な状態になっていることを意味します。
upgrading は、モデルがアップグレード中であることを意味します。
failed は、モデルのトレーニングが失敗したことを意味します。モデルの単語リソースに含まれる単語を調べて、モデルのトレーニングの妨げとなった誤りを判別してください。

さらに、出力には、カスタム・モデルのトレーニングの状況を示すprogressフィールドが含まれます。 POST /v1/customizations/{customization_id}/trainメソッドを使用してモデルを正常にトレーニングした場合、このフィールドの値は100になります。モデルが完全にトレーニングされておらず、availableである場合、このフィールドの値は0になります。

カスタムモデルのトレーニングまたはアップグレードを監視する際には、 progress フィールドの値ではなく、 status フィールドの値をポーリングします。何らかの理由で操作に失敗した場合、 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"

資格情報により、以下の 2 つのモデルが所有されています。 1 番目のモデルは、データを待機中であるか、サービスによって処理中です。 2 番目のモデルは、トレーニングが完了しており使用できる状態です。どちらのカスタム・モデルも、前世代モデルに基づいています。最初のカスタム・モデルには、2 つの使用可能なバージョンがあります。

{
  "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 メソッドを使用します。モデルをリセットすると、モデルからすべてのコーパスと単語が削除され、モデルが作成時の状態に初期化されます。このメソッドによって、モデル自体またはモデルの名前や言語などのメタデータが削除されることはありません。ただし、モデルをリセットすると、モデルの単語リソースが空になるため、コーパスや単語を追加して再作成する必要があります。

カスタム言語モデルのリセットの例

以下に、指定のカスタマイズ 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}"