クイックスタート: オーケストレーション ワークフロー

前提条件

• Azure サブスクリプション - 無料アカウントを作成します。
• 会話言語理解プロジェクト。

Language Studio にサインインする

1. Language Studio にアクセスし、Azure アカウントでサインインします。

2. 表示される [Choose a language resource](言語リソースの選択) ウィンドウで、自分の Azure サブスクリプションを見つけ、言語リソースを選びます。 リソースがない場合は、新しいものを作成できます。

   インスタンスの詳細	必須値
   Azure サブスクリプション	Azure サブスクリプション。
   Azure リソース グループ	Azure リソース グループ。
   Azure リソース名	Azure リソース名。
   場所	Azure リソースの有効な場所。 たとえば "米国西部 2" にします。
   価格レベル	Azure リソースでサポートされている価格レベル。 Free (F0) レベルを利用して、サービスを試用できます。

   

オーケストレーション ワークフロー プロジェクトを作成する

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

このクイック スタートのため、会話言語理解のクイックスタートを完了して、後で使用する会話言語理解プロジェクトを作成できるようにします。

1. Language Studio で [質問と会話言語を理解する] というラベルのセクションを見つけて、[オーケストレーション ワークフロー] を選択します。

   

2. これにより、オーケストレーション ワークフロー プロジェクト ページに移動します。 [新しいプロジェクトの作成] を選択します。 プロジェクトを作成するには、次の詳細を指定する必要があります。

完了したら、[次へ] を選択し、詳細を確認します。 [プロジェクトの作成] を選択してプロセスを完了します。 プロジェクトの [Build Schema](スキーマのビルド) 画面が表示されます。

スキーマの作成

会話言語理解のクイックスタートを完了し、オーケストレーション プロジェクトを作成したら、次の手順として意図を追加します。

以前に作成した会話言語理解プロジェクトに接続するには、次の手順に従います。

• オーケストレーション プロジェクトの [ビルド スキーマ] ページで、[追加] を選択して意図を追加します。
• 表示されるウィンドウで、意図に名前を付けます。
• [はい、これを既存のプロジェクトに接続します] を選択します。
• 接続されたサービス ドロップダウンから、[会話言語理解] を選択します。
• プロジェクト名サービス ドロップダウンから、会話言語理解プロジェクトを選択します。
• [意図の追加] を選択して意図を作成します。

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

モデルをトレーニングするには、トレーニング ジョブを開始する必要があります。 成功したトレーニング ジョブの出力は、トレーニング済みのモデルです。

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

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

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

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

   発話にタグ付けする際に [your project to manually split your data] (プロジェクトでデータを手動で分割する) を有効にした場合、2 つのデータ分割オプションが表示されます。

   • トレーニング用データからテスト用セットを自動分割: タグ付けされた発話が、選択した割合に従ってランダムにトレーニング用セットとテスト用セットに分割されます。 既定の分割割合は、トレーニング用が 80%、テスト用が 20% です。 これらの値を変更するには、変更するセットを選択し、新しい値を入力します。

   注意

   [トレーニング用データからテスト用セットを自動分割] オプションを選択した場合、トレーニング用セット内の発話のみが指定された割合に従って分割されます。

   • トレーニング用データとテスト用データの手動分割を使用: プロジェクトのタグ付け手順中に、各発話をトレーニング用セットまたはテスト用セットに割り当てます。

   注意

   [トレーニング用データとテスト用データの手動分割を使用] オプションは、タグ データ ページでテスト用セットに発話を追加する場合にのみ有効になります。 それ以外の場合は無効になります。

   

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

モデルをデプロイする

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

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

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

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

   

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

   注意

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

   

4. 1 つ以上の LUIS アプリケーションまたは会話言語理解プロジェクトを接続する場合は、デプロイ名を指定する必要があります。

   • カスタム質問と回答、またはリンクされていない意図には、構成は必要ありません。

   • LUIS プロジェクトは、オーケストレーションのデプロイ中に構成されたスロットに発行する必要があります。また、カスタムの質問と回答 KB も運用スロットに発行する必要があります。

5. [デプロイ] を選択して、デプロイ ジョブを送信します

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

モデルをテストする

モデルがデプロイされたら、モデルの使用を開始し、予測 API を使って予測することができます。 このクイックスタートでは、Language Studio を使用して、発話を送信し、予測を取得して、結果を視覚化します。

Language Studio からモデルをテストするには、次の手順を行います

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

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

3. [デプロイ名] ドロップダウンから、デプロイ名を選択します。

4. テキスト ボックスに、テストする発話を入力します。

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

6. テストを実行すると、結果にモデルの応答が表示されます。 結果はエンティティ カード ビューで表示することも、JSON 形式で表示することもできます。

   

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

プロジェクトが不要な場合は、Language Studio を使ってプロジェクトを削除できます。 左側のナビゲーション メニューで [プロジェクト] を選択し、削除するプロジェクトを選択して、上部のメニューで [削除] を選択します。

前提条件

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

Azure portal から Language リソースを作成する

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

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

2. [リソースの作成を続行する] を選択します

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

   インスタンスの詳細	必須値
   リージョン	サポートされているリージョンのいずれか。
   名前	Language リソースの名前。
   Pricing tier	サポートされている価格レベルのいずれか。

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

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

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

   

オーケストレーション ワークフロー プロジェクトを作成する

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

このクイックスタートでは、CLU クイックスタートを完了して、オーケストレーション ワークフローで使用する CLU プロジェクトを作成します。

新しいプロジェクトを作成するには、次の URL、ヘッダー、JSON 本文を使って PATCH 要求を送信します。

要求 URL

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

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

ヘッダー

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

Body

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

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "Orchestration",
  "description": "Project description"
 }

スキーマの作成

CLU クイックスタートを完了し、オーケストレーション プロジェクトを作成したら、次の手順として意図を追加します。

次の URL、ヘッダー、JSON 本文を使用して POST 要求を送信し、プロジェクトをインポートします。

要求 URL

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

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

ヘッダー

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

Body

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

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Orchestration",
    "settings": {
      "confidenceThreshold": 0
    },
    "projectName": "{PROJECT-NAME}",
    "description": "Project description",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Orchestration",
    "intents": [
      {
        "category": "string",
        "orchestration": {
          "kind": "luis",
          "luisOrchestration": {
            "appId": "00000000-0000-0000-0000-000000000000",
            "appVersion": "string",
            "slotName": "string"
          },
          "cluOrchestration": {
            "projectName": "string",
            "deploymentName": "string"
          },
          "qnaOrchestration": {
            "projectName": "string"
          }
        }
      }
    ],
    "utterances": [
      {
        "text": "Trying orchestration",
        "language": "{LANGUAGE-CODE}",
        "intent": "string"
      }
    ]
  }
}

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

モデルをトレーニングするには、トレーニング ジョブを開始する必要があります。 成功したトレーニング ジョブの出力は、トレーニング済みのモデルです。

次の URL、ヘッダー、JSON 本文を使用して POST 要求を作成し、トレーニング ジョブを送信します。

要求 URL

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

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

ヘッダー

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

要求本文

要求では次のオブジェクトを使います。 トレーニングが完了すると、モデルに MyModel という名前が付けられます。

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "standard",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}

API 要求を送信すると、成功を示す 202 応答が返されます。 応答ヘッダーで、operation-location の値を抽出します。 それは次のように書式設定されています。

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

この URL を使用してトレーニング ジョブの状態を取得できます。

トレーニング状態の取得

トレーニングには 10 分から 30 分かかる場合があります。 次の要求を使用して、トレーニング ジョブが正常に完了するまで、その状態をポーリングし続けることができます。

モデルのトレーニングの進行状況を表す状態を取得するには、次の GET 要求を使用します。 次のプレースホルダーの値を実際の値に置き換えてください。

要求 URL

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

ヘッダー

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

応答本文

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

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-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": "xxxxxx-xxxxx-xxxxxx-xxxxxx",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

モデルをデプロイする

通常はモデルをトレーニングした後、その評価の詳細を確認します。 このクイック スタートでは、モデルをデプロイし、予測 API を呼び出して結果を照会します。

デプロイ ジョブを送信する

次の URL、ヘッダー、JSON 本文を使用して PUT 要求を作成し、オーケストレーション ワークフロー モデルのデプロイを開始します。

要求 URL

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

ヘッダー

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

要求本文

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

API 要求を送信すると、成功を示す 202 応答が返されます。 応答ヘッダーで、operation-location の値を抽出します。 それは次のように書式設定されています。

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

この URL を使用してデプロイ ジョブの状態を取得できます。

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

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

要求 URL

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

ヘッダー

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

応答本文

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

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

モデルにクエリを実行する

モデルがデプロイされたら、モデルの使用を開始し、予測 API を使用して予測を行うことができます。

デプロイが成功すると、予測用にデプロイしたモデルに対してクエリを開始できます。

次の URL、ヘッダー、JSON 本文を使って POST 要求を作成し、オーケストレーション ワークフロー モデルのテストを始めます。

要求 URL

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

ヘッダー

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

要求本文

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "text": "Text1",
      "participantId": "1",
      "id": "1"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "directTarget": "qnaProject",
    "targetProjectParameters": {
      "qnaProject": {
        "targetProjectKind": "QuestionAnswering",
        "callingOptions": {
          "context": {
            "previousUserQuery": "Meet Surface Pro 4",
            "previousQnaId": 4
          },
          "top": 1,
          "question": "App Service overview"
        }
      }
    }
  }
}

応答本文

要求を送信すると、予測に対して次の応答を受け取ります。

{
  "kind": "ConversationResult",
  "result": {
    "query": "App Service overview",
    "prediction": {
      "projectKind": "Orchestration",
      "topIntent": "qnaTargetApp",
      "intents": {
        "qnaTargetApp": {
          "targetProjectKind": "QuestionAnswering",
          "confidenceScore": 1,
          "result": {
            "answers": [
              {
                "questions": [
                  "App Service overview"
                ],
                "answer": "The compute resources you use are determined by the *App Service plan* that you run your apps on.",
                "confidenceScore": 0.7384000000000001,
                "id": 1,
                "source": "https://video2.skills-academy.com/azure/app-service/overview",
                "metadata": {},
                "dialog": {
                  "isContextOnly": false,
                  "prompts": []
                }
              }
            ]
          }
        }
      }
    }
  }
}

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

プロジェクトが不要になったら、API を使用してプロジェクトを削除できます。

会話言語理解プロジェクトを削除するには、次の URL、ヘッダー、JSON 本文を使って DELETE 要求を作成します。

要求 URL

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

ヘッダー

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

API 要求を送信すると、成功を示す 202 応答を受け取ります。これは、プロジェクトが削除されたことを意味します。