如何控制C#中的平行OCR記憶體使用量
每個由IronOCR平行處理的頁面都會分配其自己本機的Tesseract引擎實例。 對於大量批次 - 來自掃描PDF或圖片資料夾的數百頁 - 記憶體消耗隨著同時處理頁面的數量線性增長。 IronTesseract.MaxDegreeOfParallelism 屬性限制在單個 Read 呼叫中同時進行 OCR 的頁面數量,並在設置為 false 時切換為完全順序處理的 IronTesseract.MultiThreaded。
設定單一屬性來限制IronOCR一次讀取的頁面數量,保持峰值記憶體在預算範圍內。
-
1使用 IronOCR 安裝 NuGet Package Manager
-
2複製並運行這段程式碼。
var ocr = new IronOcr.IronTesseract { MaxDegreeOfParallelism = 4 };Dim ocr = New IronOcr.IronTesseract With { .MaxDegreeOfParallelism = 4 }Dim ocr = New IronOcr.IronTesseract With { .MaxDegreeOfParallelism = 4 } -
3部署到您的生產環境進行測試
立即在您的項目中開始使用 IronOCR,並使用 免費試用
最小工作流程(5 個步驟)
- 通過NuGet安裝IronOCR來控制OCR平行度
- 建立一個
IronTesseract實例 - 將
MaxDegreeOfParallelism設置為所需上限 - 將頁面載入
OcrInput - 呼叫
Read- 僅限設定上限的頁面數量同時處理
為什麼在大批次中OCR記憶體會增長?
當 MultiThreaded 為 true(默認值)時,IronOCR 在並行處理頁面。 每個同時進行的頁面啟動其自己本機的Tesseract引擎,持有影像緩衝區、識別模組和未管理記憶體中的中間狀態。
因此,Read呼叫的峰值記憶體由兩個部分組成,其中只有一個受到您的控制:
- 文檔本身的固定成本,無論如何安排頁面,它隨頁數增長。
- 同時讀取每頁的邊際成本,各自的本機引擎。
MaxDegreeOfParallelism僅作用於第二項。 這種區分很重要:在一個長文檔中,固定成本可能是較大的一部分,因此限制平行處理可以大幅度減少峰值記憶體而不會將其降至零。
在容器環境中 - Docker具有固定的--memory限制,Kubernetes pods具有資源配額 - 邊際項是將工作作業變成 OOM 殺手的原因,因為它隨著主機的邏輯處理器數量而不是您配置的內容進行擴大。 在裸機服務器上,它會導致換頁並降低吞吐量。 我們限制平行處理以保持峰值工作集在已知的預算範圍內。
每個同時進行的頁面使用多少記憶體?
與下面的基準工作負載相比,這兩個項的數值如下:
峰值 ≈ 固定文檔成本 + (每台引擎成本 × 同時執行數)
將測量的數據作為起點,並測量您自己的工作負載以對其進行改進 - 兩個項都會隨DPI、頁面複雜性、文檔長度和語言包而變動。
這是如何測量的?
- 每個配置在其自己的過程中運行,使用EnglishFast語言包,在單頁預熱後執行五次。
- 記憶體是這些運行的中位數; 吞吐量則是最快的。
單獨的過程很重要,因為峰值記憶體是永不重置的高水位線 - 在同一過程中測量的第二個配置會重新報告第一個配置的峰值。 吞吐量使用最快的運行次數而非中值,因為機器上的其他工作只能讓讀取變慢,絕無可能加快。
資料是《生物多樣性研究經驗:實地課程》,作者Thea B. Gessler,Iowa State University - 這是一個可下載的49頁文本密集型PDF,以便複製結果。 同樣的運行也確認了底部前置表的每一行。
結果如何?
| MaxDegreeOfParallelism | 峰值記憶體 | 每增加一頁的邊際成本 | 吞吐量 |
|---|---|---|---|
順序式 - MultiThreaded = false | 782 MB | baseline | 0.77 頁/秒 |
| 2 | 859 MB | +77 MB | 1.32 頁/秒 |
| 4 | 1008 MB | +75 MB | 2.09 頁/秒 |
| 8 | 1279 MB | +68 MB | 2.56 頁/秒 |
| 16 - 本機的預設值 | 1829 MB | +69 MB | 3.01 頁/秒 |
測試設備:8核 / 16線程 x64 筆記本電腦CPU · 1.9 GHz · 16 GB RAM · Windows 11 x64 · .NET 8 · IronOCR 2026.8.1 · 最後驗證於2026年8月
第一行完全關閉了平行處理; 最後一行是您未設置任何值時所獲得的結果。 峰值記憶體是進程在任何單一時刻達到的最高值。 每增加一頁的邊際成本是每增加一個並行頁面的記憶體額外成本,相較於上一行 - 整列從頭到尾近乎平坦,而這種穩定性使得模型值得進行規劃。
遞減報酬何時開始?
記憶體隨著並行度穩定增長。 吞吐量則不是,隨著記憶體成本保持同等增長率,增長變得平坦。 比較最後兩行:記憶體列在它們之間的上升比吞吐量列明顯得多。
這是實際發現:默認選項很少是批量工作的最佳選擇。 它是為單文檔的延遲而調整的,而不是為佔用空間。 如果您正批量處理文檔在一個記憶體有限的主機上,通常在邏輯處理器數量以下的明確上限會讓您損失很少的速度,但節省大量記憶體。 衡量您自己文檔上的拐點,因為它隨頁面複雜性而變化。
如何設置一次讀取多少頁?
將 IronTesseract.MaxDegreeOfParallelism 設置為應在單個 Read 呼叫中同時處理的最大頁數。 不設置的話會預設為Environment.ProcessorCount。
using IronOcr;
using System;
var ocr = new IronTesseract();
// Cap concurrency at 2 pages. Each concurrent page holds its own native
// engine, so this bounds peak memory for every Read on this instance.
ocr.MaxDegreeOfParallelism = 2;
// The cap applies per Read call, however many pages the document has.
using var input = new OcrInput();
input.LoadPdf("500-page-archive.pdf");
OcrResult result = ocr.Read(input);
Console.WriteLine(result.Text.Length);using IronOcr;
using System;
var ocr = new IronTesseract();
// Cap concurrency at 2 pages. Each concurrent page holds its own native
// engine, so this bounds peak memory for every Read on this instance.
ocr.MaxDegreeOfParallelism = 2;
// The cap applies per Read call, however many pages the document has.
using var input = new OcrInput();
input.LoadPdf("500-page-archive.pdf");
OcrResult result = ocr.Read(input);
Console.WriteLine(result.Text.Length);Imports IronOcr
Imports System
Dim ocr = New IronTesseract()
' Cap concurrency at 2 pages. Each concurrent page holds its own native
' engine, so this bounds peak memory for every Read on this instance.
ocr.MaxDegreeOfParallelism = 2
' The cap applies per Read call, however many pages the document has.
Using input = New OcrInput()
input.LoadPdf("500-page-archive.pdf")
Dim result As OcrResult = ocr.Read(input)
Console.WriteLine(result.Text.Length)
End UsingImports IronOcr
Imports System
Dim ocr = New IronTesseract()
' Cap concurrency at 2 pages. Each concurrent page holds its own native
' engine, so this bounds peak memory for every Read on this instance.
ocr.MaxDegreeOfParallelism = 2
' The cap applies per Read call, however many pages the document has.
Using input = New OcrInput()
input.LoadPdf("500-page-archive.pdf")
Dim result As OcrResult = ocr.Read(input)
Console.WriteLine(result.Text.Length)
End Using應選擇什麼值?
根據上面的兩部分模型而不是隨意選擇一個數字來確定尺寸:
固定文檔成本 + 每台引擎成本 × MaxDegreeOfParallelism ≤ OCR的記憶體預算
要為您自己的文件填充這兩個成本,請讀取代表文件兩次——一次設置 MultiThreaded 為 false,一次設置 MaxDegreeOfParallelism = 2 並每次記錄峰值工作集。順序運行為您提供固定成本;兩者之間的差異為一個額外引擎的成本。兩者的參考數字在上表中。
在應用它時有兩個需要注意的方面。 固定項隨文檔長度擴大,因此一個長期檔案將不會如上面量測的樣本般行為。 而另外,為.NET運行時、管理堆和程序中其他任何東西預留頭部空間 - 保留大約40%的容器限制作為合理的起點。
擁有足夠記憶體的主機可以保持默認設置。 受限主機應明確設置上限,正如上述遞減報酬數據所示,這種上限對吞吐量的影響往往比其記憶體節省所顯示的要小得多。
MaxDegreeOfParallelism 僅在一個Read 呼叫中限制頁面。 如果您的代碼也同時運行多個文檔,則兩者相乘 - 四個並行文檔對比16的默認值是64個引擎而非16。限制這兩層。 請參見批量OCR中的高峰記憶體,以了解外環模式。如何順序讀取頁面?
將 MultiThreaded 設置為 false。 這是最低記憶體的選擇,因為只會有一台本機引擎處於活動狀態。權衡之處在於吞吐量:批量處理大約需要比N個並行工作者長N倍的時間。
using IronOcr;
var ocr = new IronTesseract();
// One page at a time. Overrides MaxDegreeOfParallelism, whatever it is set to.
ocr.MultiThreaded = false;
using var input = new OcrInput();
input.LoadPdf("scans.pdf");
OcrResult result = ocr.Read(input);using IronOcr;
var ocr = new IronTesseract();
// One page at a time. Overrides MaxDegreeOfParallelism, whatever it is set to.
ocr.MultiThreaded = false;
using var input = new OcrInput();
input.LoadPdf("scans.pdf");
OcrResult result = ocr.Read(input);Imports IronOcr
Dim ocr = New IronTesseract()
' One page at a time. Overrides MaxDegreeOfParallelism, whatever it is set to.
ocr.MultiThreaded = False
Using input = New OcrInput()
input.LoadPdf("scans.pdf")
Dim result As OcrResult = ocr.Read(input)
End UsingImports IronOcr
Dim ocr = New IronTesseract()
' One page at a time. Overrides MaxDegreeOfParallelism, whatever it is set to.
ocr.MultiThreaded = False
Using input = New OcrInput()
input.LoadPdf("scans.pdf")
Dim result As OcrResult = ocr.Read(input)
End UsingMultiThreaded 在此版本之前無效——現在是一個有效的設定。 設置為false的程式碼期望無決的會在升級後順序讀取,無編譯器警告且無異常。 若吞吐量出現意外下降,請檢查現有用途。這兩個屬性如何互動?
| MultiThreaded | MaxDegreeOfParallelism | 有效並行度 |
|---|---|---|
true (預設) | 未設置 | Environment.ProcessorCount |
true | 一個正數 | 該行數的並行頁面 |
true | 0 或負數 | 回退至Environment.ProcessorCount |
false | 任何值 | 1 - 順序,忽略MaxDegreeOfParallelism |
Environment.ProcessorCount 報告邏輯處理器,而非實體核心。 在具有同時多線程的機器上,預設值是核心數的兩倍 - 8核CPU默認為16個並行頁面,而非8。根據邏輯數量設置您的記憶體預算。是否可以在頁面方向檢測期間限製記憶體?
OcrInput.DetectPageOrientation 的新重載接受一個 maxDegreeOfParallelism 參數,限制同時檢測方向的頁數。 非正值退回至Environment.ProcessorCount。 單參數重載未更改,並保持源和二進制兼容性。
using IronOcr;
using System;
using var input = new OcrInput();
input.LoadPdf("rotated-scans.pdf");
// Analyse at most 2 pages at once. Orientation detection runs before the
// OCR read, so capping it here prevents a spike ahead of the real workload.
var results = input.DetectPageOrientation(
OrientationDetectionMode.Fast,
maxDegreeOfParallelism: 2);
// One result per page, in page order.
foreach (var result in results)
{
Console.WriteLine($"Page {result.PageNumber}: {result.RotationAngle}");
}using IronOcr;
using System;
using var input = new OcrInput();
input.LoadPdf("rotated-scans.pdf");
// Analyse at most 2 pages at once. Orientation detection runs before the
// OCR read, so capping it here prevents a spike ahead of the real workload.
var results = input.DetectPageOrientation(
OrientationDetectionMode.Fast,
maxDegreeOfParallelism: 2);
// One result per page, in page order.
foreach (var result in results)
{
Console.WriteLine($"Page {result.PageNumber}: {result.RotationAngle}");
}Imports IronOcr
Imports System
Using input = New OcrInput()
input.LoadPdf("rotated-scans.pdf")
' Analyse at most 2 pages at once. Orientation detection runs before the
' OCR read, so capping it here prevents a spike ahead of the real workload.
Dim results = input.DetectPageOrientation(OrientationDetectionMode.Fast, maxDegreeOfParallelism := 2)
' One result per page, in page order.
For Each result In results
Console.WriteLine($"Page {result.PageNumber}: {result.RotationAngle}")
Next
End UsingImports IronOcr
Imports System
Using input = New OcrInput()
input.LoadPdf("rotated-scans.pdf")
' Analyse at most 2 pages at once. Orientation detection runs before the
' OCR read, so capping it here prevents a spike ahead of the real workload.
Dim results = input.DetectPageOrientation(OrientationDetectionMode.Fast, maxDegreeOfParallelism := 2)
' One result per page, in page order.
For Each result In results
Console.WriteLine($"Page {result.PageNumber}: {result.RotationAngle}")
Next
End UsingFast模式在每個工作線程中重複使用一個引擎,而不是為每頁分配一個,以進一步減少峰值記憶體。 這在方向檢測作為主OCR讀取的預處理步驟時很重要,因為在這裡限制平行處理可以防止在實際工作負載開始之前記憶體激增。
大的批量中平行OCR仍會崩潰嗎?
由於不安全的跨線程訪問本機Tesseract狀態,先前版本可能在平行或高容量OCR過程中拋出致命的AccessViolationException。 該異常無法恢復 - 它在沒有捕捉機會的情況下終止進程。 現在已解決。 以前的解決方法,每個線程一個 IronTesseract 實例和每次一個文件,已不再需要:引擎正確地為每個工作者隔離本地狀態,MaxDegreeOfParallelism 提供了一個官方限制,取代了這些臨時模式。
何時應調整這些設置?
- 具有記憶體上限的容器或CI運行者 - 設置
MaxDegreeOfParallelism以保持峰值記憶體在限制範圍內。 - 批量處理數千頁 - 降低
MaxDegreeOfParallelism以防止OOM殺死。 吞吐量成比例減少,但作業完成而不是崩潰。 - 最低可能內存 - 將
MultiThreaded設置為false以啟動順序模式。 一個引擎,每次一頁。 - 最大吞吐量 - 保持兩者在默認狀態,以便引擎使用所有可用核心。 請參考多線程加速示例。
- 準確性與速度的調整 - 這是不同的軸線。 調整Tesseract速度指南涵蓋準確性與速度的平衡,而此頁面則涵蓋記憶體與吞吐量的權衡。
有關異步和響應性的問題,例如在 OCR 過程中保持 UI 響應,請參見 async OCR 操作指南,其擁有 ReadAsync 和 OcrReadTask。 本文覆蓋了資源限制:保持記憶體消耗可預測,不論批次大小。
探索 IronTesseract 配置指南,了解完整的屬性範圍,載入 PDF 輸入和載入圖像輸入以獲得 OcrInput 使用模式,還有 頁面方向檢測新並行性重載的 DetectPageOrientation 方法。
探索IronOCR授權選項以從試用轉向生產。
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。