How to create a CLU project

Use this article to learn how to set up these requirements and create a project.

Prerequisites

Before you start using CLU, you will need several things:

• An Azure subscription - Create one for free.
• An Azure AI Language resource

Create a Language resource

Before you start using CLU, you will need an Azure AI Language resource.

Note

• You need to have an owner role assigned on the resource group to create a Language resource.

Create a new resource from the Azure portal

1. Sign in to the Azure portal to create a new Azure AI Language resource.

2. Select Create a new resource

3. In the window that appears, search for Language service

4. Select Create

5. Create a Language resource with following details.

   Instance detail	Required value
   Region	One of the supported regions for your Language resource.
   Name	Required name for your Language resource
   Pricing tier	One of the supported pricing tiers for your Language resource.

Create a new Language resource from Language Studio

If it's your first time logging in, you'll see a window in Language Studio that will let you choose an existing Language resource or create a new one. You can also create a resource by clicking the settings icon in the top-right corner, selecting Resources, then clicking Create a new resource.

Create a Language resource with following details.

Instance detail	Required value
Azure subscription	Your Azure subscription
Azure resource group	Your Azure resource group
Azure resource name	Your Language resource name
Location	A supported regions for your Language resource.
Pricing tier	A supported pricing tiers for your Language resource.

Important

• Make sure to enable Managed Identity when you create a Language resource.
• Read and confirm Responsible AI notice

Sign in to Language Studio

1. Go to the Language Studio and sign in with your Azure account.

2. In the Choose a language resource window that appears, find your Azure subscription, and choose your Language resource. If you don't have a resource, you can create a new one.

   Instance detail	Required value
   Azure subscription	Your Azure subscription.
   Azure resource group	Your Azure resource group name.
   Azure resource name	Your Azure resource name.
   Location	One of the supported regions for your Language resource. For example "West US 2".
   Pricing tier	One of the valid pricing tiers for your Language resource. You can use the Free (F0) tier to try the service.

   

Create a conversation project

Once you have a Language resource created, create a Conversational Language Understanding project.

Language Studio

1. In Language Studio, find the section named Understand questions and conversational language and select Conversational language understanding.
   

2. This will bring you to the Conversational language understanding projects page. Select Create new project.

   

To create a new project you need to provide the following details:

Value	Description
Name	A name for your project. Once it's created, it can't be changed
Description	Optional project description.
Utterances primary language	The primary language of your project. Your training data should primarily be in this language.
Enable multiple languages	Whether you would like to enable your project to support multiple languages at once.

Once you're done, select Next and review the details. Select create to complete the process. You should now see the Build Schema screen in your project.

REST APIs

Submit a PATCH request using the following URL, headers, and JSON body to create a new project.

Request URL

Use the following URL when creating your API request. Replace the placeholder values below with your own values.

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

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	myProject
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.
Content-Type	'application/merge-patch+json'

Body

Use the following sample JSON as your body.

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

Key	Placeholder	Value	Example
projectName	{PROJECT-NAME}	The name of your project. This value is case-sensitive.	EmailApp
language	{LANGUAGE-CODE}	A string specifying the language code for the utterances used in your project. If your project is a multilingual project, choose the language code of the majority of the utterances.	en-us
multilingual	true	A boolean value that enables you to have documents in multiple languages in your dataset and when your model is deployed you can query the model in any supported language (not necessarily included in your training documents). See Language support to learn more about multilingual support.	true

Import project

Language Studio

You can export a Conversational Language Understanding project as a JSON file at any time by going to the conversation projects page, selecting a project, and from the top menu, clicking on Export.

That project can be reimported as a new project. If you import a project with the exact same name, it replaces the project's data with the newly imported project's data.

If you have an existing LUIS application, you can import the LUIS application JSON to Conversational Language Understanding directly, and it will create a Conversation project with all the pieces that are currently available: Intents, ML entities, and utterances. See the LUIS migration article for more information.

To import a project, select the arrow button next to Create a new project and select Import, then select the LUIS or Conversational Language Understanding JSON file.

REST APIs

You can import a CLU JSON into the service

Submit a POST request using the following URL, headers, and JSON body to import your project.

Request URL

Use the following URL when creating your API request. Replace the placeholder values with your own values.

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

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive, and must match the project name in the JSON file you're importing.	EmailAppDemo
{API-VERSION}	The version of the API you're calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

Body

The JSON body you send is similar to the following example. See the reference documentation for more details about the JSON object.

{
  "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": []
      }
    ]
  }
}

Key	Placeholder	Value	Example
{API-VERSION}	The version of the API you're calling.	2023-04-01
projectName	{PROJECT-NAME}	The name of your project. This value is case-sensitive.	EmailAppDemo
language	{LANGUAGE-CODE}	A string specifying the language code for the utterances used in your project. If your project is a multilingual project, choose the language code of the majority of the utterances.	en-us
multilingual	true	A boolean value that enables you to have documents in multiple languages in your dataset. When your model is deployed, you can query the model in any supported language including languages that aren't included in your training documents.	true
dataset	{DATASET}	See how to train a model for information on splitting your data between a testing and training set. Possible values for this field are Train and Test.	Train

Upon a successful request, the API response will contain an operation-location header with a URL you can use to check the status of the import job. It is formatted like this:

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

Export project

Language Studio

You can export a Conversational Language Understanding project as a JSON file at any time by going to the conversation projects page, selecting a project, and pressing Export.

REST APIs

You can export a Conversational Language Understanding project as a JSON file at any time.

Create a POST request using the following URL, headers, and JSON body to export your project.

Request URL

Use the following URL when creating your API request. Replace the placeholder values below with your own values.

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

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	EmailApp
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

Once you send your API request, you will receive a 202 response indicating success. In the response headers, extract the operation-location value. It will be formatted like this:

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

JOB-ID is used to identify your request, since this operation is asynchronous. Use this URL to get the exported project JSON, using the same authentication method.

Get CLU project details

Language Studio

1. Go to your project settings page in Language Studio.

2. You can see project details.

3. In this page you can update project description and enable/disable Multi-lingual dataset in project settings.

4. You can also retrieve your resource primary key from this page.

   

REST APIs

To get your project details, submit a GET request using the following URL and headers. Replace the placeholder values with your own values.

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

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	myProject
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

Response Body

Once you send the request, you will get the following response.

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

Once you send your API request, you will receive a 200 response indicating success and JSON response body with your project details.

Delete project

Language Studio

When you don't need your project anymore, you can delete your project using Language Studio. Select Projects from the left navigation menu, select the project you want to delete, and then select Delete from the top menu.

REST APIs

When you don't need your project anymore, you can delete your project using the APIs.

Create a DELETE request using the following URL, headers, and JSON body to delete a conversational language understanding project.

Request URL

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

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	myProject
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

Once you send your API request, you will receive a 202 response indicating success, which means your project has been deleted.

Next Steps

Build schema