Como usar o IronQR com o ChatGPT Codex

Curtis Chau
Curtis Chau
Atualizado: 9 de outubro de 2026

Os reveses de códigos QR frequentemente chegam como pastas desorganizadas contendo etiquetas de ativos digitalizadas, fotos de celular no local, cópias de fax, arquivos de zero bytes devido a erros de scanner e folhas de rosto sem códigos. Um loop ingênuo que processa um arquivo de cada vez para no primeiro arquivo corrompido e não rastreia quais imagens falharam ou as razões da falha.

ChatGPT Codex é a agente de codificação da OpenAI. Ele opera em terminais, IDEs, no aplicativo de desktop do ChatGPT e na nuvem, tudo sob um único login do ChatGPT. IronQR é a biblioteca de código QR para .NET da Iron Software.

Cada prompt instrui o Codex a executar a tarefa e gerar um arquivo de resultados com uma linha por imagem. Como os trabalhos em lote podem processar arquivos que não produzem resultados, todas as contagens referenciadas neste guia são derivadas desses arquivos de resultados, conforme indicado nos prompts.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronQR

Instale o IronQR executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Inicie o Codex em um projeto de console .NET contendo sua pasta de imagens e especifique os requisitos de processamento em lote.

$ironqr Add the IronQR package to this console project, then make Program.cs
decode every file in Backlog/sample/ with QrReader.ReadAsync. Write
out/quickstart.csv with one row per file (name, decoded value or empty, QR
type, exception type if the file threw) and print the decoded, empty, and
threw counts by reading that CSV back. Load the key out of the
IRONQR_LICENSE_KEY variable. Call Dispose() on each QrImageInput yourself
instead of a using block, which throws in IronQR 2026.10.1. Run dotnet build
and dotnet run and fix whatever fails.
Text

A menção $ironqr carrega a habilidade do IronQR antes que o Codex escreva o código.



O que é ChatGPT Codex e como ele se encaixa no trabalho de código QR para .NET?

O Codex trabalha dentro das permissões que você concede a ele. Ele escreve o decodificador, roda nas imagens, lê a saída e corrige o código. Instale o CLI com npm install -g @openai/codex do repositório Codex CLI e veja a documentação Codex CLI para uso no terminal.

Um revés com a verdade absoluta torna a revisão curta. Um membro inventado falha na compilação, e uma decodificação errada aparece como uma linha que não concorda com Backlog/manifest.csv.

O agente pode estruturar cada lote de forma diferente, mas o decodificador deve retornar o mesmo valor para uma determinada imagem em qualquer contagem de threads. Essa consistência pertence à biblioteca, e o IronQR cobre as partes que um revés necessita.

  • Fotos e digitalizações em uma chamada: o modo QrScanMode.Auto executa o modelo de detecção e, quando o modelo não encontra nada, tenta novamente com uma digitalização básica. O guia de modos de digitalização compara-o com os dois modos de passagem única.
  • O tipo de símbolo em cada resultado: QrResult.QrType separa QR padrão (QrEncoding.QRCode) de Micro QR e rMQR, para que um validador possa rejeitar etiquetas que não são etiquetas de ativos.

Como você escreve um prompt de IronQR e configura o Codex para ele?

Um prompt eficaz de lote IronQR declara seis coisas. Para este revés, a entrada é cada PNG e JPEG em Backlog/images/, um SemaphoreSlim dimensionado por uma opção --concurrency define a concorrência, e a saída é out/pipeline.csv com uma linha por arquivo. Um arquivo que gera um erro recebe uma linha enquanto o lote continua. A prova é uma correspondência linha a linha com out/sequential.csv, e as restrições são nenhum novo pacote e Auto como padrão.

A pesquisa da OpenAI sobre alucinação conclui que o treinamento e a avaliação recompensam a adivinhação, e em um trabalho em lote a adivinhação é geralmente um total no resumo de encerramento.

Dicas: Antes de enviar um prompt de lote, encontre o arquivo de saída que ele nomeia.

O Codex descobre habilidades na pasta .agents/skills do repositório, e cada habilidade é uma pasta contendo um SKILL.md com um nome e uma descrição em seu frontmatter. Salve o skill.md do IronQR como .agents/skills/ironqr/SKILL.md e a menção $ironqr é resolvida. O Codex também pode escolher a habilidade sem a menção quando uma tarefa coincide com sua descrição.

AGENTS.md carrega as regras com as quais cada sessão começa. O Codex lê no máximo um desses arquivos de cada diretório entre a raiz do repositório e a pasta em que foi iniciado, e um arquivo mais profundo sobrepõe as orientações acima. O comando /init esboça um. O prompt abaixo também nomeia o índice llms.txt do IronQR como uma referência de API.

Create the repository's AGENTS.md with a section titled QR decoding. It
should say that IronQR (package IronQR, namespace IronQr) is the only QR
library here, that the ironqr skill in .agents/skills/ironqr/ and IronQR's
llms.txt documentation index are the API references, that the key is read
from IRONQR_LICENSE_KEY and never printed or written to a file, that
QrImageInput is disposed with an explicit Dispose() call and never a using
block, that Backlog/manifest.csv is ground truth and read-only, and that any
count, rate, or timing you report must come from a per-image results file
written in the same turn, named in your reply.
Text

Como você pede ao Codex para adicionar o IronQR e decodificar uma primeira pasta?

Show me the IronQR PackageReference in AssetBacklog.csproj and the installed
version. Then run dotnet list package --include-transitive and quote the lines
for IronQR.Slim and Microsoft.ML.OnnxRuntime, since the detection model
depends on them. Change no package references.
Text

O pacote IronQR traz IronQR.Slim para a API gerenciada, Microsoft.ML.OnnxRuntime para detecção e os leitores nativos do Windows. Um projeto apenas com IronQR.Slim, que no Windows também precisa de IronSoftware.ReaderInternals.Windows, ainda lê com a digitalização básica mas não pode rodar o modelo de detecção. O pacote é IronQR com R maiúsculo enquanto o namespace é IronQr, então uma diretiva using IronQR falha na compilação. Verifique o changelog do IronQR antes de fixar uma versão.

O IronQR não adiciona marca d'água de teste nas leituras. Uma primeira leitura sem licença lança LicensingException com a mensagem "Produção Licença Necessária", e com ReadAsync a exceção fica visível quando a tarefa é esperada. Em um lote, isso se torna uma linha de falha idêntica por imagem.

Move the license setup into a Startup.ApplyIronQrKey method called first in
Program.cs. If IRONQR_LICENSE_KEY is unset or License.IsLicensed is false,
exit with code 2 and one clear line on stderr before any image is opened,
because IronQR throws on the first read instead of degrading. Run the program
once as is and once with the variable removed for that single command, and
report both exit codes and what IsLicensed returned.
Text

A página de chaves de licença cobre chaves de teste e os arquivos de configuração que o IronQR também lê. O tipo de exceção é interno para o assembly IronQr, então capturar LicensingException por tipo falha na compilação com o erro CS0122.

Um decodificador sequencial vem a seguir, e seu arquivo de resultados torna-se a referência para cada modo mais rápido.

Create Services/BacklogDecoder.cs with DecodeAsync(string path) returning an
ImageOutcome record: file, status (Decoded, Empty, Unreadable), values, QR
types, exception type and message, and milliseconds. Open the file with
AnyBitmap.FromFile, read with QrScanMode.Auto, and never let one file stop
the batch. Add a --sequential mode that runs it over Backlog/images/ one file
at a time, writes out/sequential.csv, and starts out/runs.csv with the mode
and wall time. Report the status counts and the wall time from those files.
Text

Como você decodifica uma pasta em paralelo com o IronQR?

O guia de async e multithreading chama um leitor separado por iteração o padrão seguro, porque o IronQR não faz garantias explícitas de segurança de thread para uma instância compartilhada. O próximo prompt tem o agente explorador integrado do Codex, um agente focado em leitura para exploração de base de código, verificar isso na documentação antes que algo vá para paralelo.

Ask the explorer agent to answer this without editing anything. Before the
decoder goes parallel, list every QrReader, QrImageInput, and AnyBitmap that
BacklogDecoder creates or keeps, say which could be shared across threads,
and back each answer with a quote from
https://ironsoftware.com/qr/csharp/how-to/async-multithreading/ or the
ironqr skill. Flag anything the documentation leaves unstated.
Text

Na calibração, compartilhando um leitor em 32 threads produziu os mesmos resultados que um leitor por arquivo. Uma versão posterior pode diferir, e um leitor por arquivo custa pouco.

O objeto de entrada também precisa de cuidado. Na versão 2026.10.1, um bloco de uso em torno dele lança NotImplementedException na saída, mesmo após uma leitura bem-sucedida, então um lote registraria cada imagem boa como uma falha. Revise cada diferença para um.

Para a versão paralela, o prompt nomeia o agente de trabalho incorporado, que faz a edição em seu próprio thread.

Have the worker agent add a --parallel mode with Parallel.ForEach,
MaxDegreeOfParallelism from a --threads option (default
Environment.ProcessorCount), and a new QrReader per file. Use the synchronous
Read inside the loop body, since Parallel.ForEach does not await an async
lambda. Write out/parallel.csv sorted by file name, then compare its status
and value columns with out/sequential.csv and fix any row that differs
before you finish. Append mode, thread count, and wall time to out/runs.csv.
Text

Uma lambda assíncrona passada para Parallel.ForEach compila como async void, então o loop retorna antes que as leituras terminem e o arquivo de resultados sai curto. A comparação com o arquivo sequencial o detecta.

Como você limita leituras simultâneas com ReadAsync?

Um loop paralelo bloqueia um thread por leitura. ReadAsync atrás de um SemaphoreSlim mantém um número fixo de leituras em andamento e deixa o thread de chamada livre, o padrão que o guia async fornece para lotes de alto volume. Ele requer um IQrInput e não possui sobrecarga para um caminho de arquivo, então cada tarefa ainda abre seu próprio bitmap.

Add a --pipeline mode: Task.WhenAll over every file, each task waiting on a
SemaphoreSlim sized by --concurrency and awaiting ReadAsync. Run it at
concurrency 2, 8, and Environment.ProcessorCount, writing
out/pipeline-c<N>.csv for each and appending to out/runs.csv. Confirm each
file matches out/sequential.csv row for row, then tell me which setting was
fastest according to runs.csv.
Text

O modelo de detecção já espalha uma leitura por vários núcleos, então um limite maior não precisa ser mais rápido. Deixe runs.csv escolher o limite para seu hardware, e mantenha o semáforo para o que faz de forma confiável, que é limitar o uso de memória.

Qual modo de digitalização um lote deve usar?

O modelo de detecção lê fotos que a passagem básica não detecta, e também contabiliza a maior parte do tempo que cada leitura leva.

Measure what the machine learning detector costs on this backlog. Run the
pipeline at the fastest concurrency from runs.csv, first under
QrScanMode.Auto and then under QrScanMode.OnlyBasicScan, writing
out/mode-auto.csv and out/mode-basic.csv with per-image milliseconds. Join
both with the category column of Backlog/manifest.csv and report decoded
count and median milliseconds per category for each mode. If either mode
reads files the other misses, keep Auto as the default and build a single
OnlyBasicScan retry of its Empty files into the decoder for every later run.
Rerun to out/mode-fallback.csv and count the recoveries.
Text

Ambos os modos leem cada digitalização limpa e cópia de fax, e cada uma perdeu um punhado diferente de fotos de telefone. Nas fotos que apenas a passagem básica leu, o modelo de detecção localizou o código mas não pôde decodificá-lo, então o Auto nunca retrocedeu. Repetindo os arquivos vazios com QrScanMode.OnlyBasicScan recuperou cada foto.

Como você valida valores decodificados e relata falhas?

Um lote encontra três tipos de falha, e cada um parece diferente no código.

EntradaResultadoStatus
Vazio, truncado ou arquivo não-imagemO carregamento da imagem lança antes que o IronQR rodeIlegível
Sem código, ou dano além da correção de erroUma coleção vazia, nunca nulaVazio
Qualquer código, lido no modo somente detecçãoPontos de canto, um Value vazio, um QrType de QrEncoding.NoneVazio, não Decodificado

A terceira linha é a perigosa. Nosso primeiro decodificador sequencial teria contado como Decodificado, porque só verificava se algum resultado retornava.

Backlog/README.md defines a valid asset tag. Add Services/TagValidator.cs and
apply it after each read: a decode only counts when the symbol is a standard
QR code (QrEncoding.QRCode), the value matches the documented pattern, and
the Luhn check digit holds. Give the others the statuses WrongSymbol,
InvalidFormat, or BadCheckDigit. Rerun the pipeline to out/validated.csv and
list every file whose status disagrees with expected_status in the manifest.
Text

Um dígito de verificação faz parte dos seus dados, então o IronQR não pode validá-lo. A correção de Reed-Solomon dentro da leitura, que o guia de checksum e tolerância a falhas descreve, apenas prova que o símbolo foi decodificado, e um resultado não carrega propriedade de confiança. Uma etiqueta com um dígito de verificação errado é digitalizada perfeitamente, mas ainda é inválida.

O guia de mensagens de erro do IronQR mostra o padrão de registro por arquivo que o próximo prompt aplica a todo o revés.

Every file that is not Decoded needs a recorded reason. Write one JSON line
per file to out/decode-log.jsonl (file, status, exception type, message,
milliseconds), send IronQR's own log to out/ironqr-debug.log through
IronQr.Logging.Logger, and generate out/failures.md from the JSONL only: one
section per status other than Decoded, a count, and every file name. Then
check the section counts against out/validated.csv.
Text

Na versão 2026.10.1, o log IronQr.Logging.Logger registra o caminho da digitalização que cada leitura tomou, como uma digitalização de detecção com o modelo de aprendizado de máquina. Como o relatório é construído apenas a partir do JSONL, uma falha que o decodificador nunca registrou aparece como uma contagem que não concorda com o arquivo de resultados.

Como você diagnostica uma imagem que não será decodificada?

O Codex pode olhar uma imagem. Anexe o arquivo com codex --image quando você iniciar a sessão, ou cole-o no compositor.

I attached IMG_0018.png from Backlog/images/ with codex --image. The pipeline
marks it Empty. Look at the picture and tell me whether it is a damaged code,
a page with no code, or a capture problem a rescan would fix. Then test your
answer: read it with all three QrScanMode values and write
out/retry-IMG_0018.csv. Do not change the pipeline.
Text

Em nossa execução, todos os três modos retornaram vazios para este arquivo, e na calibração o modelo de detecção não encontrou nada para localizar. O código em si está danificado, então a perda está além do que a correção de erros recupera, e nem outra leitura nem uma nova digitalização da mesma etiqueta mudarão isso. A correção é uma etiqueta de substituição e, se você imprimir as etiquetas você mesmo, um nível mais alto de correção de erro.

Como você depura a saída incorreta de lotes de ponta a ponta?

Send the explorer agent into Jobs/NightlyImport.cs and Logs/nightly-2026-10-06/
before anything is edited. That run reported six unreadable files and no other
failure, yet Backlog/archive-index-gaps.csv lists assets the archive never
received. Find what the missing assets have in common, explain why the job
counted them as successes, and propose the smallest fix together with the
command that would prove it. Put the findings in out/nightly-diagnosis.md and
change no code.
Text

Aprove o diagnóstico antes de qualquer correção. Um bom cota a linha que decide o sucesso. Verifique a correção proposta contra out/mode-fallback.csv também.

Como transformar código único em componentes reutilizáveis e testados?

Put the worker agent on folding the modes into a BacklogJob class. Add the
Microsoft.Extensions.DependencyInjection package, register the job with it,
and configure it with a BacklogOptions record (input folder, concurrency,
scan mode, output folder). Keep the validator, the basic-scan retry, and the
logging in it, stay under 160 lines, and add XML doc comments. Before
finishing, run it over Backlog/images/ into out/final.csv and confirm every
row agrees with the manifest's expected_status and expected_value.
Text

Um refatoramento pode descartar o validador, o retry de varredura básica, ou o leitor por arquivo sem um erro de compilação. Apenas uma repetição completa contra a verdade absoluta detecta isso.

Add an xUnit project, AssetBacklog.Tests, and cover BacklogJob with tests
that read real files from Backlog/images/: a clean scan decodes to its
manifest value, the zero-byte file comes back Unreadable without throwing, a
damaged image is Empty, a Micro QR label is WrongSymbol, a bad check digit is
BadCheckDigit, and a parallel run over 40 files matches a sequential one.
Assert on status and value. Run dotnet test and report the totals it prints.
Text

O manifesto corrige o status e o valor, enquanto os tempos mudam de execução para execução.

Mantenha perguntas recorrentes sobre o IronQR na habilidade do repositório. A página de prompts personalizados do OpenAI marca a pasta ~/.codex/prompts obsoleta em favor das habilidades.

$ironqr Using the IronQR API reference, list every member of QrResult and say
whether IronQR reports a confidence or checksum score for a read. Then point
to the line in BacklogJob that decides a file is Decoded.
Text

Em nossa execução, o Codex listou os quatro membros de um resultado e rastreou Decodificado do trabalho através do decodificador até a linha do validador que o retorna.

Como você reutiliza esses prompts em outra pasta de imagens?

Altere os caminhos, e todos os prompts acima serão executados conforme escritos. O guia de assistentes de codificação AI executa um único prompt de aceitação de ponta a ponta e publica o resultado.

O que os prompts produziram em uma execução real?

Enviamos todos os prompts acima para o Codex na ordem, em um único thread, contra um repositório de exemplo. Ele contém um aplicativo de console e um revés de 301 imagens (digitalizações limpas, fotos de celular, cópias de fax, etiquetas danificadas, folhas de rosto em branco, etiquetas de prateleira Micro QR, etiquetas inválidas e seis arquivos que não são imagens), com um manifesto do status e valor esperados de cada um. Após a sessão, reconstruímos o projeto em Release e executamos os testes. Também decodificamos cada imagem independentemente para verificar os resultados abaixo.

  • O retry de varredura básica elevou Decodificado de 256 a 264. Antes disso, cada modo decodificou 256 de 301, e 16 arquivos diferiram entre os dois.
  • Uma digitalização limpa levou uma mediana de 360 ms sob Auto e 35 ms sob a varredura básica, que rodou todo o revés em 7 s ao limite 2.
  • O decodificador sequencial registrou 256 Decodificado, 39 Vazio e 6 Ilegível em 71 s.
  • O modo paralelo escreveu as mesmas 301 linhas em 60 s a 32 threads, e o pipeline as escreveu em 55, 66 e 68 s aos limites 2, 8 e 32.
  • No início rápido, 9 de 12 linhas foram decodificadas, 2 voltaram vazias e 1 arquivo de zero bytes gerou erro.
  • A validação combinou com o manifesto com 240 Decodificado, 31 Vazio, 8 SímboloErrado, 8 FormatoInválido, 8 DígitoDeVerificaçãoErrado e 6 Ilegível.
  • O relatório de falhas teve 61 registros, um por arquivo falhado.
  • Após o refatoramento, o trabalho de 64 linhas combinou com o manifesto em 301 de 301 linhas, e 6 de 6 testes passaram, novamente em Release.
  • Todos os 16 prompts rodaram com cada compilação passando e sem edições manuais de código. Os prompts de 13 a 16 atingiram o limite de uso do plano gratuito e retomaram no mesmo thread após o Codex ter sido reiniciado.
  • Antes do prompt de investigação, adicionamos um trabalho noturno com uma falha planejada, seus logs e uma lista de lacunas. O Codex encontrou o modo apenas de detecção em JPEGs de foto e uma verificação de sucesso que aceita qualquer resultado.

A versão do Codex, modelo, tempo e máquina de teste para esta execução estão no registro de execução compartilhado.


Solução de problemas


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.

Leia Mais

Pronto para começar?

Downloads no NuGet 82,442Versão:2026.11recém-lançado