安裝 Azure AI 視覺 3.2 GA 讀取 OCR 容器

發行項
05/17/2024

容器可讓您在自己的環境中執行電腦 Azure AI API。容器非常適合用於特定的安全性和資料控管需求。在本文中，您將瞭解如何下載、安裝及執行 Read （OCR）容器。

讀取容器可讓您從影像和檔擷取印刷和手寫文字，並支援 JPEG、PNG、BMP、PDF 和 TIFF 檔格式。如需詳細資訊，請參閱讀取 API 操作指南。

必要條件

使用容器之前，您必須先符合下列必要條件：

必要	目的
Docker 引擎	您必須在主機電腦上安裝 Docker 引擎。 Docker 提供可在 macOS、Windows 和 Linux 上設定 Docker 環境的套件。如需 Docker 和容器基本概念的入門，請參閱 Docker 概觀 \(英文\)。 Docker 必須設定為允許容器與 Azure 連線，以及傳送帳單資料至 Azure。在 Windows 上，Docker 也必須設定為支援 Linux 容器。
熟悉 Docker	您應該對 Docker 概念有基本的瞭解，例如登錄、存放庫、容器和容器映像，以及基本 `docker` 命令的知識。
電腦視覺資源	若要使用容器，您必須具備：電腦視覺資源和相關聯的 API 金鑰 (端點 URI)。這兩個值都可在資源的 [概觀] 和 [金鑰] 頁面上取得，而且必須啟動容器。 {API_KEY}： [金鑰] 頁面上的兩個可用資源索引鍵之一 {ENDPOINT_URI}： [概觀] 頁面上提供的端點

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

收集必要的參數

所有 Azure AI 容器都需要三個主要參數。 Microsoft 軟體授權條款必須具有接受值。也需要端點 URI 和 API 金鑰。

端點 URI

{ENDPOINT_URI} 值可在相對應 Azure AI 服務資源的 Azure 入口網站 [概觀] 頁面上取得。移至 [ 概觀 ] 頁面，將滑鼠停留在端點上，然後 會出現 [複製到剪貼簿 ] 圖示。視需要複製並使用端點。

顯示收集端點 URI 以供稍後使用的螢幕快照。

索引鍵

{API_KEY} 值可用來啟動容器，並可在相對應 Azure AI 服務資源的 Azure 入口網站 [金鑰] 頁面上取得。移至 [ 金鑰 ] 頁面，然後選取 [複製到剪貼簿] 圖示。

顯示取得兩個金鑰之一以供日後使用的螢幕快照。

重要

這些訂用帳戶金鑰可用於存取 Azure AI 服務 API。請勿共用您的金鑰。安全地儲存它們。例如，使用 Azure 金鑰保存庫。我們也建議您定期重新產生這些密鑰。呼叫 API 只需一把金鑰。當您重新產生第一個金鑰時，您可以使用第二個金鑰繼續存取服務。

主機電腦需求

主機是執行 Docker 容器的 x64 型電腦。它可以是您內部部署的電腦，或是在 Azure 中裝載服務的 Docker，例如：

Azure Kubernetes Service。
Azure 容器執行個體。
部署至 Azure Stack 的 Kubernetes \(英文\) 叢集。如需詳細資訊，請參閱將 Kubernetes 部署至 Azure Stack。

進階向量延伸模組支援

主電腦是執行 Docker 容器的電腦。主機 必須支援進階向量延伸模組（AVX2）。您可以使用下列命令檢查 Linux 主機上的 AVX2 支援：

grep -q avx2 /proc/cpuinfo && echo AVX2 supported || echo No AVX2 support detected

警告

需要主計算機才能支援AVX2。 容器無法在沒有AVX2支援的情況下正確運作。

容器的需求和建議

注意

這些需求和建議是以每秒單一要求的基準為基礎，使用已掃描商務信件的 523 KB 映像 (包含 29 行，共 803 個字元)。相較於最小設定，建議的設定會產生大約 2 倍的回應。

下表描述每個讀取 OCR 容器的資源下限和建議配置。

容器	最小值	建議需求
讀取 3.2 2022-04-30	4 核心，8 GB 記憶體	8 核心，16-GB 記憶體
閱讀 3.2 2021-04-12	4 核心，16 GB 記憶體	8 核心、24 GB 記憶體

每個核心必須至少 2.6 GHz 或更快。

核心和記憶體會對應至 --cpus 和 --memory 設定，這些設定會當做命令的 docker run 一部分使用。

取得容器映像

您可以在 mcr.microsoft.com 容器登錄聯盟上找到 Azure AI 視覺讀取 OCR 容器映像。其位於 azure-cognitive-services 存放庫內，並命名為 read。完整容器映像名稱為 mcr.microsoft.com/azure-cognitive-services/vision/read

若要使用最新版本的容器，您可以使用 latest 標記。您也可以在 MCR 上找到標記的完整清單。

下列是可使用讀取的容器映像。

容器	Container Registry / 存放庫 / 映射名稱	標籤
讀取 3.2 GA	`mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30`	latest， 3.2， 3.2-model-2022-04-30

docker pull使用命令來下載容器映像。

docker pull mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30

提示

您可以使用 docker images \(英文\) 命令來列出已下載的容器映像。例如，下列命令會列出每個已下載之容器映像的識別碼、存放庫和標籤，並將它格式化為表格：

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

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

如何使用容器

容器在主計算機上之後，請使用下列程式來處理容器。

使用必要的計費設定執行容器。有更多命令範例docker run可供使用。
查詢容器的預測端點。

執行容器

使用 docker run 命令來執行容器。如需如何取得 {ENDPOINT_URI} 和 {API_KEY} 值的詳細資訊，請參閱收集必要的參數。

命令的docker run範例可供使用。

docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

上述命令：

從容器映像執行讀取 OCR 最新 GA 容器。
配置 8 個 CPU 核心和 16 GB 的記憶體。
公開 TCP 連接埠 5000，並為容器配置虛擬 TTY。
在容器結束之後自動將其移除。容器映像仍可在主機電腦上使用。

您也可以使用環境變數來執行容器：

docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
--env Eula=accept \
--env Billing={ENDPOINT_URI} \
--env ApiKey={API_KEY} \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30

有更多命令範例docker run可供使用。

重要

必須指定 Eula、Billing 及 ApiKey 選項以執行容器，否則容器將不會啟動。如需詳細資訊，請參閱帳單。

如果您需要更高的輸送量（例如，處理多頁檔案時），請考慮使用 Azure 儲存體和 Azure 佇列在 Kubernetes 叢集上部署多個容器。

如果您使用 Azure 儲存體來儲存影像進行處理，您可以在呼叫容器時建立要使用的連接字串。

若要尋找您的連接字串：

流覽至 Azure 入口網站上的儲存體帳戶，然後尋找您的帳戶。
在左側導覽清單中，選取 [存取金鑰]。
您的連接字串位於連線字串下方

在相同主機上執行多個容器

如果您打算使用公開的連接埠執行多個容器，請務必使用不同的公開連接埠來執行每個容器。例如，在連接埠 5000 上執行第一個容器，以及在連接埠 5001 上執行第二個容器。

您可以讓此容器和不同的 Azure AI 服務容器在主機上一起執行。您也可以針對相同的 Azure AI 服務容器執行多個容器。

驗證容器正在執行

有數種方式可驗證容器正在執行。找出有問題容器的外部 IP 位址和公開的連接埠，然後開啟您最愛的網頁瀏覽器。使用下列各項要求 URL，以驗證容器是否正在執行。此處列出的範例要求 URL 為 http://localhost:5000，但您的特定容器可能會有所不同。請務必依賴您容器的「外部 IP」位址和公開的連接埠。

要求 URL	目的
`http://localhost:5000/`	容器會提供首頁。
`http://localhost:5000/ready`	以 GET 提出要求，此 URL 將會驗證容器是否已準備好接受對模型的查詢。此要求可用來進行 Kubernetes 活躍度和整備度探查 \(英文\)。
`http://localhost:5000/status`	也會以 GET 提出要求，此 URL 會在不需進行端點查詢的同時，確認用來啟動容器的 API 金鑰是否有效。此要求可用來進行 Kubernetes 活躍度和整備度探查 \(英文\)。
`http://localhost:5000/swagger`	容器會為端點提供一組完整的文件和立即試用功能。使用此功能，您可以將自己的設定輸入至以 Web 為基礎的 HTML 表單並進行查詢，而無須撰寫任何程式碼。當查詢傳回時，會提供範例 CURL 命令來示範所需的 HTTP 標頭和本文格式。

容器的首頁

查詢容器的預測端點

容器會提供以 REST 為基礎的查詢預測端點 API。

請對容器 API 使用主機 http://localhost:5000。您可以在： http://localhost:5000/swagger/檢視 Swagger 路徑。

異步讀取

您可以將 POST /vision/v3.2/read/analyze 和 GET /vision/v3.2/read/operations/{operationId} 作業一同使用，以非同步地讀取映像，類似 Azure AI 視覺服務使用那些相對應 REST 作業的方式。非同步 POST 方法會傳回 operationId，做為 HTTP GET 要求的識別碼。

從 Swagger UI 中，選取 Analyze 以在瀏覽器中展開它。然後選取 [試用>選擇檔案]。 在此範例中，我們將使用下列影像：

索引標籤與空格

當異步 POST 成功執行時，它會傳 回 HTTP 202 狀態代碼。在回應中，有一個 operation-location 標頭會保存要求的結果端點。

 content-length: 0
 date: Fri, 04 Sep 2020 16:23:01 GMT
 operation-location: http://localhost:5000/vision/v3.2/read/operations/a527d445-8a74-4482-8cb3-c98a65ec7ef9
 server: Kestrel

operation-location是完整的 URL，可透過 HTTP GET 存取。以下是從上圖執行 URL 的 operation-location JSON 回應：

{
  "status": "succeeded",
  "createdDateTime": "2021-02-04T06:32:08.2752706+00:00",
  "lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",
  "analyzeResult": {
    "version": "3.2.0",
    "readResults": [
      {
        "page": 1,
        "angle": 2.1243,
        "width": 502,
        "height": 252,
        "unit": "pixel",
        "lines": [
          {
            "boundingBox": [
              58,
              42,
              314,
              59,
              311,
              123,
              56,
              121
            ],
            "text": "Tabs vs",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.96
              }
            },
            "words": [
              {
                "boundingBox": [
                  68,
                  44,
                  225,
                  59,
                  224,
                  122,
                  66,
                  123
                ],
                "text": "Tabs",
                "confidence": 0.933
              },
              {
                "boundingBox": [
                  241,
                  61,
                  314,
                  72,
                  314,
                  123,
                  239,
                  122
                ],
                "text": "vs",
                "confidence": 0.977
              }
            ]
          },
          {
            "boundingBox": [
              286,
              171,
              415,
              165,
              417,
              197,
              287,
              201
            ],
            "text": "paces",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.746
              }
            },
            "words": [
              {
                "boundingBox": [
                  286,
                  179,
                  404,
                  166,
                  405,
                  198,
                  290,
                  201
                ],
                "text": "paces",
                "confidence": 0.938
              }
            ]
          }
        ]
      }
    ]
  }
}

重要

如果您在負載平衡器後方部署多個讀取 OCR 容器，例如，在 Docker Compose 或 Kubernetes 下，您必須有外部快取。因為處理容器和 GET 要求容器可能不相同，因此外部快取會儲存結果，並跨容器共享結果。如需快取設定的詳細資料，請參閱設定 Azure AI 視覺 Docker 容器。

同步讀取

您可以使用下列作業來同步讀取映像。

POST /vision/v3.2/read/syncAnalyze

當映像完整讀取時，則 API 只會傳回 JSON 回應。行為唯一的例外狀況是發生錯誤。如果發生錯誤時，會傳回下列 JSON：

{
    "status": "Failed"
}

JSON 回應對象與異步版本具有相同的物件圖形。如果您是 JavaScript 使用者且想要類型安全性，請考慮使用 TypeScript 來轉換 JSON 回應。

如需範例使用案例，請參閱這裡的 TypeScript 沙盒，然後選取 [ 執行 ] 以可視化其易於使用。

執行與網際網路中斷連線的容器

若要使用此與網際網路中斷連線的容器，您必須先填寫申請表並購買承諾用量方案來要求存取權。如需詳細資訊，請參閱「在中斷連線環境中使用 Docker 容器」。

如果您已獲核准執行與網際網路中斷連線的容器，請使用下列範例顯示您會使用之 docker run 命令的格式設定以及預留位置值。以您自己的值取代這些佔位元值。

您 docker run 命令中的 DownloadLicense=True 參數會下載授權檔案，讓您的 Docker 容器可在未連線至網際網路時執行。它也包含到期日，之後授權檔將無效來執行容器。您只能搭配已核准的適當容器使用授權檔案。例如，您無法將語音轉換文字容器的授權檔案和文件智慧容器搭配使用。

預留位置	值	格式或範例
`{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=容器本機檔系統上授權資料夾的位置。也必須指定輸出掛接，以便寫入計費使用量記錄。

預留位置	值	格式或範例
`{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 容器常見問題（常見問題）。

如果您在執行 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}

容器會測試帳單端點的網路連線能力。

計費

Azure AI 容器會使用 Azure 帳戶上的對應資源，將帳單資訊傳送至 Azure。

針對容器的查詢，會以 ApiKey 參數使用的 Azure 資源定價層來計費。

Azure AI 服務容器若未連線至計量或計費端點，即無法獲得執行的授權。您必須讓容器隨時都能與計量端點進行帳單資訊的通訊。 Azure AI 服務容器不會將客戶資料 (例如正在分析的影像或文字) 傳送給 Microsoft。

連接到 Azure

容器需要計費引數值才能執行。這些值讓容器能夠連線到計費端點。容器會每隔 10 到 15 分鐘回報使用量。如果容器未在允許的時間範圍內連線到 Azure，容器會繼續執行，但在還原計費端點之前不會提供查詢。以 10 到 15 分鐘的相同時間間隔嘗試連線 10 次。如果無法在 10 次嘗試內連線到計費端點，容器會停止處理要求。請參閱「Azure AI 服務容器常見問題集」，以獲得需傳送哪些資訊給 Microsoft 以供計費的範例。

計費引數

當下列三個選項都提供有效值時，此命令 docker run 會啟動容器：

選項	描述
`ApiKey`	Azure AI 服務資源的 API 金鑰，用於追蹤計費資訊。此選項值必須設定為已佈建 `Billing` 指定資源的 API 金鑰。
`Billing`	Azure AI 服務資源的端點，用於追蹤計費資訊。此選項的值必須設定為已佈建 Azure 資源的端點 URI。
`Eula`	表示您接受容器的授權。此選項的值必須設定為接受。

如需這些選項的詳細資訊，請參閱設定容器。

摘要

在本文中，您已了解下載、安裝及執行 Azure AI 視覺容器的概念和工作流程。摘要中：

Azure AI 視覺提供適用於 Docker 的 Linux 容器，並封裝讀取。
讀取容器映像需要應用程式才能執行它。
容器映像是在 Docker 中執行。
您可以藉由指定容器的主機 URI，使用 REST API 或 SDK 來呼叫讀取 OCR 容器中的作業。
將容器具現化時，您必須指定帳單資訊。

重要

Azure AI 容器若未連線至用於計量的 Azure，即無法獲得執行的授權。客戶必須啟用容器以持續與計量服務進行帳單資訊的通訊。 Azure AI 容器不會將客戶資料 (例如正在分析的影像或文字) 傳送至 Microsoft。

下一步

檢閱設定容器以了解組態設定
檢閱 OCR 概觀以深入了解辨識印刷和手寫文字
參閱讀取 API 以取得容器支援的方法的詳細資訊。
參閱常見問題集 (FAQ) 來解決與 Azure AI 視覺功能相關的問題。
使用更多 Azure AI 容器

共用方式為