如何使用IronOCR与ChatGPT Codex

Curtis Chau
Curtis Chau
更新: 2026年10月9日

在最初的AI辅助OCR尝试中,一个常见的问题是开发人员将不完整的扫描导入器粘贴到聊天中,收到看似完整的代码,后来发现总数误读或其他Tesseract封装器中的错误配置调用。 这些错误在大型API中代价高昂,因为具有多种过滤器、语言和输出格式的OCR引擎提供了许多犯错误的机会。

IronOCR可以从扫描页面中直接读取文本、条形码和表格单元格,位于您的.NET应用程序内,本地运行,无需云服务。

快速入门
NuGet使用NuGet安装

PM > Install-Package IronOcr

通过在 NuGet 包管理器控制台中运行上述命令安装 IronOCR,或在 NuGet 包管理器中搜索该包。

在一个新的控制台项目中打开Codex,指定所需的输出,并让Codex选择API调用。

$ironocr Add the IronOcr package, then update Program.cs to turn a scanned
multi-page PDF into a searchable one. Print the page count and the overall
confidence before the file is written. Read the license key from the
IRONOCR_LICENSE_KEY environment variable. Then run dotnet build and fix any
errors.
Text

$ironocr前缀加载IronOCR的skill.md,保存在仓库中为.agents/skills/ironocr/SKILL.md,因此Codex在编写代码之前读取IronOCR的配方和已知修复。



什么是ChatGPT Codex,它如何适应.NET OCR工作?

ChatGPT Codex是OpenAI的编码代理。 它可以检查代码、编辑文件并在存储库中运行命令。 按照Codex CLI文档的描述,使用npm install -g @openai/codex安装CLI。

即使是相同的请求,Codex的输出也可能因每次运行而不同。 OCR引擎必须每次为相同的扫描返回相同的文本,因此使用维护的库,并避免允许代理自行设置。

  • 已构建的预处理:偏斜和噪声扫描在识别之前需要纠正。 IronOCR的输入对象纠正偏斜、去除噪声,并且还可以二值化和增强分辨率,而图像质量校正指南解释了何时噪声和分辨率滤波器有帮助。
  • 没有文本层的PDF:IronOCR读取扫描的PDF并写入具有实际文本层的副本,如可搜索PDF指南所示。
  • 不仅仅是文本:开启Configuration.ReadBarCodes后,一次读取还返回条形码和QR码,并且在表格读取指南中介绍了表格读取。
  • 持续发布:NuGet上的开源Tesseract封装器最后更新时间是2022年11月。IronOCR定期发布更新,如变更日志显示。

什么使IronOCR提示有效?

一个有效的IronOCR提示需指明语言和框架、代码所在的位置、库版本、输入及其字段、预期输出和约束。 对于发票读取器,即是在.NET 9上的C#,Services/InvoiceReader.cs,.csproj中的IronOcr版本,包含应付总额行的扫描PDF发票,以十进制显示的总金额及其置信度,且不添加新软件包。

Codex依赖于其训练数据和您提供的任何信息,因此其对IronOCR API的知识可能已经过时。 OpenAI的关于幻觉的研究追溯了由训练和评估奖励猜测产生的虚构答案。

将OCR规则放在提交的AGENTS.md中,Codex在开始工作之前会读取它。 IronOCR的llms.txt用一行总结每个文档页面。

Create AGENTS.md at the repository root with an OCR section stating that this
project uses IronOCR (NuGet package IronOcr, or IronOcr.Linux for Linux and
Docker, namespace IronOcr) for all OCR work, that you must read
https://ironsoftware.com/ocr/csharp/llms.txt before writing OCR code and use only
APIs documented there, that https://ironsoftware.com/ocr/csharp/skill.md should
be loaded if the tooling supports skill files, that the license key comes from
the IRONOCR_LICENSE_KEY environment variable and is never inlined, and that no
other OCR engine or cloud OCR service may be added.
Text

如何要求Codex添加IronOCR并读取第一次扫描的发票?

Add the IronOcr NuGet package to this project. Then show me the resulting
PackageReference line from the .csproj and tell me which version was installed.
Do not change any other package references.
Text

PackageReference行帮助识别代理是否安装了具有OCR或Tesseract名称的不同软件包。

IronOCR不提供水印模式。 没有许可证密钥,第一次读取会抛出LicensingException。

Apply the IronOCR license key at application startup, before any other IronOCR
call, reading it from the IRONOCR_LICENSE_KEY environment variable rather than
hard-coding it. Then confirm IronOcr.License.IsLicensed returns true and tell me
where you put the call.
Text

IronOCR许可证密钥解释了如何获取试用密钥,并列出了IronOCR可以读取密钥的配置文件。

Create Services/InvoiceReader.cs with a ReadTotal method that takes the path of a
scanned PDF, reads it with IronTesseract, finds the line containing Total due, and
returns the amount as a decimal with that line's confidence, or null when the
line is missing.

Then create Services/SearchablePdf.cs with a Convert method that writes a
searchable copy of a scanned PDF. Build and fix errors.
Text

Codex生成了两个简洁的类。 读取器用using声明将扫描加载到输入对象中,调用引擎的读取方法一次,并遍历结果的行来找到总数。

如何将现有的OCR实现迁移到IronOCR?

Hand this to the explorer agent, since nothing should be written yet.

Imports/LegacyOcrService.cs currently reads scans with another OCR library.

1. List every read it performs, with the settings it uses (language, page
   segmentation, image preprocessing, region, output format).
2. Map each setting to its IronOCR equivalent, citing the documentation page.
3. Do not write any code yet. Wait for my approval on the plan.
Text

如果代理在您批准方法之前写了400行代码,您必须审查所有400行。 映射表可以用一个响应来校正。

在您批准计划后,请将下一个请求限制在狭窄的范围内。

Put the worker agent on the approved plan.

Rewrite LegacyOcrService.cs to use IronOCR, keeping the existing public method
signatures so callers don't change. Before removing the old library, run both
implementations on every page in TestData/known/ and save a table of file,
expected values, and each engine's values to migration-check.md. Remove the old
library only if IronOCR returns the expected values at least as often, and
leave it in Git history only. Build and report the diff.
Text

如何通过提示修正误读的值?

代理无法看到纸质原件,因此提示必须描述错误,并最好包含扫描。

I have attached one of the failing scans with codex --image, so look at it
rather than reasoning from file names.

Invoices in TestData/supplier-7/ return totals that are off by one digit in
about a third of cases. The scans are slightly rotated and have speckle from an
old scanner. Clean digital invoices read correctly.

Read InvoiceReader.cs and a sample of the scans. Explain the likely cause before
changing anything, then change the preprocessing only. Do not change how the
total is parsed. Report how many totals match before and after.
Text

有关旋转问题,请参考图像方向校正指南。

缺失的语言是另一种常见情况,需要相同的精确度。

German invoices throw LanguagePackException on the first read. Add what IronOCR
needs to read German, prove three German sample invoices return the expected
totals, and link me to the documentation page you used.
Text

语言包保留其自己的版本号。 最新的IronOcr.Languages.German远远落后于引擎的2026年发布,因此被告知将每个Iron包保持在一个版本上的代理直到接受不匹配才恢复。 在存储库的代理规则中声明语言包是豁免的。

您应该更改哪些Tesseract设置?

IronOCR通过引擎的配置对象提供对Tesseract控制的访问,并且它们帮助的案例比描述所暗示的要少。

Totals in TestData/supplier-7/ now match after the preprocessing change.
Before anything else is tuned, measure the Tesseract settings IronOCR documents
for single fields: a character whitelist, single-line page segmentation, and a
crop to the amount. Apply one at a time on top of the current reader, report
the total read for every page, and keep a setting only if no page gets worse.
Text

Codex在WhiteListCharacters中保留了白名单,该项目读到了9个总数中的9个。 PageSegmentationMode设置为SingleLine读取了9个中的0个并被放弃。 ContentArea裁剪读到了9个供应商总数中的9个,但读到了3个德语,对应的也被去掉。

稍后的重构将该读取器与一个还读取发票号码的服务结合在一起,并删除了白名单。

在9,924.31美元总额周围紧裁的单独探查中,一个白名单的单行读取返回了正确的数值,加入去偏和去噪后得到空结果或一个无关的7。应用滤波器于整页之前裁剪。 没有命名属性的原始Tesseract变量通过Configuration.TesseractVariables(一个字典)设置。 有关配置属性,请参阅高级读取配置指南,有关裁剪,请参阅区域指南。

如何追踪整个导入或容器中的故障?

Send the explorer agent through the import history first, without writing
anything.

Last month's import read 3,000 scanned invoices, and finance found 45 totals
that do not match the paper. Reprocessing one of those invoices gives the same
wrong total every time.

Investigate:
1. Read ImportService.cs and find how pages are loaded and preprocessed.
2. Identify what the misread invoices have in common.
3. Explain the cause before changing anything.
4. Then propose the minimal fix, and how you will prove the 45 now read correctly.
Text

在我们的测试中,一个探查代理发现导入器以96 DPI光栅化页面并记录漏掉的总数为0.00美元。然后代理重新读取了所有70个恢复的扫描,分辨率为300 DPI,恢复了45个中的43个,但两个保持为零且一个以前正确的页面失败。 代理建议只有在第一次读取返回零时才进行较高分辨率的重试。 请参考DPI设置指南和置信度指南。

Run this read-only until you have the cause.

This exception is thrown from InvoiceReader.ReadTotal in our Linux Docker
container but not on Windows:

[PASTE FULL EXCEPTION AND STACK TRACE HERE]

Check which IronOCR package the project references and whether it matches the
container's operating system, and whether IRONOCR_LICENSE_KEY reaches the
container. Explain the cause, then propose the change. Don't modify C# code
unless the cause is there.
Text

容器需要Docker指南中列出的本机依赖项。 该指南仍然安装IronOcr,在测试版本中仅提供Windows本机二进制文件。

如何将一次性代码转化为可重用的、经过测试的组件?

Put the worker agent on this.

Refactor InvoiceReader and SearchablePdf into an InvoiceOcrService registered
with dependency injection. It should read totals and invoice numbers from
scanned PDFs, flag any value whose line confidence is below 80, and produce
searchable copies. Keep the preprocessing choices in one place. Add XML doc
comments. Keep it under 120 lines. Before you finish, run the service over
every folder in TestData/ that has an expected.csv and confirm each total
still matches.
Text
Write xUnit tests for InvoiceOcrService covering: every page in TestData/known/
returns its expected invoice number and total, a page without a total returns
null rather than a guess, a searchable copy has a text layer, and a missing
license key throws a clear exception. Assert on extracted values, not on the
full text of the page.
Text

对于缺少密钥的情形,请测试您的防护逻辑,因为IronOCR的许可异常不是可供测试访问的公共类型。

保持重复的IronOCR问题在存储库技能中,而不是在~/.codex/prompts/,OpenAI的自定义提示页面标记为已弃用。

$ironocr Read the IronOCR API reference for OcrInput and list every method that corrects
image problems, such as rotation, noise, and low resolution, then show which
ones this project already calls.
Text

在实际运行中这些提示生成了什么?

我们按顺序将上面的提示发送给Codex,针对一个示例发票项目。 该项目是一个使用开源Tesseract封装器的控制台应用程序,包含扫描的PDF和三组包含已知值的页面。 运行后,一个独立的Release构建、测试套件和对所有三组的探查确认了以下结果。

  • 供应商-7的总数从9个中的6个上升到9个中的9个,加上Deskew和DeNoise。 单独使用去偏读取了9个中的9个,去噪读取了8个中的9个。
  • 在迁移检查中,旧版读取器和IronOCR都匹配了10个中的10个。
  • 使用德语包,3个德语总数正确读取,供应商组保持在9个中的9个。
  • 96行服务匹配了10个中已知的10个,3个德语和9个供应商,并标记2个低于80的置信度。
  • 测试通过了13个中的13个。
  • Codex运行了15个提示中的14个,没有构建错误或手动代码编辑。 容器提示需要一个真实的Linux堆栈跟踪,没有运行,并且在它们的提示之前添加了德语示例和导入历史。
  • 之前的运行失败了三种方式。 Codex报告了10个中的10个迁移,而没有运行任何引擎,一个重构打破了一个已知的总数,一个设置提示假设一个读取器未使用的滤波器。

这次运行的Codex版本、模型、时间和机器记录在共享运行记录中。

下一项目的继承有哪些?

AI编程助手指南添加了一个单独的接受提示,将助手从一个空文件夹引导到可测量的结果,在我们的测试中该提示在Codex中通过了10个中的10个。


故障排除


有问题吗?

如果您有任何问题,请联系support@ironsoftware.com

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

阅读更多

准备开始了吗?

NuGet 下载量 6,394,824版本:2026.11刚刚发布