安裝 Azure AI Vision 3.2 GA 讀取 OCR 容器
容器可讓您在自己的環境中執行 Azure AI 視覺 API。 容器非常適合用於特定的安全性和資料控管需求。 在本文中，您將了解如何下載、安裝及執行 Read (OCR) 容器。
Read 容器可讓您從影像和文件中擷取列印和手寫的文字，並支援 JPEG、PNG、BMP、PDF 和 TIFF 檔案格式。 如需詳細資訊，請參閱讀取 API 操作說明指南。
最新消息
Read 容器的 3.2-model-2022-04-30 GA 版本支援 164 種語言和其他增強功能。 如果您是現有的客戶，請遵循 下載指示 以開始使用。
Read 3.2 OCR 容器是最新的 GA 模型，並提供：
- 增強精確度的新模型。
- 在相同文件中支援多種語言。
- 總共支援 164 種語言。 請參閱 OCR 支援語言的完整清單。
- 適用於文件和映像的單一作業。
- 支援較大的文件和映像。
- 信賴分數。
- 支援列印和手寫文字的文件。
- 能夠只擷取文件中所選頁面的文字。
- 從預設值選擇 [文字行輸出順序]，改為僅限拉丁語言的更自然讀取順序。
- 將文字行分類為手寫樣式，或僅適用於拉丁語言。
如果您目前使用讀取 2.0 容器，請參閱移轉指南，以瞭解新版本中的變更。
必要條件
使用容器之前，您必須符合下列必要條件：
| 必要 | 目的 |
|---|---|
| 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 入口網站 [概觀] 頁面上取得。 移至 [概觀] 頁面，將滑鼠停留在端點上，然後會出現 [複製到剪貼簿] 圖示。 複製端點並用在需要之處。
索引鍵
{API_KEY} 值可用來啟動容器，並可在相對應 Azure AI 服務資源的 Azure 入口網站 [金鑰] 頁面上取得。 移至 [金鑰] 頁面，然後選取 [複製到剪貼簿] 圖示。
重要事項
這些訂用帳戶金鑰可用於存取 Azure AI 服務 API。 請勿共用您的金鑰。 安全地儲存金鑰。 例如，使用 Azure Key Vault。 我們也建議您定期重新產生這些金鑰。 進行 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 容器的資源配置下限和建議。
| 容器 | 最小值 | 建議 |
|---|---|---|
| Read 3.2 2022-04-30 | 4 核心，8 GB 記憶體 | 8 核心，16-GB 記憶體 |
| Read 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 上找到標籤的完整清單。
有下列適用于讀取的容器映射可供使用。
| 容器 | 容器登錄/存放庫/映像名稱 | 標籤 |
|---|---|---|
| Read 3.2 GA | mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 |
最新、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 命令執行容器。 請參閱收集必要參數來了解如何獲得 {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}
上述命令：
- 從容器映像執行 Read 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。 您可以在下列位置檢視 Swagger 路徑：http://localhost:5000/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 存取。 以下是從上一個映像執行 operation-location URL 的 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
}
]
}
]
}
]
}
}
重要
如果您在負載平衡器 (例如 Docker Compose 或 Kubernetes) 後部署多個讀取 OCR 容器，則您必須有外部快取。 因為處理容器和 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 Vision 提供適用于 Docker 的 Linux 容器，並封裝讀取。
- 讀取容器映像需要應用程式才能執行。
- 容器映像是在 Docker 中執行。
- 您可以藉由指定容器的主機 URI，使用 REST API 或 SDK 來呼叫讀取 OCR 容器中的作業。
- 將容器具現化時，您必須指定帳單資訊。
重要
Azure AI 容器若未連線至用於計量的 Azure，即無法獲得執行的授權。 客戶必須啟用容器以持續與計量服務進行帳單資訊的通訊。 Azure AI 容器不會將客戶資料 (例如正在分析的影像或文字) 傳送至 Microsoft。
後續步驟
- 檢閱設定容器以了解組態設定
- 檢閱 OCR 概觀，以深入了解辨識印刷和手寫的文字
- 參閱讀取 API 以取得容器支援方法的詳細資訊。
- 請參閱 常見問題 (常見問題) 來解決與 Azure AI 視覺功能相關的問題。
- 使用更多 Azure AI 容器