クイックスタート: カスタムテキスト分類

[アーティクル]
12/19/2023

この記事を使って、テキスト分類のカスタムモデルをトレーニングできるカスタムテキスト分類プロジェクトの作成を開始します。モデルとは、特定のタスクを実行するためにトレーニングされる人工知能ソフトウェアです。このシステムでは、モデルによってテキストが分類され、タグ付けされたデータから学習することでモデルがトレーニングされます。

カスタムテキスト分類では、次の 2 種類のプロジェクトがサポートされています。

単一ラベル分類 - データセットの各ドキュメントに単一のクラスを割り当てることができます。たとえば、1 本の映画の脚本を "ロマンス" と "コメディ" のどちらかに分類できます。
複数ラベル分類 - データセットの各ドキュメントに複数のクラスを割り当てることができます。たとえば、1 本の映画の脚本を "コメディ" か、"ロマンス" かつ "コメディ" に分類できます。

このクイックスタートでは、用意されているサンプルデータセットを使用して、映画の脚本を 1 つまたは複数のカテゴリに分類できる複数ラベル分類を構築する、または、科学論文の要約を、定義されたドメインの 1 つに分類できる単一ラベル分類データセットを使用することができます。

前提条件

Azure サブスクリプション - 無料アカウントを作成します。

新しい Azure AI Language リソースと Azure ストレージアカウントを作成する

カスタムテキスト分類を使用する前に、Azure AI Language リソースを作成する必要があります。これにより、プロジェクトの作成とモデルのトレーニング開始に必要な認証情報が提供されます。また、モデルの構築に使用するデータセットをアップロードできる Azure ストレージアカウントも必要です。

重要

すぐに始めるには、この記事で示す手順を使用して新しい Azure AI Language リソースを作成することをお勧めします。この記事の手順を使用すると、言語リソースとストレージアカウントを同時に作成することができ、後で行うより簡単です。

使用したい既存のリソースがある場合は、それをストレージアカウントに接続する必要があります。

Azure portal から新しいリソースを作成します

Azure portal に移動し、新しい Azure AI Language リソースを作成します。
ウィンドウが表示されるので、カスタム機能から [カスタムテキスト分類とカスタム固有表現認識] を選びます。画面の下部にある [続けてリソースの作成を行う] を選択します。

次の詳細を使用して言語リソースを作成します。

名前	必須値
サブスクリプション	Azure サブスクリプション。
リソースグループ	リソースが格納されるリソースグループ。既存のものを使用するか、新しく作成することができます。
リージョン	サポートされているリージョンのいずれか。たとえば、"米国西部 2" です。
名前	リソースの名前。
価格レベル	サポートされている価格レベルのいずれか。 Free (F0) レベルを利用して、サービスを試用できます。

"ログインアカウントが選択したストレージアカウントのリソースグループの所有者ではない" ことを通知するメッセージが表示された場合は、言語リソースを作成する前に、アカウントでそのリソースグループに所有者ロールを割り当てる必要があります。 Azure サブスクリプションの所有者に問い合わせてください。

Azure サブスクリプションの所有者を確認するには、リソースグループを検索し、リンクに従ってそれに関連付けられているサブスクリプションに移動します。その後、以下を実行します。

[アクセス制御 (IAM)] タブを選びます
[ロールの割り当て] を選びます
Role:Owner でフィルター処理します。

[カスタムテキスト分類とカスタム固有表現認識] セクションで、既存のストレージアカウントを選ぶか、[新しいストレージアカウント] を選びます。これらの値は使用を開始するためのものであり、必ずしもご自分の運用環境で使用するストレージアカウントの値ではないことに注意してください。プロジェクトのビルド中の待機時間を回避するには、言語リソースと同じリージョンのストレージアカウントに接続します。

ストレージアカウントの値推奨値

ストレージアカウント名任意の名前

ストレージアカウントの種類標準 LRS
[責任ある AI の通知] がオンになっていることを確認します。ページ下部にある [確認と作成] を選択します。

ストレージアカウントの値	推奨値
ストレージアカウント名	任意の名前
ストレージアカウントの種類	標準 LRS

サンプルデータを BLOB コンテナーにアップロードする

Azure storage アカウントを作成し、それを言語リソースに接続したら、サンプルデータセットのドキュメントをコンテナーのルートディレクトリにアップロードする必要があります。これらのドキュメントは、後ほどモデルのトレーニングで使われます。

複数ラベルの分類
単一ラベルの分類

複数ラベル分類プロジェクトのサンプルデータセットをダウンロードします。
.zip ファイルを開き、ドキュメントが格納されているフォルダーを展開します。

提供されるサンプルデータセットには約 200 個のドキュメントが含まれており、それぞれが映画の要約です。各ドキュメントは、次のクラスの 1 つ以上に属します:

"ミステリー"
"ドラマ"
"スリラー"
"コメディ"
"アクション"

Azure portal で、作成したストレージアカウントに移動して選択します。これを行うには、[ストレージアカウント] をクリックし、[任意のフィールドのフィルター] にストレージアカウント名を入力します。

自分のリソースグループが表示されない場合は、[サブスクリプションが次に等しい] フィルターが [すべて] に設定されていることを確認します。
ストレージアカウントで、左側のメニューの [データストレージ] の下にある [コンテナー] を選択します。表示された画面で、[+ コンテナー] を選択します。コンテナーに example-data という名前を付け、既定のパブリックアクセスレベルをそのまま使用します。
コンテナーが作成されたら、それを選択します。次に、[アップロード] ボタンを選択して、先ほどダウンロードした .txt および .json ファイルを選択します。

カスタムテキスト分類プロジェクトを作成する

リソースとストレージコンテナーが構成されたら、新しいカスタムテキスト分類プロジェクトを作成します。プロジェクトは、データに基づいてカスタム ML モデルを構築するための作業領域です。ご自分のプロジェクトにアクセスできるのは、本人と、使用されている言語リソースへのアクセス権を持つ方のみです。

Language Studio にサインインします。サブスクリプションと言語リソースを選ぶためのウィンドウが表示されます。言語リソースを選びます。
Language Studio の [テキストの分類] セクションで、[カスタムテキストの分類] を選択します。
プロジェクトページの上部メニューから、 [Create new project](新しいプロジェクトの作成) を選択します。プロジェクトを作成すると、データのラベル付け、モデルのトレーニング、評価、改善、デプロイを実行できます。
[新しいプロジェクトの作成] をクリックすると、ストレージアカウントを接続するためのウィンドウが表示されます。既にストレージアカウントを接続している場合は、そのストレージアカウントが表示されます。まだ接続していない場合は、表示されるドロップダウンからストレージアカウントを選択し、[ストレージアカウントの接続] を選択します。これにより、ストレージアカウントに必要なロールが設定されます。ストレージアカウントの所有者として割り当てられていない場合、この手順でエラーが返される可能性があります。
注意
- この手順は、使用する各言語リソースに対して 1 回のみ行う必要があります。
- この処理は元に戻すことができません。ストレージアカウントを言語リソースに接続すると、後で切断することはできません。
- 言語リソースは 1 つのストレージアカウントにのみ接続できます。
プロジェクトタイプを選択します。各ドキュメントが 1 つまたは複数のクラスに属することができる複数ラベル分類プロジェクト、または各ドキュメントが 1 つのクラスにのみ属することができる単一ラベル分類プロジェクトのいずれかを作成できます。選択したタイプを後で変更することはできません。プロジェクトの種類の詳細
名前、説明、プロジェクト内のドキュメントの言語など、プロジェクトの情報を入力します。サンプルデータセットを使用する場合は、[英語] を選択します。プロジェクトの名前は後で変更できません。 [次へ] を選択します。

ヒント

データセットは、すべて同じ言語である必要はありません。サポートされる言語がそれぞれ異なる複数のドキュメントを得ることができます。データセットに異なる言語のドキュメントが含まれる場合や、実行時に異なる言語のテキストが必要になると考えられる場合は、プロジェクトの基本情報を入力するときに、[多言語データセットを有効にする] オプションを選択します。このオプションは、後で [プロジェクトの設定] ページから有効にすることができます。
データセットをアップロードしたコンテナーを選択します。

注意

データが既にラベル付けされている場合は、サポートされている形式に従っていることを確認し、[はい、ドキュメントは既にラベル付けされており、JSON ラベルファイルを書式設定しています] を選択し、下のドロップダウンメニューからラベルファイルを選択します。

データセットの例のいずれかを使っている場合は、含まれる webOfScience_labelsFile または movieLabels の json ファイルを使います。 [次へ] を選択します。
入力したデータを確認し、 [Create Project](プロジェクトの作成) を選びます。

モデルをトレーニングする

通常、プロジェクトを作成した後、先に進み、プロジェクトに接続されているコンテナーにあるドキュメントのラベル付けを開始します。このクイックスタートでは、サンプルのラベル付けされたデータセットをインポートし、サンプルの JSON ラベルファイルを使用してプロジェクトを初期化しました。

Language Studio 内からモデルのトレーニングを開始するには:

左側のメニューから [トレーニングジョブ] を選択します。
上部のメニューから [Start a training job] (トレーニングジョブの開始) を選択します。
[新しいモデルのトレーニング] を選択し、テキストボックスにモデル名を入力します。また、[既存のモデルを上書きする] オプションを選択し、ドロップダウンメニューから上書きするモデルを選択することにより、既存のモデルを上書きすることもできます。トレーニング済みモデルを上書きすると、元に戻すことはできません。ただし、新しいモデルをデプロイするまで、デプロイされているモデルには影響しません。
データの分割方法を選択します。 [トレーニング用データからテスト用セットを自動的に分割する] を選択できます。その場合、システムは、指定された割合に従って、ラベル付けされたデータをトレーニング用セットとテスト用セットに分割します。または、[トレーニング用データとテスト用データの手動分割を使用] を選択することもできます。このオプションは、データのラベル付け中にドキュメントをテスト用セットに追加した場合にのみ有効になります。データ分割の詳細については、モデルのトレーニング方法をご覧ください。
[トレーニング] ボタンを選択します。
一覧からトレーニングジョブ ID を選択すると、サイドペインが表示され、そのジョブの [トレーニングの進行状況]、[ジョブの状態]、その他の詳細を確認できます。
注意
- 正常に完了したトレーニングジョブでのみ、モデルが生成されます。
- モデルのトレーニングには、ラベル付けされたデータのサイズに基づいて、数分から数時間かかる場合があります。
- 一度に実行できるトレーニングジョブは 1 つだけです。実行中のジョブが完了するまで、同じプロジェクト内で他のトレーニングジョブを開始することはできません。

モデルをデプロイする

通常はモデルをトレーニングした後、その評価の詳細を確認し、必要に応じて改善を行います。このクイックスタートでは、モデルをデプロイして Language Studio で試せるようにするところまで行いますが、予測 API を呼び出すこともできます。

Language Studio 内からモデルのデプロイを開始するには、次の手順を行います。

左側のメニューから [Deploying a model](モデルのデプロイ) を選びます。
[デプロイの追加] を選択して、新しいデプロイジョブを開始します。
[デプロイの新規作成] を選択して新しいデプロイを作成し、下のドロップダウンからトレーニング済みのモデルを割り当てます。 既存のデプロイを上書きすることもできます。そのためにはこのオプションを選択して、下のドロップダウンから割り当てるトレーニング済みモデルを選択します。

注意

既存のデプロイを上書きしても、Prediction API の呼び出しを変更する必要はありませんが、その結果は、新しく割り当てたモデルに基づくものになります。
[デプロイ] を選択して、デプロイジョブを開始します。
デプロイが成功すると、その横に有効期限が表示されます。デプロイの有効期限とは、デプロイされたモデルを予測に使用できなくなるときであり、通常は、トレーニング構成の有効期限が切れる 12 か月後に発生します。

モデルのテスト

モデルがデプロイされたら、モデルの使用を開始して予測 API を使ってテキストを分類できます。このクイックスタートでは、Language Studio を使用して、カスタムテキスト分類タスクを送信し、結果を視覚化します。先ほどダウンロードしたサンプルデータセットに、この手順で使用できるテストドキュメントがいくつか用意されています。

デプロイされたモデルを Language Studio 内でテストするには、次のようにします。

画面左側のメニューから [Testing deployments](デプロイのテスト) を選択します。
テストするデプロイを選択します。テストできるのは、デプロイに割り当てられているモデルのみです。
多言語プロジェクトの場合は、言語ドロップダウンを使用してテストするテキストの言語を選択します。
ドロップダウンからクエリ/テストするデプロイを選択します。
要求で送信するテキストを入力するか、使用する .txt ドキュメントをアップロードします。データセットの例のいずれかを使っている場合は、含まれている .txt ファイルのいずれかを使用できます。
上部のメニューから [テストの実行] を選択します。
[Result](結果) タブで、テキストに対して予測されたクラスを確認できます。 [JSON] タブで JSON 応答を表示することもできます。次の例は、単一ラベル分類プロジェクトの場合です。複数ラベル分類プロジェクトでは、結果に複数のクラスが返される可能性があります。

プロジェクトをクリーンアップする

プロジェクトが不要な場合は、Language Studio を使ってプロジェクトを削除できます。上部の [カスタムテキスト分類] を選び、削除するプロジェクトを選びます。上部のメニューから [削除] を選んで、プロジェクトを削除します。

前提条件

Azure サブスクリプション - 無料アカウントを作成します。

新しい Azure AI Language リソースと Azure ストレージアカウントを作成する

カスタムテキスト分類を使用する前に、Azure AI Language リソースを作成する必要があります。これにより、プロジェクトの作成とモデルのトレーニング開始に必要な認証情報が提供されます。また、モデルの構築時に使用するデータセットをアップロードできるように、Azure ストレージアカウントも必要です。

重要

すぐに始めるには、この記事に記載されている手順を使用して新しい Azure AI Language リソースを作成することをお勧めします。言語リソースの作成と、ストレージアカウントの作成、接続、またはその両方を同時に行うことができ、後で行うより簡単だからです。

使用したい既存のリソースがある場合は、それをストレージアカウントに接続する必要があります。

Azure portal から新しいリソースを作成します

Azure portal に移動し、新しい Azure AI Language リソースを作成します。
ウィンドウが表示されるので、カスタム機能から [カスタムテキスト分類とカスタム固有表現認識] を選びます。画面の下部にある [続けてリソースの作成を行う] を選択します。

次の詳細を使用して言語リソースを作成します。

名前	必須値
サブスクリプション	Azure サブスクリプション。
リソースグループ	リソースが格納されるリソースグループ。既存のものを使用するか、新しく作成することができます。
リージョン	サポートされているリージョンのいずれか。たとえば、"米国西部 2" です。
名前	リソースの名前。
価格レベル	サポートされている価格レベルのいずれか。 Free (F0) レベルを利用して、サービスを試用できます。

[アクセス制御 (IAM)] タブを選びます
[ロールの割り当て] を選びます
Role:Owner でフィルター処理します。

[カスタムテキスト分類とカスタム固有表現認識] セクションで、既存のストレージアカウントを選ぶか、[新しいストレージアカウント] を選びます。これらの値は使用を開始するためのものであり、必ずしもご自分の運用環境で使用するストレージアカウントの値ではないことに注意してください。プロジェクトのビルド中の待機時間を回避するには、言語リソースと同じリージョンのストレージアカウントに接続します。

ストレージアカウントの値推奨値

ストレージアカウント名任意の名前

ストレージアカウントの種類標準 LRS
[責任ある AI の通知] がオンになっていることを確認します。ページ下部にある [確認と作成] を選択します。

ストレージアカウントの値	推奨値
ストレージアカウント名	任意の名前
ストレージアカウントの種類	標準 LRS

複数ラベル分類プロジェクトのサンプルデータセットをダウンロードします。
.zip ファイルを開き、ドキュメントが格納されているフォルダーを展開します。

"ミステリー"
"ドラマ"
"スリラー"
"コメディ"
"アクション"

Azure portal で、作成したストレージアカウントに移動して選択します。これを行うには、[ストレージアカウント] をクリックし、[任意のフィールドのフィルター] にストレージアカウント名を入力します。

自分のリソースグループが表示されない場合は、[サブスクリプションが次に等しい] フィルターが [すべて] に設定されていることを確認します。
ストレージアカウントで、左側のメニューの [データストレージ] の下にある [コンテナー] を選択します。表示された画面で、[+ コンテナー] を選択します。コンテナーに example-data という名前を付け、既定のパブリックアクセスレベルをそのまま使用します。
コンテナーが作成されたら、それを選択します。次に、[アップロード] ボタンを選択して、先ほどダウンロードした .txt および .json ファイルを選択します。

リソースのキーとエンドポイントを取得する

Azure portal でリソースの概要ページに移動します
左側のメニューで [キーとエンドポイント] を選びます。 API 要求のエンドポイントとキーを使います

カスタムテキスト分類プロジェクトを作成する

プロジェクトジョブのインポートをトリガーする

ラベルファイルをインポートするには、次の 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`

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
`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"
          }
        ]
      }
    ]
  }
}

Key	プレースホルダー	値	例
api-version	`{API-VERSION}`	呼び出している API のバージョン。ここで使用するバージョンは、URL 内と同じ API バージョンである必要があります。その他の利用可能な API バージョンの詳細を確認する	`2022-05-01`
projectName	`{PROJECT-NAME}`	プロジェクトの名前。この値は、大文字と小文字が区別されます。	`myProject`
projectKind	`customMultiLabelClassification`	プロジェクトの種類。	`customMultiLabelClassification`
language	`{LANGUAGE-CODE}`	プロジェクトで使用されるドキュメントの言語コードを指定する文字列。プロジェクトが多言語プロジェクトの場合は、ほとんどのドキュメントの言語コードを選択します。多言語サポートの詳細については、言語サポートをご覧ください。	`en-us`
複数言語	`true`	データセットに複数の言語のドキュメントを含め、モデルをデプロイするときに、サポートされている任意の言語 (トレーニングドキュメントに含まれているとは限りません) でモデルにクエリを実行できるブール値です。多言語サポートの詳細については、言語サポートをご覧ください。	`true`
storageInputContainerName	`{CONTAINER-NAME}`	ドキュメントをアップロードした Azure ストレージコンテナーの名前。	`myContainer`
クラス	[]	プロジェクト内のすべてのクラスを含む配列。これらはドキュメントの分類先となるクラスです。	[]
ドキュメント	[]	プロジェクト内のすべてのドキュメントと、このドキュメントにラベル付けされたクラスを含む配列。	[]
location	`{DOCUMENT-NAME}`	ストレージコンテナー内のドキュメントの場所。すべてのドキュメントはコンテナーのルートに含まれているので、これはドキュメント名にする必要があります。	`doc1.txt`
dataset	`{DATASET}`	トレーニング前に分割する場合にこのドキュメントが移動するテストセット。データ分割の詳細については、モデルのトレーニング方法をご覧ください。このフィールドで使用できる値は `Train` および `Test` です。	`Train`

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customSingleLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customSingleLabelClassification",
        "classes": [
            {
                "category": "Class1"
            },
            {
                "category": "Class2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class2"
                }
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class1"
                }
            }
        ]
    }
}

Key	プレースホルダー	値	例
api-version	`{API-VERSION}`	呼び出している API のバージョン。ここで使用するバージョンは、URL 内と同じ API バージョンである必要があります。	`2022-05-01`
projectName	`{PROJECT-NAME}`	プロジェクトの名前。この値は、大文字と小文字が区別されます。	`myProject`
projectKind	`customSingleLabelClassification`	プロジェクトの種類。	`customSingleLabelClassification`
language	`{LANGUAGE-CODE}`	プロジェクトで使用されるドキュメントの言語コードを指定する文字列。プロジェクトが多言語プロジェクトの場合は、ほとんどのドキュメントの言語コードを選択します。サポートされている言語コードの詳細については、言語サポートをご覧ください。	`en-us`
複数言語	`true`	データセットに複数の言語のドキュメントを含め、モデルをデプロイするときに、サポートされている任意の言語 (トレーニングドキュメントに含まれているとは限りません) でモデルにクエリを実行できるブール値です。多言語サポートの詳細については、言語サポートをご覧ください。	`true`
storageInputContainerName	`{CONTAINER-NAME}`	ドキュメントをアップロードした Azure ストレージコンテナーの名前。	`myContainer`
クラス	[]	プロジェクト内のすべてのクラスを含む配列。これらはドキュメントの分類先となるクラスです。	[]
ドキュメント	[]	プロジェクト内のすべてのドキュメントと、このドキュメントが属するクラスを含む配列。	[]
location	`{DOCUMENT-NAME}`	ストレージコンテナー内のドキュメントの場所。すべてのドキュメントはコンテナーのルートに含まれているので、これはドキュメント名にする必要があります。	`doc1.txt`
dataset	`{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`

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
`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`

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
`Ocp-Apim-Subscription-Key`	リソースへのキー。 API 要求の認証に使われます。

要求本文

要求本文では次の JSON を使います。トレーニングが完了すると、モデルに {MODEL-NAME} が与えられます。正常に完了したトレーニングジョブでのみ、モデルが生成されます。

{
	"modelLabel": "{MODEL-NAME}",
	"trainingConfigVersion": "{CONFIG-VERSION}",
	"evaluationOptions": {
		"kind": "percentage",
		"trainingSplitPercentage": 80,
		"testingSplitPercentage": 20
	}
}

Key	プレースホルダー	値	例
modelLabel	`{MODEL-NAME}`	トレーニングが正常に行われた後にモデルに割り当てられるモデル名。	`myModel`
trainingConfigVersion	`{CONFIG-VERSION}`	これは、モデルをトレーニングするために使用されるモデルバージョンです。	`2022-05-01`
evaluationOptions		データをトレーニング用セットとテスト用セットに分割するオプション。	`{}`
kind	`percentage`	分割方法。指定できる値は `percentage` または `manual` です。詳細については、モデルのトレーニング方法に関する記事をご覧ください。	`percentage`
trainingSplitPercentage	`80`	トレーニングセットに含まれるタグ付きデータの割合。推奨値は `80` です。	`80`
testingSplitPercentage	`20`	テストセットに含まれるタグ付きデータの割合。推奨値は `20` です。	`20`

注意

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 のバージョン。ここで参照される値は、リリース済みの最新バージョン用です。使用可能な他の API バージョンの詳細については、「モデルのライフサイクル」を参照してください。	`2022-05-01`

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
`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`

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
`Ocp-Apim-Subscription-Key`	リソースへのキー。 API 要求の認証に使われます。

要求本文

要求の本文で次の JSON を使います。デプロイに割り当てるモデルの名前を使います。

{
  "trainedModelLabel": "{MODEL-NAME}"
}

Key	プレースホルダー	値	例
trainedModelLabel	`{MODEL-NAME}`	デプロイに割り当てられるモデル名。正常にトレーニングされたモデルのみ割り当てることができます。この値は、大文字と小文字が区別されます。	`myModel`

{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`

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
`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 のバージョン。ここで参照される値は、リリース済みの最新バージョン用です。使用可能な他の API バージョンの詳細については、モデルのライフサイクルに関するページを参照してください。	`2022-05-01`

ヘッダー

Key	価値
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}"
      }
    }
  ]
}

Key	プレースホルダー	値	例
`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`	CustomMultiLabelClassification	タスク名	CustomMultiLabelClassification
`parameters`		タスクに渡すパラメーターのリスト。
`project-name`	`{PROJECT-NAME}`	プロジェクトの名前。この値は、大文字と小文字が区別されます。	`myProject`
`deployment-name`	`{DEPLOYMENT-NAME}`	デプロイの名前。この値は、大文字と小文字が区別されます。	`prod`

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "Single Classification Label",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

Key	プレースホルダー	値	例
displayName	`{JOB-NAME}`	ジョブの名前。	`MyJobName`
ドキュメント		タスクを実行するドキュメントのリスト。
`id`	`{DOC-ID}`	ドキュメント名または ID。	`doc1`
`language`	`{LANGUAGE-CODE}`	ドキュメントの言語コードを指定する文字列。このキーが指定されていない場合、サービスではプロジェクトの作成時に選択されたプロジェクトの既定の言語を想定します。サポートされている言語コードの一覧については、言語のサポートに関するページを参照してください。	`en-us`
`text`	`{DOC-TEXT}`	タスクを実行するドキュメントタスク。	`Lorem ipsum dolor sit amet`
`taskName`	CustomSingleLabelClassification	タスク名	CustomSingleLabelClassification
`tasks`	[]	実行するタスクの配列。	[]
`parameters`		タスクに渡すパラメーターのリスト。
`project-name`	`{PROJECT-NAME}`	プロジェクトの名前。この値は、大文字と小文字が区別されます。	`myProject`
`deployment-name`	`{DEPLOYMENT-NAME}`	デプロイの名前。この値は、大文字と小文字が区別されます。	`prod`

Response

成功を示す 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`

ヘッダー

Key	価値
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"
        }
      }
    ]
  }
}

{
  "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": "customSingleClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "class": [
                  {
                      "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`

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	価値
Ocp-Apim-Subscription-Key	リソースへのキー。 API 要求の認証に使われます。

API 要求を送信すると、成功を示す 202 応答を受け取ります。これは、プロジェクトが削除されたことを意味します。呼び出しが成功すると、ジョブの状態を確認するために使用する Operation-Location ヘッダーが返されます。

次のステップ

カスタムテキスト分類モデルを作成した後は、次のことができます。

ランタイム API を使用してテキストを分類する

独自のカスタムテキスト分類プロジェクトの作成を開始するときは、ハウツー記事を使用して、モデルの開発の詳細について確認してください。

クイックスタート: カスタム テキスト分類

前提条件

新しい Azure AI Language リソースと Azure ストレージ アカウントを作成する

Azure portal から新しいリソースを作成します

サンプル データを BLOB コンテナーにアップロードする

カスタム テキスト分類プロジェクトを作成する

モデルをトレーニングする

モデルをデプロイする

モデルのテスト

プロジェクトをクリーンアップする

前提条件

新しい Azure AI Language リソースと Azure ストレージ アカウントを作成する

Azure portal から新しいリソースを作成します

サンプル データを BLOB コンテナーにアップロードする

リソースのキーとエンドポイントを取得する

カスタム テキスト分類プロジェクトを作成する

プロジェクト ジョブのインポートをトリガーする

ヘッダー

Body

インポート ジョブの状態を取得する

要求 URL

ヘッダー

モデルをトレーニングする

モデルのトレーニングを開始する

ヘッダー

要求本文

トレーニング ジョブの状態を取得する

要求 URL

ヘッダー

応答本文

モデルをデプロイする

デプロイ ジョブを送信する

ヘッダー

要求本文

デプロイ ジョブの状態を取得する

ヘッダー

応答本文

テキストを分類する

カスタム テキスト分類タスクを送信する

ヘッダー

Body

Response

タスクの結果を取得する

ヘッダー

応答本文

リソースをクリーンアップする

ヘッダー

次のステップ

その他のリソース

クイックスタート: カスタムテキスト分類

新しい Azure AI Language リソースと Azure ストレージアカウントを作成する

サンプルデータを BLOB コンテナーにアップロードする

カスタムテキスト分類プロジェクトを作成する

新しい Azure AI Language リソースと Azure ストレージアカウントを作成する

サンプルデータを BLOB コンテナーにアップロードする

カスタムテキスト分類プロジェクトを作成する

プロジェクトジョブのインポートをトリガーする

インポートジョブの状態を取得する

トレーニングジョブの状態を取得する

デプロイジョブを送信する

デプロイジョブの状態を取得する

カスタムテキスト分類タスクを送信する