如何控制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仅处理第二项。 这种区别很重要:在长文档中,固定成本可能是更大的部分,因此限制并行度可大幅减少峰值内存,而不会将其降低到零。
在容器化环境中 - 固定的--memory限制的Docker,资源配额的Kubernetes pods - 边际术语是使工作工作变为OOM终止的原因,因为它随主机的逻辑处理器数量扩展,而不是您配置的任何东西。 在裸机服务器上,它会导致交换并降低吞吐量。 我们限制并行度以将峰值工作集保持在一个已知预算内。
每个并发页面使用多少内存?
相对于下面的参考工作负载测量,这两项的结果为:
峰值 ≈ 固定文档成本 + (每引擎成本 × 并发量)
将测量值作为起点,测量您自己的工作负载以加以完善 - 这两项会随DPI、页面复杂性、文档长度和语言包而变化。
这是如何测量的?
- 每个配置在自己的进程中运行,使用EnglishFast语言包,在单页预热后,运行五次。
- 内存为这些运行的中位数; 吞吐量是最快的。
分开进程很重要,因为峰值内存是一个永不重置的最高水位线 - 在同一进程中测量的第二个配置会重新报告第一个的峰值。 吞吐量使用最快的运行而非中位数,因为机器上的其他工作只能使读取变慢,而不能使其加快。
语料库为Thea B.的《体验生物多样性研究:田野课程》。 Gessler,爱荷华州立大学 - 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 Using在此发布之前,
MultiThreaded无效 - 现在是一个实时设置。 代码将其设置为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在大批次上仍会崩溃吗?
以前的版本在并行或高量OCR期间由于对本机Tesseract状态的不安全的跨线程访问可能抛出致命AccessViolationException。 那个异常是不可恢复的 - 它会在没有捕捉机会的情况下终止进程。 现在已经解决。 之前的解决方案,每个线程一个IronTesseract实例以及一次一个文档,已不再必要:引擎正确地隔离每个工作者的本地状态,并且MaxDegreeOfParallelism提供了一个官方限制,取代那些临时模式。
我何时应该调整这些设置?
- 具有内存上限的容器或CI运行器 - 设置
MaxDegreeOfParallelism以保持峰值内存在限制以内。 - 批量处理成千上万的页面 - 降低
MaxDegreeOfParallelism以防止OOM终止。 吞吐量按比例下降,但工作完成而不是崩溃。 - 最低可能内存 - 将
MultiThreaded设置为false以进入顺序模式。 一个引擎,一次一页。 - 最大吞吐量 - 保持两者在其默认值以便引擎使用所有可用核心。 参见速度多线程示例。
- 准确性与速度调优 - 这是另一种轴。 快速调优Tesseract指南涵盖准确性和速度权衡,而本页涵盖内存和吞吐量权衡。
对于异步和响应性问题,例如在OCR期间保持UI响应,请参阅异步OCR指南,它拥有ReadAsync和OcrReadTask。 本页涵盖资源限制:保持内存消耗在不管批量大小的可预测范围内。
探索IronTesseract配置指南以了解完整的属性表面,加载PDF输入和加载图像输入以使用OcrInput的使用模式,以及页面方向检测以用于DetectPageOrientation方法及其新的并行重载。
探索IronOCR许可选项以从试用版到生产版移动。
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。