How to create a CLU project

Article
09/27/2024

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 trial.
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

Sign in to the Azure portal to create a new Azure AI Language resource.
Select Create a new resource
In the window that appears, search for Language service
Select Create

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

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

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 "China North 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
REST APIs

In Language Studio, find the section named Understand questions and conversational language and select Conversational language understanding.
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.

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.cn`
`{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`

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.

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.cn`
`{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
REST APIs

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.

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.cn`
`{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
REST APIs

Go to your project settings page in Language Studio.
You can see project details.
In this page you can update project description and enable/disable Multi-lingual dataset in project settings.
You can also retrieve your resource primary key from this page.

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.cn`
`{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
REST APIs

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.

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.cn`
`{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

How to create a CLU project

Prerequisites

Create a Language resource

Create a new resource from the Azure portal

Create a new Language resource from Language Studio

Sign in to Language Studio

Create a conversation project

Import project

Export project

Get CLU project details

Delete project

Next Steps

Additional resources