Quickstart: Conversational language understanding (preview)

Članak
04/06/2022
10 min. za čitanje

Use this article to get started with Custom text classification 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.

Note

Currently only resources with the standard (S) pricing tier can be used with the Conversational Language Understanding service.

Create a conversation project

Once you have a Language resource associated with your account, create a Conversational Language Understanding project. In this quickstart, you'll create a project that can identify commands for email, such as: reading emails by certain people, deleting emails, and attaching a document to an email.

In Language Studio, find the section named Understand conversational language and select Conversational language understanding.
This will bring you to the Conversations project page. Select Create new project. Select Conversation project, then select Next.

You then need to provide the following details:

Value	Description
Name	A name for your project.
Description	Optional project description.
Text primary language	The primary language of your project. Your training data should primarily be in this language. For this quickstart, choose English.
Enable multiple languages	Whether you would like to enable your project to support multiple languages at once. For this quickstart, enable this option.

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

Build schema

Select the Intents or Entities tab in the Build Schema page, and select Add. You will be prompted for a name before completing the creation of the intent or entity.
Create three intents with the following names:
- Read
- Delete
- Attach
Create three entities with the following names. Once you create the entity, go back to the Build Schema page without adding details to the entity:
- Sender
- FileName
- FileType

When you select the intent, you will see the tag utterances page, where you can add examples for intents and label them with entities.

Tag utterances

In the tag utterances page, let's add a few examples to the intents. Select the Read intent from the drop-down box that says Select Intent.

In the text box that says Write your example utterance and press enter, write the sentence "read the email from Carol" and press enter to add it as an example utterance.

Drag your cursor over the word "Carol" and select the Sender entity, to label "Carol" as the entity.

Add the rest of these utterances with the following intents and entities.

Utterance	Intent	Entities
Read John's email for me	Read	"John": Sender
What did the email from Matt say	Read	"Matt": Sender
Open Blake's email	Read	"Blake": Sender
Delete my last email from Martha	Delete	"Martha": Sender
Delete this	Delete	No entities
Remove this one	Delete	No entities
Move this to the deleted folder	Delete	No entities
Attach the excel file called reports q1	Attach	"excel": FileType, "reports q1" -> FileName
Attach the PowerPoint file	Attach	"PowerPoint": FileType
Add the PDF file with the name signed contract	Attach	"PDF": FileType, "signed contract": FileName

When you're done, select Save Changes to save the utterances and labels to the project. The icon next to the button will turn green when the changes are saved. Next, go to the Train Model page.

Train your model and view its details

Select train model on the left of the screen. Select Start a training job. To train your model, you need to provide a name for the model. Write a name like "v1" and press the enter key.

Note

If you did not tag utterances you will only be allowed to train using the Automatically split the testing set from all data option. See Add utterances to testing set for more information.

When the training job is complete, which may take some time, you should see the output model performance in the View model details page.

Deploy your model

From the Deploy model page on the left of the screen, select Add deployment.

In the window that appears, give your deployment a deployment name and then assign your trained model to this deployment name and then select Submit.

Test your model

Select Test model on the left of the screen, and select the model link. Write the utterance "trash this one", and select Run the test.

You now see the top intent as Delete with no entities.

You can test other utterances such as:

"attach my docx file",
"read the email by Jason",
"attach the ppt file named CLU demo".

You can also test out utterances in other languages such as the following phrases:

"Joindre le fichier PDF" (in French: "Attach the PDF file"),
"Lesen Sie die E-mail von Macy" (in German: "Read Macy's e-mail")

Prerequisites

Azure subscription - Create one for free.
The current version of cURL.
A Language resource. If you don't have one, you can create one using the Azure portal. If you create a new resource, click the link, follow the steps, and wait for it to deploy. Then click Go to 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 project

To get started, you can import a CLU JSON into the service. The quickstart will provide a sample JSON below that sets up a couple of intents and entities for an email application called "EmailProject".

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

Request URL

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

{YOUR-ENDPOINT}/language/analyze-conversations/projects/EmailProject/:import?api-version=2021-11-01-preview

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

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.
`format`	`clu`

Body

Use the following sample JSON as your body.

{
    "api-version": "2021-11-01-preview",
    "metadata": {
        "name": "EmailProject",
        "description": "A test application",
        "type": "Conversation",
        "multilingual": true,
        "language": "en-us",
        "settings": {
        }
    },
    "assets": {
        "intents": [
            {
                "name": "Read"
            },
            {
                "name": "Delete"
            },
            {
                "name": "Attach"
            }
        ],
        "entities": [
            {
                "name": "Sender"
            },
            {
                "name": "FileName"
            },
            {
                "name": "FileType"
            }
        ],
        "examples": [
            {
                "text": "Open Blake's email",
                "language": "en-us",
                "intent": "Read",
                "entities": [
                    {
                        "entityName": "Sender",
                        "offset": 5,
                        "length": 5
                    }
                ],
                "dataset": "Train"
            },
            {
                "text": "Add the PDF file with the name signed contract",
                "language": "en-us",
                "intent": "Attach",
                "entities": [
                    {
                        "entityName": "FileType",
                        "offset": 8,
                        "length": 3
                    },
                    {
                        "entityName": "FileName",
                        "offset": 31,
                        "length": 15
                    }
                ],
                "dataset": "Train"
            },
            {
                "text": "Attach the PowerPoint file",
                "language": "en-us",
                "intent": "Attach",
                "entities": [
                    {
                        "entityName": "FileType",
                        "offset": 11,
                        "length": 10
                    }
                ],
                "dataset": "Train"
            },
            {
                "text": "Attach the excel file called reports q1",
                "language": "en-us",
                "intent": "Attach",
                "entities": [
                    {
                        "entityName": "FileType",
                        "offset": 11,
                        "length": 5
                    },
                    {
                        "entityName": "FileName",
                        "offset": 29,
                        "length": 10
                    }
                ],
                "dataset": "Train"
            },
            {
                "text": "Move this to the deleted folder",
                "language": "en-us",
                "intent": "Delete",
                "entities": [],
                "dataset": "Train"
            },
            {
                "text": "Remove this one",
                "language": "en-us",
                "intent": "Delete",
                "entities": [],
                "dataset": "Train"
            },
            {
                "text": "Delete this",
                "language": "en-us",
                "intent": "Delete",
                "entities": [],
                "dataset": "Train"
            },
            {
                "text": "Delete my last email from Martha",
                "language": "en-us",
                "intent": "Delete",
                "entities": [
                    {
                        "entityName": "Sender",
                        "offset": 26,
                        "length": 6
                    }
                ],
                "dataset": "Train"
            },
            {
                "text": "Read John's email for me",
                "language": "en-us",
                "intent": "Read",
                "entities": [
                    {
                        "entityName": "Sender",
                        "offset": 5,
                        "length": 4
                    }
                ],
                "dataset": "Train"
            },
            {
                "text": "read the email from Carol",
                "language": "en-us",
                "intent": "Read",
                "entities": [
                    {
                        "entityName": "Sender",
                        "offset": 20,
                        "length": 5
                    }
                ],
                "dataset": "Train"
            }
        ]
    }
}

Start training your model

After your project has been imported, you can begin training a model. Create a POST request using the following URL, headers, and JSON body to start training.

Request URL

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

{YOUR-ENDPOINT}/language/analyze-conversations/projects/EmailProject/:train?api-version=2021-11-01-preview

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

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/json

Request body

Use the following object in your request. The model will be named MyModel once training is complete.

{
  "modelLabel":"MyModel",
  "RunVerification":True,
  "evaluationOptions":
    {
        "type":"percentage",
        "testingSplitPercentage":"30",
        "trainingSplitPercentage":"70"
    }
  
}

Key	Value	Example
`modelLabel`	Your Model name.	`MyModel`
`RunVerification`	Boolean value to run validation on the test set.	`True`
`evaluationOptions`	Specifies evaluation options.
`type`	Specifies datasplit type.	set or percentage
`testingSplitPercentage`	Required integer field if `type` is percentage. Specifies testing split.	`30`
`trainingSplitPercentage`	Required integer field if `type` is percentage. Specifies training split.	`70`

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

{YOUR-ENDPOINT}/language/analyze-conversations/projects/EmailProject/train/jobs/{JOB-ID}?api-version=2021-11-01-preview

JOB-ID is used to identify your request, since this operation is asynchronous. You will use this URL in the next step to get the training status.

Get Training Status

Use the following GET request to query the status of your model's training process. You can use the URL you received from the previous step, or replace the placeholder values below with your own values.

Request URL

{YOUR-ENDPOINT}/language/analyze-conversations/projects/EmailProject/train/jobs/{JOB-ID}?api-version=2021-11-01-preview

Placeholder	Value	Example
`{YOUR-ENDPOINT}`	The endpoint for authenticating your API request.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{JOB-ID}`	The ID for locating your model's training status. This is in the `location` header value you received in the previous step.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`

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":
    {
          "trainedModelLabel":"MyModel",
          "trainStatus":{"percentComplete":0,"elapsedTime":null},
          "evaluationStatus":{"percentComplete":0,"elapsedTime":null}
     },
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Deploy your model

Once training is completed, you can deploy your model for predictions.

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

Request URL

{YOUR-ENDPOINT}/language/analyze-conversations/projects/EmailProject/deployments/production?api-version=2021-11-01-preview

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

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/json

Request Body

{
  "trainedModelLabel":"MyModel",
  "deploymentName":"production"
}

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

{YOUR-ENDPOINT}/language/analyze-conversations/projects/EmailProject/deployments/production/jobs/{JOB-ID}?api-version=2021-11-01-preview

JOB-ID is used to identify your request, since this operation is asynchronous. You will use this URL in the next step to get the training status.

Get Deployment Status

Use the following GET request to query the status of your model's deployment process. You can use the URL you received from the previous step, or replace the placeholder values below with your own values.

Request URL

{YOUR-ENDPOINT}/language/analyze-conversations/projects/EmailProject/deployments/production/jobs/{JOB-ID}?api-version=2021-11-01-preview

Placeholder	Value	Example
`{YOUR-ENDPOINT}`	The endpoint for authenticating your API request.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{JOB-ID}`	The ID for locating your model's training status. This is in the `location` header value you received in the previous step.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`

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

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

Query Model

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

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

Request URL

{YOUR-ENDPOINT}/language/:analyze-conversations?projectName=EmailProject&deploymentName=production&api-version=2021-11-01-preview

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

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/json

Request Body

{
  "query":"attach a docx file"
}

Response Body

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

{
    "query":"attach a docx file",
    "prediction": {
        "topIntent":"Attach",
        "projectKind":"conversation",
        "intents":[{"category":"Attach","confidenceScore":0.9998592},{"category":"Read","confidenceScore":0.00010551753},{"category":"Delete","confidenceScore":3.5209276E-05}],
        "entities":[{"category":"FileType","text":"docx","offset":9,"length":4,"confidenceScore":1}]
     }
}

Next steps

Learn about entity components

Quickstart: Conversational language understanding (preview)

Je li ova stranica od pomoći?

Prerequisites

Sign in to Language Studio

Create a conversation project

Build schema

Tag utterances

Train your model and view its details

Deploy your model

Test your model

Prerequisites

Get your resource keys and endpoint

Import a project

Request URL

Headers

Body

Start training your model

Request URL

Headers

Request body

Get Training Status

Request URL

Headers

Response Body

Deploy your model

Request URL

Headers

Request Body

Get Deployment Status

Request URL

Headers

Response Body

Query Model

Request URL

Headers

Request Body

Response Body

Next steps

Povratne informacije