在本地使用摘要 Docker 容器

容器让你能够在自己的基础结构上托管摘要 API。 如果你的安全或数据管理要求不能通过远程调用摘要来完成,则容器可能是一个不错的选择。

先决条件

  • 如果没有 Azure 订阅,请创建一个试用帐户
  • 在主机上安装 Docker。 必须将 Docker 配置为允许容器连接 Azure 并向其发送账单数据。
    • 在 Windows 上,还必须将 Docker 配置为支持 Linux 容器。
    • 应基本了解 Docker 概念
  • 使用免费 (F0) 或标准 (S) 定价层语言资源

收集必需的参数

所有 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 调用只需一个密钥。 重新生成第一个密钥时,可以使用第二个密钥继续访问服务。

主机要求和建议

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

下表介绍了摘要容器技能的最小和推荐规范。 列出的 CPU/内存组合适用于 4000 标记输入(会话消耗适用于同一请求中的所有方面)。

容器类型 推荐的 CPU 核心数 建议的内存 说明
摘要 CPU 容器 16 48 GB
摘要 GPU 容器 2 24 GB 需要支持 Cuda 11.8 和 16GB VRAM 的 Nvidia GPU。

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

使用 docker pull 获取容器映像

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

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

使用 docker pull 命令从 Microsoft 容器注册表下载容器映像。

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu

对于 CPU 容器,

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:gpu

用于 GPU 容器。

提示

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

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

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

下载摘要容器模型

运行摘要容器的先决条件是先下载模型。 为此,可以使用 CPU 容器映像作为示例运行以下命令之一:

docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ExtractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=AbstractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ConversationSummarization billing={ENDPOINT_URI} apikey={API_KEY}

不推荐下载同一 HOST_MODELS_PATH 内的所有技能的模型,因为容器会加载 HOST_MODELS_PATH 内的所有模型。 这样做会占用大量内存。 建议仅下载你在特定的 HOST_MODELS_PATH 中所需的技能的模型。

为了确保模型与容器之间的兼容性,请在使用新映像版本创建容器时重新下载已利用的模型。

通过 docker run 运行容器

摘要”容器位于主计算机上后,使用以下 docker run 命令运行容器。 容器将继续运行,直到停止它。 将下面的占位符替换为你自己的值:

占位符 Value 格式或示例
{HOST_MODELS_PATH} 主计算机的卷装载点,Docker 使用它来持久保存模型。 例如 c:\SummarizationModel,其中 c:\ 驱动器位于主机上。
{ENDPOINT_URI} 用于访问摘要 API 的终结点。 可以在 Azure 门户中资源的“密钥和终结点”页上找到此项。 https://<your-custom-subdomain>.cognitiveservices.azure.cn
{API_KEY} 语言资源的密钥。 可以在 Azure 门户中资源的“密钥和终结点”页上找到此项。 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
docker run -p 5000:5000 -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu eula=accept rai_terms=accept billing={ENDPOINT_URI} apikey={API_KEY}

或者,如果运行的是 GPU 容器,请改用此命令。

docker run -p 5000:5000 --gpus all -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:gpu eula=accept rai_terms=accept billing={ENDPOINT_URI} apikey={API_KEY}

如果计算机上有多个 GPU,请将 --gpus all 替换为 --gpus device={DEVICE_ID}

重要

  • 以下各节中的 docker 命令使用反斜杠 \ 作为行继续符。 根据主机操作系统的要求替换或删除字符。
  • 必须指定 EulaBillingrai_termsApiKey 选项才能运行容器,否则容器不会启动。 有关详细信息,请参阅计费

此命令:

  • 通过容器映像运行摘要容器
  • 分配一个 CPU 核心和 4 GB 内存
  • 公开 TCP 端口 5000,并为容器分配伪 TTY
  • 退出后自动删除容器。 容器映像在主计算机上仍然可用。

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

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

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

查询容器的预测终结点

容器提供了基于 REST 的查询预测终结点 API。

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

验证容器是否正在运行

有几种方法可用于验证容器是否正在运行。 找到相关容器的外部 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 标头和正文格式。

容器的主页

停止容器

若要关闭容器,请在运行容器的命令行环境中选择 Ctrl+C

故障排除

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

提示

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

计费

摘要容器使用你的 Azure 帐户中的语言资源向 Azure 发送账单信息。

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

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

连接到 Azure

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

计费参数

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

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

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

总结

在本文中,你学习了摘要容器的下载、安装和运行的相关概念和工作流。 综上所述:

  • 摘要为 Docker 提供 Linux 容器
  • 从 Microsoft 容器注册表 (MCR) 下载容器映像。
  • 容器映像在 Docker 中运行。
  • 必须在实例化容器时指定账单信息。

重要

如果未连接到 Azure 进行计量,则不会授权此容器运行。 客户需要始终让容器向计量服务传送账单信息。 Azure AI 容器不会向 Microsoft 发送客户数据(例如正在分析的文本)。

后续步骤