安装和运行容器

此内容适用于：🟩v3.0 （正式版）🟩v3.1 （正式版）🟩v4.0 （正式版）

Azure文档智能是一项Azure AI 服务，可用于使用机器学习技术构建自动化数据处理软件。 使用文档智能，可以从文档中识别并提取文本、键值对、选择标记、表数据等内容。 结果以结构化数据的形式提供，其中包含原始文件中的关系。 容器仅处理提供给它们的数据，并仅利用它们有权访问的资源。 容器无法处理来自其他区域的数据。

在本文中，你可以了解如何下载、安装和运行文档智能容器。 使用容器，可以在自己的环境中运行文档智能服务。 容器非常适合用于满足特定的安全性和数据管理要求。

  • 文档智能 v4.0 容器支持读取模型布局模型。

  • 文档智能 v3.1 容器支持 读取、布局、身份证件、收据和 发票 模型。

  • 文档智能 v3.0 容器支持 读取、布局、常规文档、名片和 自定义等模型。

版本支持

目前，文档智能版本 v3.0: 2022-08-31 (GA) 对所有模型均支持容器，v3.1 2023-07-31 (GA) 对读取、布局、ID 文档、收据和发票模型支持容器，v4.0 2024-11-30 (GA) 对读取和布局模型支持容器：

先决条件

若要开始，你需要一个有效的 Azure 帐户。 如果没有，可以创建一个试用帐户。

你还需要以下资源才能使用文档智能容器：

必填 目的
熟悉 Docker 应对 Docker 概念有基本的了解，例如注册表、存储库、容器和容器映像，以及基本的 docker术语和命令的知识。
已安装 Docker 引擎
  • 需要在主计算机上安装 Docker 引擎。 Docker 提供用于在 macOS、Windows 和 Linux 上配置 Docker 环境的包。 有关 Docker 和容器的基础知识，请参阅 Docker 概述。
  • 必须将 Docker 配置为允许容器连接 Azure 并向其发送账单数据。
  • 在 Windows 上，还必须将 Docker 配置为支持 Linux 容器 。
文档智能资源 Azure 门户中的单服务 Azure 文档智能或多服务资源。 若要使用这些容器，必须具有关联的密钥和终结点 URI。 这两个值可以从 Azure 门户文档智能的“密钥和终结点”页获取：
  • {FORM_RECOGNIZER_KEY}：两个可用资源密钥之一。
  • {FORM_RECOGNIZER_ENDPOINT_URI}：用于跟踪计费信息的资源终结点。
可选 目的
Azure CLI（命令行接口） Azure CLI 使你能够使用一组联机命令来创建和管理 Azure 资源。 它可用于在 Windows、macOS 和 Linux 环境中安装，并且可在 Docker 容器和 Azure Cloud Shell 中运行。

主机计算机要求

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

注意

无法在 Azure Kubernetes 服务中部署和运行 Studio 容器。 仅支持在本地计算机上运行 Studio 容器。

容器要求和建议

所需的配套容器

下表列出了你下载的每个文档智能容器对应的一个或多个配套容器。 有关详细信息，请参阅计费部分。

功能容器 支持的容器
读取 不是必需
布局 不是必需
名片 读取
常规文档 布局
发票 布局
回执 阅读 或 布局
身份证件 读取
自定义模板 布局

注意

最小值和建议值基于 Docker 限制，而不是基于主机资源。

文档智能容器
容器 最小值 建议
Read 8 核，10 GB 内存 8 个内核，24 GB 内存
Layout 8 核，16 GB 内存 8 个内核，24 GB 内存
Business Card 8 核，16 GB 内存 8 个内核，24 GB 内存
General Document 8 核，12 GB 内存 8 个内核，24 GB 内存
ID Document 8 个内核，8 GB 内存 8 个内核，24 GB 内存
Invoice 8 核，16 GB 内存 8 个内核，24 GB 内存
Receipt 8 核，11 GB 内存 8 个内核，24 GB 内存
Custom Template 8 核，16 GB 内存 8 个内核，24 GB 内存
  • 每个核心必须至少为 2.6 千兆赫 (GHz) 或更快。
  • 核心和内存对应于 --cpus 和 --memory 设置，用作 docker compose 或 docker run 命令的一部分。

提示

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

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

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

使用 docker-compose up 命令运行容器

  • 将 {ENDPOINT_URI} 和 {API_KEY} 值替换为“Azure 资源”页中的资源终结点 URI 和密钥。

    Azure 门户“密钥和终结点”页面的屏幕截图。

  • 确保 EULA 值设置为“接受”。

  • 必须指定 EULA、Billing 和 ApiKey 值；否则容器将无法启动。

重要

密钥用于访问文档智能资源。 请勿共享密钥。 以安全方式存储密钥（例如，使用 Azure 密钥保管库 来存储）。 此外，我们建议定期重新生成这些密钥。 发出 API 调用只需一个密钥。 重新生成第一个密钥时，可以使用第二个密钥来持续访问服务。

以下代码示例是独立的docker compose示例，用于运行文档智能布局容器。 利用 docker compose，可以使用 YAML 文件来配置应用程序服务。 然后，通过 docker-compose up 命令基于配置创建并启动所有服务。 为你的布局容器实例输入 {FORM_RECOGNIZER_ENDPOINT_URI} 和 {FORM_RECOGNIZER_KEY} 的值。

version: "3.9"
services:
  azure-form-recognizer-layout:
    container_name: azure-form-recognizer-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-4.0
    environment:
      - EULA=accept
      - billing={FORM_RECOGNIZER_ENDPOINT_URI}
      - apiKey={FORM_RECOGNIZER_KEY}
    ports:
      - "5000:5000"
    networks:
      - ocrvnet
networks:
  ocrvnet:
    driver: bridge

现在，则可以通过 docker compose 命令启动该服务：

docker-compose up

使用 docker-compose up 命令运行容器

  • 将 {ENDPOINT_URI} 和 {API_KEY} 值替换为“Azure 资源”页中的资源终结点 URI 和密钥。

    Azure 门户“密钥和终结点”页面的屏幕截图。

  • 确保 EULA 值设置为“接受”。

  • 必须指定 EULA、Billing 和 ApiKey 值；否则容器将无法启动。

重要

密钥用于访问文档智能资源。 请勿共享密钥。 以安全方式存储密钥（例如，使用 Azure 密钥保管库 来存储）。 此外，我们建议定期重新生成这些密钥。 发出 API 调用只需一个密钥。 重新生成第一个密钥时，可以使用第二个密钥来持续访问服务。

以下代码示例是独立的docker compose示例，用于运行文档智能布局容器。 利用 docker compose，可以使用 YAML 文件来配置应用程序服务。 然后，通过 docker-compose up 命令基于配置创建并启动所有服务。 为你的布局容器实例输入 {FORM_RECOGNIZER_ENDPOINT_URI} 和 {FORM_RECOGNIZER_KEY} 的值。

version: "3.9"
services:
  azure-form-recognizer-layout:
    container_name: azure-form-recognizer-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1
    environment:
      - EULA=accept
      - billing={FORM_RECOGNIZER_ENDPOINT_URI}
      - apiKey={FORM_RECOGNIZER_KEY}
    ports:
      - "5000:5000"
    networks:
      - ocrvnet
networks:
  ocrvnet:
    driver: bridge

现在，则可以通过 docker compose 命令启动该服务：

docker-compose up

创建一个 docker compose 文件

  1. 将此文件命名为 docker-compose.yml

  2. 以下代码示例是独立的 docker compose 示例，可以同时运行文档智能布局、Studio 和自定义模板容器。 利用 docker compose，可以使用 YAML 文件来配置应用程序服务。 然后，通过 docker-compose up 命令基于配置创建并启动所有服务。

version: '3.3'
services:
  nginx:
    image: nginx:alpine
    container_name: reverseproxy
    depends_on:
      - layout
      - custom-template
    volumes:
      - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
    ports:
      - "5000:5000"
  layout:
    container_name: azure-cognitive-service-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest
    environment:
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  custom-template:
    container_name: azure-cognitive-service-custom-template
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/custom-template-3.0:latest
    restart: always
    depends_on:
      - layout
    environment:
      AzureCognitiveServiceLayoutHost: http://azure-cognitive-service-layout:5000
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  studio:
    container_name: form-recognizer-studio
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:3.0
    environment:
      ONPREM_LOCALFILE_BASEPATH: /onprem_folder
      STORAGE_DATABASE_CONNECTION_STRING: /onprem_db/Application.db
    volumes:
      - type: bind
        source: ${FILE_MOUNT_PATH} # path to your local folder
        target: /onprem_folder
      - type: bind
        source: ${DB_MOUNT_PATH} # path to your local folder
        target: /onprem_db
    ports:
      - "5001:5001"
    user: "1000:1000" # echo $(id -u):$(id -g)

创建一个 docker compose 文件

  1. 将此文件命名为 docker-compose.yml

  2. 以下代码示例是独立的 docker compose 示例，可以同时运行文档智能布局、Studio 和自定义模板容器。 利用 docker compose，可以使用 YAML 文件来配置应用程序服务。 然后，通过 docker-compose up 命令基于配置创建并启动所有服务。

version: '3.3'
services:
  nginx:
    image: nginx:alpine
    container_name: reverseproxy
    depends_on:
      - layout
      - custom-template
    volumes:
      - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
    ports:
      - "5000:5000"
  layout:
    container_name: azure-cognitive-service-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1:latest
    environment:
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  custom-template:
    container_name: azure-cognitive-service-custom-template
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/custom-template-3.1:latest
    restart: always
    depends_on:
      - layout
    environment:
      AzureCognitiveServiceLayoutHost: http://azure-cognitive-service-layout:5000
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  studio:
    container_name: form-recognizer-studio
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:3.1
    environment:
      ONPREM_LOCALFILE_BASEPATH: /onprem_folder
      STORAGE_DATABASE_CONNECTION_STRING: /onprem_db/Application.db
    volumes:
      - type: bind
        source: ${FILE_MOUNT_PATH} # path to your local folder
        target: /onprem_folder
      - type: bind
        source: ${DB_MOUNT_PATH} # path to your local folder
        target: /onprem_db
    ports:
      - "5001:5001"
    user: "1000:1000" # echo $(id -u):$(id -g)

自定义模板容器和布局容器可以使用 Azure 存储队列或内存队列。 仅当使用 Azure 存储队列时，才需要设置 Storage:ObjectStore:AzureBlob:ConnectionString 和 queue:azure:connectionstring 环境变量。 在本地运行时，请删除这些变量。

确保该服务正在运行

确保该服务已启动并正在运行。 在 Ubuntu shell 中运行这些命令。

$cd <folder containing the docker-compose file>

$source .env

$docker-compose up

自定义模板容器需要几个不同的配置，并支持其他可选配置。

设置 必填 说明
EULA 是 许可证接受示例：Eula=accept
计费 是 FR 资源的计费终结点 URI
API 密钥 是 FR 资源的终结点密钥
Queue:Azure:ConnectionString 否 Azure 队列连接字符串
存储:对象存储:AzureBlob:连接字符串 否 Azure Blob 连接字符串
HealthCheck:MemoryUpperboundInMB 否 用于报告运行不正常的内存阈值。 默认值：与建议的内存相同
存储生存时间（分钟） 否 删除所有中间文件和最终文件所需的 TTL 时间。 默认值：两天，TTL 可设置的值为 5 分钟到 7 天
任务:最长运行时间跨度（分钟） 否 将请求视为超时的最大运行时间。默认值：60 分钟
HTTP_PROXY_BYPASS_URLS 否 指定绕过代理的 URL 示例：HTTP_PROXY_BYPASS_URLS = abc.com，xyz.com
AzureCognitiveServiceReadHost（仅限收据和 IdDocument 容器） 是 指定 Read 容器 URI 示例：AzureCognitiveServiceReadHost=http://onprem-frread:5000
AzureCognitiveServiceLayoutHost（仅适用于文档和发票容器） 是 指定布局容器 uri 示例：AzureCognitiveServiceLayoutHost=http://onprem-frlayout:5000

使用文档智能工作室训练模型

  • 收集一组至少五份相同类型的表单。 使用此数据训练模型并测试表单。 可使用示例数据集（下载并提取 sample_data.zip）。

  • 确认容器正在运行后，打开浏览器并导航到部署了容器的终结点。 如果此部署是本地计算机，则终结点为 [http://localhost:5001](http://localhost:5001)。

  • 选择自定义提取模型磁贴。

  • 选择Create project选项

  • 提供项目名称和说明（可选）

  • 在“配置资源”步骤中，提供自定义模板模型的终结点。 如果在本地计算机上部署了容器，请使用此 URL [http://localhost:5000](http://localhost:5000)。

  • 为训练数据在 files 文件夹中的位置提供子文件夹。

  • 最后，创建项目

现在你应该已经创建好了一个项目，可以开始标注了。 上传训练数据并开始标记。 如果你不熟悉标记，请参阅生成和训练自定义模型。

使用 API 进行训练

如果打算直接调用 API 来训练模型，则自定义模板模型训练 API 需要 base64 编码的 zip 文件，该文件是标记项目的内容。 可以省略 PDF 或图像文件，并仅提交 JSON 文件。

标记数据并将 *.ocr.json、*.labels.json 和 fields.json 文件添加到 zip 后，请使用 PowerShell 命令生成 base64 编码的字符串。

$bytes = [System.IO.File]::ReadAllBytes("<your_zip_file>.zip")
$b64String = [System.Convert]::ToBase64String($bytes, [System.Base64FormattingOptions]::None)

使用生成模型 API 发布请求。


  POST http://localhost:5000/formrecognizer/documentModels:build?api-version=2023-07-31

  {
      "modelId": "mymodel",
      "description": "test model",
      "buildMode": "template",

      "base64Source": "<Your base64 encoded string>",
      "tags": {
         "additionalProp1": "string",
         "additionalProp2": "string",
         "additionalProp3": "string"
       }
  }

验证该服务是否正在运行

有几种方法可用于验证容器是否正在运行：

  • 容器在 \ 处提供主页作为容器正在运行的视觉验证。

  • 可以打开你常用的 Web 浏览器并导航到相关容器的外部 IP 地址和公开端口。 使用列出的请求 URL 验证容器是否正在运行。 列出的示例请求 URL 是 http://localhost:5000，但是特定容器可能会有所不同。 请记住，你访问的是容器的 外部 IP 地址 和暴露的端口。

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

屏幕截图：Azure 容器欢迎页。

停止容器

若要停止容器，请使用以下命令：

docker-compose down

计费

文档智能容器使用 Azure 帐户上的文档智能资源将账单信息发送到 Azure。

对该容器的查询将按照用于 API Key 的 Azure 资源的定价层级计费。 针对用于处理文档和映像的每个容器实例计费。

如果收到以下错误：“容器未处于有效状态。订阅验证失败，状态为‘OutOfQuota’的 API 密钥超出配额”。 这是一个指标，表明容器不与计费终结点通信。

连接到 Azure

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

计费参数

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

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

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

摘要

就这么简单！ 在本文中，我们学习了下载、安装和运行文档智能容器的概念与工作流。 综上所述：

  • 文档智能提供 7 个适用于 Docker 的 Linux 容器。
  • 容器映像可从 mcr 下载。
  • 容器映像在 Docker 中运行。
  • 在实例化容器时必须指定账单信息。

重要

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

后续步骤

  • Last updated on