使用英语阅读

通过

安装和运行容器

  • 项目

此内容适用于：选中标记 v3.0 (GA) 选中标记 v3.1 (GA)

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

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

  • 文档智能 v3.1 容器支持“读取”、“布局”、“ID 文档”、“收据”和“发票”模型。

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

版本支持

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

先决条件

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

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

必需 目的
熟悉 Docker 应对 Docker 概念有基本的了解，例如注册表、存储库、容器和容器映像，以及基本的 docker 术语和命令的知识。
已安装 Docker 引擎
  • 需要在主计算机上安装 Docker 引擎。 Docker 提供用于在 macOS、Windows 和 Linux 上配置 Docker 环境的包。 有关 Docker 和容器的基础知识，请参阅 Docker 概述。
  • 必须将 Docker 配置为允许容器连接 Azure 并向其发送账单数据。
  • 在 Windows 上，还必须将 Docker 配置为支持 Linux 容器 。
文档智能资源 Azure 门户中的单服务 Azure AI 文档智能或多服务资源。 若要使用这些容器，必须具有关联的密钥和终结点 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 容器。 仅支持在本地计算机上运行工作室容器。

容器要求和建议

所需的配套容器

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

功能容器 支持容器
读取 不是必需
布局 不是必需
名片 读取
常规文档 布局
发票 布局
回执 读取或布局
ID 文档 读取
自定义模板 Layout

备注

最小值和建议值基于 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 Key Vault 来存储）。 此外，我们建议定期重新生成这些密钥。 发出 API 调用只需一个密钥。 重新生成第一个密钥时，可以使用第二个密钥来持续访问服务。

除了先决条件之外，还需要执行以下操作才能处理自定义文档：

创建一个文件夹并存储以下文件

创建一个文件夹并存储输入数据

  • 将此文件夹命名为 files。
  • 我们将以 {FILE_MOUNT_PATH} 形式引用此文件夹的文件路径。
  • 将文件路径复制到方便的位置，需要将其添加到 .env 文件。 例如，如果文件夹名为“文件”（与 docker-compose 文件位于同一文件夹中），则 .env 文件条目为 FILE_MOUNT_PATH="./files"

在本地计算机上创建文件夹，用于存储由文档智能服务写入的日志

  • 将此文件夹命名为 output。
  • 我们将以 {OUTPUT_MOUNT_PATH} 形式引用此文件夹的文件路径。
  • 将文件路径复制到方便的位置，需要将其添加到 .env 文件。 例如，如果文件夹名为“输出”（与 docker-compose 文件位于同一文件夹中），则 .env 文件条目为 OUTPUT_MOUNT_PATH="./output"

创建一个文件夹，用于存储容器之间共享的内部处理

  • 将此文件夹命名为 shared。
  • 我们将以 {SHARED_MOUNT_PATH} 形式引用此文件夹的文件路径。
  • 将文件路径复制到方便的位置，需要将其添加到 .env 文件。 例如，如果文件夹名为“共享”（与 docker-compose 文件位于同一文件夹中），则 .env 文件条目为 SHARED_MOUNT_PATH="./share"
  • 将此文件夹命名为 db。
  • 我们将以 {DB_MOUNT_PATH} 形式引用此文件夹的文件路径。
  • 将文件路径复制到方便的位置，需要将其添加到 .env 文件。 例如，如果文件夹名为“db”（与 docker-compose 文件位于同一文件夹中），则 .env 文件条目为 DB_MOUNT_PATH="./db"

创建环境文件

  1. 将此文件命名为 .env。

  2. 声明以下环境变量：

SHARED_MOUNT_PATH="./share"
OUTPUT_MOUNT_PATH="./output"
FILE_MOUNT_PATH="./files"
DB_MOUNT_PATH="./db"
FORM_RECOGNIZER_ENDPOINT_URI="YourFormRecognizerEndpoint"
FORM_RECOGNIZER_KEY="YourFormRecognizerKey"
NGINX_CONF_FILE="./nginx.conf"

创建一个 nginx 文件

  1. 将此文件命名为 nginx.conf。

  2. 输入以下配置：

worker_processes 1;

events { worker_connections 1024; }

http {

    sendfile on;
    client_max_body_size 90M;
    upstream docker-custom {
        server azure-cognitive-service-custom-template:5000;
    }

    upstream docker-layout {
        server  azure-cognitive-service-layout:5000;
    }

    server {
        listen 5000;

        location = / {
            proxy_set_header Host $host:$server_port;
            proxy_set_header Referer $scheme://$host:$server_port;
            proxy_pass http://docker-custom/;
        }

        location /status {
            proxy_pass http://docker-custom/status;
        }

        location /test {
            return 200 $scheme://$host:$server_port;
        }

        location /ready {
            proxy_pass http://docker-custom/ready;
        }

        location /swagger {
            proxy_pass http://docker-custom/swagger;
        }

        location /formrecognizer/documentModels/prebuilt-layout {
            proxy_set_header Host $host:$server_port;
            proxy_set_header Referer $scheme://$host:$server_port;

            add_header 'Access-Control-Allow-Origin' '*' always;
            add_header 'Access-Control-Allow-Headers' 'cache-control,content-type,ocp-apim-subscription-key,x-ms-useragent' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
            add_header 'Access-Control-Expose-Headers' '*' always;

            if ($request_method = 'OPTIONS') {
                return 200;
            }

            proxy_pass http://docker-layout/formrecognizer/documentModels/prebuilt-layout;
        }

        location /formrecognizer/documentModels {
            proxy_set_header Host $host:$server_port;
            proxy_set_header Referer $scheme://$host:$server_port;

            add_header 'Access-Control-Allow-Origin' '*' always;
            add_header 'Access-Control-Allow-Headers' 'cache-control,content-type,ocp-apim-subscription-key,x-ms-useragent' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, DELETE' always;
            add_header 'Access-Control-Expose-Headers' '*' always;

            if ($request_method = 'OPTIONS') {
                return 200;
            }

            proxy_pass http://docker-custom/formrecognizer/documentModels;
        }

        location /formrecognizer/operations {
            add_header 'Access-Control-Allow-Origin' '*' always;
            add_header 'Access-Control-Allow-Headers' 'cache-control,content-type,ocp-apim-subscription-key,x-ms-useragent' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE, PATCH' always;
            add_header 'Access-Control-Expose-Headers' '*' always;

            if ($request_method = OPTIONS ) {
                return 200;
            }

            proxy_pass http://docker-custom/formrecognizer/operations;
        }
    }
}

创建 docker 编译文件

  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.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)

自定义模板容器和布局容器可以使用 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
ApiKey 是 FR 资源的终结点密钥
Queue:Azure:ConnectionString 否 Azure 队列连接字符串
Storage:ObjectStore:AzureBlob:ConnectionString 否 Azure Blob 连接字符串
HealthCheck:MemoryUpperboundInMB 否 用于报告运行不正常的内存阈值。 默认值：与建议的内存相同
StorageTimeToLiveInMinutes 否 删除所有中间文件和最终文件的 TTL 持续时间。 默认值：两天，TTL 可设置的值为 5 分钟到 7 天
Task:MaxRunningTimeSpanInMinutes 否 将请求视为超时的最大运行时间。 默认值：60 分钟
HTTP_PROXY_BYPASS_URLS 否 指定绕过代理的 URL 示例：HTTP_PROXY_BYPASS_URLS = abc.com，xyz.com
AzureCognitiveServiceReadHost (收据，仅 IdDocument 容器) 是 指定读取容器 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

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

计费参数

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

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

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

摘要

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

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

重要

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

后续步骤