快速入门:使用 cURL 和 REST 来更改模型Quickstart: Use cURL and REST to change model

此快速入门介绍如何将示例言语添加到披萨应用并训练该应用。This quickstart will show you how to add example utterances to a Pizza app and train the app. 示例话语是映射到意向的对话式用户文本。Example utterances are conversational user text mapped to an intent. 通过提供意向的示例话语,可以教 LUIS 识别用户提供的文本类型属于哪种意向。By providing example utterances for intents, you teach LUIS what kinds of user-supplied text belongs to which intent.

在本快速入门中,将按顺序执行三次 REST 调用。By following this quickstart, you will perform three REST calls in sequence.

参考文档Reference documentation

先决条件Prerequisites

  • 免费的 LUIS 帐户。A free LUIS account.

  • 文本编辑器,如 Visual Studio CodeA text editor such as Visual Studio Code.

  • 命令行程序 cURL。The command-line program cURL. 在 macOS、大多数 Linux 分发版和 Windows 10 版本 1803 及更高版本上已安装该 cURL 程序。The cURL program is already installed on macOS, most Linux distributions, and Windows 10 build 1803 and later.

    若需要安装 cURL,可在 cURL 下载页中下载 cURL。If you need to install cURL, you can download cURL from the cURL download page.

创建 Pizza 应用Create Pizza app

Create the pizza app.

  1. Select pizza-app-for-luis-v6.json to bring up the GitHub page for the pizza-app-for-luis.json file.
  2. Right-click or long tap the Raw button and select Save link as to save the pizza-app-for-luis.json to your computer.
  3. Sign into the LUIS portal.
  4. Select My Apps.
  5. On the My Apps page, select + New app for conversation.
  6. Select Import as JSON.
  7. In the Import new app dialog, select the Choose File button.
  8. Select the pizza-app-for-luis.json file you downloaded, then select Open.
  9. In the Import new app dialog Name field, enter a name for your Pizza app, then select the Done button.

The app will be imported.

If you see a dialog How to create an effective LUIS app, close the dialog.

Train and publish the Pizza app

You should see the Intents page with a list of the intents in the Pizza app.

  1. 在 LUIS 网站的右上方,选择“训练”按钮。In the top-right side of the LUIS website, select the Train button.

    “训练”按钮

  2. 当“训练”按钮上的状态指示器为绿色时,即表示训练完成。Training is complete when status indicator on the Train button is green.

若要在聊天机器人或其他客户端应用程序中接收 LUIS 预测,需要将应用发布到预测终结点。In order to receive a LUIS prediction in a chat bot or other client application, you need to publish the app to the prediction endpoint.

  1. 在右上方的导航栏中选择“发布”。Select Publish in the top-right navigation.

    右上方菜单中的“LUIS 发布到终结点”按钮的屏幕截图

  2. 选择“生产”槽,然后选择“完成” 。Select the Production slot, then select Done.

    “LUIS 发布到终结点”的屏幕截图Screenshot of LUIS publish to endpoint

  3. 在通知中选择“访问终结点 URL”链接,转到“Azure 资源”页。 Select the Access your endpoint URLs link in the notification to go to the Azure Resources page. 终结点 URL 作为“示例查询”列出。The endpoint URLs are listed as the Example Query.

Add an authoring resource to the Pizza app

  1. Select MANAGE.
  2. Select Azure Resources.
  3. Select Authoring Resource.
  4. Select Change authoring resource.

If you have an authoring resource, enter the Tenant Name, Subscription Name, and LUIS resource name of your authoring resource.

If you do not have an authoring resource:

  1. Select Create new resource.
  2. Enter a Tenant Name, Resource Name, Subscription Name, and Azure Resource Group Name.

Your Pizza app is now ready to use.

Record the access values for your Pizza app

To use your new Pizza app, you will need the app ID, authoring key, and authoring endpoint of your Pizza app.

To find these values:

  1. From the Intents page, select MANAGE.
  2. From the Application Settings page, record the App ID.
  3. Select Azure Resources.
  4. Select Authoring Resource.
  5. From the Authoring Resource tab, record the Primary Key. This value is your authoring key.
  6. Record the Endpoint URL. This value is your authoring endpoint.

创建 JSON 文件来训练 Pizza 应用Create a JSON file to train the Pizza app

若要创建包含三个示例言语的 JSON 文件,请将以下 JSON 数据保存到名为 ExampleUtterances.JSON 的文件中:To create a JSON file with three example utterances, save the following JSON data to a file named ExampleUtterances.JSON:

[
  {
    "text": "order a pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "order a large pepperoni pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 14,
        "endCharIndex": 28
      },
      {
        "entityName": "Size",
        "startCharIndex": 8,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "I want two large pepperoni pizzas on thin crust",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 17,
        "endCharIndex": 32
      },
      {
        "entityName": "Size",
        "startCharIndex": 11,
        "endCharIndex": 15
      },
      {
        "entityName": "Quantity",
        "startCharIndex": 7,
        "endCharIndex": 9
      },
      {
        "entityName": "Crust",
        "startCharIndex": 37,
        "endCharIndex": 46
      }
    ]
  }
]`

示例言语 JSON 遵循特定格式。The example utterances JSON follows a specific format.

text 字段包含示例话语的文本。The text field contains the text of the example utterance. intentName 字段必须对应于 LUIS 应用中的现有意向名称。The intentName field must correspond to the name of an existing intent in the LUIS app. entityLabels 字段是必填的。The entityLabels field is required. 如果不想标记任何实体,请提供一个空数组。If you don't want to label any entities, provide an empty array.

如果 entityLabels 数组不为空,则 startCharIndexendCharIndex 需要标记 entityName 字段中引用的实体。If the entityLabels array is not empty, the startCharIndex and endCharIndex need to mark the entity referred to in the entityName field. 该索引从零开始。The index is zero-based. 如果标签的起始或结尾位于文本中的空白处,则添加话语的 API 调用将失败。If you begin or end the label at a space in the text, the API call to add the utterances fails.

添加示例话语Add example utterances

  1. 若要上传这批示例言语,请将以下命令复制到文本编辑器中:To upload the batch of example utterances, copy this command into your text editor:

    curl "***YOUR-AUTHORING-ENDPOINT***/luis/authoring/v3.0-preview/apps/***YOUR-APP-ID***/versions/***YOUR-APP-VERSION***/examples?verbose=true&show-all-intents=true" ^
          --request POST ^
          --header "Content-Type:application/json" ^
          --header "Ocp-Apim-Subscription-Key: ***YOUR-AUTHORING-KEY***" ^
          --data "@ExampleUtterances.JSON"
    
  2. 将以 ***YOUR- 开头的值替换为你自己的值。Replace the values starting with ***YOUR- with your own values.

    信息Information 目的Purpose
    ***YOUR-AUTHORING-ENDPOINT*** 创作 URL 终结点。Your authoring URL endpoint. 例如“https://REPLACE-WITH-YOUR-RESOURCE-NAME.api.cognitive.azure.cn/”。For example, "https://REPLACE-WITH-YOUR-RESOURCE-NAME.api.cognitive.azure.cn/". 在创建资源时设置资源名称。You set your resource name when you created the resource.
    ***YOUR-APP-ID*** LUIS 应用 ID。Your LUIS app ID.
    ***YOUR-APP-VERSION*** LUIS 应用版本。Your LUIS app version. 对于 Pizza 应用,版本号为“0.1”(不含引号)。For the Pizza app, the version number is "0.1" without the quotes.
    ***YOUR-AUTHORING-KEY*** 32 字符创作密钥。Your 32 character authoring key.

    分配的密钥和资源可以在 LUIS 门户的“Azure 资源”页上的“管理”部分中看到。Assigned keys and resources are visible in the LUIS portal in the Manage section, on the Azure resources page. 应用 ID 可以在“应用程序设置”页的同一“管理”部分中找到。The app ID is available in the same Manage section, on the Application Settings page.

  3. 启动命令提示符 (Windows) 或终端(macOS 和 Linux),并将目录更改为保存 ExampleUtterances.JSON 文件的目录。Start a Command Prompt (Windows) or Terminal (macOS and Linux), and change directories to the same directory where you saved the ExampleUtterances.JSON file.

  4. 从编辑器中复制 cURL 命令,并将其粘贴到命令提示符 (Windows) 或终端(macOS 和 Linux)中。Copy the cURL command from the editor, and paste it into a Command Prompt (Windows) or Terminal (macOS and Linux). 按 Enter 执行该命令。Press Enter to execute the command.

    应会看到以下响应:You should see the following response:

    [{"value":{"ExampleId":1255129706,"UtteranceText":"order a pizza"},"hasError":false},{"value":{"ExampleId":1255129707,"UtteranceText":"order a large pepperoni pizza"},"hasError":false},{"value":{"ExampleId":1255129708,"UtteranceText":"i want two large pepperoni pizzas on thin crust"},"hasError":false}]
    

    下面是为提高可读性而进行了格式设置的输出:Here is the output formatted for readability:

    [
      {
        "value": {
          "ExampleId": 1255129706,
          "UtteranceText": "order a pizza"
        },
        "hasError": false
      },
      {
        "value": {
          "ExampleId": 1255129707,
          "UtteranceText": "order a large pepperoni pizza"
        },
        "hasError": false
      },
      {
        "value": {
          "ExampleId": 1255129708,
          "UtteranceText": "i want two large pepperoni pizzas on thin crust"
        },
        "hasError": false
      }
    ]
    

训练 Pizza 应用模型Train the Pizza app model

  1. 若要开启 Pizza 应用的训练会话,请将以下命令复制到文本编辑器中:To begin a training session for the Pizza app, copy this command into your text editor:

    curl "***YOUR-AUTHORING-ENDPOINT***/luis/authoring/v3.0-preview/apps/***YOUR-APP-ID***/versions/***YOUR-APP-VERSION***/train?verbose=true&show-all-intents=true" ^
          --data "" ^
          --request POST ^
          --header "Content-Type:application/json" ^
          --header "Ocp-Apim-Subscription-Key: ***YOUR-AUTHORING-KEY***"
    
  2. 与之前所做的操作一样,将以 ***YOUR- 开头的值替换为你自己的值。As you did before, replace the values starting with ***YOUR- with your own values.

  3. 从编辑器中复制 cURL 命令,并将其粘贴到命令提示符 (Windows) 或终端(macOS 和 Linux)中。Copy the cURL command from the editor, and paste it into a Command Prompt (Windows) or Terminal (macOS and Linux). 按 Enter 执行该命令。Press Enter to execute the command.

    应会看到以下响应:You should see the following response:

    {"statusId":2,"status":"UpToDate"}
    

    下面是为提高可读性而进行了格式设置的输出:Here is the output formatted for readability:

    {
      "statusId": 2,
      "status": "UpToDate"
    }
    

获取训练状态Get the status of training

  1. 若要获取训练会话的训练状态,请将以下命令复制到文本编辑器中:To get the training status for the training session, copy this command into your text editor:

    curl "***YOUR-AUTHORING-ENDPOINT***/luis/authoring/v3.0-preview/apps/***YOUR-APP-ID***/versions/***YOUR-APP-VERSION***/train?verbose=true&show-all-intents=true" ^
            --request GET ^
            --header "Content-Type:application/json" ^
            --header "Ocp-Apim-Subscription-Key: ***YOUR-AUTHORING-KEY***"
    
  2. 与之前所做的操作一样,将以 ***YOUR- 开头的值替换为你自己的值。As you did before, replace the values starting with ***YOUR- with your own values.

  3. 从编辑器中复制 cURL 命令,并将其粘贴到命令提示符 (Windows) 或终端(macOS 和 Linux)中。Copy the cURL command from the editor, and paste it into a Command Prompt (Windows) or Terminal (macOS and Linux). 按 Enter 执行该命令。Press Enter to execute the command.

    应会看到以下响应:You should see the following response:

    [{"modelId":"8eb7ad8f-5db5-4c28-819b-ca3905fffd80","details":{"statusId":2,"status":"UpToDate","exampleCount":171}},{"modelId":"6f53bc92-ae54-44ce-bc4e-010d1f8cfda0","details":{"statusId":2,"status":"UpToDate","exampleCount":171}},{"modelId":"6cb17888-ad6e-464c-82c0-d37fd1f2c4f8","details":{"statusId":2,"status":"UpToDate","exampleCount":171}},{"modelId":"a16fc4fd-1949-4e77-9de3-30369f16c3a5","details":{"statusId":2,"status":"UpToDate","exampleCount":171}},{"modelId":"6bacdb75-1889-4f93-8971-8c8995ff8960","details":{"statusId":2,"status":"UpToDate","exampleCount":171}},{"modelId":"be963f4c-4898-48d7-9eba-3c6af0867b9d","details":{"statusId":2,"status":"UpToDate","exampleCount":171}}]
    

    下面是为提高可读性而进行了格式设置的输出:Here is the output formatted for readability:

    [
      {
        "modelId": "8eb7ad8f-5db5-4c28-819b-ca3905fffd80",
        "details": {
          "statusId": 2,
          "status": "UpToDate",
          "exampleCount": 171
        }
      },
      {
        "modelId": "6f53bc92-ae54-44ce-bc4e-010d1f8cfda0",
        "details": {
          "statusId": 2,
          "status": "UpToDate",
          "exampleCount": 171
        }
      },
      {
        "modelId": "6cb17888-ad6e-464c-82c0-d37fd1f2c4f8",
        "details": {
          "statusId": 2,
          "status": "UpToDate",
          "exampleCount": 171
        }
      },
      {
        "modelId": "a16fc4fd-1949-4e77-9de3-30369f16c3a5",
        "details": {
          "statusId": 2,
          "status": "UpToDate",
          "exampleCount": 171
        }
      },
      {
        "modelId": "6bacdb75-1889-4f93-8971-8c8995ff8960",
        "details": {
          "statusId": 2,
          "status": "UpToDate",
          "exampleCount": 171
        }
      },
      {
        "modelId": "be963f4c-4898-48d7-9eba-3c6af0867b9d",
        "details": {
          "statusId": 2,
          "status": "UpToDate",
          "exampleCount": 171
        }
      }
    ]
    

清理资源Clean up resources

完成本快速入门后,请从文件系统中删除 ExampleUtterances.JSON 文件。When you are finished with this quickstart, delete the ExampleUtterances.JSON file from the file system.

后续步骤Next steps