次の方法で共有

クイック スタート: カスタム Text Analytics for health

  • [アーティクル]

Note

カスタム Text Analytics for health (プレビュー) は、2025 年 1 月 10 日に廃止されます。その日までに、Azure AI Language のカスタム固有表現認識など、他のカスタム モデル トレーニング サービスに移行してください。 2025 年 1 月 10 日までは、既存のプロジェクトでカスタム Text Analytics for health (プレビュー) を中断することなく引き続き使用できます。 新しいプロジェクトを作成することはできません。 2025 年 1 月 10 日 – カスタム Text Analytics for health (プレビュー) で実行されているワークロードが削除され、関連するプロジェクト データは失われます。

この記事では、カスタム Text Analytics for health プロジェクトの作成を開始する方法について説明します。このプロジェクトでは、カスタム エンティティ認識用の Text Analytics for health のカスタム モデルをトレーニングできます。 モデルとは、特定のタスクを実行するためにトレーニングされる人工知能ソフトウェアです。 このシステムでは、モデルによって医療に関する名前付きエンティティが抽出され、ラベル付けされたデータから学習することでモデルがトレーニングされます。

この記事では、Language Studio を使って、カスタム Text Analytics for health の主要な概念を示します。 例としてカスタム Text Analytics for health のモデルを作成し、短い退院メモから施設または治療場所を抽出します。

前提条件

問題が発生しました

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

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

重要

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

既存のリソースを使いたい場合は、それとストレージ アカウントを接続する必要があります。 詳細については、既存のリソースを使用するためのガイダンスを参照してください。

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

  1. Azure portal にサインインし、新しい Azure AI Language リソースを作成します。

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

    Azure portal 内の [カスタム テキスト分類とカスタム固有表現認識] を示すスクリーンショット。

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

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

    注意

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

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

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

  5. [責任ある AI の通知] がオンになっていることを確認します。 ページの下部にある [確認と作成] を選択して、[作成] を選択します。

問題が発生しました

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

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

  1. GitHub からサンプル データセットをダウンロードします。

  2. .zip ファイルを開き、ドキュメントが格納されているフォルダーを展開します。

  3. Azure portal で、作成したストレージ アカウントに移動して選択します。

  4. ストレージ アカウントで、左側のメニューの [データ ストレージ] の下にある [コンテナー] を選択します。 表示された画面で、[+ コンテナー] を選択します。 コンテナーに example-data という名前を付け、既定のパブリック アクセス レベルをそのまま使用します。

    ストレージ アカウントのメイン ページを示すスクリーンショット。

  5. コンテナーが作成されたら、それを選択します。 次に、[アップロード] ボタンを選択して、先ほどダウンロードした .txt および .json ファイルを選択します。

    ストレージ アカウントにファイルをアップロードするためのボタンを示すスクリーンショット。

提供されているサンプル データセットには、12 件の臨床記録が含まれています。 各臨床記録には、いくつかの医療エンティティと治療場所が記載されています。 事前構築済みのエンティティを使用して医療エンティティを抽出し、エンティティの学習済みコンポーネントとリスト コンポーネントを使用して治療場所を抽出するカスタム モデルをトレーニングします。

問題が発生しました

カスタム Text Analytics for health プロジェクトを作成する

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

  1. Language Studio にサインインします。 サブスクリプションと言語リソースを選ぶためのウィンドウが表示されます。 上の手順で作成した言語リソースを選択します。

  2. Language Studio の [情報の抽出] セクションで、[Custom Text Analytics for health] (カスタム Text Analytics for health) を選択します。

  3. プロジェクト ページの上部メニューから、 [Create new project](新しいプロジェクトの作成) を選択します。 プロジェクトを作成すると、データのラベル付け、モデルのトレーニング、評価、改善、デプロイを実行できます。

    プロジェクト作成ページのスクリーンショット。

  4. 名前、説明、プロジェクト内のファイルの言語など、プロジェクト情報を入力します。 サンプル データセットを使用する場合は、[英語] を選択します。 プロジェクトの名前は後で変更できません。 [次へ] を選択します

    ヒント

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

  5. [新しいプロジェクトの作成] を選択すると、ストレージ アカウントを接続するためのウィンドウが表示されます。 既にストレージ アカウントを接続している場合は、そのストレージ アカウントが表示されます。 まだ接続していない場合は、表示されるドロップダウンからストレージ アカウントを選択し、[ストレージ アカウントの接続] を選択します。これにより、ストレージ アカウントに必要なロールが設定されます。 ストレージ アカウントの所有者として割り当てられていない場合、この手順でエラーが返される可能性があります。

    Note

    • この手順は、使用する新しいリソースごとに 1 回だけ行う必要があります。
    • この処理は元に戻すことができません。ストレージ アカウントを言語リソースに接続すると、後で切断することはできません。
    • 言語リソースは 1 つのストレージ アカウントにのみ接続できます。

    ストレージ接続画面を示すスクリーンショット。

  6. データセットをアップロードしたコンテナーを選択します。

  7. 既にデータのラベル付けを完了している場合は、それがサポートされている形式に従っていることを確認し、[はい、ファイルは既にラベル付けされており、JSON ラベル ファイルを書式設定しています] を選択し、ドロップダウン メニューからラベル ファイルを選択します。 [次へ] を選択します。 クイックスタートのデータセットを使用している場合、JSON ラベル ファイルの書式設定を確認する必要はありません。

  8. 入力したデータを確認し、 [Create Project](プロジェクトの作成) を選びます。

問題が発生しました

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

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

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

  1. 左側のメニューから [トレーニング ジョブ] を選択します。

  2. 上部のメニューから [Start a training job] (トレーニング ジョブの開始) を選択します。

  3. [新しいモデルのトレーニング] を選択し、テキスト ボックスにモデル名を入力します。 また、[既存のモデルを上書きする] オプションを選択し、ドロップダウン メニューから上書きするモデルを選択することにより、既存のモデルを上書きすることもできます。 トレーニング済みモデルを上書きすると、元に戻すことはできません。ただし、新しいモデルをデプロイするまで、デプロイされているモデルには影響しません。

    Language Studio のトレーニング ジョブ作成画面を示すスクリーンショット。

  4. データの分割方法を選択します。 [トレーニング用データからテスト用セットを自動的に分割する] を選択できます。その場合、システムは、指定された割合に従って、ラベル付けされたデータをトレーニング用セットとテスト用セットに分割します。 または、[トレーニングおよびテスト データの手動分割を使用する] を選択することもできます。このオプションは、ドキュメントをテスト用セットに追加した場合にのみ有効になります。 データの分割の詳細については、データのラベル付けに関する記事とモデルをトレーニングする方法に関するセクションを参照してください。

  5. [トレーニング] ボタンを選択します。

  6. 一覧からトレーニング ジョブ ID を選択すると、サイド ペインが表示され、そのジョブの [トレーニングの進行状況]、[ジョブの状態]、その他の詳細を確認できます。

    注意

    • 正常に完了したトレーニング ジョブでのみ、モデルが生成されます。
    • トレーニングは、ラベル付けされたデータのサイズに応じて、数分から数時間かかる場合があります。
    • 一度に実行できるトレーニング ジョブは 1 つだけです。 実行中のジョブが完了するまで、同じプロジェクト内で他のトレーニング ジョブを開始することはできません。

問題が発生しました

モデルをデプロイする

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

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

  1. 左側のメニューから [Deploying a model](モデルのデプロイ) を選びます。

  2. [デプロイの追加] を選択して、新しいデプロイ ジョブを開始します。

    Language Studio のデプロイ ボタンを示すスクリーンショット。

  3. [デプロイの新規作成] を選択して新しいデプロイを作成し、下のドロップダウンからトレーニング済みのモデルを割り当てます。 既存のデプロイを上書きすることもできます。そのためにはこのオプションを選択して、下のドロップダウンから割り当てるトレーニング済みモデルを選択します。

    注意

    既存のデプロイを上書きしても、予測 API の呼び出しを変更する必要はありませんが、その結果は、新しく割り当てたモデルに基づくものになります。

    Language Studio のモデル デプロイ オプションを示すスクリーンショット。

  4. [デプロイ] を選択して、デプロイ ジョブを開始します。

  5. デプロイが成功すると、その横に有効期限が表示されます。 デプロイの有効期限は、デプロイされたモデルを予測に使用できなくなるときで、通常、トレーニング構成の有効期限が切れる 12 か月後に発生します。

問題が発生しました

モデルのテスト

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

Language Studio 内からデプロイされたモデルをテストするには、次の手順を行います。

  1. 左側のメニューから [デプロイのテスト] を選びます。

  2. テストするデプロイを選択します。 テストできるのは、デプロイに割り当てられているモデルのみです。

  3. ドロップダウンからクエリ/テストするデプロイを選択します。

  4. 要求に送信するテキストを入力するか、使用する .txt ファイルをアップロードできます。

  5. 上部のメニューから [テストの実行] を選択します。

  6. [Result](結果) タブでは、テキストから抽出されたエンティティとその型を確認できます。 [JSON] タブで JSON 応答を表示することもできます。

    Language Studio のデプロイ テスト画面を示すスクリーンショット。

問題が発生しました

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

プロジェクトが不要な場合は、Language Studio を使ってプロジェクトを削除できます。

  1. ページの上部で、使用している言語サービス機能を選択します。
  2. 削除するプロジェクトを選択します。
  3. 上部のメニューで [削除] を選択します。

問題が発生しました

前提条件

問題が発生しました

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

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

重要

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

既存のリソースを使いたい場合は、それとストレージ アカウントを接続する必要があります。 詳細については、プロジェクトの作成に関する記事を参照してください。

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

  1. Azure portal にサインインし、新しい Azure AI Language リソースを作成します。

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

    Azure portal 内の [カスタム テキスト分類とカスタム固有表現認識] を示すスクリーンショット。

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

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

    注意

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

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

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

  5. [責任ある AI の通知] がオンになっていることを確認します。 ページの下部にある [確認と作成] を選択して、[作成] を選択します。

問題が発生しました

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

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

  1. GitHub からサンプル データセットをダウンロードします。

  2. .zip ファイルを開き、ドキュメントが格納されているフォルダーを展開します。

  3. Azure portal で、作成したストレージ アカウントに移動して選択します。

  4. ストレージ アカウントで、左側のメニューの [データ ストレージ] の下にある [コンテナー] を選択します。 表示された画面で、[+ コンテナー] を選択します。 コンテナーに example-data という名前を付け、既定のパブリック アクセス レベルをそのまま使用します。

    ストレージ アカウントのメイン ページを示すスクリーンショット。

  5. コンテナーが作成されたら、それを選択します。 次に、[アップロード] ボタンを選択して、先ほどダウンロードした .txt および .json ファイルを選択します。

    ストレージ アカウントにファイルをアップロードするためのボタンを示すスクリーンショット。

提供されているサンプル データセットには、12 件の臨床記録が含まれています。 各臨床記録には、いくつかの医療エンティティと治療場所が記載されています。 事前構築済みのエンティティを使用して医療エンティティを抽出し、エンティティの学習済みコンポーネントとリスト コンポーネントを使用して治療場所を抽出するカスタム モデルをトレーニングします。

問題が発生しました

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

  1. Azure portal でリソースの概要ページに移動します

  2. 左側のメニューで [キーとエンドポイント] を選びます。 API 要求のエンドポイントとキーを使用します。

    Azure portal のキーとエンドポイントのページを示すスクリーンショット

問題が発生しました

カスタム Text Analytics for health プロジェクトを作成する

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

前の手順でサンプル データからダウンロードしたラベル ファイルを使用して、次の要求の本文に追加します。

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

ラベル ファイルをインポートするには、次の 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}",
		"projectKind": "CustomHealthcare",
		"description": "Trying out custom Text Analytics for health",
		"language": "{LANGUAGE-CODE}",
		"multilingual": true,
		"storageInputContainerName": "{CONTAINER-NAME}",
		"settings": {}
	},
	"assets": {
		"projectKind": "CustomHealthcare",
		"entities": [
			{
				"category": "Entity1",
				"compositionSetting": "{COMPOSITION-SETTING}",
				"list": {
					"sublists": [
						{
							"listKey": "One",
							"synonyms": [
								{
									"language": "en",
									"values": [
										"EntityNumberOne",
										"FirstEntity"
									]
								}
							]
						}
					]
				}
			},
			{
				"category": "Entity2"
			},
			{
				"category": "MedicationName",
				"list": {
					"sublists": [
						{
							"listKey": "research drugs",
							"synonyms": [
								{
									"language": "en",
									"values": [
										"rdrug a",
										"rdrug b"
									]
								}
							]

						}
					]
				}
				"prebuilts": "MedicationName"
			}
		],
		"documents": [
			{
				"location": "{DOCUMENT-NAME}",
				"language": "{LANGUAGE-CODE}",
				"dataset": "{DATASET}",
				"entities": [
					{
						"regionOffset": 0,
						"regionLength": 500,
						"labels": [
							{
								"category": "Entity1",
								"offset": 25,
								"length": 10
							},
							{
								"category": "Entity2",
								"offset": 120,
								"length": 8
							}
						]
					}
				]
			},
			{
				"location": "{DOCUMENT-NAME}",
				"language": "{LANGUAGE-CODE}",
				"dataset": "{DATASET}",
				"entities": [
					{
						"regionOffset": 0,
						"regionLength": 100,
						"labels": [
							{
								"category": "Entity2",
								"offset": 20,
								"length": 5
							}
						]
					}
				]
			}
		]
	}
}
Key プレースホルダー 値 例
multilingual true データセットで複数の言語のドキュメントを得ることを可能とするブール値であり、モデルがデプロイされる場合に、サポートする任意の言語 (必ずしもトレーニング ドキュメントに含まれているとは限りません) でモデルに関するクエリを実行することができます。 多言語サポートの詳細については、言語サポートをご覧ください。 true
projectName {PROJECT-NAME} プロジェクト名 myproject
storageInputContainerName {CONTAINER-NAME} コンテナー名 mycontainer
entities プロジェクト内にあるすべてのエンティティ型を含めた配列。 これらは、ドキュメントから抽出されるエンティティ型です。
category エンティティ型の名前。新しいエンティティ定義に対してユーザー定義したり、事前構築済みエンティティに対して事前定義したりすることができます。
compositionSetting {COMPOSITION-SETTING} エンティティ内の複数のコンポーネントを管理する方法を定義するルール。 combineComponents または separateComponents のいずれかを選択できます。 combineComponents
list 特定のエンティティのプロジェクトに含まれるすべてのサブリストを含む配列。 リストは、事前構築済みエンティティまたは学習済みコンポーネントを含む新しいエンティティに追加できます。
sublists [] サブリストを含む配列。 各サブリストは、キーとそれに関連する値です。 []
listKey One 予測でマップし直すシノニムの一覧の正規化された値。 One
synonyms [] すべてのシノニムを含む配列 シノニム
language {LANGUAGE-CODE} サブリスト内の同意語の言語コードを指定する文字列。 プロジェクトが多言語プロジェクトで、プロジェクト内のすべての言語の同意語のリストをサポートする場合は、各言語に同意語を明示的に追加する必要があります。 サポートされている言語コードの詳細については、言語サポートを参照してください。 en
values "EntityNumberone"、"FirstEntity" 抽出用に正確に一致し、リスト キーにマップされるコンマ区切り文字列の一覧。 "EntityNumberone"、"FirstEntity"
prebuilts MedicationName 事前構築済みエンティティに設定する事前構築済みコンポーネントの名前。 事前構築済みエンティティは既定でプロジェクトに自動的に読み込まれますが、ラベル ファイル内のリスト コンポーネントを使用して拡張できます。 MedicationName
documents プロジェクト内のすべてのドキュメントと、各ドキュメント内でラベル付けされたエンティティのリストを含む配列。 []
location {DOCUMENT-NAME} ストレージ コンテナー内のドキュメントの場所。 すべてのドキュメントはコンテナーのルートに含まれているので、これはドキュメント名にする必要があります。 doc1.txt
dataset {DATASET} トレーニングの前に分割する場合にこのファイルが移動するテスト セット。 このフィールドで使用できる値は Train および Test です。 Train
regionOffset テキストの先頭の包括的な文字位置。 0
regionLength UTF16 文字を基準とした場合の境界ボックスの長さ。 トレーニングではこの領域のデータのみが考慮されます。 500
category 指定されたテキストのスパンに関連付けられているエンティティ型。 Entity1
offset エンティティ テキストの開始位置。 25
length UTF16 文字を基準とした場合のエンティティの長さ。 20
language {LANGUAGE-CODE} プロジェクトで使用されるドキュメントの言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどのドキュメントの言語コードを選択します。 サポートされている言語コードの詳細については、言語サポートを参照してください。 en

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
	}
}
キー プレースホルダー 値 例
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

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

ヘッダー

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

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

応答本文

要求を送信すると、次の要求を受け取ります。 [status](状態) パラメーターが [succeeded](成功) に変更されるまで、このエンドポイントのポーリングを続けます。 要求の成功を示す 200 コードを取得します。

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

問題が発生しました

トレーニング済みのモデルを使用して予測を行う

モデルがデプロイされたら、予測 API を使ってテキストからエンティティの抽出を行うために、使用を開始することができます。 先ほどダウンロードしたサンプル データセットには、この手順で使用できるテスト ドキュメントがいくつかあります。

カスタム Text Analytics for health のタスクを送信する

この POST 要求を使用して、カスタム Text Analytics for health の抽出タスクを開始します。

{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": "Extracting entities",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomHealthcare",
      "taskName": "Custom TextAnalytics for Health Test",
      "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 Custom Text Analytics for Health Test タスク名 Custom Text Analytics for Health Test
kind CustomHealthcare 実行しようとしているプロジェクトまたはタスクの種類 CustomHealthcare
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 のバージョン。 ここで参照される値は、リリース済みの最新バージョン用です。 使用可能な他の 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-xxxx-xxxxx-xxxxx",
	"lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
	"status": "succeeded",
	"tasks": {
		"completed": 1,
		"failed": 0,
		"inProgress": 0,
		"total": 1,
		"items": [
			{
				"kind": "CustomHealthcareLROResults",
				"taskName": "Custom Text Analytics for Health Test",
				"lastUpdateDateTime": "2020-10-01T15:01:03Z",
				"status": "succeeded",
				"results": {
					"documents": [
						{
							"entities": [
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "learnedComponent"
										}
									],
									"offset": 0,
									"length": 11,
									"text": "first entity",
									"category": "Entity1",
									"confidenceScore": 0.98
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "listComponent"
										}
									],
									"offset": 0,
									"length": 11,
									"text": "first entity",
									"category": "Entity1.Dictionary",
									"confidenceScore": 1.0
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "learnedComponent"
										}
									],
									"offset": 16,
									"length": 9,
									"text": "entity two",
									"category": "Entity2",
									"confidenceScore": 1.0
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "prebuiltComponent"
										}
									],
									"offset": 37,
									"length": 9,
									"text": "ibuprofen",
									"category": "MedicationName",
									"confidenceScore": 1,
									"assertion": {
										"certainty": "negative"
									},
									"name": "ibuprofen",
									"links": [
										{
											"dataSource": "UMLS",
											"id": "C0020740"
										},
										{
											"dataSource": "AOD",
											"id": "0000019879"
										},
										{
											"dataSource": "ATC",
											"id": "M01AE01"
										},
										{
											"dataSource": "CCPSS",
											"id": "0046165"
										},
										{
											"dataSource": "CHV",
											"id": "0000006519"
										},
										{
											"dataSource": "CSP",
											"id": "2270-2077"
										},
										{
											"dataSource": "DRUGBANK",
											"id": "DB01050"
										},
										{
											"dataSource": "GS",
											"id": "1611"
										},
										{
											"dataSource": "LCH_NW",
											"id": "sh97005926"
										},
										{
											"dataSource": "LNC",
											"id": "LP16165-0"
										},
										{
											"dataSource": "MEDCIN",
											"id": "40458"
										},
										{
											"dataSource": "MMSL",
											"id": "d00015"
										},
										{
											"dataSource": "MSH",
											"id": "D007052"
										},
										{
											"dataSource": "MTHSPL",
											"id": "WK2XYI10QM"
										},
										{
											"dataSource": "NCI",
											"id": "C561"
										},
										{
											"dataSource": "NCI_CTRP",
											"id": "C561"
										},
										{
											"dataSource": "NCI_DCP",
											"id": "00803"
										},
										{
											"dataSource": "NCI_DTP",
											"id": "NSC0256857"
										},
										{
											"dataSource": "NCI_FDA",
											"id": "WK2XYI10QM"
										},
										{
											"dataSource": "NCI_NCI-GLOSS",
											"id": "CDR0000613511"
										},
										{
											"dataSource": "NDDF",
											"id": "002377"
										},
										{
											"dataSource": "PDQ",
											"id": "CDR0000040475"
										},
										{
											"dataSource": "RCD",
											"id": "x02MO"
										},
										{
											"dataSource": "RXNORM",
											"id": "5640"
										},
										{
											"dataSource": "SNM",
											"id": "E-7772"
										},
										{
											"dataSource": "SNMI",
											"id": "C-603C0"
										},
										{
											"dataSource": "SNOMEDCT_US",
											"id": "387207008"
										},
										{
											"dataSource": "USP",
											"id": "m39860"
										},
										{
											"dataSource": "USPMG",
											"id": "MTHU000060"
										},
										{
											"dataSource": "VANDF",
											"id": "4017840"
										}
									]
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "prebuiltComponent"
										}
									],
									"offset": 30,
									"length": 6,
									"text": "100 mg",
									"category": "Dosage",
									"confidenceScore": 0.98
								}
							],
							"relations": [
								{
									"confidenceScore": 1,
									"relationType": "DosageOfMedication",
									"entities": [
										{
											"ref": "#/documents/0/entities/1",
											"role": "Dosage"
										},
										{
											"ref": "#/documents/0/entities/0",
											"role": "Medication"
										}
									]
								}
							],
							"id": "1",
							"warnings": []
						}
					],
					"errors": [],
					"modelVersion": "2020-04-01"
				}
			}
		]
	}
}
Key 値の例 説明
entities [] 抽出されたすべてのエンティティを含む配列。
entityComponentKind prebuiltComponent 特定のエンティティを返したコンポーネントを示す変数。 指定できる値: prebuiltComponent、learnedComponent、listComponent
offset 0 文字にインデックスを付けることで抽出されたエンティティの開始点を示す数値
length 10 抽出されたエンティティの長さを文字数で示す数値。
text first entity 特定のエンティティに対して抽出されたテキスト。
category MedicationName 抽出されたテキストに対応するエンティティ型またはカテゴリの名前。
confidenceScore 0.9 抽出されたエンティティのモデルの確実性レベルを示す数値。0 から 1 までの範囲で、数値が大きいほど確実性が高いことを示します。
assertion certainty 抽出されたエンティティに関連付けられているアサーション。 アサーションは、事前構築済みの Text Analytics for health エンティティでのみサポートされます。
name Ibuprofen 抽出されたエンティティに関連付けられているエンティティ リンク設定の正規化された名前。 エンティティ リンク設定は、事前構築済みの Text Analytics for health エンティティでのみサポートされます。
リンク [] 抽出されたエンティティに関連付けられているエンティティ リンク設定からのすべての結果を含む配列。 エンティティ リンク設定は、事前構築済みの Text Analytics for health エンティティでのみサポートされます。
dataSource UMLS 抽出されたエンティティに関連付けられたエンティティ リンク設定によって得られる参照標準。 エンティティ リンク設定は、事前構築済みの Text Analytics for health エンティティでのみサポートされます。
id C0020740 抽出されたデータ ソースに属する抽出されたエンティティに関連付けられたエンティティ リンク設定によって得られる参照コード。 エンティティ リンク設定は、事前構築済みの Text Analytics for health エンティティでのみサポートされます。
リレーションシップ [] 抽出されたすべてのリレーションシップを含む配列。 リレーションシップの抽出は、事前構築済みの Text Analytics for health エンティティでのみサポートされます。
relationType DosageOfMedication 抽出されたリレーションシップのカテゴリ。 リレーションシップの抽出は、事前構築済みの Text Analytics for health エンティティでのみサポートされます。
entities "Dosage", "Medication" 抽出されたリレーションシップに関連付けられているエンティティ。 リレーションシップの抽出は、事前構築済みの Text Analytics for health エンティティでのみサポートされます。

問題が発生しました

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

プロジェクトが不要になったら、次の 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 ヘッダーが返されます。

問題が発生しました

次のステップ

エンティティ抽出モデルを作成した後は、次のことができます。

独自のカスタム Text Analytics for health プロジェクトの作成を開始するときは、ハウツー記事を使用して、データのラベル付け、トレーニング、使用の詳細について確認してください。