如何使用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提示命名語言和框架、代碼的位置、程式庫版本、輸入及其字段、預期輸出和約束。 對於發票讀取來說,是C#在.NET 9上,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個總數。 設置為SingleLine的PageSegmentationMode讀取了9個中的0個並被棄用。 內容區剪裁讀取了9個中的9個供應商總數但3個德語中的0個,因此也被刪除。

後來的重構將此讀取器與一個同時讀取發票號的服務結合,白名單被移除。

在對$9,924.31總額進行嚴格剪裁的單獨探測中,白名單單行讀取返回了正確的數量,並且添加deskew和降噪留下空白結果或零星的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的反覆問題保留在存儲庫技能中,而不是在OpenAI的自訂提示頁面上標記為已棄用的~/.codex/prompts/中。

$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包的遺留服務,有已知值的三組頁面。 運行後,一個獨立的Release構建、測試套件和跨三組的探測確認了以下結果。

  • 供應商-7的總數從9個中的6個上升到9個中的9個,使用Deskew和DeNoise。 單獨,Deskew讀取了9個中的9個,DeNoise讀取了9個中的8個。
  • 在遷移檢查中,遺留讀取器和IronOCR都匹配10個中的10個。
  • 使用德語包,3個德語總數中讀取正確,供應商設置保持在9個中的9個。
  • 96行服務匹配了10個中的10個已知,3個德語中的3個和9個供應商中的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。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

閱讀更多

準備好開始了嗎?

NuGet 下載次數 6,394,824版本:2026.11剛剛發布