你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

安装并运行 LUIS 的 Docker 容器

项目
09/03/2024

重要

LUIS 将于 2025 年 10 月 1 日停用，从 2023 年 4 月 1 日开始，你将无法创建新的 LUIS 资源。建议将 LUIS 应用程序迁移到对话语言理解，以便从持续的产品支持和多语言功能中受益。

注意

容器图像位置最近发生了更改。阅读本文以查看此容器的更新位置。

容器使你能够在自己的环境中使用 LUIS。容器非常适合用于满足特定的安全性和数据管理要求。本文介绍如何下载、安装以及运行 LUIS 容器。

语言理解 (LUIS) 容器加载已训练或已发布的语言理解模型。作为 LUIS 应用，docker 容器提供从容器的 API 终结点执行预测查询的访问权限。可以从容器中收集查询日志并将这些日志上传回语言理解应用以提高应用的预测准确性。

以下视频演示如何使用此容器。

如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

先决条件

若要运行 LUIS 容器，请注意以下先决条件：

在主计算机上安装的 Docker。必须将 Docker 配置为允许容器连接 Azure 并向其发送账单数据。
- 在 Windows 上，还必须将 Docker 配置为支持 Linux 容器。
- 应基本了解 Docker 概念。
A 使用免费 (F0) 或标准 (S) 定价层来LUIS 资源。
已训练或已发布的应用，作为已装载的输入打包到具有其关联的应用 ID 的容器。可以通过 LUIS 门户或创作 API 获取打包文件。若要通过创作 API 获得 LUIS 打包应用，还将需要创作密钥。

收集必需的参数

所有 Azure AI 容器都需要三个主要参数。 Microsoft 软件许可条款的值必须为 accept。还需要终结点 URI 和 API 密钥。

终结点 URI

可在 Azure 门户中相应 Azure AI 服务资源的“概览”页上找到 {ENDPOINT_URI} 值。转到“概述”页，将鼠标悬停在终结点上就会显示一个“复制到剪贴板” 图标。在需要的地方复制并使用终结点。

屏幕截图显示如何收集终结点 URI 以供将来使用。

键

{API_KEY} 值用于启动容器，可在 Azure 门户中相应 Azure AI 服务资源的“密钥”页上找到。转到“密钥”页，选择“复制到剪贴板” 图标。

屏幕截图显示如何获取两个密钥之一以供将来使用。

重要

这些订阅密钥用于访问 Azure AI 服务 API。请勿共享密钥。安全地存储它们。例如，使用 Azure Key Vault。此外，建议定期重新生成这些密钥。发出 API 调用只需一个密钥。重新生成第一个密钥时，可以使用第二个密钥继续访问服务。

应用 ID `{APP_ID}`

使用此 ID 来选择应用。可在 LUIS 门户找到应用 ID，方法是单击应用屏幕顶部的“管理”，然后单击“设置” 。

创作密钥 `{AUTHORING_KEY}`

此密钥用于从云中的 LUIS 服务获取打包的应用并将查询日志上传回云。如果使用 REST API 导出应用，则需要创作密钥，本文稍后将对此进行介绍。

可在 LUIS 门户获取创作密钥，方法是单击应用屏幕顶部的“管理”，然后单击“Azure 资源” 。

用于包文件的创作 API

用于打包应用的创作 API：

主计算机

主机是运行 Docker 容器且基于 x64 的计算机。它可以是本地计算机或 Azure 中的 Docker 托管服务，例如：

Azure Kubernetes 服务。
Azure 容器实例。
部署到 Azure Stack 的 Kubernetes 群集。有关详细信息，请参阅将 Kubernetes 部署到 Azure Stack。

容器要求和建议

下表列出了容器主机的最小值和建议值。你的要求可能会根据流量的多少而发生变化。

容器	最小值	建议	TPS (最小值, 最大值)
LUIS	单核，2-GB 内存	单核，4-GB 内存	20, 40

每个核心必须至少为 2.6 千兆赫 (GHz) 或更快。
TPS - 每秒事务数

核心和内存对应于 --cpus 和 --memory 设置，用作 docker run 命令的一部分。

使用 `docker pull` 获取容器映像

在 mcr.microsoft.com 容器注册表联合项中可以找到 LUIS 容器映像。该映像驻留在 azure-cognitive-services/language 存储库中，名为 luis。完全限定的容器映像名称为 mcr.microsoft.com/azure-cognitive-services/language/luis。

要使用最新版本的容器，可以使用 latest 标记。还可以在 MCR 上找到标记的完整列表。

使用 docker pull 命令从 mcr.microsoft.com/azure-cognitive-services/language/luis 存储库下载容器映像：

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

有关可用标记的完整说明（如上述命令中使用的 latest），请参阅 Docker Hub 上的 LUIS。

提示

可以使用 docker images 命令列出下载的容器映像。例如，以下命令以表格列出每个下载的容器映像的 ID、存储库和标记：

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

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

如何使用容器

一旦容器位于主计算机上，请通过以下过程使用容器。

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

通过 LUIS 门户或 LUIS API 导出容器的包。
将包文件移动到主计算机上的所需输入目录中。请勿重命名、更改、覆盖或解压缩 LUIS 包文件。
使用所需的输入装入点和计费设置运行容器。提供 docker run 命令的多个示例。
查询容器的预测终结点。
使用完此容器后，从 LUIS 门户的输出装入点导入终结点日志并停止容器。
在“查看终结点话语”页上使用 LUIS 门户的主动学习改进应用。

无法更改正在容器中运行的应用。若要更改容器中的应用，必须使用 LUIS 门户或使用 LUIS 创作 API 更改 LUIS 服务中的应用。然后进行训练和/或发布，下载新包并再次运行该容器。

容器内的 LUIS 应用无法导出回 LUIS 服务。只能上传查询日志。

从 LUIS 导出打包的应用

LUIS 容器需要已训练或已发布的 LUIS 应用才能回复用户话语的预测查询。若要获取 LUIS 应用，请使用已训练或已发布的包 API。

默认位置是运行 docker run 命令的 input 子目录。

将包文件置于某个目录中，然后在运行 docker 容器时引用此目录作为输入装入点。

包类型

输入装入点目录可以同时包含应用的生产、过渡和版本控制模型。所有包均已装载。

包类型	查询终结点 API	查询可用性	包文件名格式
带有版本	GET、POST	仅容器	`{APP_ID}_v{APP_VERSION}.gz`
过渡	GET、POST	Azure 和容器	`{APP_ID}_STAGING.gz`
生产	GET、POST	Azure 和容器	`{APP_ID}_PRODUCTION.gz`

重要

请勿重命名、更改、覆盖或解压缩 LUIS 包文件。

打包先决条件

在打包 LUIS 应用程序之前，必须满足以下条件：

打包要求	详细信息
Azure Azure AI 服务资源实例	支持的区域包括美国西部 (`westus`) 西欧 (`westeurope`) 澳大利亚东部 (`australiaeast`)
已训练或已发布的 LUIS 应用	没有不受支持的依赖项。
访问主计算机的文件系统	主计算机必须允许输入装入点。

通过 LUIS 门户导出应用包

LUIS Azure 门户提供导出已训练或已发布的应用包的功能。

通过 LUIS 门户导出已发布的应用包

可从“我的应用”列表页中获取已发布的应用包。

登录到 LIUS Azure 门户。
选中列表中应用名称左侧的复选框。
从列表上方的上下文工具栏中选择“导出”项。
选择“导出容器 (GZIP)”。
选择“生产槽”或“过渡槽”的环境。
将从浏览器下载包。

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

通过 LUIS 门户导出已进行版本控制的应用包

可从“版本”列表页中获取已进行版本控制的应用包。

登录到 LIUS Azure 门户。
在列表中选择该应用。
在应用的导航栏中选择“管理”。
在左侧导航栏中选择“版本”。
选中列表中版本名称左侧的复选框。
从列表上方的上下文工具栏中选择“导出”项。
选择“导出容器 (GZIP)”。
将从浏览器下载包。

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

通过 API 导出已发布的应用包

使用以下 REST API 方法打包已发布的 LUIS 应用。使用 HTTP 规范下方的表将 API 调用中的占位符替换为自己相应的值。

GET /luis/api/v2.0/package/{APP_ID}/slot/{SLOT_NAME}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}

占位符	值
{APP_ID}	已发布 LUIS 应用的应用程序 ID。
{SLOT_NAME}	已发布 LUIS 应用的环境。使用以下值之一： `PRODUCTION` `STAGING`
{AUTHORING_KEY}	已发布 LUIS 应用的 LUIS 帐户的创作密钥。可以从 LUIS 门户的“用户设置”页面中获取创作密钥。
{AZURE_REGION}	相应的 Azure 区域： `westus` - 美国西部 `westeurope` - 西欧 `australiaeast` - 澳大利亚东部

若要下载已发布的包，请参考此处的 API 文档。如果下载成功，响应是一个 LUIS 包文件。将文件保存在为容器的输入装入点指定的存储位置中。

通过 API 导出已进行版本控制的应用包

使用以下 REST API 方法打包已训练的 LUIS 应用程序。使用 HTTP 规范下方的表将 API 调用中的占位符替换为自己相应的值。

GET /luis/api/v2.0/package/{APP_ID}/versions/{APP_VERSION}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}

占位符	值
{APP_ID}	已训练 LUIS 应用的应用程序 ID。
{APP_VERSION}	已训练 LUIS 应用的应用程序版本。
{AUTHORING_KEY}	已发布 LUIS 应用的 LUIS 帐户的创作密钥。可以从 LUIS 门户的“用户设置”页面中获取创作密钥。
{AZURE_REGION}	相应的 Azure 区域： `westus` - 美国西部 `westeurope` - 西欧 `australiaeast` - 澳大利亚东部

若要下载已进行版本控制的包，请参考此处的 API 文档。如果下载成功，响应是一个 LUIS 包文件。将文件保存在为容器的输入装入点指定的存储位置中。

通过 `docker run` 运行容器

使用 docker run 命令运行容器。有关如何获取 {ENDPOINT_URI} 和 {API_KEY} 值的详细信息，请参阅收集必需的参数。

docker run 命令的示例可用。

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 上的任何权限冲突。如果需要使用特定目录作为输入目录，则需要授予 docker 服务权限。
除非熟悉 docker 容器，否则不要更改参数顺序。
如果使用的是不同的操作系统，请使用正确的控制台/终端、用于装载的文件夹语法和系统的行继续符。这些示例假定 Windows 控制台使用行继续符 ^。由于容器是 Linux 操作系统，因此目标装载使用 Linux 样式的文件夹语法。

此命令：

从 LUIS 容器映像运行容器
从位于容器主机上的 C:\input 中的输入装入点加载 LUIS 应用
分配两个 CPU 内核和 4 千兆字节 (GB) 的内存
公开 TCP 端口 5000，并为容器分配伪 TTY
将容器和 LUIS 日志保存到位于容器主机上的 C:\output 中的输出装入点
退出后自动删除容器。容器映像在主计算机上仍然可用。

提供 docker run 命令的多个示例。

重要

必须指定 Eula、Billing 和 ApiKey 选项运行容器；否则，该容器不会启动。有关详细信息，请参阅计费。 ApiKey 值是 LUIS 门户中“Azure 资源”页中的“密钥”，也可以在 Azure Azure AI services 资源密钥页上找到。

在同一主机上运行多个容器

若要使用公开端口运行多个容器，请确保在运行每个容器时使用不同的公开端口。例如，在端口 5000 上运行第一个容器，在端口 5001 上运行第二个容器。

可以让此容器和其他 Azure AI 服务容器一起在主机上运行。此外，还可以让同一 Azure AI 服务容器的多个容器一起运行。

容器支持的终结点 API

容器同时提供了 V2 和 V3 版 API。

查询容器的预测终结点

容器提供了基于 REST 的查询预测终结点 API。已发布（过渡或生产）应用的终结点包含的路由与已进行版本控制的应用的终结点不同。

为容器 API 使用主机 http://localhost:5000。

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

查询参数配置查询响应的返回方式以及返回内容：

查询参数	类型	用途
`query`	string	用户的话语。
`verbose`	boolean	一个布尔值，表示是否为预测的模型返回所有元数据。默认值为 false。
`log`	boolean	记录查询，以便以后用于主动学习。默认值为 false。
`show-all-intents`	boolean	一个布尔值，表示是返回所有意向，还是只返回打分最高的意向。默认为 false。

查询 LUIS 应用

用于查询已发布应用的容器的示例 CURL 命令是：

V3 预测终结点
V2 预测终结点

若要查询槽中的模型，请使用以下 API：

curl -G \
-d verbose=false \
-d log=true \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/slots/production/predict"

若要对过渡环境执行查询，请将路由中的 production 替换为 staging：

http://localhost:5000/luis/v3.0/apps/{APP_ID}/slots/staging/predict

若要查询进行了版本控制的模型，请使用以下 API：

curl -G \
-d verbose=false \
-d log=false \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/versions/{APP_VERSION}/predict"

若要查询槽中的模型，请使用以下 API：

curl -X GET \
"http://localhost:5000/luis/v2.0/apps/{APP_ID}?q=turn%20on%20the%20lights&staging=false&timezoneOffset=0&verbose=false&log=true" \
-H "accept: application/json"

若要对过渡环境执行查询，请将过渡查询字符串参数值更改为 true：

staging=true

若要查询进行了版本控制的模型，请使用以下 API：

curl -X GET \
"http://localhost:5000/luis/v2.0/apps/{APP_ID}/versions/{APP_VERSION}?q=turn%20on%20the%20lights&timezoneOffset=0&verbose=false&log=true" \
-H "accept: application/json"

版本名称最多包含 10 个字符，并且仅包含 URL 中允许的字符。

导入终结点日志以供主动学习

如果为 LUIS 容器指定了输出装入点，则应用查询日志文件将保存在输出目录中，其中 {INSTANCE_ID} 是容器 ID。应用查询日志包含提交到 LUIS 容器的每个预测查询的查询、响应和时间戳。

以下位置显示了容器的日志文件的嵌套目录结构。

/output/luis/{INSTANCE_ID}/

从 LUIS 门户中选择应用，然后选择“导入终结点日志”以上传这些日志。

导入容器的日志文件以供主动学习

上传日志后，在 LUIS 门户中查看终结点话语。

验证容器是否正在运行

有几种方法可用于验证容器是否正在运行。找到相关容器的外部 IP 地址和公开端口，并打开你常用的 Web 浏览器。使用以下各种请求 URL 验证容器是否正在运行。此处列出的示例请求 URL 是 http://localhost:5000，但是你的特定容器可能会有所不同。请确保依赖容器的外部 IP 地址和公开端口。

请求 URL	用途
`http://localhost:5000/`	容器提供主页。
`http://localhost:5000/ready`	使用 GET 对此 URL 进行请求，可以验证容器是否已准备好接受针对模型的查询。此请求可用于 Kubernetes 运行情况和就绪情况探测。
`http://localhost:5000/status`	同样使用 GET 对此 URL 进行请求，可以验证用于启动容器的 api-key 是否有效，而不会导致终结点查询。此请求可用于 Kubernetes 运行情况和就绪情况探测。
`http://localhost:5000/swagger`	容器为终结点提供一组完整的文档以及“尝试”功能。使用此功能可以将设置输入到基于 Web 的 HTML 表单并进行查询，而无需编写任何代码。查询返回后，将提供示例 CURL 命令，用于演示所需的 HTTP 标头和正文格式。

容器的主页

运行已与 Internet 断开连接的容器

要使用此与 Internet 断开连接的容器，必须首先通过填写申请并购买承诺计划来请求访问权限。有关详细信息，请参阅在断开连接的环境中使用 Docker 容器。

如果已获准运行与 Internet 断开连接的容器，请使用以下示例，其中显示了将会使用的 docker run 命令的格式和占位符值。将这些占位符值替换为你自己的值。

docker run 命令中的 DownloadLicense=True 参数将会下载一个许可证文件，该文件将支持 Docker 容器能够在未连接到 Internet 时运行。它还包含到期日期，在此日期之后，许可证文件将失效，无法运行容器。只能将许可证文件用于已获批准的相应容器。例如，不能将语音转文本容器的许可证文件用于文档智能容器。

占位符	Value	格式或示例
`{IMAGE}`	要使用的容器映像。	`mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice`
`{LICENSE_MOUNT}`	将下载和装载许可证的路径。	`/host/license:/path/to/license/directory`
`{ENDPOINT_URI}`	用于对服务请求进行身份验证的终结点。可以在 Azure 门户中资源的“密钥和终结点”页上找到此项。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{API_KEY}`	文本分析资源的密钥。可以在 Azure 门户中资源的“密钥和终结点”页上找到此项。	`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
`{CONTAINER_LICENSE_DIRECTORY}`	容器本地文件系统上的许可证文件夹的位置。	`/path/to/license/directory`

docker run --rm -it -p 5000:5000 \ 
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}

下载许可证文件后，可以在断开连接的环境中运行容器。以下示例演示你将使用的 docker run 命令的格式设置以及占位符值。将这些占位符值替换为你自己的值。

无论容器在何处运行，都必须将许可证文件装载到容器，并且必须使用 Mounts:License= 指定容器本地文件系统上许可证文件夹的位置。还必须指定输出装载，以便可以写入计费使用情况记录。

占位符	Value	格式或示例
`{IMAGE}`	要使用的容器映像。	`mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice`
`{MEMORY_SIZE}`	要分配给容器的适当内存大小。	`4g`
`{NUMBER_CPUS}`	要分配给容器的适当 CPU 数。	`4`
`{LICENSE_MOUNT}`	将放置和装载许可证的路径。	`/host/license:/path/to/license/directory`
`{OUTPUT_PATH}`	记录使用情况记录的输出路径。	`/host/output:/path/to/output/directory`
`{CONTAINER_LICENSE_DIRECTORY}`	容器本地文件系统上的许可证文件夹的位置。	`/path/to/license/directory`
`{CONTAINER_OUTPUT_DIRECTORY}`	容器本地文件系统上的输出文件夹的位置。	`/path/to/output/directory`

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \ 
-v {LICENSE_MOUNT} \ 
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

停止容器

若要关闭容器，请在运行容器的命令行环境中按 Ctrl+C。

故障排除

如果运行启用了输出装入点和日志记录的容器，该容器会生成有助于排查启动或运行容器时发生的问题的日志文件。

提示

如需更多的故障排除信息和指南，请参阅 Azure AI 容器常见问题解答 (FAQ)。

如果在运行 Azure AI 服务容器时遇到问题，可以尝试使用 Microsoft 诊断容器。使用此容器可以诊断部署环境中可能阻止 Azure AI 容器按预期运行的常见错误。

若要获取容器，请使用以下 docker pull 命令：

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

然后运行容器。将 {ENDPOINT_URI} 替换为你的终结点，将 {API_KEY} 替换为你的资源的密钥：

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

容器会测试与计费终结点之间的网络连接性。

计费

LUIS 容器使用 Azure 帐户中的 Azure AI 服务资源向 Azure 发送账单信息。

对该容器的查询在用于 ApiKey 参数的 Azure 资源的定价层计费。

Azure AI 服务容器在未连接到计量或计费终结点的情况下无权运行。必须始终让容器可以向计费终结点传送计费信息。 Azure AI 服务容器不会将客户数据（例如，正在分析的图像或文本）发送给 Microsoft。

连接到 Azure

容器需要计费参数值才能运行。这些值使容器可以连接到计费终结点。容器约每 10 到 15 分钟报告一次使用情况。如果容器未在允许的时间范围内连接到 Azure，容器将继续运行，但不会为查询提供服务，直到计费终结点恢复。尝试连接按 10 到 15 分钟的相同时间间隔进行 10 次。如果无法在 10 次尝试内连接到计费终结点，容器会停止处理请求。有关发送给 Microsoft 进行计费的信息的示例，请参阅 Azure AI 服务容器常见问题解答。

计费参数

当以下三个选项都提供了有效值时，docker run 命令会启动容器：

选项	说明
`ApiKey`	用于跟踪账单信息的 Azure AI 服务资源的 API 密钥。必须将此选项的值设置为 `Billing` 中指定的已预配资源的 API 密钥。
`Billing`	用于跟踪账单信息的 Azure AI 服务资源的终结点。必须将此选项的值设置为已预配的 Azure 资源的终结点 URI。
`Eula`	表示已接受容器的许可条款。此选项的值必须设置为 accept。

有关这些选项的详细信息，请参阅配置容器。

摘要

在本文中，我们已学习相关的概念，以及语言理解 (LUIS) 容器的下载、安装和运行工作流。综上所述：

语言理解 (LUIS) 为 Docker 提供一个 Linux 容器，用于提供话语的终结点查询预测。
从 Microsoft 容器注册表 (MCR) 下载容器映像。
容器映像在 Docker 中运行。
可以使用 REST API 来通过指定容器的主机 URI 查询容器终结点。
必须在实例化容器时指定账单信息。

重要

如果未连接到 Azure 进行计量，则无法授权并运行 Azure AI 容器。客户需要始终让容器向计量服务传送账单信息。 Azure AI 容器不会将客户数据（例如，正在分析的图像或文本）发送给 Microsoft。

后续步骤

查看配置容器，了解配置设置。
请参阅 LUIS 容器限制了解已知功能限制。
若要解决与 LUIS 功能相关的问题，请参阅故障排除。
使用更多 Azure AI 容器

通过