モデルをデプロイし、ランタイム API を使ってテキストを分類する

モデルのパフォーマンスに問題がなければ、デプロイして、テキストの分類に使うことができます。 モデルをデプロイすると、Prediction API で使えるようになります。

前提条件

• Azure ストレージ アカウントが構成されているカスタム テキスト分類プロジェクト。
• ストレージ アカウントにアップロードされたテキスト データ。
• ラベルが付けられたデータと正しくトレーニングされたモデル
• モデルの評価の詳細を調べて、モデルのパフォーマンスを確認した。

詳細については、「プロジェクト開発ライフサイクル」を参照してください。

モデルのデプロイ

モデルのパフォーマンスを確認し、環境で使用できると判断したら、クエリを実行できるようにデプロイに割り当てる必要があります。 モデルをデプロイに割り当てると、Prediction API を通じて使用できるようになります。 これまでに構築した最適なモデルを割り当ててシステムで使用するには、production という名前のデプロイを作成することをお勧めします。 staging という名前の別のデプロイを作成し、現在作業しているモデルをそれに割り当ててテストすることができます。 プロジェクトでは、最大 10 個のデプロイを使用できます。

Language Studio

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

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

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

   

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

   注意

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

   

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

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

REST 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"
}

デプロイのスワップ

あるデプロイに割り当てたモデルをテストした後で、別のデプロイに割り当てたい場合は、デプロイをスワップできます。 デプロイをスワップするときは、最初のデプロイに割り当てたモデルを取得し、2 番目のデプロイに割り当てます。 次に、2 番目のデプロイに割り当てたモデルを取得して、最初のデプロイに割り当てます。 staging に割り当てられているモデルを取得し、それを production に割り当てたい場合は、これを使用して、production と staging のデプロイをスワップすることができます。

Language Studio

Language Studio 内からデプロイをスワップするには

1. [モデルのデプロイ] ページで、入れ替える 2 つのデプロイを選び、上部のメニューから [デプロイのスワップ] を選択します。

2. 表示されたウィンドウで、スワップするデプロイの名前を選びます。

REST API

デプロイ スワップ ジョブを始めるには、次の URL、ヘッダー、JSON 本文を使って POST 要求を作ります。

要求 URL

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/:swap?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{API-VERSION}	呼び出す API のバージョン。 ここで参照される値は、リリース済みの最新のモデル バージョンです。	2022-05-01

ヘッダー

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

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

要求本文

{
  "firstDeploymentName": "{FIRST-DEPLOYMENT-NAME}",
  "secondDeploymentName": "{SECOND-DEPLOYMENT-NAME}"
}

キー	プレースホルダー	値	例
firstDeploymentName	{FIRST-DEPLOYMENT-NAME}	1 番目のデプロイの名前。 この値は、大文字と小文字が区別されます。	production
secondDeploymentName	{SECOND-DEPLOYMENT-NAME}	2 番目のデプロイの名前。 この値は、大文字と小文字が区別されます。	staging

API 要求を送信すると、成功を示す 202 応答が返されます。

展開の削除

Language Studio

Language Studio 内からデプロイを削除するには、[モデルのデプロイ] ページに移動します。 削除するデプロイを選び、上部のメニューから [デプロイの削除] を選択します。

REST API

デプロイを削除するには、次の URL、ヘッダー、JSON 本文を使って DELETE 要求を作成します。

要求 URL

{Endpoint}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{deploymentName}?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{DEPLOYMENT-NAME}	デプロイの名前。 この値は、大文字と小文字が区別されます。	prod
{API-VERSION}	呼び出している API のバージョン。 ここで参照される値は、リリース済みの最新バージョン用です。 その他の利用可能な API バージョンの詳細を確認する	2022-05-01

ヘッダー

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

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

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

デプロイ リソースを割り当てる

異なるリージョンに存在する異なる Language リソースを割り当てることで、プロジェクトを複数のリージョンにデプロイすることができます。

Language Studio

Language Studio で他のリージョンにデプロイ リソースを割り当てるには:

1. プロジェクトの作成に使用したリソースに Cognitive Service Language 所有者として自分自身を割り当てていることを確認します。
2. Language Studio の [モデルのデプロイ] ページに移動します。
3. [リージョン] タブを選択します。
4. [デプロイ リソースの追加] を選択します。
5. 別のリージョンで Language リソースを選びます。

これで、リソースを割り当てたリージョンにプロジェクトをデプロイする準備ができました。

REST API

デプロイ リソースをプログラムで割り当てるには、Microsoft Entra 認証が必要です。 Microsoft Entra ID は、複数リージョンのデプロイのためにプロジェクトに割り当てる目的のリソースへのアクセス権があることを確認するために使用されます。 REST API 呼び出しを行うときにプログラムで Microsoft Entra 認証を使用するには、Azure AI サービスのドキュメントで詳細を確認してください。

リソースを割り当てる

以下の URL、ヘッダー、JSON 本文を使って POST 要求を送信し、デプロイ リソースを割り当てます。

要求 URL

API 要求を作るときは、次の URL を使います。 次のプレースホルダーの値を実際の値に置き換えてください。

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/:assign?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{API-VERSION}	呼び出している API のバージョン。	2022-10-01-preview

ヘッダー

Microsoft Entra 認証を使用して、この API を認証します。

本文

次のサンプル JSON を本文として使います。

{
  "resourcesMetadata": [
    {
      "azureResourceId": "{AZURE-RESOURCE-ID}",
      "customDomain": "{CUSTOM-DOMAIN}",
      "region": "{REGION-CODE}"
    }
  ]
}

Key	プレースホルダー	値	例
azureResourceId	{AZURE-RESOURCE-ID}	割り当てる完全なリソース ID パス。 Azure portal で、リソースの [プロパティ] タブの [リソース ID] フィールドにあります。	/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource
customDomain	{CUSTOM-DOMAIN}	割り当てるリソースのカスタム サブドメイン。 Azure portal で、リソースの [キーとエンドポイント] タブの [エンドポイント] フィールドとして URL https://<your-custom-subdomain>.cognitiveservices.azure.com/ に含まれます	contosoresource
region	{REGION-CODE}	割り当てるリソースのリージョンを指定するリージョン コード。 Azure portal で、リソースの [キーとエンドポイント] タブの [場所/地域] フィールドにあります。	eastus

リソースの割り当て状態を取得する

デプロイ リソース割り当てジョブの状態を取得するには、次の GET 要求を使います。 次のプレースホルダーの値を実際の値に置き換えてください。

要求 URL

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/assign/jobs/{JOB-ID}?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{JOB-ID}	デプロイ割り当ての状態を取得するジョブ ID。 これは、デプロイ リソース割り当て要求の応答で API から受け取った operation-location ヘッダー値内にあります。	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION}	呼び出している API のバージョン。	2022-10-01-preview

ヘッダー

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

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

応答本文

要求を送信すると、次の応答を受け取ります。 status パラメーターが succeeded に変わるまで、このエンドポイントのポーリングを続けます。

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

デプロイ リソースの割り当てを解除する

プロジェクトからデプロイ リソースの割り当てを解除または削除すると、そのリソースのリージョンにデプロイされているすべてのデプロイも削除されます。

Language Studio

Language Studio を使用して他のリージョンのデプロイ リソースの割り当てを解除または削除するには:

1. [モデルのデプロイ] ページの [リージョン] タブに移動します。
2. 割り当てを解除するリソースを選択します。
3. [割り当ての削除] ボタンを選択します。
4. 表示されるウィンドウに、削除するリソースの名前を入力します。

REST API

リソースの割り当てを解除する

プロジェクトからデプロイ リソースの割り当てを解除または削除するには、以下の URL、ヘッダー、JSON 本文を使って POST 要求を送信します。

要求 URL

API 要求を作るときは、次の URL を使います。 次のプレースホルダーの値を実際の値に置き換えてください。

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/:unassign?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{API-VERSION}	呼び出している API のバージョン。	2022-10-01-preview

ヘッダー

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

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

Body

次のサンプル JSON を本文として使います。

{
  "assignedResourceIds": [
    "{AZURE-RESOURCE-ID}"
  ]
}

Key	プレースホルダー	値	例
assignedResourceIds	{AZURE-RESOURCE-ID}	割り当て解除する完全なリソース ID パス。 Azure portal で、リソースの [プロパティ] タブの [リソース ID] フィールドにあります。	/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource

リソースの割り当て解除状態を取得する

デプロイ リソースの割り当て解除ジョブの状態を取得するには、次の GET 要求を使います。 次のプレースホルダーの値を実際の値に置き換えてください。

要求 URL

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/unassign/jobs/{JOB-ID}?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{JOB-ID}	デプロイ割り当ての状態を取得するジョブ ID。 これは、デプロイ リソース割り当て解除要求の応答で API から受け取った operation-location ヘッダー値内にあります。	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION}	呼び出している API のバージョン。	2022-10-01-preview

ヘッダー

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

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

応答本文

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

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

次の手順

• 予測 API を使用してモデルに対するクエリを実行する