クイックスタート: カスタム固有表現認識

このガイドでは、Microsoft Foundry または REST API でカスタムの名前付きエンティティ認識 (NER) を使用する手順について説明します。 NER を使用すると、人、場所、組織、数値などの非構造化テキスト内のエンティティを検出して分類できます。カスタム NER を使用すると、モデルをトレーニングして、ビジネスに固有のエンティティを識別し、ニーズの進化に合わせて調整できます。

まず、カスタム NER モデルを構築し、次の主要エンティティを抽出するためのデータセットとして、サンプルローン契約が提供されます。

契約の日付
借り手の名前、住所、市区町村、都道府県
貸し手の名前、住所、市区町村、都道府県
ローンと利息の金額

注

Foundry Tools またはマルチサービスリソースに Azure 言語が既にある場合 (単独で使用する場合でも、Language Studio を使用する場合でも)、Microsoft Foundry ポータル内で引き続きこれらの既存の言語リソースを使用できます。詳細については、「 Foundry ポータルで Foundry Tools を使用する方法」を参照してください。

前提条件

Azure サブスクリプション。持っていない場合は、無料で作成できます。
必要なアクセス許可。アカウントとプロジェクトを確立しているユーザーが、サブスクリプションレベルで Azure AI アカウント所有者ロールとして割り当てられていることを確認します。または、サブスクリプションスコープで 共同作成者 ロールまたは Cognitive Services 共同作成者 ロールを持つことも、この要件を満たします。詳細については、「ロールベースのアクセス制御 (RBAC)」を参照してください。
ストレージアカウントを持つ言語リソース。 [ 追加機能の選択 ] ページで、必要なストレージアカウントをこのリソースにリンクするには、[ カスタムテキスト分類]、[カスタム名前付きエンティティ認識]、[カスタムセンチメント分析]、[正常性用のカスタムテキスト分析 ] ボックスの順に選択します。

注

言語リソースを作成するには、リソースグループに 所有者 ロールが割り当てられている必要があります。
既存のストレージアカウントを接続する場合は、所有者ロールが割り当てられている必要があります。
Azure Language リソースにリンクされた後は、ストレージアカウントを別のリソースグループまたはサブスクリプションに移動しないでください。

Foundry で作成されたプロジェクト。詳細については、「Foundry プロジェクトの作成」を参照してください。
ストレージコンテナーにアップロードされたカスタム NER データセット。カスタム名前付きエンティティ認識 (NER) データセットは、カスタム NER モデルのトレーニングに使用されるラベル付きテキストドキュメントのコレクションです。このクイックスタートのサンプルデータセットをダウンロードできます。ソース言語は英語です。

手順 1: 必要なロール、アクセス許可、設定を構成する

まず、リソースを構成します。

カスタムの名前付きエンティティ認識機能を有効にする

Azure portal でカスタムテキスト分類/カスタム名前付きエンティティ認識機能が有効になっていることを確認します。

Azure portal で言語リソースに移動します。
左側のメニューの [ リソース管理 ] セクションで、[ 機能] を選択します。
カスタムテキスト分類/カスタム名前付きエンティティ認識機能が有効になっていることを確認します。
ストレージアカウントが割り当てられていない場合は、ストレージアカウントを選択して接続します。
を選択してを適用します。

言語リソースに必要なロールを追加する

Azure portal の [言語リソース] ページで、左側のウィンドウで [アクセス制御 (IAM)] を選択します。
[追加]、[ロールの割り当てを追加] の順に選び、Language リソースに対する [Cognitive Services Language 所有者] または [Cognitive Services 共同作成者] ロールの割り当てを追加します。
[アクセスの割り当て先] 内で、[ユーザー、グループ、またはサービスプリンシパル] を選択します。
[メンバーの選択] を選びます。
ユーザー名を選択します。 [選択] フィールドでユーザー名を検索できます。すべてのロールに対してこの手順を繰り返します。
このリソースへのアクセスが必要なすべてのユーザーアカウントに対して、これらの手順を繰り返します。

ストレージアカウントに必要なロールを追加する

Azure portal でストレージアカウントページに移動します。
左側のウィンドウで [アクセス制御 (IAM)] を選択します。
[追加] を選択して [ロールの割り当ての追加] を行い、ストレージアカウントに対して [ストレージ BLOB データ所有者] ロールを選択します。
[ アクセスの割り当て] で、[ マネージド ID] を選択します。
[メンバーの選択] を選びます。
サブスクリプションを選択し、マネージド ID として言語を選択します。 [選択] フィールドで言語リソースを検索できます。

必要なユーザーロールを追加する

重要

この手順をスキップすると、カスタムプロジェクトに接続しようとすると 403 エラーが発生します。自分がストレージアカウントの所有者であっても、現在のユーザーがストレージアカウント BLOB データにアクセスするためにこのロールを持っていることが重要です。

Azure portal でストレージアカウントページに移動します。
左側のウィンドウで [アクセス制御 (IAM)] を選択します。
[追加] を選択して [ロールの割り当ての追加] を行い、ストレージアカウントに対して [ストレージ BLOB データ所有者] ロールを選択します。
[アクセスの割り当て先] 内で、[ユーザー、グループ、またはサービスプリンシパル] を選択します。
[メンバーの選択] を選びます。
ユーザーを選択します。 [選択] フィールドでユーザー名を検索できます。

重要

ファイアウォールまたは仮想ネットワークまたはプライベートエンドポイントがある場合は、Azure portal の [ネットワーク] タブで、信頼されたサービスの一覧で [Azure サービスにこのストレージアカウントへのアクセスを許可する] を選択してください。

Foundry で有効になっている Azure サービスを許可するスクリーンショット。

手順 2: データセットをストレージコンテナーにアップロードする

次に、コンテナーを追加し、データセットファイルをストレージコンテナーのルートディレクトリに直接アップロードします。これらのドキュメントは、モデルのトレーニングに使用されます。

言語リソースに関連付けられているストレージアカウントにコンテナーを追加します。詳細については、「コンテナーの作成」を参照してください。
GitHub からサンプルデータセットをダウンロードします。提供されるサンプルデータセットには、20 件のローン契約が含まれています。
- 各契約には貸し手と借り手の 2 人の当事者が含まれています。
- 両方の当事者、契約日、ローン金額、利率に関する関連情報を抽出します。
.zip ファイルを開き、ドキュメントが格納されているフォルダーを展開します。
Foundry に移動します。
まだサインインしていない場合は、Azure 資格情報を使用してサインインするように求められます。
サインインしたら、このクイックスタートのために既存の Foundry プロジェクトにアクセスします。
左側のナビゲーションメニューから [管理センター ] を選択します。
[管理センター] メニューの [ハブ] セクションから [接続済みリソース] を選択します。
次に、接続されたリソースとして設定されたワークスペース BLOB ストレージを選択します。
ワークスペースの BLOB ストレージで、Azure ポータルで 表示を選択します。
BLOB ストレージの AzurePortal ページで、上部のメニューから [アップロード ] を選択します。次に、前にダウンロードした .txt と .json ファイルを選択します。最後に、[ アップロード ] ボタンを選択して、ファイルをコンテナーに追加します。

必要な Azure リソースが Azure portal 内でプロビジョニングおよび構成されたので、Foundry でこれらのリソースを使用して、微調整されたカスタムの名前付きエンティティ認識 (NER) モデルを作成しましょう。

手順 3: 言語リソースを接続する

次に、Foundry が安全にアクセスできるように、言語リソースへの接続を作成します。この接続により、セキュリティで保護された ID 管理と認証、およびデータへの制御された分離アクセスが提供されます。

Foundry に戻ります。
このクイックスタートでは、既存の Foundry プロジェクトにアクセスします。
左側のナビゲーションメニューから [管理センター ] を選択します。
[管理センター] メニューの [ハブ] セクションから [接続済みリソース] を選択します。
メインウィンドウで、[ + 新しい接続 ] ボタンを選択します。
[外部資産への接続の追加] ウィンドウから [言語] を選択します。
[ 接続の追加] を選択し、[閉じる] を選択 します。

手順 4: カスタム NER モデルを微調整する

これで、カスタム NER 微調整モデルを作成する準備ができました。

管理センター メニューの [プロジェクト] セクションで、[プロジェクトに移動] を選択します。
[ 概要 ] メニューの [ 微調整] を選択します。
メインウィンドウから、[AI サービスのファインチューニング] タブを選択し、[+ ファインチューニング] ボタンをクリックします。
[ サービスの微調整の作成 ] ウィンドウで、[ カスタムの名前付きエンティティ認識 ] タブを選択し、[ 次へ] を選択します。
[ サービスの微調整タスクの作成 ] ウィンドウで、次のようにフィールドに入力します。
- 接続されたサービス。言語リソースの名前は、既定でこのフィールドに既に表示されている必要があります。そうでない場合は、ドロップダウンメニューから追加します。
- 名前。微調整タスクプロジェクトに名前を付けます。
- 言語. 英語が既定値として設定され、フィールドに既に表示されます。
- Description. 必要に応じて、説明を入力するか、このフィールドを空のままにすることができます。
- ブロブストアコンテナー。手順 2 でワークスペース BLOB ストレージコンテナーを選択し、[接続] ボタンを選択します。
最後に [作成] ボタンを選択します。作成操作が完了するまでに数分かかる場合があります。

手順 5: モデルをトレーニングする

Foundry の微調整ワークフローのスクリーンショット。

メニューの操作開始からデータの管理を選択します。 [ トレーニングとテスト用のデータの追加] ウィンドウに、以前に Azure Blob Storage コンテナーにアップロードしたサンプルデータが表示されます。
次に、スタートメニューからモデルのトレーニングを選択します。
[+ Train model] ボタンを選択します。 [ 新しいモデルのトレーニング ] ウィンドウが表示されたら、新しいモデルの名前を入力し、既定値をそのまま使用します。 [ 次へ ] ボタンを選択します。
[ 新しいモデルのトレーニング ] ウィンドウで、既定の [トレーニングデータからテストセットを自動的に分割 する] を保持します。推奨される割合はトレーニングデータの場合は 80%、テストデータの場合は 20% に設定されます。
モデルの構成を確認し、[ 作成 ] ボタンを選択します。
モデルのトレーニング後、[概要] メニューから [モデルの評価] を選択できます。 [モデルの評価] ウィンドウから モデル を選択し、必要に応じて改善を加えることができます。

手順 6: モデルをデプロイする

通常、モデルのトレーニング後は、その評価の詳細を確認します。このクイックスタートでは、モデルをデプロイして、Azure Language プレイグラウンドでテストできるようにするか、予測 API を呼び出すことでテストできるようにします。ただし、必要に応じて左側のメニューから [モデルの評価] を選択し、モデルの詳細なテレメトリを確認することもできます。 Foundry 内にモデルをデプロイするには、次の手順を実行します。

左側のメニューから [モデルのデプロイ] を選択します。
次に、[モデルのデプロイ] ウィンドウから [➕トレーニング済みモデルのデプロイ] を選択します。
[新しいデプロイの作成] ボタンが選択されていることを確認してください。
[トレーニング済みモデルのデプロイ] ウィンドウの各フィールドに入力します。
- デプロイ名。モデルに名前を付けます。
- モデルを割り当てます。ドロップダウンメニューからトレーニング済みのモデルを選択します。
- リージョン。ドロップダウンメニューからリージョンを選択します。
最後に [作成] ボタンを選択します。モデルのデプロイには数分かかる場合があります。
デプロイが正常に完了すると、[モデルのデプロイ] ページでモデルのデプロイ状況を確認できます。表示される有効期限は、デプロイ済みモデルが予測タスクに使用できなくなる日付を示しています。この日付は通常、トレーニング構成がデプロイされてから 18 か月後です。

$Foundry の [Deploy your model status]$モデルのデプロイ$ ステータスウィンドウのスクリーンショット。$

手順 7: Azure 言語のプレイグラウンドを試す

Language playground には、コードを記述せずに運用環境にデプロイする前に、微調整されたモデルをテストおよび構成するためのサンドボックスが用意されています。

上部のメニューバーで、[ プレイグラウンドで試す] を選択します。
Azure Language Playground ウィンドウで、[ カスタムの名前付きエンティティ認識 ] タイルを選択します。
[ 構成 ] セクションで、ドロップダウンメニューから プロジェクト名 と 配置名 を選択します。
エンティティを入力し、[ 実行] を選択します。
結果は [詳細 ]ウィンドウで評価できます。

以上です。お疲れさまでした。

このクイックスタートでは、微調整されたカスタム NER モデルを作成し、Foundry にデプロイし、Azure Language プレイグラウンドでモデルをテストしました。

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

プロジェクトが不要になった場合は、Foundry から削除できます。

Foundry ホームページに移動します。この手順を既に完了していてセッションがアクティブでない限り、サインインして認証プロセスを開始します。
Keep building with Foundryから削除したいプロジェクトを選択します。
[管理センター] を選択します。
[ プロジェクトの削除] を選択します。

ハブとそのすべてのプロジェクトを削除するには:

[ハブ] セクションの [概要] タブに移動します。
右側の [ハブの削除] を選択します。
リンクをクリックすると、Azure portal が開き、そこでハブが削除されます。

前提条件

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

Foundry Tools リソースと Azure ストレージアカウントで新しい Azure 言語を作成する

カスタムの名前付きエンティティ認識 (NER) を使用するには、プロジェクトを作成してモデルのトレーニングを開始するために必要な資格情報を提供する言語リソースを作成する必要があります。また、モデルの構築に使用されるデータセットをアップロードできる Azure ストレージアカウントも必要です。

重要

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

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

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

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

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

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

注

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

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

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

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

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

ストレージアカウントの値	推奨値
ストレージアカウント名	任意の名前
ストレージアカウントの種類	Standard 地域冗長ストレージ (LRS)

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

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

GitHub からサンプルデータセットをダウンロードします。
.zip ファイルを開き、ドキュメントが格納されているフォルダーを展開します。
Azure portal で、作成したストレージアカウントに移動して選択します。
ストレージアカウントで、左側のメニューの [データストレージ] の下にある [コンテナー] を選択します。表示された画面で、[+ コンテナー] を選択します。コンテナーに example-data という名前を付け、既定のパブリックアクセスレベルをそのまま使用します。
コンテナーが作成されたら、それを選択します。次に、[アップロード] ボタンを選択して、先ほどダウンロードした .txt および .json ファイルを選択します。

提供されているサンプルデータセットには、20 件のローン契約が含まれています。各契約には貸し手と借り手の 2 人の当事者が含まれています。提供されているサンプルファイルを使って、関連情報 (両当事者、契約日、ローン金額、利率) を抽出できます。

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

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

カスタム NER プロジェクトを作成する

リソースとストレージアカウントを構成したら、新しいカスタム NER プロジェクトを作成します。プロジェクトは、データに基づいてカスタム 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 のバージョン。ここで参照されている値は、リリースされた最新バージョンの値です。詳細については、「モデルのライフサイクル」を参照してください。	`2022-05-01`

ヘッダー

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

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

本文

要求では次の JSON を使います。プレースホルダーの値をあなた自身の値に置き換えてください。

{
    "projectFileVersion": "{API-VERSION}",
    "stringIndexType": "Utf16CodeUnit",
    "metadata": {
        "projectName": "{PROJECT-NAME}",
        "projectKind": "CustomEntityRecognition",
        "description": "Trying out custom NER",
        "language": "{LANGUAGE-CODE}",
        "multilingual": true,
        "storageInputContainerName": "{CONTAINER-NAME}",
        "settings": {}
    },
    "assets": {
    "projectKind": "CustomEntityRecognition",
        "entities": [
            {
                "category": "Entity1"
            },
            {
                "category": "Entity2"
            }
        ],
        "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
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

鍵	プレースホルダー	価値	例
`api-version`	`{API-VERSION}`	呼び出している API のバージョン。ここで使用するバージョンは、URL 内と同じ API バージョンである必要があります。その他の利用可能な API バージョンの詳細を確認する	`2022-03-01-preview`
`projectName`	`{PROJECT-NAME}`	プロジェクトの名前。この値は、大文字と小文字が区別されます。	`myProject`
`projectKind`	`CustomEntityRecognition`	プロジェクトの種類。	`CustomEntityRecognition`
`language`	`{LANGUAGE-CODE}`	プロジェクトで使用されるドキュメントの言語コードを指定する文字列。プロジェクトが多言語プロジェクトの場合は、ほとんどのドキュメントの言語コードを選択します。	`en-us`
`multilingual`	`true`	データセットに複数の言語のドキュメントを含め、モデルをデプロイするときに、サポートされている任意の言語 (トレーニングドキュメントに含まれているとは限りません) でモデルにクエリを実行できるブール値です。多言語サポートの詳細については、「言語サポート」を参照してください。	`true`
`storageInputContainerName`	{コンテナーの名前}	アップロードしたドキュメントを含む Azure ストレージコンテナーの名前。	`myContainer`
`entities`		プロジェクト内に存在し、ドキュメントから抽出したすべてのエンティティ型を含む配列。
`documents`		プロジェクト内のすべてのドキュメントと、各ドキュメント内でラベル付けされたエンティティのリストを含む配列。	[]
`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 のバージョン。参照される値は、リリースされた最新バージョン用です。詳細については、「モデルのライフサイクル」を参照してください。	`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 のバージョン。参照される値は、リリースされた最新バージョン用です。詳細については、「モデルのライフサイクル」を参照してください。	`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`
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 のバージョン。参照される値は、リリースされた最新バージョン用です。詳細については、「モデルのライフサイクル」を参照してください。	`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 のバージョン。参照される値は、リリースされた最新バージョン用です。詳細については、「モデルのライフサイクル」を参照してください。	`2022-05-01`

ヘッダー

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

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

要求本文

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

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

鍵	プレースホルダー	価値	例
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 のバージョン。参照される値は、リリースされた最新バージョン用です。詳細については、「モデルのライフサイクル」を参照してください。	`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 を使ってテキストからエンティティの抽出を行うために、使用を開始することができます。前にダウンロードしたサンプルデータセットでは、この手順で使用できるいくつかのテストドキュメントを見つけることができます。

カスタム NER タスクを送信する

この 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 へのアクセスを提供するキー。

本文

{
  "displayName": "Extracting entities",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomEntityRecognition",
      "taskName": "Entity Recognition",
      "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`	`CustomEntityRecognition`	タスク名	カスタムエンティティ認識
`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-xxxx-xxxxx-xxxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "EntityRecognitionLROResults",
        "taskName": "Recognize Entities",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "entities": [
                {
                  "category": "Event",
                  "confidenceScore": 0.61,
                  "length": 4,
                  "offset": 18,
                  "text": "trip"
                },
                {
                  "category": "Location",
                  "confidenceScore": 0.82,
                  "length": 7,
                  "offset": 26,
                  "subcategory": "GPE",
                  "text": "Seattle"
                },
                {
                  "category": "DateTime",
                  "confidenceScore": 0.8,
                  "length": 9,
                  "offset": 34,
                  "subcategory": "DateRange",
                  "text": "last week"
                }
              ],
              "id": "1",
              "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 のバージョン。参照される値は、リリースされた最新バージョン用です。詳細については、「モデルのライフサイクル」を参照してください。	`2022-05-01`

ヘッダー

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

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

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

エンティティ抽出モデルを作成したら、ランタイム API を使用してエンティティを抽出できます。

独自のカスタム NER プロジェクトを作成するときは、ハウツー記事を使用して、モデルのタグ付け、トレーニング、使用についてさらに詳しく学習してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-18

次の方法で共有

クイック スタート: カスタム固有表現認識

前提条件

手順 1: 必要なロール、アクセス許可、設定を構成する

カスタムの名前付きエンティティ認識機能を有効にする

言語リソースに必要なロールを追加する

ストレージ アカウントに必要なロールを追加する

必要なユーザー ロールを追加する

手順 2: データセットをストレージ コンテナーにアップロードする

手順 3: 言語リソースを接続する

手順 4: カスタム NER モデルを微調整する

手順 5: モデルをトレーニングする

手順 6: モデルをデプロイする

手順 7: Azure 言語のプレイグラウンドを試す

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

前提条件

Foundry Tools リソースと Azure ストレージ アカウントで新しい Azure 言語を作成する

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

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

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

カスタム NER プロジェクトを作成する

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

ヘッダー

本文

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

リクエストURL

ヘッダー

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

トレーニング ジョブを開始する

ヘッダー

要求本文

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

リクエストURL

ヘッダー

応答本文

モデルをデプロイする

デプロイ ジョブを開始する

ヘッダー

要求本文

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

ヘッダー

応答本文

カスタム エンティティを抽出する

カスタム NER タスクを送信する

ヘッダー

本文

[応答]

タスクの結果を取得する

ヘッダー

応答本文

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

ヘッダー

関連コンテンツ

フィードバック

その他のリソース

クイックスタート: カスタム固有表現認識

ストレージアカウントに必要なロールを追加する

必要なユーザーロールを追加する

手順 2: データセットをストレージコンテナーにアップロードする

Foundry Tools リソースと Azure ストレージアカウントで新しい Azure 言語を作成する

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

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

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

トレーニングジョブを開始する

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

デプロイジョブを開始する

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

カスタムエンティティを抽出する