CLU プロジェクトを作成する方法

この記事では、これらの要件を設定し、プロジェクトを作成する方法について説明します。

前提条件

CLU の使用を開始する前に、必要なものがいくつかあります。

• Azure サブスクリプション - 無料で作成できます。
• Azure AI Language リソース

言語リソースを作成

CLU の使用を開始する前に、Azure AI Language リソースが必要になります。

Note

• 言語リソースを作成するには、リソース グループに所有者ロールが割り当てられている必要があります。

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

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

2. [新しいリソースを作成] を選択します

3. 表示されるウィンドウで、言語サービスを検索します

4. [作成] を選択します。

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

   インスタンスの詳細	必須値
   リージョン	言語リソースのサポートされているリージョンの 1 つ。
   Name	Language リソースに必須の名前
   価格レベル	言語リソースのサポートされている価格レベルの 1 つ。

Language Studio から新しい言語リソースを作成する

初めてログインするときは、既存の言語リソースを選択したり、新規に作成したりできるようにするウィンドウが Language Studio に表示されます。 また、右上隅にある設定アイコンをクリックし、 [リソース] を選び、 [新しいリソースを作成する] をクリックしてリソースを作成することもできます。

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

インスタンスの詳細	必須値
Azure サブスクリプション	お使いの Azure サブスクリプション
Azure リソース グループ	Azure リソース グループ
Azure リソース名	お使いの言語リソース名
場所	言語リソースのサポートされているリージョン。
価格レベル	言語リソースのサポートされている価格レベル。

重要

• Language リソースを作成する際は、必ず [マネージド ID] を有効にしてください。
• 責任ある AI 通知を読んで確認する

Language Studio にサインインする

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

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

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

   

会話プロジェクトを作成する

言語リソースを作成したら、会話言語理解プロジェクトを作成します。

Language Studio

1. Language Studio で、[Understand questions and conversational language] (質問と会話言語を理解する) というセクションを見つけ、[会話言語理解] を選択します。
   

2. これにより、[会話言語理解プロジェクト] ページが表示されます。 [新しいプロジェクトの作成] を選択します。

   

新しいプロジェクトを作成するには、次の詳細を指定する必要があります。

値	内容
名前	プロジェクトの名前。 一度作成した後は変更できません
説明	オプションのプロジェクトの説明。
発話の主要言語	プロジェクトの第一言語。 トレーニング データは、主にこの言語にする必要があります。
Enable multiple languages (複数の言語を有効にする)	複数の言語の同時サポートをプロジェクトで有効にするかどうか。

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

REST API

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

要求 URL

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

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

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

ヘッダー

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

Key	値
Ocp-Apim-Subscription-Key	リソースへのキー。 API 要求の認証に使われます。
Content-Type	'application/merge-patch+json'

Body

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

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "Conversation",
  "description": "Project description",
  "multilingual": true
}

Key	プレースホルダー	値	例
projectName	{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	EmailApp
language	{LANGUAGE-CODE}	プロジェクトで使用される発話の言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどの発話の言語コードを選択します。	en-us
multilingual	true	データセットで複数の言語のドキュメントを得ることを可能とするブール値であり、モデルがデプロイされる場合に、サポートする任意の言語 (必ずしもトレーニング ドキュメントに含まれているとは限りません) でモデルに関するクエリを実行することができます。 多言語サポートの詳細については、言語サポートに関する記事をご覧ください。	true

プロジェクトのインポート

Language Studio

いつでも、会話プロジェクトのページに移動し、プロジェクトを選択して、上部のメニューで [エクスポート] をクリックすることで、会話言語理解プロジェクトを JSON ファイルとしてエクスポートできます。

そのプロジェクトを新しいプロジェクトとしてインポートし直すことができます。 まったく同じ名前でプロジェクトをインポートすると、プロジェクトのデータが新しくインポートしたプロジェクトのデータに置き換えられます。

既存の LUIS アプリケーションがある場合は、LUIS アプリケーションの JSON を Conversational Language Understanding に直接 "インポート" することができます。それにより、現在使用できるすべての要素 (意図、ML エンティティ、発話) を使って会話プロジェクトが作成されます。 詳細については、LUIS の移行に関する記事を参照してください。

プロジェクトをインポートするには、[新しいプロジェクトの作成] の横にある矢印ボタンを選び、[インポート] を選んでから、LUIS または会話言語理解 JSON ファイルを選びます。

REST API

CLU JSON をサービスにインポートできます。

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

要求 URL

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

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

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

ヘッダー

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

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

本文

送信する JSON 本文は、次の例のようになります。 JSON オブジェクトの詳細については、リファレンス ドキュメントを参照してください。

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Conversation",
    "settings": {
      "confidenceThreshold": 0.7
    },
    "projectName": "{PROJECT-NAME}",
    "multilingual": true,
    "description": "Trying out CLU",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Conversation",
    "intents": [
      {
        "category": "intent1"
      },
      {
        "category": "intent2"
      }
    ],
    "entities": [
      {
        "category": "entity1"
      }
    ],
    "utterances": [
      {
        "text": "text1",
        "dataset": "{DATASET}",
        "intent": "intent1",
        "entities": [
          {
            "category": "entity1",
            "offset": 5,
            "length": 5
          }
        ]
      },
      {
        "text": "text2",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "intent": "intent2",
        "entities": []
      }
    ]
  }
}

キー	プレースホルダー	値	例
{API-VERSION}	呼び出している API のバージョン。	2023-04-01
projectName	{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	EmailAppDemo
language	{LANGUAGE-CODE}	プロジェクトで使用される発話の言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどの発話の言語コードを選択します。	en-us
multilingual	true	データセット内に複数の言語のドキュメントを含めるブール値。 モデルがデプロイされると、サポートされている任意の言語 (トレーニング ドキュメントに含まれていない言語も含む) でモデルにクエリを実行できます。	true
dataset	{DATASET}	テスト セットとトレーニング セットの間でデータを分割する方法については、モデルをトレーニングする方法を参照してください。 このフィールドで使用できる値は Train および Test です。	Train

要求が成功すると、API 応答には、インポート ジョブの状態を確認するために使用できる URL を含む operation-location ヘッダーが含まれます。 次のように書式設定されています。

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

プロジェクトをエクスポートする

Language Studio

いつでも、会話プロジェクトのページに移動し、プロジェクトを選択して、 [エクスポート] をクリックすることで、Conversational Language Understanding プロジェクトを JSON ファイルとしてエクスポートできます。

REST API

会話言語理解プロジェクトを JSON ファイルとしていつでもエクスポートできます。

プロジェクトをエクスポートするには、次の URL、ヘッダー、JSON 本文を使って POST 要求を作成します。

要求 URL

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

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&api-version={API-VERSION}

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

ヘッダー

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

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

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

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

この操作は非同期であるため、JOB-ID を使って要求が識別されます。 この URL を使用し、同じ認証方法を使用して、エクスポートされたプロジェクト JSON を取得します。

CLU プロジェクトの詳細を取得する

Language Studio

1. Language Studio でプロジェクト設定のページに移動します。

2. プロジェクトの詳細を確認できます。

3. このページでは、プロジェクトの説明を更新し、プロジェクト設定で多言語データセットを有効または無効にすることができます。

4. このページからリソースの主キーを取得することもできます。

   

REST API

プロジェクトの詳細を取得するには、次の URL とヘッダーを使用して GET 要求を送信します。 プレースホルダーの値は、実際の値に置き換えます。

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

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

ヘッダー

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

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

応答本文

要求を送信すると、次の応答を受け取ります。

{
  "createdDateTime": "2022-04-18T13:53:03Z",
  "lastModifiedDateTime": "2022-04-18T13:53:03Z",
  "lastTrainedDateTime": "2022-04-18T14:14:28Z",
  "lastDeployedDateTime": "2022-04-18T14:49:01Z",
  "projectKind": "Conversation",
  "projectName": "{PROJECT-NAME}",
  "multilingual": true,
  "description": "This is a sample conversation project.",
  "language": "{LANGUAGE-CODE}"
}

API 要求を送信すると、成功を示す 200 応答とプロジェクトの詳細を含む JSON 応答本文が返されます。

プロジェクトの削除

Language Studio

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

REST API

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

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

要求 URL

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

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

ヘッダー

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

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

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

次の手順

スキーマの作成