Quickstart: Conversational language understanding

บทความ
10/21/2024

Use this article to get started with Conversational Language understanding using Language Studio and the REST API. Follow these steps to try out an example.

Prerequisites

Azure subscription - Create one for free.

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 "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 conversational language understanding project

Once you have a Language resource selected, create a conversational language understanding project. A project is a work area for building your custom ML models based on your data. Your project can only be accessed by you and others who have access to the Language resource being used.

For this quickstart, you can download this sample project file and import it. This project can predict the intended commands from user input, such as: reading emails, deleting emails, and attaching a document to an email.

Under the Understand questions and conversational language section of Language Studio, select Conversational language understanding.
This will bring you to the Conversational language understanding projects page. Next to the Create new project button select Import.
In the window that appears, upload the JSON file you want to import. Make sure that your file follows the supported JSON format.

Once the upload is complete, you will land on Schema definition page. For this quickstart, the schema is already built, and utterances are already labeled with intents and entities.

Train your model

Typically, after you create a project, you should build a schema and label utterances. For this quickstart, we already imported a ready project with built schema and labeled utterances.

To train a model, you need to start a training job. The output of a successful training job is your trained model.

To start training your model from within the Language Studio:

Select Train model from the left side menu.
Select Start a training job from the top menu.
Select Train a new model and enter a new model name in the text box. Otherwise to replace an existing model with a model trained on the new data, select Overwrite an existing model and then select an existing model. Overwriting a trained model is irreversible, but it won't affect your deployed models until you deploy the new model.
Select training mode. You can choose Standard training for faster training, but it is only available for English. Or you can choose Advanced training which is supported for other languages and multilingual projects, but it involves longer training times. Learn more about training modes.
Select a data splitting method. You can choose Automatically splitting the testing set from training data where the system will split your utterances between the training and testing sets, according to the specified percentages. Or you can Use a manual split of training and testing data, this option is only enabled if you have added utterances to your testing set when you labeled your utterances.
Select the Train button.
Select the training job ID from the list. A panel will appear where you can check the training progress, job status, and other details for this job.
Note
- Only successfully completed training jobs will generate models.
- Training can take some time between a couple of minutes and couple of hours based on the count of utterances.
- You can only have one training job running at a time. You can't start other training jobs within the same project until the running job is completed.
- The machine learning used to train models is regularly updated. To train on a previous configuration version, select Select here to change from the Start a training job page and choose a previous version.

Deploy your model

Generally after training a model you would review its evaluation details. In this quickstart, you will just deploy your model, and make it available for you to try in Language studio, or you can call the prediction API.

To deploy your model from within the Language Studio:

Select Deploying a model from the left side menu.
Select Add deployment to start the Add deployment wizard.
Select Create a new deployment name to create a new deployment and assign a trained model from the dropdown below. You can otherwise select Overwrite an existing deployment name to effectively replace the model that's used by an existing deployment.

Note

Overwriting an existing deployment doesn't require changes to your Prediction API call but the results you get will be based on the newly assigned model.
Select a trained model from the Model dropdown.
Select Deploy to start the deployment job.
After deployment is successful, an expiration date will appear next to it. Deployment expiration is when your deployed model will be unavailable to be used for prediction, which typically happens twelve months after a training configuration expires.

Test deployed model

To test your deployed models from within the Language Studio:

Select Testing deployments from the left side menu.
For multilingual projects, from the Select text language dropdown, select the language of the utterance you're testing.
From the Deployment name dropdown, select the deployment name corresponding to the model that you want to test. You can only test models that are assigned to deployments.
In the text box, enter an utterance to test. For example, if you created an application for email-related utterances you could enter Delete this email.
Towards the top of the page, select Run the test.
After you run the test, you should see the response of the model in the result. You can view the results in entities cards view or view it in JSON format.

Clean up resources

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.

Prerequisites

Azure subscription - Create one for free.

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.

Get your resource keys and endpoint

Go to your resource overview page in the Azure portal.
From the menu on the left side, select Keys and Endpoint. You will use the endpoint and key for the API requests

Import a new CLU sample project

Once you have a Language resource created, create a conversational language understanding project. A project is a work area for building your custom ML models based on your data. Your project can only be accessed by you and others who have access to the Language resource being used.

For this quickstart, you can download this sample project and import it. This project can predict the intended commands from user input, such as: reading emails, deleting emails, and attaching a document to an email.

Trigger the import project job

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}

Get the import job status

When you send a successful project import request, the full request URL for checking the import job's status (including your endpoint, project name, and job ID) is contained in the response's operation-location header.

Use the following GET request to query the status of your import job. You can use the URL you received from the previous step, or replace the placeholder values with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?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`
`{JOB-ID}`	The ID for locating your import job status.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	The version of the API you are calling.	`2023-04-01`

Headers

Use the following header to authenticate your request.

Key	Description	Value
`Ocp-Apim-Subscription-Key`	The key to your resource. Used for authenticating your API requests.	`{YOUR-PRIMARY-RESOURCE-KEY}`

Response body

Once you send the request, you'll get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".

{
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx",
  "createdDateTime": "2022-04-18T15:17:20Z",
  "lastUpdatedDateTime": "2022-04-18T15:17:22Z",
  "expirationDateTime": "2022-04-25T15:17:20Z",
  "status": "succeeded"
}

Start training your model

Typically, after you create a project, you should build schema and tag utterances. For this quickstart, we already imported a ready project with built schema and tagged utterances.

Create a POST request using the following URL, headers, and JSON body to submit a training job.

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}/:train?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.

Request body

Use the following object in your request. The model will be named after the value you use for the modelLabel parameter once training is complete.

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

Key	Placeholder	Value	Example
`modelLabel`	`{MODEL-NAME}`	Your Model name.	`Model1`
`trainingConfigVersion`	`{CONFIG-VERSION}`	The training configuration model version. By default, the latest model version is used.	`2022-05-01`
`trainingMode`	`{TRAINING-MODE}`	The training mode to be used for training. Supported modes are Standard training, faster training, but only available for English and Advanced training supported for other languages and multilingual projects, but involves longer training times. Learn more about training modes.	`standard`
`kind`	`percentage`	Split methods. Possible Values are `percentage` or `manual`. See how to train a model for more information.	`percentage`
`trainingSplitPercentage`	`80`	Percentage of your tagged data to be included in the training set. Recommended value is `80`.	`80`
`testingSplitPercentage`	`20`	Percentage of your tagged data to be included in the testing set. Recommended value is `20`.	`20`

Note

The trainingSplitPercentage and testingSplitPercentage are only required if Kind is set to percentage and the sum of both percentages should be equal to 100.

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}/train/jobs/{JOB-ID}?api-version={API-VERSION}

You can use this URL to get the training job status.

Get the training job status

Training may take time to complete - sometimes between 10 and 30 minutes. You can use the following request to keep polling the status of the training job until it is successfully completed.

When you send a successful training request, the full request URL for checking the job's status (including your endpoint, project name, and job ID) is contained in the response's operation-location header.

Use the following GET request to get the status of your model's training progress. Replace the placeholder values below with your own values.

Request URL

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

Placeholder	Value	Example
`{YOUR-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`
`{JOB-ID}`	The ID for locating your model's training status.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{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. Keep polling this endpoint until the status parameter changes to "succeeded".

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

Key	Value	Example
`modelLabel`	The model name	`Model1`
`trainingConfigVersion`	The training configuration version. By default, the latest version is used.	`2022-05-01`
`trainingMode`	Your selected training mode.	`standard`
`startDateTime`	The time training started	`2022-04-14T10:23:04.2598544Z`
`status`	The status of the training job	`running`
`estimatedEndDateTime`	Estimated time for the training job to finish	`2022-04-14T10:29:38.2598544Z`
`jobId`	Your training job ID	`xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx`
`createdDateTime`	Training job creation date and time	`2022-04-14T10:22:42Z`
`lastUpdatedDateTime`	Training job last updated date and time	`2022-04-14T10:23:45Z`
`expirationDateTime`	Training job expiration date and time	`2022-04-14T10:22:42Z`

Deploy your model

Generally after training a model you would review its evaluation details. In this quickstart, you will just deploy your model, and call the prediction API to query the results.

Submit deployment job

Create a PUT request using the following URL, headers, and JSON body to start deploying a conversational language understanding model.

Request URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-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`
`{DEPLOYMENT-NAME}`	The name for your deployment. This value is case-sensitive.	`staging`
`{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.

Request Body

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

Key	Placeholder	Value	Example
trainedModelLabel	`{MODEL-NAME}`	The model name that will be assigned to your deployment. You can only assign successfully trained models. This value is case-sensitive.	`myModel`

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}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

You can use this URL to get the deployment job status.

Get deployment job status

When you send a successful deployment request, the full request URL for checking the job's status (including your endpoint, project name, and job ID) is contained in the response's operation-location header.

Use the following GET request to get the status of your deployment job. Replace the placeholder values with your own values.

Request URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?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`
`{DEPLOYMENT-NAME}`	The name for your deployment. This value is case-sensitive.	`staging`
`{JOB-ID}`	The ID for locating your model's training status.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{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'll get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".

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

Query model

After your model is deployed, you can start using it to make predictions through the prediction API.

Once deployment succeeds, you can begin querying your deployed model for predictions.

Create a POST request using the following URL, headers, and JSON body to start testing a conversational language understanding model.

Request URL

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

Placeholder	Value	Example
`{ENDPOINT}`	The endpoint for authenticating your API request.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{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.

Request body

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

Key	Placeholder	Value	Example
`participantId`	`{JOB-NAME}`		`"MyJobName`
`id`	`{JOB-NAME}`		`"MyJobName`
`text`	`{TEST-UTTERANCE}`	The utterance that you want to predict its intent and extract entities from.	`"Read Matt's email`
`projectName`	`{PROJECT-NAME}`	The name of your project. This value is case-sensitive.	`myProject`
`deploymentName`	`{DEPLOYMENT-NAME}`	The name of your deployment. This value is case-sensitive.	`staging`

Once you send the request, you will get the following response for the prediction

Response body

{
  "kind": "ConversationResult",
  "result": {
    "query": "Text1",
    "prediction": {
      "topIntent": "inten1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        },
        {
          "category": "intent3",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text1",
          "offset": 29,
          "length": 12,
          "confidenceScore": 1
        }
      ]
    }
  }
}

Key	Sample Value	Description
query	"Read Matt's email"	the text you submitted for query.
topIntent	"Read"	The predicted intent with highest confidence score.
intents	[]	A list of all the intents that were predicted for the query text each of them with a confidence score.
entities	[]	array containing list of extracted entities from the query text.

API response for a conversations project

In a conversations project, you'll get predictions for both your intents and entities that are present within your project.

The intents and entities include a confidence score between 0.0 to 1.0 associated with how confident the model is about predicting a certain element in your project.
The top scoring intent is contained within its own parameter.
Only predicted entities will show up in your response.
Entities indicate:
- The text of the entity that was extracted
- Its start location denoted by an offset value
- The length of the entity text denoted by a length value.

Clean up resources

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

Learn about entity components

แชร์ผ่าน

Quickstart: Conversational language understanding

Prerequisites

Sign in to Language Studio

Create a conversational language understanding project

Train your model

Deploy your model

Test deployed model

Clean up resources

Prerequisites

Create a new resource from the Azure portal

Get your resource keys and endpoint

Import a new CLU sample project

Trigger the import project job

Request URL

Headers

Body

Get the import job status

Headers

Response body

Start training your model

Request URL

Headers

Request body

Get the training job status

Request URL

Headers

Response Body

Deploy your model

Submit deployment job

Request URL

Headers

Request Body

Get deployment job status

Request URL

Headers

Response Body

Query model

Request URL

Headers

Request body

Response body

API response for a conversations project

Clean up resources

Request URL

Headers

Next steps

คำติชม

แหล่งทรัพยากรเพิ่มเติม