Como usar IronOCR com o ChatGPT Codex
Um problema comum nas tentativas iniciais de OCR assistido por IA é que os desenvolvedores colam importadores de escaneamento incompletos em um chat, recebem código aparentemente completo e, mais tarde, descobrem totais lidos incorretamente ou chamadas de configuração incorretas de outros wrappers Tesseract. Tais erros são caros com grandes APIs, pois motores de OCR com múltiplos filtros, idiomas e formatos de saída apresentam muitas oportunidades para erros.
IronOCR lê texto, códigos de barras e células de tabelas a partir de páginas escaneadas diretamente dentro de sua aplicação .NET, localmente e sem um serviço em nuvem.
Início RápidoAbra o Codex em um novo projeto de console e especifique a saída desejada, e deixe o Codex selecionar as chamadas de 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.
O prefixo $ironocr carrega o skill.md do IronOCR, salvo no repositório como .agents/skills/ironocr/SKILL.md, para que o Codex leia as receitas do IronOCR e correções conhecidas antes de escrever o código.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca OCR C# do NuGet
- Faça o commit de um
AGENTS.mdque nomeia o IronOCR como o motor OCR do repositório - Comece cada tarefa do Codex em um branch limpo e descreva as páginas e os valores que elas contêm
- Deixe o Codex editar arquivos e executar
dotnet build, depois revise o diff antes de aceitá-lo - Compare os valores extraídos com as páginas conhecidas e verifique cada membro na referência de API
O que é o ChatGPT Codex e como ele se encaixa no trabalho de OCR .NET?
ChatGPT Codex é a agente de codificação da OpenAI. Ele pode inspecionar código, editar arquivos e executar comandos em um repositório. Instale o CLI com npm install -g @openai/codex, conforme a documentação do CLI do Codex descreve.
A saída do Codex pode variar a cada execução, mesmo para requisições idênticas. O motor de OCR deve retornar o mesmo texto para o mesmo escaneamento todas as vezes, então use uma biblioteca mantida e evite permitir que agentes improvisem configurações.
- Pré-processamento já construído: escaneamentos inclinados e ruidosos precisam de correção antes do reconhecimento. O objeto de entrada do IronOCR endireita inclinações, remove ruído e pode também binarizar e melhorar a resolução, e o guia de correção de qualidade de imagem explica quando os filtros de ruído e resolução ajudam.
- PDFs sem camada de texto: IronOCR lê PDFs escaneados e escreve uma cópia com uma camada de texto real, como mostra o guia de PDF pesquisável.
- Mais que texto: com
Configuration.ReadBarCodesativado, uma leitura retorna códigos de barras e QR codes junto com o texto, e a leitura de tabela é abordada no guia de leitura de tabela. - Releases contínuas: o wrapper Tesseract de código aberto no NuGet foi atualizado pela última vez em novembro de 2022. IronOCR lança atualizações regularmente, como seu changelog mostra.
O que torna um prompt de IronOCR eficaz?
Um prompt eficaz do IronOCR nomeia a linguagem e o framework, onde o código será inserido, a versão da biblioteca, a entrada e seus campos, a saída esperada e as restrições. Para um leitor de faturas, isso é C# no .NET 9, Services/InvoiceReader.cs, a versão IronOcr no .csproj, faturas em PDF escaneadas com uma linha de Total devido, o total como decimal com confiança, e sem novos pacotes.
Codex depende de seus dados de treinamento e de qualquer informação que você fornecer, portanto seu conhecimento da API do IronOCR pode estar desatualizado. A pesquisa da OpenAI sobre alucinação rastreia respostas inventadas até o treinamento e avaliação que recompensam adivinhações.
Coloque as regras de OCR uma vez em um AGENTS.md que foi commitado, que o Codex lê antes de começar a trabalhar. O llms.txt do IronOCR resume cada página de documentação em uma linha.
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.
Como você pede ao Codex para adicionar IronOCR e ler a primeira fatura escaneada?
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.
A linha PackageReference ajuda a identificar se um agente instalou um pacote diferente com OCR ou Tesseract em seu nome.
IronOCR não oferece um modo de marca d'água. Sem uma chave de licença, a primeira leitura lança uma 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.
Chaves de Licença IronOCR explica como obter uma chave de teste e lista os arquivos de configuração dos quais o IronOCR pode ler uma chave.
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.
Codex gerou duas classes concisas. O leitor carrega o escaneamento em um objeto de entrada com uma declaração using, chama o método de leitura do motor uma vez, e itera pelas linhas do resultado para encontrar o total.
Como você migra uma implementação de OCR existente para o 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.
Se um agente escreve 400 linhas antes de você aprovar a abordagem, você deve revisar todas as 400 linhas. Uma tabela de mapeamento pode ser corrigida com uma única resposta.
Após aprovar o plano, mantenha a próxima solicitação com escopo restrito.
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.
Como você corrige valores lidos incorretamente através de prompts?
O agente não pode ver o original em papel, então o prompt tem que descrever o erro e, idealmente, incluir os escaneamentos.
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.
Consulte o guia de correção de orientação de imagem para problemas de rotação.
Idiomas ausentes são o outro caso comum e precisam da mesma precisão.
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.
Pacotes de idioma têm seus próprios números de versão. O IronOcr.Languages.German mais recente está muito atrás dos lançamentos do motor de 2026, então um agente instruído a manter todos os pacotes Iron na mesma versão falha na restauração até aceitar a discrepância. Diga nas regras do agente do repositório que os pacotes de idioma estão isentos.
Quais configurações do Tesseract você deve alterar?
IronOCR fornece acesso aos controles do Tesseract através do objeto de configuração do motor, e eles ajudam em menos casos do que suas descrições sugerem.
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.
Codex manteve a lista branca em WhiteListCharacters, que leu 9 de 9 totais. PageSegmentationMode definido para SingleLine leu 0 de 9 e foi descartado. Um recorte ContentArea leu 9 de 9 totais de fornecedores mas 0 de 3 alemães, então também foi.
Uma posterior refatoração combinou este leitor com um serviço que também lê números de fatura, e a lista branca foi removida.
Em uma sonda separada em um recorte apertado ao redor do total $9,924.31, uma leitura de linha única na lista branca retornou o valor correto, e ao adicionar remoção de inclinação e ruído resultou num resultado vazio ou um 7 perdido. Aplique filtros na página inteira antes de cortar. Variáveis brutas do Tesseract sem propriedades nomeadas são configuradas via Configuration.TesseractVariables, um dicionário. Consulte o guia de configuração de leitura avançada para propriedades de configuração e o guia de regiões para recorte.
Como você rastreia uma falha em uma importação inteira ou em um contêiner?
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.
Em nosso teste, um agente explorador descobriu que o importador rasterizava páginas a 96 DPI e registrava totais ausentes como $0.00. O agente então reliu todos os 70 escaneamentos restaurados a 300 DPI e recuperou 43 de 45, mas dois permaneceram em zero e uma página anteriormente correta falhou. O agente recomendou uma nova tentativa de maior resolução apenas quando a primeira leitura retornar zero. Consulte o guia de configurações de DPI e o guia de confiança.
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.
O contêiner precisa das dependências nativas que o guia Docker lista. Esse guia ainda instala IronOcr, que na versão testada envia apenas binários nativos do Windows.
Como transformar código único em componentes reutilizáveis e testados?
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.
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.
Para o cenário de chave ausente, teste sua própria lógica de salvaguarda, pois a exceção de licenciamento do IronOCR não é um tipo público acessível aos testes.
Mantenha as perguntas recorrentes do IronOCR na habilidade do repositório ao invés de ~/.codex/prompts/, que a página de prompts personalizados da OpenAI marca como obsoleta.
$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.
O que os prompts produziram em uma execução real?
Enviamos os prompts acima para o Codex em ordem, contra um projeto de fatura de exemplo. O projeto é uma aplicação de console com PDFs escaneados, um serviço legado usando o wrapper Tesseract de código aberto, e três conjuntos de páginas com valores conhecidos. Após a execução, uma compilação de Release independente, suíte de testes, e sondas por todos os três conjuntos confirmaram os resultados abaixo.
- Os totais do Fornecedor-7 subiram de 6 de 9 para 9 de 9 com
DeskeweDeNoise. Sozinho, Deskew leu 9 de 9 e DeNoise 8 de 9. - Tanto o leitor legado quanto o IronOCR coincidiram 10 de 10 na verificação de migração.
- Com o pacote alemão, 3 de 3 totais alemães foram lidos corretamente e o conjunto do fornecedor manteve 9 de 9.
- O serviço de 96 linhas coincidiu 10 de 10 conhecidos, 3 de 3 alemães e 9 de 9 fornecedores, e sinalizou 2 abaixo de 80 de confiança.
- Testes passaram 13 de 13.
- O Codex executou 14 de 15 prompts sem erros de compilação ou edições manuais de código. O prompt do contêiner precisa de um stack trace real do Linux e não foi executado, e as amostras alemãs e o histórico de importação foram adicionados antes de seus prompts.
- Uma execução anterior falhou de três maneiras. Codex reportou uma migração de 10 de 10 sem executar nenhum dos motores, uma refatoração quebrou um total conhecido, e um prompt de configurações assumiu um filtro que o leitor não usou.
A versão do Codex desta execução, modelo, tempo e máquina estão no registro de execução compartilhado.
O que se leva para o próximo projeto?
O guia de assistentes de codificação de IA adiciona um único prompt de aceitação que leva um assistente de uma pasta vazia a resultados medidos, e o mesmo prompt passou 10 de 10 no Codex durante nossos testes.
Solução de problemas
- Aplique uma chave de licença no IronOCR se o código passar na revisão mas a execução parar na primeira leitura
- Melhore a precisão do OCR se os totais lidos dos escaneamentos não corresponderem aos originais no papel
- Leia múltiplos idiomas se o Codex selecionar um idioma que o repositório não tenha instalado
- IronOCR no Docker se leituras funcionarem no Windows e falharem em um contêiner Linux
Questões?
Se você tiver dúvidas, entre em contato com support@ironsoftware.com
Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.