この記事を使って、テキスト分類のカスタム モデルをトレーニングできるカスタム テキスト分類プロジェクトの作成を開始します。 モデルは、特定のタスクを実行するようにトレーニングされた AI ソフトウェアです。 このシステムでは、モデルによってテキストが分類され、タグ付けされたデータから学習することでモデルがトレーニングされます。
カスタム テキスト分類では、次の 2 種類のプロジェクトがサポートされています。
- 単一ラベル分類 - データセットの各ドキュメントに単一のクラスを割り当てることができます。 たとえば、映画のスクリプトは、"ロマンス" または "コメディ" としてのみ分類できます。
- 複数ラベル分類 - データセットの各ドキュメントに複数のクラスを割り当てることができます。 たとえば、映画のスクリプトは、"コメディ" または "ロマンス" と "コメディ" に分類できます。
このクイック スタートでは、提供されているサンプル データセットを使用して複数のラベル分類を作成し、ムービー スクリプトを 1 つ以上のカテゴリに分類できます。 または、単一のラベル分類データセットを使用して、科学論文の要約を定義されたドメインのいずれかに分類することもできます。
前提条件
- Azure サブスクリプション - 無料アカウントを作成します。
Foundry Tools リソースと Azure ストレージ アカウントで新しい Azure 言語を作成する
カスタム テキスト分類を使用するには、プロジェクトを作成してモデルのトレーニングを開始するために必要な資格情報を提供する言語リソースを作成する必要があります。 また、モデルの構築に使用されるデータセットをアップロードできる Azure ストレージ アカウントも必要です。
重要
すぐに開始するには、この記事で説明する手順を使用して、新しい言語リソースを作成することをお勧めします。 この記事の手順を使用すると、Azure 言語リソースとストレージ アカウントを同時に作成できます。これは後で行うよりも簡単です。
使用する既存の リソース がある場合は、ストレージ アカウントに接続する必要があります。
ストレージ アカウントを利用するすべてのリソースを操作するには、ストレージ BLOB データ共同作成者ロールの追加が不可欠です。
Azure portal から新しいリソースを作成する
Azure portal に移動して、Foundry Tools リソースで新しい Azure 言語を作成します。
ウィンドウが表示されるので、カスタム機能から [カスタム テキスト分類とカスタム固有表現認識] を選びます。 画面の下部にある [リソースの作成を続行する] を選択します。
次の詳細を使用して言語リソースを作成します。
名前 必須値 サブスクリプション Azure サブスクリプション。 リソースグループ リソースを含むリソース グループ。 既存のものを使用するか、新しく作成することができます。 リージョン サポートされているリージョンのいずれか。 たとえば、"米国西部 2" です。 名前 リソースの名前。 価格階層 サポートされている価格レベルのいずれか。 Free (F0) レベルを利用してサービスを試用できます。 "ログイン アカウントが選択したストレージ アカウントのリソース グループの所有者ではない" ことを通知するメッセージが表示された場合は、言語リソースを作成する前に、アカウントでそのリソース グループに所有者ロールを割り当てる必要があります。 Azure サブスクリプションの所有者に問い合わせてください。
Azure サブスクリプションの所有者を確認するには、リソース グループを検索し、リンクに従ってそれに関連付けられているサブスクリプションに移動します。 その後、以下を実行します。
- [アクセス制御 (IAM)] タブを選びます
- [ロールの割り当て] を選びます
- Role:Owner でフィルター処理します。
[カスタム テキスト分類とカスタム固有表現認識] セクションで、既存のストレージ アカウントを選択するか、[新しいストレージ アカウント] を選択します。 これらの値は使用を開始するためのものであり、運用環境で使用したいストレージ アカウントの値である必要はないことに注意してください。 プロジェクト ビルド中の待機時間をなくすには、言語リソースと同じリージョンのストレージ アカウントに接続します。
ストレージ アカウントの値 推奨値 ストレージ アカウント名 任意の名前 ストレージ アカウントの種類 標準 LRS [責任ある AI の通知] がオンになっていることを確認します。 ページ下部にある [確認と作成] を選択します。
サンプル データを BLOB コンテナーにアップロードする
Azure ストレージ アカウントを作成して言語リソースに接続したら、サンプル データセットからコンテナーのルート ディレクトリにドキュメントをアップロードする必要があります。 これらのドキュメントは、モデルのトレーニングに使用されます。
.zip ファイルを開き、ドキュメントが格納されているフォルダーを展開します。
用意されているサンプル データセットには約 200 個のドキュメントが含まれており、それぞれが映画の要約です。 各ドキュメントは、次のクラスの 1 つまたは複数に属します。
- "ミステリー"
- "ドラマ"
- "スリラー"
- "コメディ"
- "アクション"
Azure portal で、作成したストレージ アカウントに移動し、ストレージ アカウントを選択し、任意のフィールドの [フィルター] にストレージ アカウント名を入力して選択します。
リソース グループが表示されない場合は、[ サブスクリプションと等しい ] フィルターが [すべて] に設定されていることを確認します。
ストレージ アカウントで、左側のメニューの [データ ストレージ] の下にある [コンテナー] を選択します。 表示された画面で、[+ コンテナー] を選択します。 コンテナーに example-data という名前を付け、既定のパブリック アクセス レベルをそのまま使用します。
コンテナーが作成されたら、それを選択します。 次に、[アップロード] ボタンを選択して、先ほどダウンロードした
.txtおよび.jsonファイルを選択します。
カスタム テキスト分類プロジェクトを作成する
リソースとストレージ コンテナーが構成されたら、新しいカスタム テキスト分類プロジェクトを作成します。 プロジェクトとは、データに基づいてカスタム ML モデルを構築するための作業領域です。 プロジェクトには、使用されている Azure 言語リソースにアクセスできるユーザーと他のユーザーのみがアクセスできます。
Language Studio にサインインします。 サブスクリプションと言語リソースを選択できるウィンドウが表示されます。 言語リソースを選びます。
Language Studio の [テキストの分類] セクションで、[カスタム テキストの分類] を選択します。
プロジェクト ページの上部メニューから、[Create new project]\(新しいプロジェクトの作成\) を選択します。 プロジェクトを作成すると、データのラベル付け、モデルのトレーニング、評価、改善、デプロイを行うことができます。
[ 新しいプロジェクトの作成] を選択すると、ストレージ アカウントを接続するためのウィンドウが表示されます。 ストレージ アカウントを既に接続している場合は、プロジェクトに接続されているのを確認できます。 表示されない場合は、表示されるドロップダウンからストレージ アカウントを選択し、[ ストレージ アカウントの接続] を選択します。この選択により、ストレージ アカウントに必要なロールが設定されます。 この手順では、ストレージ アカウントの 所有者 として割り当てられていない場合、エラーが返される可能性があります。
Note
- この手順は、新しい言語リソースを使用するたびに 1 回だけ行う必要があります。
- このプロセスは元に戻すことはできません。ストレージ アカウントを言語リソースに接続した場合、後で切断することはできません。
- 言語リソースは 1 つのストレージ アカウントにのみ接続できます。
プロジェクト タイプを選択します。 各ドキュメントが 1 つまたは複数のクラスに属することができる複数ラベル分類プロジェクト、または各ドキュメントが 1 つのクラスにのみ属することができる単一ラベル分類プロジェクトのいずれかを作成できます。 選択したタイプを後で変更することはできません。 プロジェクトの種類の詳細
名前、説明、プロジェクト内のドキュメントの言語など、プロジェクトの情報を入力します。 サンプル データセットを使用する場合は、[英語] を選択します。 後でプロジェクトの名前を変更することはできません。 [次へ]を選択します。
ヒント
データセットは、すべて同じ言語である必要はありません。 サポート言語がそれぞれ異なるドキュメントを複数用意することができます。 データセットに異なる言語のドキュメントが含まれている場合、または実行時に異なる言語のテキストを想定している場合は、プロジェクトの基本情報を入力するときに [多言語データセットを有効にする] オプションを選択します。 このオプションは、後で [プロジェクトの設定] ページから有効にすることができます。
データセットをアップロードしたコンテナーを選択します。
Note
既にデータにラベルを付けた場合は、 サポートされている形式 に従っていることを確認し、[はい] を選択します。 ドキュメントには既にラベルが付いています。また、JSON ラベル ファイルを書式設定 し、ドロップダウン メニューからラベル ファイルを選択します。
データセットの例のいずれかを使用している場合は、含まれている
webOfScience_labelsFileまたは json ファイルmovieLabels使用します。 [次へ]を選択します。入力したデータを確認し、[Create Project]\(プロジェクトの作成\) を選びます。
モデルをトレーニングする
通常、プロジェクトを作成した後、先に進み、プロジェクトに接続されているコンテナーにあるドキュメントのラベル付けを開始します。 このクイック スタートでは、ラベル付けされたサンプル データセットをインポートし、サンプル JSON ラベル ファイルを使用してプロジェクトを初期化しました。
Language Studio 内からモデルのトレーニングを開始するには:
左側のメニューから [トレーニング ジョブ] を選びます。
上部のメニューから [トレーニング ジョブの開始] を選択します。
[新しいモデルのトレーニング] を選択し、テキスト ボックスにモデル名を入力します。 また、[既存のモデルを上書きする] オプションを選択し、ドロップダウン メニューから上書きするモデルを選択することにより、既存のモデルを上書きすることもできます。 トレーニング済みモデルを上書きすると、元に戻すことはできません。ただし、新しいモデルをデプロイするまで、デプロイされているモデルには影響しません。
データの分割方法を選択します。 [トレーニング用データからテスト用セットを自動分割] を選択できます。その場合、システムにより、指定した割合に従って、ラベル付けされたデータがトレーニング用セットとテスト用セットに分割されます。 または、 トレーニング データとテスト データを手動で分割して使用することもできます。このオプションは、 データのラベル付け中にテスト セットにドキュメントを追加した場合にのみ有効になります。 データ分割の詳細については、モデルのトレーニング方法に関するセクションを参照してください。
[トレーニング] ボタンを選択します。
一覧からトレーニング ジョブ ID を選択すると、サイド ペインが表示され、そのジョブの [トレーニングの進行状況]、[ジョブの状態]、その他の詳細を確認できます。
Note
- 正常に完了したトレーニング ジョブでのみ、モデルが生成されます。
- モデルのトレーニングには、ラベル付けされたデータのサイズに基づいて、数分から数時間かかる場合があります。
- 一度に実行できるトレーニング ジョブは 1 つだけです。 実行中のジョブが完了するまで、同じプロジェクト内で他のトレーニング ジョブを開始することはできません。
モデルをデプロイする
通常はモデルをトレーニングした後、その評価の詳細を確認し、必要に応じて改善を行います。 このクイック スタートでは、モデルをデプロイし、Language Studio で試用できるようにするか、 予測 API を呼び出すことができます。
Language Studio 内からモデルをデプロイするには、次の手順を行います。
左側のメニューから [モデルのデプロイ] を選択します。
[デプロイの追加] を選択して、新しいデプロイ ジョブを開始します。
[新しいデプロイの作成] を選択して新しいデプロイを作成し、下のドロップダウンからトレーニング済みモデルを割り当てます。 また、[既存のデプロイを上書きする] オプションを選択し、ドロップダウン メニューからトレーニング済みモデルを選択することにより、既存のデプロイを上書きすることもできます。
Note
既存のデプロイを上書きする場合、予測 API 呼び出しを変更する必要はなく、新しく割り当てたモデルに基づいて結果が得られるようになります。
[デプロイ] を選択して、デプロイ ジョブを開始します。
デプロイが成功すると、その横に有効期限が表示されます。 デプロイの有効期限とは、デプロイされたモデルを予測に使用できなくなるときであり、通常は、トレーニング構成の有効期限が切れる 12 か月後に発生します。
モデルのテスト
モデルがデプロイされたら、モデルの使用を開始して 予測 API を使ってテキストを分類できます。 このクイック スタートでは、 Language Studio を使用してカスタム テキスト分類タスクを送信し、結果を視覚化します。 サンプル データセットでは、前にダウンロードしたテスト ドキュメントの中から、この手順で使用できるテスト ドキュメントを見つけることができます。
デプロイされたモデルを Language Studio 内でテストするには、次のようにします。
画面左側のメニューから [Testing deployments](デプロイのテスト) を選択します。
テストするデプロイを選択します。 テストできるのは、デプロイに割り当てられているモデルのみです。
多言語プロジェクトの場合は、言語ドロップダウンを使用してテストするテキストの言語を選択します。
ドロップダウンからクエリを実行またはテストするデプロイを選択します。
要求で送信するテキストを入力するか、使用する
.txtドキュメントをアップロードします。 データセットの例のいずれかを使っている場合は、含まれている .txt ファイルのいずれかを使用できます。上部のメニューから [テストを実行する] を選択します。
[Result]\(結果\) タブで、テキストに対して予測されたクラスを確認できます。 [JSON] タブで JSON 応答を表示することもできます。次の例は、単一ラベル分類プロジェクトの場合です。 複数ラベル分類プロジェクトでは、結果に複数のクラスが返される可能性があります。
プロジェクトをクリーンアップする
プロジェクトが不要な場合は、Language Studio を使ってプロジェクトを削除できます。 上部の [カスタム テキスト分類] を選択し、削除するプロジェクトを選択します。 上部のメニューから [削除] を選択して、プロジェクトを削除します。
前提条件
- Azure サブスクリプション - 無料アカウントを作成します。
Foundry Tools リソースと Azure ストレージ アカウントで新しい Azure 言語を作成する
カスタム テキスト分類を使用する前に、言語リソースを作成する必要があります。このリソースでは、プロジェクトを作成してモデルのトレーニングを開始するために必要な資格情報が提供されます。 また、モデルの構築に使用するデータセットをアップロードできる Azure ストレージ アカウントも必要です。
重要
すぐに開始するには、この記事で説明する手順を使用して新しい言語リソースを作成することをお勧めします。これにより、Azure 言語リソースを作成し、ストレージ アカウントの作成と接続を同時に行うことができます。これは後で行うよりも簡単です。
使用する既存のリソースがある場合は、ストレージ アカウントに接続する必要があります。
Azure portal から新しいリソースを作成する
Azure portal に移動して、Foundry Tools リソースで新しい Azure 言語を作成します。
ウィンドウが表示されるので、カスタム機能から [カスタム テキスト分類とカスタム固有表現認識] を選びます。 画面の下部にある [リソースの作成を続行する] を選択します。
次の詳細を使用して言語リソースを作成します。
名前 必須値 サブスクリプション Azure サブスクリプション。 リソースグループ リソースを含むリソース グループ。 既存のものを使用するか、新しく作成することができます。 リージョン サポートされているリージョンのいずれか。 たとえば、"米国西部 2" です。 名前 リソースの名前。 価格階層 サポートされている価格レベルのいずれか。 Free (F0) レベルを利用してサービスを試用できます。 "ログイン アカウントが選択したストレージ アカウントのリソース グループの所有者ではない" ことを通知するメッセージが表示された場合は、言語リソースを作成する前に、アカウントでそのリソース グループに所有者ロールを割り当てる必要があります。 Azure サブスクリプションの所有者に問い合わせてください。
Azure サブスクリプションの所有者を確認するには、リソース グループを検索し、リンクに従ってそれに関連付けられているサブスクリプションに移動します。 その後、以下を実行します。
- [アクセス制御 (IAM)] タブを選びます
- [ロールの割り当て] を選びます
- Role:Owner でフィルター処理します。
[カスタム テキスト分類とカスタム固有表現認識] セクションで、既存のストレージ アカウントを選択するか、[新しいストレージ アカウント] を選択します。 これらの値は使用を開始するためのものであり、運用環境で使用したいストレージ アカウントの値である必要はないことに注意してください。 プロジェクト ビルド中の待機時間をなくすには、言語リソースと同じリージョンのストレージ アカウントに接続します。
ストレージ アカウントの値 推奨値 ストレージ アカウント名 任意の名前 ストレージ アカウントの種類 標準 LRS [責任ある AI の通知] がオンになっていることを確認します。 ページ下部にある [確認と作成] を選択します。
サンプル データを BLOB コンテナーにアップロードする
Azure ストレージ アカウントを作成して言語リソースに接続したら、サンプル データセットからコンテナーのルート ディレクトリにドキュメントをアップロードする必要があります。 これらのドキュメントは、モデルのトレーニングに使用されます。
.zip ファイルを開き、ドキュメントが格納されているフォルダーを展開します。
用意されているサンプル データセットには約 200 個のドキュメントが含まれており、それぞれが映画の要約です。 各ドキュメントは、次のクラスの 1 つまたは複数に属します。
- "ミステリー"
- "ドラマ"
- "スリラー"
- "コメディ"
- "アクション"
Azure portal で、作成したストレージ アカウントに移動し、ストレージ アカウントを選択し、任意のフィールドの [フィルター] にストレージ アカウント名を入力して選択します。
リソース グループが表示されない場合は、[ サブスクリプションと等しい ] フィルターが [すべて] に設定されていることを確認します。
ストレージ アカウントで、左側のメニューの [データ ストレージ] の下にある [コンテナー] を選択します。 表示された画面で、[+ コンテナー] を選択します。 コンテナーに example-data という名前を付け、既定のパブリック アクセス レベルをそのまま使用します。
コンテナーが作成されたら、それを選択します。 次に、[アップロード] ボタンを選択して、先ほどダウンロードした
.txtおよび.jsonファイルを選択します。
リソースのキーとエンドポイントを取得する
Azure portal でリソースの概要ページに移動します
左側のメニューから [キーとエンドポイント] を選びます。 エンドポイントとキーは API 要求に使用されます。
カスタム テキスト分類プロジェクトを作成する
リソースとストレージ コンテナーが構成されたら、新しいカスタム テキスト分類プロジェクトを作成します。 プロジェクトとは、データに基づいてカスタム ML モデルを構築するための作業領域です。 プロジェクトにアクセスできるのは、自分と、使用されている Azure 言語リソースにアクセスできる他のユーザーだけです。
プロジェクトのインポート ジョブをトリガーする
ラベル ファイルをインポートするには、次の URL、ヘッダー、JSON 本文を使って POST 要求を送信します。 ラベル ファイルが、許容される形式に従っていることを確認してください。
同じ名前のプロジェクトが既に存在する場合は、そのプロジェクトのデータを置き換えます。
{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新バージョン用です。 その他の利用可能な API バージョンの詳細を確認する | 2022-05-01 |
ヘッダー
要求を認証するには、次のヘッダーを使います。
| 鍵 | 値 |
|---|---|
Ocp-Apim-Subscription-Key |
リソースへのキー。 API 要求の認証に使われます。 |
Body
要求では次の JSON を使います。 プレースホルダーの値は、実際の値に置き換えます。
{
"projectFileVersion": "{API-VERSION}",
"stringIndexType": "Utf16CodeUnit",
"metadata": {
"projectName": "{PROJECT-NAME}",
"storageInputContainerName": "{CONTAINER-NAME}",
"projectKind": "customMultiLabelClassification",
"description": "Trying out custom multi label text classification",
"language": "{LANGUAGE-CODE}",
"multilingual": true,
"settings": {}
},
"assets": {
"projectKind": "customMultiLabelClassification",
"classes": [
{
"category": "Class1"
},
{
"category": "Class2"
}
],
"documents": [
{
"location": "{DOCUMENT-NAME}",
"language": "{LANGUAGE-CODE}",
"dataset": "{DATASET}",
"classes": [
{
"category": "Class1"
},
{
"category": "Class2"
}
]
},
{
"location": "{DOCUMENT-NAME}",
"language": "{LANGUAGE-CODE}",
"dataset": "{DATASET}",
"classes": [
{
"category": "Class2"
}
]
}
]
}
}
| 鍵 | プレースホルダー | 値 | 例 |
|---|---|---|---|
| api-version | {API-VERSION} |
呼び出している API のバージョン。 ここで使用するバージョンは、URL 内と同じ API バージョンである必要があります。 その他の利用可能な API バージョンの詳細を確認する | 2022-05-01 |
| projectName | {PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
| プロジェクトの種類 | customMultiLabelClassification |
プロジェクトの種類。 | customMultiLabelClassification |
| 言語 | {LANGUAGE-CODE} |
プロジェクトで使用されるドキュメントの言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどのドキュメントの言語コードを選択します。 多言語サポートの詳細については、言語サポートをご覧ください。 | en-us |
| multilingual | true |
データセットで複数の言語のドキュメントを得ることを可能とするブール値であり、モデルがデプロイされる場合に、サポートする任意の言語 (必ずしもトレーニング ドキュメントに含まれているとは限りません) でモデルに関するクエリを実行することができます。 多言語サポートの詳細については、言語サポートをご覧ください。 | true |
| ストレージ入力コンテナ名 | {CONTAINER-NAME} |
アップロードしたドキュメントの Azure ストレージ コンテナーの名前。 | myContainer |
| classes | [] | プロジェクト内にあるすべてのクラスを含む配列。 | [] |
| documents | [] | プロジェクト内のすべてのドキュメントと、このドキュメントに対してクラスでラベル付けしたものを含む配列。 | [] |
| 位置 | {DOCUMENT-NAME} |
ストレージ コンテナー内のドキュメントの場所。 すべてのドキュメントはコンテナーのルートに含まれるため、ドキュメント名にする必要があります。 | doc1.txt |
| データセット | {DATASET} |
トレーニング前に分割するときのこのドキュメントの移動先テスト セット。
モデルをトレーニングする方法を参照してください。 このフィールドで使用できる値は Train および Test です。 |
Train |
API 要求を送信すると、ジョブが正しく送信されたことを示す 202 応答を受け取ります。 応答ヘッダーで、次のように書式設定された operation-location 値を抽出します。
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
この操作は非同期であるため、{JOB-ID} を使って要求が識別されます。 この URL を使用して、インポート ジョブの状態を取得します。
この要求で考えられるエラー シナリオ:
- 選択されたリソースに、ストレージ アカウントに対する適切なアクセス許可がありません。
- 指定された
storageInputContainerNameが存在しません。 - 無効な言語コードが使用されているか、言語コードの種類が文字列でない場合。
-
multilingual値は文字列であり、ブール値ではありません。
インポート ジョブの状態を取得する
次の GET 要求を使用して、プロジェクトのインポートの状態を取得します。 プレースホルダーの値は、実際の値に置き換えます。
要求 URL
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
{JOB-ID} |
モデルのトレーニングの状態を取得するための ID。 この値は、前のステップで受け取った location ヘッダーの値に含まれています。 |
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新バージョン用です。 その他の利用可能な API バージョンの詳細を確認する | 2022-05-01 |
ヘッダー
要求を認証するには、次のヘッダーを使います。
| 鍵 | 値 |
|---|---|
Ocp-Apim-Subscription-Key |
リソースへのキー。 API 要求の認証に使われます。 |
モデルをトレーニングする
通常、プロジェクトを作成した後、先に進み、プロジェクトに接続されているコンテナーにあるドキュメントのタグ付けを開始します。 このクイックスタートでは、サンプルのタグ付けされたデータセットをインポートし、サンプルの JSON タグ ファイルを使用してプロジェクトを初期化しました。
モデルのトレーニングを開始する
プロジェクトがインポートされたら、モデルのトレーニングを開始できます。
次の URL、ヘッダー、JSON 本文を使って POST 要求を送信し、トレーニング ジョブを送信します。 プレースホルダーの値は、実際の値に置き換えます。
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新バージョン用です。 その他の利用可能な API バージョンの詳細を確認する | 2022-05-01 |
ヘッダー
要求を認証するには、次のヘッダーを使います。
| 鍵 | 値 |
|---|---|
Ocp-Apim-Subscription-Key |
リソースへのキー。 API 要求の認証に使われます。 |
要求本文
要求本文では次の JSON を使います。 トレーニングが完了すると、モデルに {MODEL-NAME} が与えられます。 正常に完了したトレーニング ジョブでのみ、モデルが生成されます。
{
"modelLabel": "{MODEL-NAME}",
"trainingConfigVersion": "{CONFIG-VERSION}",
"evaluationOptions": {
"kind": "percentage",
"trainingSplitPercentage": 80,
"testingSplitPercentage": 20
}
}
| 鍵 | プレースホルダー | 値 | 例 |
|---|---|---|---|
| モデルラベル | {MODEL-NAME} |
正常にトレーニングされた後にモデルに割り当てられるモデル名。 | myModel |
| トレーニングコンフィグバージョン | {CONFIG-VERSION} |
これは、モデルのトレーニングに使用されるモデル バージョン です。 | 2022-05-01 |
| 評価オプション | トレーニング セットとテスト セットの間でデータを分割するオプション。 | {} |
|
| kind | percentage |
Split メソッド。 指定できる値は percentage または manual です。 詳細については、モデルのトレーニング方法に関するセクションを参照してください。 |
percentage |
| trainingSplitPercentage | 80 |
トレーニング セットに含めるタグ付きデータの割合。 推奨値は 80 です。 |
80 |
| testingSplitPercentage | 20 |
テスト セットに含めるタグ付きデータの割合。 推奨値は 20 です。 |
20 |
Note
trainingSplitPercentage と testingSplitPercentage は、Kind が percentage に設定されている場合にのみ必要であり、両方のパーセンテージの合計は 100 に等しい必要があります。
API 要求を送信すると、ジョブが正しく送信されたことを示す 202 応答を受け取ります。 応答ヘッダーで、次のように書式設定された location 値を抽出します。
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
この操作は非同期であるため、{JOB ID} を使って要求が識別されます。 この URL を使用してトレーニングの状態を取得できます。
トレーニング ジョブの状態を取得する
トレーニングには 10 分から 30 分かかる場合があります。 次の要求を使用して、トレーニング ジョブが正常に完了するまで状態をポーリングし続けることができます。
モデルのトレーニングの進行状況を取得するには、次の GET 要求を使用します。 プレースホルダーの値は、実際の値に置き換えます。
要求 URL
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
{JOB-ID} |
モデルのトレーニングの状態を取得するための ID。 この値は、前のステップで受け取った location ヘッダーの値に含まれています。 |
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新バージョン用です。 詳細については、「モデルのライフサイクル」を参照してください。 | 2022-05-01 |
ヘッダー
要求を認証するには、次のヘッダーを使います。
| 鍵 | 値 |
|---|---|
Ocp-Apim-Subscription-Key |
リソースへのキー。 API 要求の認証に使われます。 |
応答本文
要求を送信すると、次の応答が返されます。
{
"result": {
"modelLabel": "{MODEL-NAME}",
"trainingConfigVersion": "{CONFIG-VERSION}",
"estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
"trainingStatus": {
"percentComplete": 3,
"startDateTime": "2022-04-18T15:45:06.8190649Z",
"status": "running"
},
"evaluationStatus": {
"percentComplete": 0,
"status": "notStarted"
}
},
"jobId": "{JOB-ID}",
"createdDateTime": "2022-04-18T15:44:44Z",
"lastUpdatedDateTime": "2022-04-18T15:45:48Z",
"expirationDateTime": "2022-04-25T15:44:44Z",
"status": "running"
}
モデルをデプロイする
通常はモデルをトレーニングした後で、評価の詳細を確認し、必要に応じて改善を行います。 このクイックスタートでは、モデルをデプロイして Language Studio で試せるようにするところまで行いますが、予測 API を呼び出すこともできます。
デプロイ ジョブを送信する
次の URL、ヘッダー、JSON 本文を使って PUT 要求を送信し、デプロイ ジョブを送信します。 プレースホルダーの値は、実際の値に置き換えます。
{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
{DEPLOYMENT-NAME} |
デプロイの名前。 この値は、大文字と小文字が区別されます。 | staging |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新バージョン用です。 その他の利用可能な API バージョンの詳細を確認する | 2022-05-01 |
ヘッダー
要求を認証するには、次のヘッダーを使います。
| 鍵 | 値 |
|---|---|
Ocp-Apim-Subscription-Key |
リソースへのキー。 API 要求の認証に使われます。 |
要求本文
要求の本文で次の JSON を使います。 デプロイに割り当てるモデルの名前を使います。
{
"trainedModelLabel": "{MODEL-NAME}"
}
| 鍵 | プレースホルダー | 値 | 例 |
|---|---|---|---|
| 訓練済みモデルラベル | {MODEL-NAME} |
デプロイに割り当てられているモデル名。 正常にトレーニングされたモデルのみ割り当てることができます。 この値は、大文字と小文字が区別されます。 | myModel |
API 要求を送信すると、ジョブが正しく送信されたことを示す 202 応答を受け取ります。 応答ヘッダーで、次のように書式設定された operation-location 値を抽出します。
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
この操作は非同期であるため、{JOB ID} を使って要求が識別されます。 この URL を使ってデプロイの状態を取得できます。
デプロイ ジョブの状態を取得する
次の GET 要求を使って、デプロイ ジョブの状態に関するクエリを実行します。 前のステップで取得した URL を使うことも、プレースホルダーの値を実際の値に置き換えることもできます。
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
{DEPLOYMENT-NAME} |
デプロイの名前。 この値は、大文字と小文字が区別されます。 | staging |
{JOB-ID} |
モデルのトレーニングの状態を取得するための ID。 これは、前の手順で受け取った location ヘッダー値にあります。 |
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新バージョン用です。 その他の利用可能な API バージョンの詳細を確認する | 2022-05-01 |
ヘッダー
要求を認証するには、次のヘッダーを使います。
| 鍵 | 値 |
|---|---|
Ocp-Apim-Subscription-Key |
リソースへのキー。 API 要求の認証に使われます。 |
応答本文
要求を送信すると、次の応答が返されます。
status パラメーターが "succeeded" に変化するまで、このエンドポイントのポーリングを続けます。 要求の成功を示す 200 コードを取得します。
{
"jobId":"{JOB-ID}",
"createdDateTime":"{CREATED-TIME}",
"lastUpdatedDateTime":"{UPDATED-TIME}",
"expirationDateTime":"{EXPIRATION-TIME}",
"status":"running"
}
テキストを分類する
モデルが正常にデプロイされたら、モデルの使用を開始して 予測 API を使ってテキストを分類できます。 先ほどダウンロードしたサンプル データセットに、この手順で使用できるテスト ドキュメントがいくつか用意されています。
カスタム テキスト分類タスクを送信する
この POST 要求を使用して、テキスト分類タスクを開始します。
{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新バージョン用です。 詳細については、「モデルのライフサイクル」を参照してください。 | 2022-05-01 |
ヘッダー
| 鍵 | 値 |
|---|---|
| Ocp-Apim-Subscription-Key | この API へのアクセスを提供するキー。 |
Body
{
"displayName": "Classifying documents",
"analysisInput": {
"documents": [
{
"id": "1",
"language": "{LANGUAGE-CODE}",
"text": "Text1"
},
{
"id": "2",
"language": "{LANGUAGE-CODE}",
"text": "Text2"
}
]
},
"tasks": [
{
"kind": "CustomMultiLabelClassification",
"taskName": "Multi Label Classification",
"parameters": {
"projectName": "{PROJECT-NAME}",
"deploymentName": "{DEPLOYMENT-NAME}"
}
}
]
}
| 鍵 | プレースホルダー | 値 | 例 |
|---|---|---|---|
displayName |
{JOB-NAME} |
ジョブの名前。 | MyJobName |
documents |
[{},{}] | タスクを実行するドキュメントのリスト。 | [{},{}] |
id |
{DOC-ID} |
ドキュメント名または ID。 | doc1 |
language |
{LANGUAGE-CODE} |
ドキュメントの言語コードを指定する文字列。 このキーを指定しない場合、サービスによって、プロジェクトの作成時に選択したプロジェクトの既定の言語と見なされます。 サポートされている言語コードの一覧については、言語サポートに関するページを参照してください。 | en-us |
text |
{DOC-TEXT} |
タスクを実行するドキュメント タスク。 | Lorem ipsum dolor sit amet |
tasks |
実行するタスクのリスト。 | [] |
|
taskName |
カスタムマルチラベル分類 | タスク名 | カスタムマルチラベル分類 |
parameters |
タスクに渡すパラメーターのリスト。 | ||
project-name |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
deployment-name |
{DEPLOYMENT-NAME} |
デプロイの名前。 この値は、大文字と小文字が区別されます。 | prod |
[応答]
成功を示す 202 応答が表示されます。 応答のヘッダーから operation-location を抽出します。
operation-location は次のように書式設定されています。
{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}
この URL を使用して、タスクの完了状態をクエリし、タスクが完了したときに結果を取得できます。
タスクの結果を取得する
テキスト分類タスクの状態と結果のクエリを実行するには、次の GET 要求を使います。
{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新の モデル バージョン の値です。 | 2022-05-01 |
ヘッダー
| 鍵 | 値 |
|---|---|
| Ocp-Apim-Subscription-Key | この API へのアクセスを提供するキー。 |
応答本文
応答は、次のパラメーターを含む JSON ドキュメントです
{
"createdDateTime": "2021-05-19T14:32:25.578Z",
"displayName": "MyJobName",
"expirationDateTime": "2021-05-19T14:32:25.578Z",
"jobId": "xxxx-xxxxxx-xxxxx-xxxx",
"lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
"status": "succeeded",
"tasks": {
"completed": 1,
"failed": 0,
"inProgress": 0,
"total": 1,
"items": [
{
"kind": "customMultiClassificationTasks",
"taskName": "Classify documents",
"lastUpdateDateTime": "2020-10-01T15:01:03Z",
"status": "succeeded",
"results": {
"documents": [
{
"id": "{DOC-ID}",
"classes": [
{
"category": "Class_1",
"confidenceScore": 0.0551877357
}
],
"warnings": []
}
],
"errors": [],
"modelVersion": "2020-04-01"
}
}
]
}
}
リソースをクリーンアップする
プロジェクトが不要になったら、次の DELETE 要求で削除できます。 プレースホルダーの値は、実際の値に置き換えます。
{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
| プレースホルダー | 値 | 例 |
|---|---|---|
{ENDPOINT} |
API 要求を認証するためのエンドポイント。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
{API-VERSION} |
呼び出している API のバージョン。 参照される値は、リリースされた最新バージョン用です。 その他の利用可能な API バージョンの詳細を確認する | 2022-05-01 |
ヘッダー
要求を認証するには、次のヘッダーを使います。
| 鍵 | 値 |
|---|---|
| Ocp-Apim-Subscription-Key | リソースへのキー。 API 要求の認証に使われます。 |
API 要求を送信すると、成功を示す 202 応答が返されます。これは、プロジェクトが削除されていることを意味します。 呼び出しが成功すると、ジョブの状態を確認するために使用する Operation-Location ヘッダーが返されます。
次のステップ
カスタム テキスト分類モデルを作成すると、次のことができます。
独自のカスタム テキスト分類プロジェクトの作成を開始するときは、ハウツー記事を使用して、モデルの開発の詳細について確認してください。