Skip to content

Commit 6d26472

Browse files
rjagiewichrjagiewich
authored
Merge pull request #46701 from v-geberr/0716-go-quickstart
go quickstarts
2 parents 9b86596 + 8da5513 commit 6d26472

File tree

3 files changed

+241
-0
lines changed

3 files changed

+241
-0
lines changed

‎articles/cognitive-services/LUIS/luis-get-started-go-add-utterance.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Quickstart learning how to add utterances to a LUIS app using Go | Microsoft Docs
3+
description: In this quickstart, you learn to call a LUIS app using Go.
4+
services: cognitive-services
5+
titleSuffix: Microsoft Cognitive Services
6+
author: v-geberr
7+
manager: kaiqb
8+
ms.service: cognitive-services
9+
ms.component: language-understanding
10+
ms.topic: quickstart
11+
ms.date: 07/17/2018
12+
ms.author: v-geberr
13+
#Customer intent: As a developer new to LUIS, I want to add an utterance to the LUIS app model using Go.
14+
---
15+
16+
# Quickstart: Add utterances to a LUIS app using Go
17+
In this quickstart, write a program to add an utterance to an intent in an app, train the app, and get training status using the Authoring APIs with Go.
18+
19+
<!-- green checkmark -->
20+
<!--
21+
> [!div class="checklist"]
22+
> * Create Visual Studio console project
23+
> * Add method to call LUIS API to add utterance and train app
24+
> * Add JSON file with example utterances for BookFlight intent
25+
> * Run console and see training status for utterances
26+
-->
27+
28+
For more information, see the technical documentation for the [add example utterance to intent](https://westus.dev.cognitive.microsoft.com/docs/services/5890b47c39e2bb17b84a55ff/operations/5890b47c39e2bb052c5b9c08), [train](https://westus.dev.cognitive.microsoft.com/docs/services/5890b47c39e2bb17b84a55ff/operations/5890b47c39e2bb052c5b9c45), and [training status](https://westus.dev.cognitive.microsoft.com/docs/services/5890b47c39e2bb17b84a55ff/operations/5890b47c39e2bb052c5b9c46) APIs.
29+
30+
For this article, you need a free [LUIS](luis-reference-regions.md#luis-website) account in order to author your LUIS application.
31+
32+
## Prerequisites
33+
34+
* [Go](https://golang.org/) installed.
35+
* Your LUIS **[authoring key](luis-concept-keys.md#authoring-key)**. You can find this key under Account Settings in the [LUIS](luis-reference-regions.md) website.
36+
* Import [TravelAgent - Sample 1
37+
](https://github.com/Microsoft/LUIS-Samples/blob/master/documentation-samples/Examples-BookFlight/travel-agent-sample-01.json) app from Github repository. Get the new app ID from **Settings** page in LUIS website.
38+
* The **version ID** within the application that receives the utterances. The default ID is `0.1`.
39+
* Create a new file named `add-utterances.go` project in VSCode.
40+
41+
> [!NOTE]
42+
> The complete Go solution including an example `utterances.json` file are available from the [**LUIS-Samples** Github repository](https://github.com/Microsoft/LUIS-Samples/blob/master/documentation-samples/authoring-api-samples/go).
43+
44+
## Add utterances and train using the Authoring API with Go
45+
You can add example utterances to an existing intent and train the app with Go. Create a new file named `add-utterances.go`. Add the following code:
46+
47+
[!code-go[Go code that adds utterance and trains app](~/samples-luis/documentation-samples/authoring-api-samples/go/add-utterances.go?range=35-136)]
48+
49+
## Specify utterances to add
50+
Create and edit the file `utterances.json` to specify the **array of utterances** you want to add to the LUIS app. The intent and entities **must** already be in the LUIS app.
51+
52+
> [!NOTE]
53+
> The LUIS `TravelAgent - Sample 1` application with the intents and entities used in the `utterances.json` file must exist prior to running the code in `add-utterances.go`. The code in this article does not create the intents and entities. It only adds the utterances for existing intents and entities.
54+
55+
The `text` field contains the text of the utterance. The `intentName` field must correspond to the name of an intent in the LUIS app. The `entityLabels` field is required. If you don't want to label any entities, provide an empty list as shown in the following example:
56+
57+
If the entityLabels list is not empty, the `startCharIndex` and `endCharIndex` need to mark the entity referred to in the `entityName` field. Both indexes are zero-based counts meaning 6 in the top example refers to the "S" of Seattle and not the space before the capital S.
58+
59+
```JSON
60+
[
61+
{
62+
"text": "go lang 1",
63+
"intentName": "None",
64+
"entityLabels": []
65+
}
66+
,
67+
{
68+
"text": "go lang 2",
69+
"intentName": "None",
70+
"entityLabels": []
71+
}
72+
]
73+
```
74+
75+
## Add an utterance from the command line, train, and get status
76+
Run the Go code from a command prompt to add an utterance, train the app, and get the training status.
77+
78+
1. From a command prompt in the directory where you created the Go file, enter `go build add-utterances.go` to compile the Go file. The command prompt does not return any information for a successful build.
79+
80+
3. Run the Go application from the command line by entering the following in the command prompt:
81+
82+
```CMD
83+
add-utterances -appID <your-app-id> -authoringKey <add-your-authoring-key> -version <your-version-id> -region westus -utteranceFile utterances.json
84+
85+
```
86+
87+
Replace `<add-your-authoring-key>` with the value of your authoring key (also known as the starter key). Replace `<your-app-id>` with the value of your app ID. Replace `<your-version-id>` with the value of your version. Default version is `0.1`.
88+
89+
This command-prompt displays the results:
90+
91+
```CMD
92+
add example utterances requested
93+
[
94+
{
95+
"text": "go lang 1",
96+
"intentName": "None",
97+
"entityLabels": []
98+
}
99+
,
100+
{
101+
"text": "go lang 2",
102+
"intentName": "None",
103+
"entityLabels": []
104+
}
105+
]
106+
201
107+
[{"value":{"ExampleId":77783998,"UtteranceText":"go lang 1"},"hasError":false},{"value":{"ExampleId":77783999,"UtteranceText":"go lang 2"},"hasError":false}]
108+
training selected
109+
202
110+
{"statusId":9,"status":"Queued"}
111+
training status selected
112+
200
113+
[{"modelId":"c52d6509-9261-459e-90bc-b3c872ee4a4b","details":{"statusId":3,"status":"InProgress","exampleCount":24}},{"modelId":"5119cbe8-97a1-4c1f-85e6-6449f3a38d77","details":{"statusId":3,"status":"InProgress","exampleCount":24}},{"modelId":"01e6b6bc-9872-47f9-8a52-da510cddfafe","details":{"statusId":3,"status":"InProgress","exampleCount":24}},{"modelId":"33b409b2-32b0-4b0c-9e91-31c6cfaf93fb","details":{"statusId":3,"status":"InProgress","exampleCount":24}},{"modelId":"1fb210be-2a19-496d-bb72-e0c2dd35cbc1","details":{"statusId":3,"status":"InProgress","exampleCount":24}},{"modelId":"3d098beb-a1aa-423f-a0ae-ce08ced216d6","details":{"statusId":3,"status":"InProgress","exampleCount":24}},{"modelId":"cce854f8-8f8f-4ed9-a7df-44dfea562f62","details":{"statusId":3,"status":"InProgress","exampleCount":24}},{"modelId":"4d97bf0d-5213-4502-9712-2d6e77c96045","details":{"statusId":3,"status":"InProgress","exampleCount":24}}]
114+
```
115+
116+
This response includes the HTTP status code for each of the three HTTP calls as well as any JSON response returned in the body of the response.
117+
118+
You can verify the example utterances were added by refreshing the LUIS website for the **None** intent.
119+
120+
## Clean up resources
121+
When you are done with the quickstart, remove the files created in this quickstart and the LUIS application.
122+
123+
## Next steps
124+
> [!div class="nextstepaction"]
125+
> [Build an app with a custom domain](luis-quickstart-intents-only.md)

‎articles/cognitive-services/LUIS/luis-get-started-go-get-intent.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: Quickstart learning how to call a Language Understanding (LUIS) app using Go | Microsoft Docs
3+
description: In this quickstart, you learn to call a LUIS app using Go.
4+
services: cognitive-services
5+
author: v-geberr
6+
manager: kaiqb
7+
ms.service: cognitive-services
8+
ms.component: language-understanding
9+
ms.topic: quickstart
10+
ms.date: 06/27/2018
11+
ms.author: v-geberr
12+
#Customer intent: As a developer new to LUIS, I want to query the endpoint of a published model using Go.
13+
---
14+
15+
# Quickstart: Call a LUIS endpoint using Go
16+
In this quickstart, pass utterances to a LUIS endpoint and get intent and entities back.
17+
18+
<!-- green checkmark -->
19+
<!--
20+
> [!div class="checklist"]
21+
> * Create LUIS subscription and copy key value for later use
22+
> * View LUIS endpoint results from browser to public sample IoT app
23+
> * Create Visual Studio Go console app to make HTTPS call to LUIS endpoint
24+
-->
25+
26+
<!-- link to free account -->
27+
For this article, you need a free [LUIS](luis-reference-regions.md#luis-website) account in order to author your LUIS application.
28+
29+
## Prerequisites
30+
31+
* [Go](https://golang.org/) installed.
32+
* Your existing LUIS [**application ID**](./luis-get-started-create-app.md). The application ID is shown in the application dashboard.
33+
34+
> [!NOTE]
35+
> The complete Go solution is available from the [**LUIS-Samples** Github repository](https://github.com/Microsoft/LUIS-Samples/blob/master/documentation-samples/endpoint-api-samples/go).
36+
37+
## Create LUIS endpoint key
38+
39+
1. You first need to create a [Language Understanding API account](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account) in the Azure portal. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
40+
41+
2. Log in to the Azure portal at https://portal.azure.com.
42+
43+
3. Follow the steps in [Creating Endpoint Keys using Azure](./luis-how-to-azure-subscription.md) to get a key.
44+
45+
4. Go back to the [LUIS](luis-reference-regions.md) website. Log in using your Azure account.
46+
47+
[![](media/luis-get-started-cs-get-intent/app-list.png "Screenshot of app list")](media/luis-get-started-cs-get-intent/app-list.png)
48+
49+
## Understand what LUIS returns
50+
51+
To understand what a LUIS app returns, you can paste the URL of a sample LUIS app into a browser window. The sample app is an [IoT app](https://azure.microsoft.com/services/cognitive-services/language-understanding-intelligent-service/) that detects whether the user wants to turn on or turn off lights.
52+
53+
1. The endpoint of the sample app is in this format: `https://westus.api.cognitive.microsoft.com/luis/v2.0/apps/df67dcdb-c37d-46af-88e1-8b97951ca1c2?subscription-key=<YOUR_API_KEY>&verbose=false&q=turn%20on%20the%20bedroom%20light` Copy the URL and substitute your endpoint key for the value of the `subscription-key` field.
54+
55+
2. Paste the URL into a browser window and press Enter. The browser displays a JSON result that indicates that LUIS detects the `HomeAutomation.TurnOn` intent and the `HomeAutomation.Room` entity with the value `bedroom`.
56+
57+
![JSON result detects the intent TurnOn](./media/luis-get-started-cs-get-intent/turn-on-bedroom.png)
58+
59+
3. Change the value of the `q=` parameter in the URL to `turn off the living room light`, and press Enter. The result now indicates that the LUIS detected the `HomeAutomation.TurnOff` intent and the `HomeAutomation.Room` entity with value `living room`.
60+
61+
![JSON result detects the intent TurnOff](./media/luis-get-started-cs-get-intent/turn-off-living-room.png)
62+
63+
## Consume a LUIS result using the Endpoint API with Go
64+
65+
You can use Go to access the same results you saw in the browser window in the previous step.
66+
67+
1. Create a new file named `endpoint.go`. Add the following code:
68+
69+
[!code-go[Go code that calls a LUIS endpoint](~/samples-luis/documentation-samples/endpoint-api-samples/go/endpoint.go?range=29-81)]
70+
71+
2. With a command prompt in the same directory as where you created the file, enter `go build endpoint.go` to compile the Go file. The command prompt does not return any information for a successful build.
72+
73+
3. Run the Go application from the command line by entering the following in the command prompt:
74+
75+
```CMD
76+
endpoint -appID df67dcdb-c37d-46af-88e1-8b97951ca1c2 -endpointKey <add-your-endpoint-key> -version 0.1 -region westus
77+
```
78+
79+
Replace `<add-your-endpoint-key>` with the value of your endpoint key.
80+
81+
The command prompt response is:
82+
83+
```CMD
84+
appID has value df67dcdb-c37d-46af-88e1-8b97951ca1c2
85+
endpointKey has value xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
86+
region has value westus
87+
utterance has value turn on the bedroom light
88+
response
89+
{
90+
"query": "turn on the bedroom light",
91+
"topScoringIntent": {
92+
"intent": "HomeAutomation.TurnOn",
93+
"score": 0.809439957
94+
},
95+
"entities": [
96+
{
97+
"entity": "bedroom",
98+
"type": "HomeAutomation.Room",
99+
"startIndex": 12,
100+
"endIndex": 18,
101+
"score": 0.8065475
102+
}
103+
]
104+
}
105+
```
106+
107+
## Clean up resources
108+
The two resources created in this quickstart are the LUIS endpoint key and the Go project. Delete the LUIS endpoint key from the Azure portal. Close the Go file and remove it from the file system.
109+
110+
## Next steps
111+
> [!div class="nextstepaction"]
112+
> [Add utterances](luis-get-started-go-add-utterance.md)

‎articles/cognitive-services/LUIS/toc.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@
1717
items:
1818
- name: C#
1919
href: luis-get-started-cs-get-intent.md
20+
- name: Go
21+
href: luis-get-started-go-get-intent.md
2022
- name: Java
2123
href: luis-get-started-java-get-intent.md
2224
- name: JavaScript
@@ -33,6 +35,8 @@
3335
items:
3436
- name: C#
3537
href: luis-get-started-cs-add-utterance.md
38+
- name: Go
39+
href: luis-get-started-go-add-utterance.md
3640
- name: Java
3741
href: luis-get-started-java-add-utterance.md
3842
- name: JavaScript

0 commit comments

Comments
 (0)