会話言語理解モデルを構築するためのリソースを理解する

9 分

Language Understanding サービスを使って NLP ソリューションを開発するには、Azure で言語リソースを作成する必要があります。このリソースは、モデルの作成と、クライアントアプリケーションからの予測要求の処理の両方に使用されます。

ヒント

このモジュールのラボでは、会話言語理解用のモデルの構築について説明します。カスタムテキスト分類とカスタム固有表現認識の方に重点を置いたモジュールについては、自然言語処理のソリューションの開発に関するラーニングパスのカスタムソリューションモジュールを参照してください。

モデルを構築する

予測にモデルを必要とする機能の場合、モデルを使用して予測する前に、そのモデルを構築してトレーニングし、デプロイする必要があります。この構築とトレーニングにより、何を探すかを Azure AI Language サービスに教えます。

まず、Azure portal で Azure AI Language リソースを作成する必要があります。次に、以下の操作を実行します。

Azure AI サービスを検索します。
言語サービスを見つけて選択します。
[言語サービス] の下にある [作成] を選択します。
必要な詳細を入力して、地理的に最も近いリージョンを選び (最適なパフォーマンスを得るため)、一意の名前を付けます。

リソースを作成したら、キーとエンドポイントが必要です。これは、左側にあるリソースの概要ページの [キーとエンドポイント] にあります。

Language Studio を使用する

モデルの構築、トレーニング、デプロイをより視覚的に行うには、Language Studio を使用してこれらの各手順を実行できます。メインページで、会話言語理解プロジェクトを作成することを選択できます。プロジェクトが作成されたら、上記と同じプロセスを実行して、モデルを構築し、トレーニングしてデプロイします。

このモジュールのラボでは、Language Studio を使用してモデルを構築する手順について説明します。詳細については、Language Studio のクイックスタートのページを参照してください

REST API を使用する

モデルを構築する方法の 1 つは、REST API を使用することです。パターンは、プロジェクトを作成し、データをインポートし、モデルをトレーニングしてデプロイし、使用することです。

これらのタスクは非同期的に実行されます。各ステップの適切な URI に要求を送信し、そのジョブの状態を取得するための別の要求を送信する必要があります。

たとえば、会話言語理解プロジェクトのモデルをデプロイする場合、デプロイジョブを送信し、デプロイジョブの状態を確認します。

認証

Azure AI Language リソースを呼び出すたびに、次のヘッダーを指定して要求を認証します。

キー	値
`Ocp-Apim-Subscription-Key`	リソースへのキー

デプロイを要求する

POST 要求を次のエンドポイントに送信します。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}

プレースホルダー	値	例
`{ENDPOINT}`	Azure AI Language リソースのエンドポイント	`https://<your-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	プロジェクトの名前。この値は、大文字と小文字が区別されます	`myProject`
`{DEPLOYMENT-NAME}`	デプロイの名前。この値は、大文字と小文字が区別されます	`staging`
`{API-VERSION}`	呼び出している API のバージョン	`2022-05-01`

要求に次の body を含めます。

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

プレースホルダー	値
`{MODEL-NAME}`	デプロイに割り当てられるモデル名。この値は、大文字と小文字が区別されます。

要求を正常に送信すると、202 応答を受信します。応答ヘッダーは operation-location です。このヘッダーには、状態の要求先である URL が次のように書式設定されて含まれています。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

デプロイ状態を取得する

上記の応答ヘッダーの URL に GET 要求を送信します。値は、初期デプロイ要求に基づいて既に入力されています。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

プレースホルダー	値
`{ENDPOINT}`	API 要求を認証するためのエンドポイント
`{PROJECT-NAME}`	プロジェクトの名前 (大文字と小文字が区別されます)
`{DEPLOYMENT-NAME}`	デプロイの名前 (大文字と小文字が区別されます)
`{JOB-ID}`	モデルのトレーニング状態を見つけるための ID。上記で詳細に説明したデプロイ要求のヘッダー値に含まれています
`{API-VERSION}`	呼び出している API のバージョン

応答本文では、デプロイ状態の詳細が提供されます。デプロイが完了すると、status フィールドの値が succeeded になります。

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"String",
    "lastUpdatedDateTime":"String",
    "expirationDateTime":"String",
    "status":"running"
}

要求の例を示した完全なチュートリアルについては、会話言語理解のクイックスタートのページを参照してください。

お使いのモデルのクエリを実行する

予測のためにモデルに対してクエリを実行するには、C# または Python で SDK を使うか、REST API を使います。

SDK を使ってクエリを実行する

SDK を使ってモデルに対してクエリを実行するには、まずクライアントを作成する必要があります。クライアントを用意したら、それを使って適切なエンドポイントを呼び出します。

var languageClient = new TextAnalyticsClient(endpoint, credentials);
var response = languageClient.ExtractKeyPhrases(document);

language_client = TextAnalyticsClient(
            endpoint=endpoint, 
            credential=credentials)
response = language_client.extract_key_phrases(documents = documents)[0]

会話言語理解など、他の言語機能では、要求の構築と送信を別の方法で行う必要があります。

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = userText,
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};
Response response = await client.AnalyzeConversationAsync(RequestContent.Create(data));

result = client.analyze_conversation(
    task={
        "kind": "Conversation",
        "analysisInput": {
            "conversationItem": {
                "participantId": "1",
                "id": "1",
                "modality": "text",
                "language": "en",
                "text": query
            },
            "isLoggingEnabled": False
        },
        "parameters": {
            "projectName": cls_project,
            "deploymentName": deployment_slot,
            "verbose": True
        }
    }
)

REST API を使ってクエリを実行する

REST を使ってモデルに対してクエリを実行するには、適切な本文を指定して、適切な URL への POST 要求を作成します。言語検出や感情分析などの組み込み機能の場合、analyze-text エンドポイントに対してクエリを実行します。

ヒント

Ocp-Apim-Subscription-Key ヘッダー内の Azure AI Language リソースキーを使用して、各要求を認証する必要があることを忘れないでください

{ENDPOINT}/language/:analyze-text?api-version={API-VERSION}

プレースホルダー	値
`{ENDPOINT}`	API 要求を認証するためのエンドポイント
`{API-VERSION}`	呼び出している API のバージョン

その要求の本文で、kind パラメーターを指定する必要があります。これは、要求している言語理解の種類をサービスに指示します。

たとえば、言語を検出する場合、JSON 本文は次のようになります。

{
    "kind": "LanguageDetection",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "text": "This is a document written in English."
            }
        ]
    }
}

会話言語理解などのその他の言語機能では、要求を別のエンドポイントにルーティングする必要があります。たとえば、会話言語理解要求は、次のエンドポイントに送信されます。

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}

プレースホルダー	値
`{ENDPOINT}`	API 要求を認証するためのエンドポイント
`{API-VERSION}`	呼び出している API のバージョン

この要求には、次のような JSON 本文が含まれます。

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Sample text"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}

プレースホルダー	値
`{PROJECT-NAME}`	モデルを構築するプロジェクトの名前
`{DEPLOYMENT-NAME}`	デプロイの名前

サンプル応答

SDK からのクエリ応答は、オブジェクトで返されますが、これは特徴によって変わります (response.key_phrases や response.Value など)。この REST API は次のような JSON を返します。

{
    "kind": "KeyPhraseExtractionResults",
    "results": {
        "documents": [{
            "id": "1",
            "keyPhrases": ["modern medical office", "Dr. Smith", "great staff"],
            "warnings": []
        }],
        "errors": [],
        "modelVersion": "{VERSION}"
    }
}

会話言語理解などの他のモデルの場合、クエリに対する応答サンプルは次のようになります。

{
  "kind": "ConversationResult",
  "result": {
    "query": "String",
    "prediction": {
      "topIntent": "intent1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text",
          "offset": 7,
          "length": 4,
          "confidenceScore": 1
        }
      ]
    }
  }
}

Python 用と C# 用の両 SDK は、REST 応答とよく似た JSON を返します。

例やハウツーガイドなど、機能に関する完全なドキュメントについては、「Azure AI Language のドキュメント」ページを参照してください。