Cómo usar IronOCR con ChatGPT Codex
Un problema común en los primeros intentos de OCR asistidos por IA es que los desarrolladores pegan importadores de escaneo incompletos en un chat, reciben un código aparentemente completo y luego descubren totales mal leídos o llamadas de configuración incorrectas desde otros encapsuladores de Tesseract. Tales errores son costosos con grandes API, ya que los motores OCR con múltiples filtros, idiomas y formatos de salida presentan muchas oportunidades para cometer errores.
IronOCR lee texto, códigos de barras y celdas de tabla de páginas escaneadas directamente dentro de su aplicación .NET, localmente y sin un servicio en la nube.
Inicio rápidoAbra Codex en un nuevo proyecto de consola y especifique la salida deseada, y deje que Codex seleccione las llamadas a la 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.
El prefijo $ironocr carga el skill.md de IronOCR, guardado en el repositorio como .agents/skills/ironocr/SKILL.md, de modo que Codex lea las recetas y correcciones conocidas de IronOCR antes de escribir el código.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de OCR C# de NuGet
- Comprometa un
AGENTS.mdque nombre a IronOCR como el motor OCR del repositorio - Comience cada tarea de Codex en una rama limpia y describa las páginas y los valores que tienen
- Deje que Codex edite archivos y ejecute
dotnet build, luego revise la diferencia antes de aceptarla - Compare los valores extraídos con las páginas conocidas y verifique cada miembro en la referencia de API
¿Qué es ChatGPT Codex y cómo encaja en el trabajo de OCR con .NET?
ChatGPT Codex es el agente de codificación de OpenAI. Puede inspeccionar código, editar archivos y ejecutar comandos en un repositorio. Instale la CLI con npm install -g @openai/codex, como se describe en la documentación de Codex CLI.
La salida de Codex puede variar con cada ejecución, incluso para solicitudes idénticas. El motor OCR debe devolver el mismo texto para el mismo escaneo cada vez, por lo que use una biblioteca mantenida y evite permitir que los agentes improvisen configuraciones.
- Preprocesamiento ya construido: los escaneos torcidos y ruidosos necesitan corrección antes del reconocimiento. El objeto de entrada de IronOCR endereza la inclinación, elimina el ruido y también puede binarizar y mejorar la resolución, y la guía de corrección de calidad de imagen explica cuándo los filtros de ruido y resolución ayudan.
- PDF sin una capa de texto: IronOCR lee PDFs escaneados y escribe una copia con una capa de texto real, como muestra la guía de PDF buscable.
- Más que texto: con
Configuration.ReadBarCodesactivado, una lectura devuelve códigos de barras y códigos QR junto con el texto, y la lectura de tablas se aborda en la guía de lectura de tablas. - Lanzamientos continuos: el encapsulador de Tesseract de código abierto en NuGet fue actualizado por última vez en noviembre de 2022. IronOCR lanza actualizaciones regularmente, como muestra su registro de cambios.
¿Qué hace que un mensaje de IronOCR sea efectivo?
Un mensaje efectivo de IronOCR nombra el idioma y el marco, dónde va el código, la versión de la biblioteca, la entrada y sus campos, la salida esperada y las restricciones. Para un lector de facturas, eso es C# en .NET 9, Services/InvoiceReader.cs, la versión IronOcr en el .csproj, facturas PDF escaneadas con una línea de Total a pagar, el total como decimal con confianza, y sin nuevos paquetes.
Codex se basa en sus datos de entrenamiento y cualquier información que proporcione, por lo que su conocimiento de la API de IronOCR puede estar desactualizado. La investigación sobre la alucinación de OpenAI rastrea respuestas inventadas hasta el entrenamiento y evaluación que recompensan adivinar.
Coloque las reglas de OCR una vez en un AGENTS.md comprometido, que Codex lea antes de comenzar a trabajar. El llms.txt de IronOCR resume cada página de documentación en una línea.
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.
¿Cómo pedir a Codex que añada IronOCR y lea una primera factura 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.
La línea PackageReference ayuda a identificar si un agente instaló un paquete diferente con OCR o Tesseract en su nombre.
IronOCR no ofrece un modo de marca de agua. Sin una clave de licencia, la primera lectura lanza una 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.
IronOCR License Keys explica cómo obtener una clave de prueba y enumera los archivos de configuración desde los que IronOCR puede leer una clave.
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 generó dos clases concisas. El lector carga el escaneo en un objeto de entrada con una declaración using, llama al método de lectura del motor una vez e itera a través de las líneas del resultado para encontrar el total.
¿Cómo migrar una implementación de OCR existente a 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.
Si un agente escribe 400 líneas antes de que apruebe el enfoque, debe revisar las 400 líneas. Una tabla de mapeo puede corregirse con una única respuesta.
Después de aprobar el plan, mantenga la próxima solicitud en un alcance reducido.
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.
¿Cómo corregir valores mal leídos a través de mensajes?
El agente no puede ver el original en papel, por lo que el mensaje tiene que describir el error e incluir, idealmente, los escaneos.
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 la guía de corrección de orientación de imagen para problemas de rotación.
Los idiomas que faltan son el otro caso común y necesitan la misma precisión.
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.
Los paquetes de idiomas mantienen sus propios números de versión. El más reciente IronOcr.Languages.German está muy por detrás de los lanzamientos del motor en 2026, por lo que un agente al que se le indica mantener cada paquete de Iron en una versión falla en la restauración hasta que acepta la discrepancia. Diga en las reglas del agente del repositorio que los paquetes de idiomas están exentos.
¿Qué configuraciones de Tesseract debería cambiar?
IronOCR proporciona acceso a los controles de Tesseract a través del objeto de configuración del motor, y son útiles en menos casos de los que sugieren sus descripciones.
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 mantuvo la lista blanca en WhiteListCharacters, que leyó 9 de 9 totales. PageSegmentationMode configurado a SingleLine leyó 0 de 9 y fue descartado. Un recorte de ContentArea leyó 9 de 9 totales de proveedores pero 0 de 3 alemán, por lo que también fue eliminado.
Una posterior refactorización combinó este lector con un servicio que también lee números de factura, y la lista blanca fue eliminada.
En una prueba separada en un recorte ajustado alrededor del total de $9,924.31, una lectura de línea única en lista blanca devolvió la cantidad correcta, y agregar deskew y eliminación de ruido dejó un resultado vacío o un 7 errante. Aplique filtros a toda la página antes de recortar. Las variables crudas de Tesseract sin propiedades nombradas se configuran a través de Configuration.TesseractVariables, un diccionario. Consulte la guía de configuración de lectura avanzada para propiedades de configuración y la guía de región para recortar.
¿Cómo rastrear un fallo a través de una importación completa o dentro de un contenedor?
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.
En nuestra prueba, un agente explorador encontró que el importador rasterizaba las páginas a 96 DPI y registraba totales perdidos como $0.00. El agente luego releyó los 70 escaneos restaurados a 300 DPI y recuperó 43 de 45, pero dos permanecieron en cero y una página previamente correcta falló. El agente recomendó un reintento a mayor resolución solo cuando la primera lectura devuelva cero. Consulte la guía de configuración de DPI y la guía de confianza.
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.
El contenedor necesita las dependencias nativas que enumera la guía de Docker. Esa guía aún instala IronOcr, que en la versión probada solo envía binarios nativos de Windows.
¿Cómo convierte el código único en componentes reutilizables y probados?
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 el escenario de clave faltante, pruebe su propia lógica de protección, ya que la excepción de licencia de IronOCR no es un tipo público accesible para pruebas.
Mantenga las preguntas recurrentes de IronOCR en la habilidad del repositorio en lugar de en ~/.codex/prompts/, que The OpenAI's página de mensajes personalizados 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.
¿Qué produjeron los prompts en una ejecución real?
Enviamos los mensajes anteriores a Codex en orden, contra un proyecto de factura de ejemplo. El proyecto es una aplicación de consola con PDFs escaneados, un servicio heredado usando el encapsulador de Tesseract de código abierto, y tres conjuntos de páginas con valores conocidos. Después de la ejecución, una compilación de liberación independiente, un conjunto de pruebas, y pruebas en todos los tres conjuntos confirmaron los resultados a continuación.
- Los totales de Proveedor-7 aumentaron de 6 de 9 a 9 de 9 con
DeskewyDeNoise. Solo, Deskew leyó 9 de 9 y DeNoise 8 de 9. - Tanto el lector heredado como IronOCR coincidieron 10 de 10 en la verificación de migración.
- Con el paquete alemán, 3 de 3 totales alemanes se leyeron correctamente y el conjunto de proveedores se mantuvo en 9 de 9.
- El servicio de 96 líneas coincidió 10 de 10 conocidos, 3 de 3 alemán y 9 de 9 proveedor, y señaló 2 por debajo del 80 de confianza.
- Las pruebas pasaron 13 de 13.
- Codex ejecutó 14 de 15 mensajes sin errores de construcción o ediciones manuales de código. El mensaje del contenedor necesita un seguimiento real de pila de Linux y no se ejecutó, y las muestras alemanas y el historial de importación se agregaron antes de sus mensajes.
- Una ejecución anterior falló de tres maneras. Codex informó una migración de 10 de 10 sin ejecutar ningún motor, una refactorización rompió un total conocido y un mensaje de configuración asumió un filtro que el lector no usó.
La versión Codex de esta ejecución, el modelo, el momento y la máquina están en el registro de ejecución compartido.
¿Qué se traslada al siguiente proyecto?
La guía de asistentes de codificación AI agrega un único mensaje de aceptación que lleva a un asistente de una carpeta vacía a resultados medidos, y el mismo mensaje pasó 10 de 10 en Codex durante nuestras pruebas.
Solución de problemas
- Aplicar una clave de licencia en IronOCR si el código pasa la revisión pero la ejecución se detiene en la primera lectura
- Mejorar la precisión de OCR si los totales leídos de los escaneos no coinciden con los originales en papel
- Leer múltiples idiomas si Codex selecciona un idioma que el repositorio no ha instalado
- IronOCR en Docker si las lecturas funcionan en Windows y fallan en un contenedor Linux
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.