安装并运行 LUIS 的 Docker 容器Install and run Docker containers for LUIS

备注

容器图像位置最近发生了更改。The container image location has recently changed. 阅读本文以查看此容器的更新位置。Read this article to see the updated location for this container.

容器使你能够在自己的环境中使用 LUIS。Containers enable you to use LUIS in your own environment. 容器非常适合用于满足特定的安全性和数据管理要求。Containers are great for specific security and data governance requirements. 本文介绍如何下载、安装以及运行 LUIS 容器。In this article you'll learn how to download, install, and run a LUIS container.

语言理解 (LUIS) 容器加载已训练或已发布的语言理解模型。The Language Understanding (LUIS) container loads your trained or published Language Understanding model. 作为 LUIS 应用,docker 容器提供从容器的 API 终结点执行预测查询的访问权限。As a LUIS app, the docker container provides access to the query predictions from the container's API endpoints. 可以从容器中收集查询日志并将这些日志上传回语言理解应用以提高应用的预测准确性。You can collect query logs from the container and upload them back to the Language Understanding app to improve the app's prediction accuracy.

以下视频演示如何使用此容器。The following video demonstrates using this container.

认知服务的容器演示Container demonstration for Cognitive Services

如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a Trial before you begin.

先决条件Prerequisites

若要运行 LUIS 容器,请注意以下先决条件:To run the LUIS container, note the following prerequisites:

必须Required 目的Purpose
Docker 引擎Docker Engine 需要在主计算机上安装 Docker 引擎。You need the Docker Engine installed on a host computer. Docker 提供用于在 macOSWindowsLinux 上配置 Docker 环境的包。Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. 有关 Docker 和容器的基础知识,请参阅 Docker 概述For a primer on Docker and container basics, see the Docker overview.

必须将 Docker 配置为允许容器连接 Azure 并向其发送账单数据。Docker must be configured to allow the containers to connect with and send billing data to Azure.

在 Windows 上,还必须将 Docker 配置为支持 Linux 容器。On Windows, Docker must also be configured to support Linux containers.

熟悉 DockerFamiliarity with Docker 应对 Docker 概念有基本的了解,例如注册表、存储库、容器和容器映像,以及基本的 docker 命令的知识。You should have a basic understanding of Docker concepts, like registries, repositories, containers, and container images, as well as knowledge of basic docker commands.
Azure Cognitive Services 资源和 LUIS 打包应用文件Azure Cognitive Services resource and LUIS packaged app file 若要使用容器,必须具有:In order to use the container, you must have:

* 一项 认知服务 Azure 资源,以及关联的计费密钥和计费终结点 URI。* A Cognitive Services Azure resource and the associated billing key the billing endpoint URI. 这两个值都可以在资源的“概述”和“密钥”页上找到,并且是启动容器所必需的。Both values are available on the Overview and Keys pages for the resource and are required to start the container.
* 已训练或已发布的应用,作为已安装的输入打包到具有其关联的应用 ID 的容器。* A trained or published app packaged as a mounted input to the container with its associated App ID. 可以通过 LUIS 门户或创作 API 获取打包文件。You can get the packaged file from the LUIS portal or the Authoring APIs. 若要通过 创作 API 获得 LUIS 打包应用,还将需要 创作密钥If you are getting LUIS packaged app from the authoring APIs, you will also need your Authoring Key.

这些要求用于将命令行参数传递到以下变量:These requirements are used to pass command-line arguments to the following variables:

{AUTHORING_KEY} :此密钥用于从云中的 LUIS 服务获取打包的应用并将查询日志上传回云。{AUTHORING_KEY}: This key is used to get the packaged app from the LUIS service in the cloud and upload the query logs back to the cloud. 格式为 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxThe format is xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

{APP_ID} :此 ID 用于选择应用。{APP_ID}: This ID is used to select the App. 格式为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxThe format is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

{API_KEY} :此密钥用于启动容器。{API_KEY}: This key is used to start the container. 可以在两个位置找到终结点密钥。You can find the endpoint key in two places. 第一个是 Azure 门户的“认知服务”资源的密钥列表。The first is the Azure portal within the Cognitive Services resource's keys list. 也可以在 LUIS 门户的“密钥和终结点”设置页上找到终结点密钥。The endpoint key is also available in the LUIS portal on the Keys and Endpoint settings page. 请勿使用初学者密钥。Do not use the starter key.

{ENDPOINT_URI} :“概述”页上提供的终结点。{ENDPOINT_URI}: The endpoint as provided on the Overview page.

创作密钥和终结点密钥具有不同的用途。The authoring key and endpoint key have different purposes. 请勿互换使用。Do not use them interchangeably.

收集必需参数Gathering required parameters

对于所有认知服务的容器来说,有三种主要参数是必需的。There are three primary parameters for all Cognitive Services' containers that are required. 最终用户许可协议 (EULA) 的值必须为 acceptThe end-user license agreement (EULA) must be present with a value of accept. 此外还需要终结点 URL 和 API 密钥。Additionally, both an Endpoint URL and API Key are needed.

终结点 URI {ENDPOINT_URI}Endpoint URI {ENDPOINT_URI}

在相应的认知服务资源的 Azure 门户“概览” 页上提供终结点 URI 值。The Endpoint URI value is available on the Azure portal Overview page of the corresponding Cognitive Service resource. 导航到“概览” 页,将鼠标悬停在“终结点”上就会显示一个 Copy to clipboard 图标。Navigate to the Overview page, hover over the Endpoint, and a Copy to clipboard icon will appear. 复制后在需要时使用。Copy and use where needed.

收集终结点 URI 供以后使用

密钥 {API_KEY}Keys {API_KEY}

此密钥用于启动容器,可以从相应认知服务资源的 Azure 门户的“密钥”页获取。This key is used to start the container, and is available on the Azure portal's Keys page of the corresponding Cognitive Service resource. 导航到“密钥”页并单击 Copy to clipboard 图标。 Navigate to the Keys page, and click on the Copy to clipboard icon.

获取两个密钥中的一个供以后使用

重要

这些订阅密钥用于访问认知服务 API。These subscription keys are used to access your Cognitive Service API. 不要共享你的密钥。Do not share your keys. 以安全方式存储密钥(例如,使用 Azure Key Vault 来存储)。Store them securely, for example, using Azure Key Vault. 此外,我们建议定期重新生成这些密钥。We also recommend regenerating these keys regularly. 发出 API 调用只需一个密钥。Only one key is necessary to make an API call. 重新生成第一个密钥时,可以使用第二个密钥来持续访问服务。When regenerating the first key, you can use the second key for continued access to the service.

用于包文件的创作 APIAuthoring APIs for package file

用于打包应用的创作 API:Authoring APIs for packaged apps:

主计算机The host computer

主机是运行 Docker 容器且基于 x64 的计算机。The host is a x64-based computer that runs the Docker container. 它可以是本地计算机或 Azure 中的 Docker 托管服务,例如:It can be a computer on your premises or a Docker hosting service in Azure, such as:

容器要求和建议Container requirements and recommendations

下表列出了容器主机的最小值和建议值。The below table lists minimum and recommended values for the container host. 你的要求可能会根据流量的多少而发生变化。Your requirements may change depending on traffic volume.

容器Container 最小值Minimum 建议Recommended TPSTPS
(最小值, 最大值)(Minimum, Maximum)
LUISLUIS 单核,2-GB 内存1 core, 2-GB memory 单核,4-GB 内存1 core, 4-GB memory 20, 4020, 40
  • 每个核心必须至少为 2.6 千兆赫 (GHz) 或更快。Each core must be at least 2.6 gigahertz (GHz) or faster.
  • TPS - 每秒事务数TPS - transactions per second

核心和内存对应于 --cpus--memory 设置,用作 docker run 命令的一部分。Core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

使用 docker pull 获取容器映像Get the container image with docker pull

使用 docker pull 命令从 mcr.microsoft.com/azure-cognitive-services/language/luis 存储库下载容器映像:Use the docker pull command to download a container image from the mcr.microsoft.com/azure-cognitive-services/language/luis repository:

docker pull mcr.microsoft.com/azure-cognitive-services/language/luis:latest

有关可用标记的完整说明(如上述命令中使用的 latest),请参阅 Docker Hub 上的 LUISFor a full description of available tags, such as latest used in the preceding command, see LUIS on Docker Hub.

提示

可以使用 docker images 命令列出下载的容器映像。You can use the docker images command to list your downloaded container images. 例如,以下命令以表格列出每个下载的容器映像的 ID、存储库和标记:For example, the following command lists the ID, repository, and tag of each downloaded container image, formatted as a table:

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID            REPOSITORY              TAG
<image-id>       <repository-path/name>     <tag-name>

如何使用容器How to use the container

一旦容器位于主计算机上,请通过以下过程使用容器。Once the container is on the host computer, use the following process to work with the container.

使用语言理解 (LUIS) 容器的过程

  1. 通过 LUIS 门户或 LUIS API 导出容器的包Export package for container from LUIS portal or LUIS APIs.
  2. 将包文件移动到主计算机上的所需输入目录中。Move package file into the required input directory on the host computer. 请勿重命名、更改、覆盖或解压缩 LUIS 包文件。Do not rename, alter, overwrite, or decompress the LUIS package file.
  3. 使用所需的输入装入点和计费设置运行容器Run the container, with the required input mount and billing settings. 提供 docker run 命令的多个示例More examples of the docker run command are available.
  4. 查询容器的预测终结点Querying the container's prediction endpoint.
  5. 使用完此容器后,从 LUIS 门户的输出装入点导入终结点日志停止容器。When you are done with the container, import the endpoint logs from the output mount in the LUIS portal and stop the container.
  6. 在“查看终结点话语”页上使用 LUIS 门户的主动学习改进应用。Use LUIS portal's active learning on the Review endpoint utterances page to improve the app.

无法更改正在容器中运行的应用。The app running in the container can't be altered. 若要更改容器中的应用,必须使用 LUIS 门户或使用 LUIS 创作 API 更改 LUIS 服务中的应用。In order to change the app in the container, you need to change the app in the LUIS service using the LUIS portal or use the LUIS authoring APIs. 然后进行训练和/或发布,下载新包并再次运行该容器。Then train and/or publish, then download a new package and run the container again.

容器内的 LUIS 应用无法导出回 LUIS 服务。The LUIS app inside the container can't be exported back to the LUIS service. 只能上传查询日志。Only the query logs can be uploaded.

从 LUIS 导出打包的应用Export packaged app from LUIS

LUIS 容器需要已训练或已发布的 LUIS 应用才能回复用户话语的预测查询。The LUIS container requires a trained or published LUIS app to answer prediction queries of user utterances. 若要获取 LUIS 应用,请使用已训练或已发布的包 API。In order to get the LUIS app, use either the trained or published package API.

默认位置是运行 docker run 命令的 input 子目录。The default location is the input subdirectory in relation to where you run the docker run command.

将包文件置于某个目录中,然后在运行 docker 容器时引用此目录作为输入装入点。Place the package file in a directory and reference this directory as the input mount when you run the docker container.

包类型Package types

输入装入点目录可以同时包含应用的生产、过渡和版本控制模型。The input mount directory can contain the Production, Staging, and Versioned models of the app simultaneously. 所有包均已装载。All the packages are mounted.

包类型Package Type 查询终结点 APIQuery Endpoint API 查询可用性Query availability 包文件名格式Package filename format
带有版本Versioned GET、POSTGET, POST 仅容器Container only {APP_ID}_v{APP_VERSION}.gz
过渡Staging GET、POSTGET, POST Azure 和容器Azure and container {APP_ID}_STAGING.gz
生产Production GET、POSTGET, POST Azure 和容器Azure and container {APP_ID}_PRODUCTION.gz

重要

请勿重命名、更改、覆盖或解压缩 LUIS 包文件。Do not rename, alter, overwrite, or decompress the LUIS package files.

打包先决条件Packaging prerequisites

在打包 LUIS 应用程序之前,必须满足以下条件:Before packaging a LUIS application, you must have the following:

打包要求Packaging Requirements 详细信息Details
Azure 认知服务资源实例Azure Cognitive Services resource instance 支持的区域包括Supported regions include

中国东部 2 (chinaeast2)China East 2 (chinaeast2)
已训练或已发布的 LUIS 应用Trained or published LUIS app 没有不受支持的依赖项With no unsupported dependencies.
访问主计算机的文件系统Access to the host computer's file system 主计算机必须允许输入装入点The host computer must allow an input mount.

通过 LUIS 门户导出应用包Export app package from LUIS portal

LUIS 门户提供导出已训练或已发布的应用包的功能。The LUIS portal provides the ability to export the trained or published app's package.

通过 LUIS 门户导出已发布的应用包Export published app's package from LUIS portal

可从“我的应用”列表页中获取已发布的应用包。The published app's package is available from the My Apps list page.

  1. 登录到 LUIS 门户Sign on to the LUIS portal.
  2. 选中列表中应用名称左侧的复选框。Select the checkbox to the left of the app name in the list.
  3. 从列表上方的上下文工具栏中选择“导出”项。Select the Export item from the contextual toolbar above the list.
  4. 选择“导出容器 (GZIP)”。Select Export for container (GZIP).
  5. 选择“生产槽”或“过渡槽”的环境。Select the environment of Production slot or Staging slot.
  6. 将从浏览器下载包。The package is downloaded from the browser.

从“应用”页面的“导出”菜单导出容器的已发布包

通过 LUIS 门户导出已进行版本控制的应用包Export versioned app's package from LUIS portal

可从“版本”列表页中获取已进行版本控制的应用包。The versioned app's package is available from the Versions list page.

  1. 登录到 LUIS 门户Sign on to the LUIS portal.
  2. 在列表中选择该应用。Select the app in the list.
  3. 在应用的导航栏中选择“管理”。Select Manage in the app's navigation bar.
  4. 在左侧导航栏中选择“版本”。Select Versions in the left navigation bar.
  5. 选中列表中版本名称左侧的复选框。Select the checkbox to the left of the version name in the list.
  6. 从列表上方的上下文工具栏中选择“导出”项。Select the Export item from the contextual toolbar above the list.
  7. 选择“导出容器 (GZIP)”。Select Export for container (GZIP).
  8. 将从浏览器下载包。The package is downloaded from the browser.

从“版本”页面的“导出”菜单导出容器的已训练包

通过 API 导出已发布的应用包Export published app's package from API

使用以下 REST API 方法打包已发布的 LUIS 应用。Use the following REST API method, to package a LUIS app that you've already published. 使用 HTTP 规范下方的表将 API 调用中的占位符替换为自己相应的值。Substituting your own appropriate values for the placeholders in the API call, using the table below the HTTP specification.

GET /luis/api/v2.0/package/{APP_ID}/slot/{SLOT_NAME}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.azure.cn
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}
占位符Placeholder Value
{APP_ID}{APP_ID} 已发布 LUIS 应用的应用程序 ID。The application ID of the published LUIS app.
{SLOT_NAME}{SLOT_NAME} 已发布 LUIS 应用的环境。The environment of the published LUIS app. 使用以下值之一:Use one of the following values:
PRODUCTION
STAGING
{AUTHORING_KEY}{AUTHORING_KEY} 已发布 LUIS 应用的 LUIS 帐户的创作密钥。The authoring key of the LUIS account for the published LUIS app.
可以从 LUIS 门户的“用户设置”页面中获取创作密钥。You can get your authoring key from the User Settings page on the LUIS portal.
{AZURE_REGION}{AZURE_REGION} 相应的 Azure 区域:The appropriate Azure region:

chinaeast2 - 中国东部 2chinaeast2 - China East 2

若要下载已发布的包,请参考此处的 API 文档To download the published package, refer to the API documentation here. 如果下载成功,响应是一个 LUIS 包文件。If successfully downloaded, the response is a LUIS package file. 将文件保存在为容器的输入装入点指定的存储位置中。Save the file in the storage location specified for the input mount of the container.

通过 API 导出已进行版本控制的应用包Export versioned app's package from API

使用以下 REST API 方法打包已训练的 LUIS 应用程序。Use the following REST API method, to package a LUIS application that you've already trained. 使用 HTTP 规范下方的表将 API 调用中的占位符替换为自己相应的值。Substituting your own appropriate values for the placeholders in the API call, using the table below the HTTP specification.

GET /luis/api/v2.0/package/{APP_ID}/versions/{APP_VERSION}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.azure.cn
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}
占位符Placeholder Value
{APP_ID}{APP_ID} 已训练 LUIS 应用的应用程序 ID。The application ID of the trained LUIS app.
{APP_VERSION}{APP_VERSION} 已训练 LUIS 应用的应用程序版本。The application version of the trained LUIS app.
{AUTHORING_KEY}{AUTHORING_KEY} 已发布 LUIS 应用的 LUIS 帐户的创作密钥。The authoring key of the LUIS account for the published LUIS app.
可以从 LUIS 门户的“用户设置”页面中获取创作密钥。You can get your authoring key from the User Settings page on the LUIS portal.
{AZURE_REGION}{AZURE_REGION} 相应的 Azure 区域:The appropriate Azure region:

chinaeast2 - 中国东部 2chinaeast2 - China East 2

若要下载已进行版本控制的包,请参考此处的 API 文档To download the versioned package, refer to the API documentation here. 如果下载成功,响应是一个 LUIS 包文件。If successfully downloaded, the response is a LUIS package file. 将文件保存在为容器的输入装入点指定的存储位置中。Save the file in the storage location specified for the input mount of the container.

通过 docker run 运行容器Run the container with docker run

使用 docker run 命令运行容器。Use the docker run command to run the container. 有关如何获取 {ENDPOINT_URI}{API_KEY} 值的详细信息,请参阅收集所需的参数Refer to gathering required parameters for details on how to get the {ENDPOINT_URI} and {API_KEY} values.

docker run 命令的示例可用。Examples of the docker run command are available.

docker run --rm -it -p 5000:5000 ^
--memory 4g ^
--cpus 2 ^
--mount type=bind,src=c:\input,target=/input ^
--mount type=bind,src=c:\output\,target=/output ^
mcr.microsoft.com/azure-cognitive-services/language/luis ^
Eula=accept ^
Billing={ENDPOINT_URI} ^
ApiKey={API_KEY}
  • 此示例使用 C: 驱动器外的目录来避免 Windows 上的任何权限冲突。This example uses the directory off the C: drive to avoid any permission conflicts on Windows. 如果需要使用特定目录作为输入目录,则需要授予 docker 服务权限。If you need to use a specific directory as the input directory, you may need to grant the docker service permission.
  • 除非熟悉 docker 容器,否则不要更改参数顺序。Do not change the order of the arguments unless you are familiar with docker containers.
  • 如果使用的是不同的操作系统,请使用正确的控制台/终端、用于装载的文件夹语法和系统的行继续符。If you are using a different operating system, use the correct console/terminal, folder syntax for mounts, and line continuation character for your system. 这些示例假定 Windows 控制台使用行继续符 ^These examples assume a Windows console with a line continuation character ^. 由于容器是 Linux 操作系统,因此目标装载使用 Linux 样式的文件夹语法。Because the container is a Linux operating system, the target mount uses a Linux-style folder syntax.

此命令:This command:

  • 从 LUIS 容器映像运行容器Runs a container from the LUIS container image
  • 从位于容器主机上的 C:\input 中的输入装入点加载 LUIS 应用Loads LUIS app from input mount at C:\input, located on container host
  • 分配两个 CPU 内核和 4 千兆字节 (GB) 的内存Allocates two CPU cores and 4 gigabytes (GB) of memory
  • 公开 TCP 端口 5000,并为容器分配伪 TTYExposes TCP port 5000 and allocates a pseudo-TTY for the container
  • 将容器和 LUIS 日志保存到位于容器主机上的 C:\output 中的输出装入点Saves container and LUIS logs to output mount at C:\output, located on container host
  • 退出后自动删除容器。Automatically removes the container after it exits. 容器映像在主计算机上仍然可用。The container image is still available on the host computer.

提供 docker run 命令的多个示例More examples of the docker run command are available.

重要

必须指定 EulaBillingApiKey 选项运行容器;否则,该容器不会启动。The Eula, Billing, and ApiKey options must be specified to run the container; otherwise, the container won't start. 有关详细信息,请参阅计费For more information, see Billing. ApiKey 值是 LUIS 门户中“Azure 资源”页中的“密钥”,也可以在 Azure Cognitive Services 资源密钥页上找到。The ApiKey value is the Key from the Azure Resources page in the LUIS portal and is also available on the Azure Cognitive Services resource keys page.

在同一主机上运行多个容器Run multiple containers on the same host

若要使用公开端口运行多个容器,请确保在运行每个容器时使用不同的公开端口。If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. 例如,在端口 5000 上运行第一个容器,在端口 5001 上运行第二个容器。For example, run the first container on port 5000 and the second container on port 5001.

可以让此容器和其他 Azure 认知服务容器一起运行在该主机上。You can have this container and a different Azure Cognitive Services container running on the HOST together. 此外,还可以让同一认知服务容器的多个容器一起运行。You also can have multiple containers of the same Cognitive Services container running.

容器支持的终结点 APIEndpoint APIs supported by the container

容器同时提供了 V2 和 V3 版 API。Both V2 and V3 versions of the API are available with the container.

查询容器的预测终结点Query the container's prediction endpoint

容器提供了基于 REST 的查询预测终结点 API。The container provides REST-based query prediction endpoint APIs. 已发布(过渡或生产)应用的终结点包含的路由与已进行版本控制的应用的终结点不同。Endpoints for published (staging or production) apps have a different route than endpoints for versioned apps.

为容器 API 使用主机 http://localhost:5000Use the host, http://localhost:5000, for container APIs.

包类型Package type HTTP 谓词HTTP verb 路由Route 查询参数Query parameters
已发布Published GET、POSTGET, POST /luis/v3.0/apps/{appId}/slots/{slotName}/predict? query={query}
[&verbose][&verbose]
[&log][&log]
[&show-all-intents][&show-all-intents]
带有版本Versioned GET、POSTGET, POST /luis/v3.0/apps/{appId}/versions/{versionId}/predict? query={query}
[&verbose][&verbose]
[&log][&log]
[&show-all-intents][&show-all-intents]

查询参数配置查询响应的返回方式以及返回内容:The query parameters configure how and what is returned in the query response:

查询参数Query parameter 类型Type 用途Purpose
query stringstring 用户的话语。The user's utterance.
verbose booleanboolean 一个布尔值,表示是否为预测的模型返回所有元数据。A boolean value indicating whether to return all the metadata for the predicted models. 默认值为 false。Default is false.
log booleanboolean 记录查询,以便以后用于主动学习Logs queries, which can be used later for active learning. 默认值为 false。Default is false.
show-all-intents booleanboolean 一个布尔值,表示是返回所有意向,还是只返回打分最高的意向。A boolean value indicating whether to return all the intents or the top scoring intent only. 默认值为 false。Default is false.