この記事では、カスタム テキスト分類を開始するための要件を設定し、プロジェクトを作成する方法について説明します。
前提条件
カスタム テキスト分類の使用を開始する前に、次のものが必要です。
- Azure サブスクリプション。無料で作成できます。
言語リソースを作成する
カスタム テキスト分類の使用を開始する前に、Foundry Tools リソースの Azure 言語が必要です。 言語リソースを作成し、Azure portal でストレージ アカウントをそれに接続することをお勧めします。 Azure portal でリソースを作成すると、必要なすべてのアクセス許可が事前に構成された Azure ストレージ アカウントを同時に作成できます。 また、既存のリソースを使用し、カスタム テキスト分類を使用するように構成する方法については、記事の詳細を参照してください。
また、テキストを分類するためにモデルをトレーニングするために使用される .txt ドキュメントをアップロードする Azure ストレージ アカウントも必要です。
Note
- 言語リソースを作成するには、リソース グループに所有者ロールが割り当てられている必要があります。
- 既存のストレージ アカウントを接続する場合は、 所有者 ロールが割り当てられている必要があります。
言語リソースを作成し、ストレージ アカウントを接続する
Note
Azure Language リソースにリンクされた後は、ストレージ アカウントを別のリソース グループまたはサブスクリプションに移動しないでください。
Azure portal から新しいリソースを作成する
Azure portal に移動して、Foundry Tools リソースで新しい Azure 言語を作成します。
ウィンドウが表示されるので、カスタム機能から [カスタム テキスト分類とカスタム固有表現認識] を選びます。 画面の下部にある [リソースの作成を続行する] を選択します。
次の詳細を使用して言語リソースを作成します。
名前 必須値 サブスクリプション Azure サブスクリプション。 リソースグループ リソースを含むリソース グループ。 既存のものを使用するか、新しく作成することができます。 リージョン サポートされているリージョンのいずれか。 たとえば、"米国西部 2" です。 名前 リソースの名前。 価格階層 サポートされている価格レベルのいずれか。 Free (F0) レベルを利用してサービスを試用できます。 "ログイン アカウントが選択したストレージ アカウントのリソース グループの所有者ではない" ことを通知するメッセージが表示された場合は、言語リソースを作成する前に、アカウントでそのリソース グループに所有者ロールを割り当てる必要があります。 Azure サブスクリプションの所有者に問い合わせてください。
Azure サブスクリプションの所有者を確認するには、リソース グループを検索し、リンクに従ってそれに関連付けられているサブスクリプションに移動します。 その後、以下を実行します。
- [アクセス制御 (IAM)] タブを選びます
- [ロールの割り当て] を選びます
- Role:Owner でフィルター処理します。
[カスタム テキスト分類とカスタム固有表現認識] セクションで、既存のストレージ アカウントを選択するか、[新しいストレージ アカウント] を選択します。 これらの値は使用を開始するためのものであり、運用環境で使用したいストレージ アカウントの値である必要はないことに注意してください。 プロジェクト ビルド中の待機時間をなくすには、言語リソースと同じリージョンのストレージ アカウントに接続します。
ストレージ アカウントの値 推奨値 ストレージ アカウント名 任意の名前 ストレージ アカウントの種類 標準 LRS [責任ある AI の通知] がオンになっていることを確認します。 ページ下部にある [確認と作成] を選択します。
Note
- ストレージ アカウントを言語リソースに接続するプロセスは元に戻すことができません。後で切断することはできません。
- 言語リソースは 1 つのストレージ アカウントにのみ接続できます。
既存の言語リソースの使用
| 要件 | 説明 |
|---|---|
| リージョン | サポートされているリージョンのいずれかで既存のリソースがプロビジョニングされていることを確認します。 リソースがない場合は、サポートされているリージョンに新しいリソースを作成する必要があります。 |
| 価格階層 | リソースの価格レベル。 |
| マネージド ID | リソースのマネージド ID 設定が有効になっていることを確認します。 これが行われていない場合、次のセクションを参照してください。 |
カスタム テキスト分類を使うには、お持ちでない場合は Azure ストレージ アカウントを作成する必要があります。
リソースの ID 管理を有効にする
Azure portal を使用して有効にするには、言語リソースに ID 管理が必要です。
- 言語リソースに移動します
- 左側のメニューの [リソース管理] セクションで、[ID] を選択します
- [システム割り当て済み] タブで、必ず [状態] を [オン] に設定します
カスタム テキスト分類機能を有効にする
Azure portal からカスタムテキスト分類/カスタム固有表現認識機能を有効にしてください。
- Azure portal で Language リソースに移動します
- 左側のメニューの [リソース管理] セクションで、[機能] を選択します
- カスタム テキスト分類またはカスタム固有表現認識機能を有効にします
- ストレージ アカウントに接続します
- [適用] を選択します
重要
- 言語リソースに、接続しているストレージ アカウントにストレージ BLOB データ共同作成者ロールが割り当てられていることを確認します。
Azure 言語リソースとストレージ アカウントのロールを設定する
言語リソースとストレージ アカウントに必要なロールを設定するには、次の手順に従います。
Foundry Tools リソースでの Azure 言語のロール
Azure portal でストレージ アカウントまたは言語リソースに移動します。
左側のウィンドウで [アクセス制御 (IAM)] を選択します。
[追加] を選択してロールの割り当ての追加を行い、アカウントに適切なロールを選択します。
所有者または共同作成者のロールが言語リソースに割り当てられている必要があります。
[アクセスの割り当て先] 内で、[ユーザー、グループ、またはサービス プリンシパル] を選択します
[メンバーの選択] を選択します
ユーザー名を選択します。 [選択] フィールドでユーザー名を検索できます。 すべてのロールに対してこれを繰り返します。
このリソースへのアクセスが必要なすべてのユーザー アカウントに対して、これらの手順を繰り返します。
ストレージ アカウントのロール
- Azure portal でストレージ アカウントのページに移動します。
- 左側のウィンドウで [アクセス制御 (IAM)] を選択します。
- [追加] を選択して [ロールの割り当ての追加] を行い、ストレージ アカウントに対して [ストレージ BLOB データ所有者] ロールを選択します。
- [アクセス権の割り当て先] 内で [マネージド ID] を選択します。
- [メンバーの選択] を選択します
- サブスクリプションを選択し、マネージド ID として [言語] を選択します。 [選択] フィールドでユーザー名を検索できます。
重要
仮想ネットワークまたはプライベート エンドポイントがある場合は、Azure portal で [信頼されたサービスの一覧にある Azure サービスがこのストレージ アカウントにアクセスすることを許可します] を選択してください。
自身のストレージ アカウントに対して CORS を有効にする
クロスオリジン リソース共有 (CORS) を有効にする場合は、必ず (GET、PUT、DELETE) メソッドを許可してください。
許可されたオリジン フィールドを https://language.cognitive.azure.com に設定します。 許可されたヘッダー値に * を追加してすべてのヘッダーを許可し、最大有効期間を 500 に設定します。
カスタム テキスト分類プロジェクトを作成する (REST API)
リソースとストレージ コンテナーが構成されたら、新しいカスタム テキスト分類プロジェクトを作成します。 プロジェクトは、データに基づいてカスタム AI モデルを構築するための作業領域です。 プロジェクトには、使用されている Azure リソースにアクセスできるユーザーと他のユーザーのみがアクセスできます。 データにラベルを付けた場合は、 データをインポート して開始できます。
カスタム テキスト分類モデルを作り始めるには、プロジェクトを作成する必要があります。 プロジェクトを作成すると、データのラベル付け、モデルのトレーニング、評価、改善、デプロイを行うことができます。
Note
プロジェクト名は、すべての操作で大文字と小文字が区別されます。
プロジェクトを作成するには、次の URL、ヘッダー、JSON 本文を使って PATCH 要求を作成します。
要求 URL
次の URL を使用してプロジェクトを作成します。 プレースホルダーの値は、実際の値に置き換えます。
{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 要求の認証に使われます。 |
Body
要求では次の JSON を使います。 プレースホルダーの値は、実際の値に置き換えます。
{
"projectName": "{PROJECT-NAME}",
"language": "{LANGUAGE-CODE}",
"projectKind": "customMultiLabelClassification",
"description": "Project description",
"multilingual": "True",
"storageInputContainerName": "{CONTAINER-NAME}"
}
| キー | プレースホルダー | 値 | 例 |
|---|---|---|---|
| projectName | {PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
| 言語 | {LANGUAGE-CODE} |
プロジェクトで使用されるドキュメントの言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどのドキュメントの言語コードを選択します。 サポートされている言語コードの詳細については、言語サポートをご覧ください。 | en-us |
| projectKind | customMultiLabelClassification |
プロジェクトの種類。 | customMultiLabelClassification |
| multilingual | true |
データセットで複数の言語のドキュメントを得ることを可能とするブール値であり、モデルがデプロイされる場合に、サポートする任意の言語 (必ずしもトレーニング ドキュメントに含まれているとは限りません) でモデルに関するクエリを実行することができます。 多言語サポートの詳細については、言語サポートをご覧ください。 | true |
| storageInputContainerName | {CONTAINER-NAME} |
アップロードしたドキュメントの Azure ストレージ コンテナーの名前。 | myContainer |
この要求は 201 応答を返します。つまり、プロジェクトが作成されます。
この要求は、次の場合にエラーを返します。
- 選んだリソースに、ストレージ アカウントに対する適切なアクセス許可がありません。
カスタム テキスト分類プロジェクトをインポートする (REST 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 |
ヘッダー
要求を認証するには、次のヘッダーを使います。
| キー | 値 |
|---|---|
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 |
| projectKind | customMultiLabelClassification |
プロジェクトの種類。 | customMultiLabelClassification |
| 言語 | {LANGUAGE-CODE} |
プロジェクトで使用されるドキュメントの言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどのドキュメントの言語コードを選択します。 多言語サポートの詳細については、言語サポートをご覧ください。 | en-us |
| multilingual | true |
データセットで複数の言語のドキュメントを得ることを可能とするブール値であり、モデルがデプロイされる場合に、サポートする任意の言語 (必ずしもトレーニング ドキュメントに含まれているとは限りません) でモデルに関するクエリを実行することができます。 多言語サポートの詳細については、言語サポートをご覧ください。 | true |
| storageInputContainerName | {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値は文字列であり、ブール値ではありません。
プロジェクトの詳細を取得する (REST API)
カスタム テキスト分類プロジェクトの詳細を取得するには、次の URL とヘッダーを使用して GET 要求を送信します。 プレースホルダーの値は、実際の値に置き換えます。
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}?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 要求の認証に使われます。 |
応答本文
要求を送信すると、次の応答が返されます。
{
"createdDateTime": "2022-04-23T13:39:09.384Z",
"lastModifiedDateTime": "2022-04-23T13:39:09.384Z",
"lastTrainedDateTime": "2022-04-23T13:39:09.384Z",
"lastDeployedDateTime": "2022-04-23T13:39:09.384Z",
"projectKind": "customSingleLabelClassification",
"storageInputContainerName": "{CONTAINER-NAME}",
"projectName": "{PROJECT-NAME}",
"multilingual": true,
"description": "Project description",
"language": "{LANGUAGE-CODE}"
}
| 値 | プレースホルダ | 説明 | 例 |
|---|---|---|---|
projectKind |
customSingleLabelClassification |
プロジェクトの種類。 | この値は、customSingleLabelClassification または customMultiLabelClassification です。 |
storageInputContainerName |
{CONTAINER-NAME} |
アップロードしたドキュメントの Azure ストレージ コンテナーの名前。 | myContainer |
projectName |
{PROJECT-NAME} |
プロジェクトの名前。 この値は、大文字と小文字が区別されます。 | myProject |
multilingual |
データセット内に複数の言語のドキュメントを含めるブール値。 モデルがデプロイされると、サポートされている任意の言語 (トレーニング ドキュメントに含まれているとは限りません) でモデルにクエリを実行できます。 多言語サポートの詳細については、「言語サポート」を参照してください。 | true |
|
language |
{LANGUAGE-CODE} |
プロジェクトで使用されるドキュメントの言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどのドキュメントの言語コードを選択します。 サポートされている言語コードの詳細については、言語サポートをご覧ください。 | en-us |
API 要求を送信すると、プロジェクトの詳細と共に成功と JSON 応答本文を示す 200 応答を受け取ります。
プロジェクトの削除 (REST API)
プロジェクトが不要になったら、次の 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 ヘッダーが返されます。
次のステップ
データのラベル付けに使用する プロジェクト スキーマ を計画する必要があります。
プロジェクトが作成されたら、 データのラベル付けを開始できます。 ラベル付けは、テキストの解釈方法をテキスト分類モデルに通知し、トレーニングと評価に使用されます。