C#에서 OCR 디버깅 방법

This article was translated from English: Does it need improvement?
Translated
View the article in English

IronOCR 사용하면 OCR 오류를 원천적으로 감지하고, 단어 및 문자 수준에서 인식 품질을 평가하고, 장시간 실행되는 작업을 실시간으로 모니터링할 수 있습니다. 진단 파일 로깅, 유형별 예외 계층 구조, 결과별 신뢰도 점수, OcrProgress 이벤트와 같은 내장 도구는 프로덕션 파이프라인에서 이러한 워크플로를 지원합니다.

이 가이드에서는 진단 로깅 활성화, 유형별 예외 처리, 신뢰도 점수를 사용한 출력 유효성 검사, 실시간 작업 진행 상황 모니터링, 배치 파이프라인 오류 분리 등 각 기능에 대한 실제 작동 예제를 살펴봅니다.

빠른 시작: 전체 OCR 진단 로깅 활성화

첫 번째 Read 호출 전에 Installation 클래스에 LogFilePathLogging방법를 설정하십시오. Tesseract 초기화, 언어 팩 로딩 및 처리 세부 정보를 로그 파일에 기록하려면 두 가지 속성만 있으면 됩니다.

  1. NuGet 패키지 관리자를 사용하여 https://www.nuget.org/packages/IronOcr 설치하기

    PM > Install-Package IronOcr
  2. 다음 코드 조각을 복사하여 실행하세요.

    IronOcr.Installation.LogFilePath = "ocr.log"; IronOcr.Installation.Logging방법 = IronOcr.Installation.Logging방법s.All;
  3. 실제 운영 환경에서 테스트할 수 있도록 배포하세요.

    무료 체험판으로 오늘 프로젝트에서 IronOCR 사용 시작하기

    arrow pointer


진단 로깅을 활성화하는 방법은 무엇인가요?

Installation 클래스는 세 가지 로깅 제어 기능을 제공합니다. Read 메서드를 호출하기 전에 다음 설정을 지정하십시오.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-enable-logging.cs
using IronOcr;

// Write logs to a specific file
Installation.LogFilePath = "logs/ocr_diagnostics.log";

// Enable all logging channels: file + debug output
Installation.LoggingMode = Installation.LoggingModes.All;

// Or pipe logs into your existing ILogger pipeline
Installation.CustomLogger = myLoggerInstance;
$vbLabelText   $csharpLabel

Logging방법Logging방법s 열거형에서 플래그 값을 허용합니다.

표 1: 로깅 모드 옵션
방법출력 대상사용 사례
None비활성화됨외부 모니터링을 사용한 프로덕션
DebugIDE 디버그 출력 창로컬 개발
FileLogFilePath서버 측 로그 수집
All디버그 + 파일전체 진단 캡처

CustomLogger 속성은 모든 Microsoft.Extensions.Logging.ILogger 구현을 지원하므로 OCR 진단을 파이프라인의 Serilog, NLog 또는 기타 구조화된 로깅 싱크로 보낼 수 있습니다. 실행 간에 누적된 로그 데이터를 제거하려면 ClearLogFiles 사용하십시오.

로깅이 설정되었으므로 다음 단계는 IronOCR 발생할 수 있는 예외와 각 예외를 처리하는 방법을 이해하는 것입니다.

IronOCR 어떤 예외를 발생시키나요?

IronOCR IronOcr.예외s 네임스페이스 아래에 형식화된 예외를 정의합니다. 포괄적인 차단 대신 이러한 오류를 구체적으로 포착하면 각 오류 유형을 올바른 복구 경로로 연결할 수 있습니다.

표 2: IronOCR 예외 참조
예외일반적인 원인수정 방법
IronOcrInput예외손상되거나 지원되지 않는 이미지/PDFOcrInput로 로딩하기 전에 파일을 검증하세요
IronOcrProduct예외OCR 실행 중 내부 엔진 오류로그를 활성화하고 로그 출력을 확인하고 최신 NuGet 버전으로 업데이트
IronOcrDictionary예외누락되었거나 손상된 .traineddata 언어 파일언어 팩 NuGet 다시 설치하거나 LanguagePackDirectory 설정하세요.
IronOcrNative예외네이티브 C++ 상호 운용 실패Visual C++ 재배포 가능 패키지를 설치하고 AVX 지원 확인
IronOcrLicensing예외누락되었거나 만료된 라이선스 키Read 호출하기 전에 LicenseKey 설정하세요.
LanguagePack예외언어 팩을 예상 경로에서 찾을 수 없습니다LanguagePackDirectory를 확인하거나 NuGet 언어 패키지를 재설치하세요
IronOcrAssemblyVersionMismatch예외부분 업데이트 후 어셈블리 버전이 일치하지 않음NuGet 캐시를 지우고, 패키지를 복원하고, 모든 IronOCR 패키지가 일치하는지 확인하세요

다음 try-catch 블록을 사용하여 각 예외 유형을 개별적으로 처리하고, 조건부 로깅을 위해 예외 필터를 적용하십시오.

입력

IronOCR Solutions에서 Acme Corporation으로 보낸 단일 페이지 공급업체 송장이 LoadPdf를 통해 OcrInput로 업로드되었습니다. 여기에는 네 가지 품목, 세금 및 총액이 포함되어 있어 각 예외 처리기가 현실적인 연습을 할 수 있을 만큼 충분한 텍스트 다양성을 제공합니다.

invoice_scan.pdf: 공급업체 송장(#INV-2024-7829)은 각 유형의 예외 처리기를 순차적으로 시연하는 데 사용됩니다.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-exception-handling.cs
using IronOcr;
using IronOcr.Exceptions;

var ocr = new IronTesseract();

try
{
    using var input = new OcrInput();
    input.LoadPdf("invoice_scan.pdf");

    OcrResult result = ocr.Read(input);
    Console.WriteLine($"Text: {result.Text}");
    Console.WriteLine($"Confidence: {result.Confidence:P1}");
}
catch (IronOcrInputException ex)
{
    // File could not be loaded — corrupt, locked, or unsupported format
    Console.Error.WriteLine($"Input error: {ex.Message}");
}
catch (IronOcrDictionaryException ex)
{
    // Language pack missing — common in containerized deployments
    Console.Error.WriteLine($"Language pack error: {ex.Message}");
}
catch (IronOcrNativeException ex) when (ex.Message.Contains("AVX"))
{
    // CPU does not support AVX instructions
    Console.Error.WriteLine($"Hardware incompatibility: {ex.Message}");
}
catch (IronOcrLicensingException)
{
    Console.Error.WriteLine("License key is missing or invalid.");
}
catch (IronOcrProductException ex)
{
    // Catch-all for other IronOCR engine errors
    Console.Error.WriteLine($"OCR engine error: {ex.Message}");
    Console.Error.WriteLine($"Stack trace: {ex.StackTrace}");
}
$vbLabelText   $csharpLabel

산출

성공 결과

송장이 깔끔하게 로드되고 엔진은 문자 수와 신뢰도 점수를 반환합니다.

터미널 출력에는 invoice_scan.pdf 파일의 OCR 읽기가 성공적으로 완료되었으며, 문자 수와 신뢰도 점수가 표시됩니다.

출력 실패

누락된 PDF 파일을 로드할 때 발생한 예외를 보여주는 터미널 출력

캐치 블록을 가장 구체적인 것부터 가장 일반적인 것 순으로 정렬하세요. when 절은 IronOcrNative예외 필터에서 AVX 관련 오류를 필터링하지만 관련 없는 네이티브 오류는 포착하지 않습니다. 각 핸들러는 예외 메시지를 기록합니다. 포괄적인 블록은 사후 분석을 위해 스택 추적 정보도 캡처합니다.

올바른 예외를 포착하면 무언가 잘못되었다는 것을 알 수 있지만, 엔진이 성공적으로 작동했을 때 얼마나 잘 작동했는지는 알 수 없습니다. 이를 위해서는 신뢰도 점수를 사용하십시오.

신뢰도 점수를 사용하여 OCR 출력 결과를 검증하는 방법은 무엇인가요?

모든 OcrResult Confidence 속성을 노출하며, 이 값은 인식된 모든 문자에 걸쳐 평균화된 엔진의 통계적 정확도를 나타내는 0에서 1 사이의 값입니다. 이 기능은 문서 , 페이지 ,단락 , 단어 ,문자 등 결과 계층 구조의 모든 수준에서 접근할 수 있습니다.

임계값 기반 게이트 패턴을 사용하여 품질이 낮은 결과가 하위 단계로 전파되는 것을 방지하십시오.

입력

품목별 내역, 할인, 합계 및 바코드가 포함된 감열식 영수증으로, LoadImage을 통해 업로드되었습니다. 좁은 폭, 고정폭 글꼴, 흐릿한 인쇄체는 단어별 신뢰도 임계값을 측정하는 실용적인 스트레스 테스트 도구로 활용될 수 있습니다.

FoodMart에서 발행한 품목별 구매 내역, 총액, 적립 포인트가 표시된 감열식 영수증 샘플입니다. 이 이미지는 OCR 입력 자료로 사용되었습니다.

receipt.png: 임계값 기반 신뢰도 검증 및 단어별 정확도 분석을 시연하기 위해 사용된 열전사 영수증 스캔 이미지.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-confidence-scoring.cs
using IronOcr;

var ocr = new IronTesseract();
using var input = new OcrInput();
input.LoadImage("receipt.png");

OcrResult result = ocr.Read(input);
double confidence = result.Confidence;

Console.WriteLine($"Overall confidence: {confidence:P1}");

// Threshold-gated decision
if (confidence >= 0.90)
{
    Console.WriteLine("ACCEPT — high confidence, processing result.");
    ProcessResult(result.Text);
}
else if (confidence >= 0.70)
{
    Console.WriteLine("FLAG — moderate confidence, queuing for review.");
    QueueForReview(result.Text, confidence);
}
else
{
    Console.WriteLine("REJECT — low confidence, logging for investigation.");
    LogRejection("receipt.png", confidence);
}

// Drill into per-page and per-word confidence for diagnostics
foreach (var page in result.Pages)
{
    Console.WriteLine($"  Page {page.PageNumber}: {page.Confidence:P1}");

    var lowConfidenceWords = page.Words
        .Where(w => w.Confidence < 0.70)
        .ToList();

    foreach (var word in lowConfidenceWords)
    {
        Console.WriteLine($"    Low-confidence word: \"{word.Text}\" ({word.Confidence:P1})");
    }
}
$vbLabelText   $csharpLabel

산출

터미널 출력에는 영수증 이미지에 대한 신뢰도 점수, 승인/플래그/거부 결정, 그리고 단어별 낮은 신뢰도 항목에 대한 상세 분석 정보가 표시됩니다.

이 패턴은 OCR이 데이터 입력, 송장 처리 또는 준수 워크플로에 피드되는 파이프라인에서 필수적입니다. 단어 단위 분석을 통해 원본 이미지의 어느 부분이 화질 저하를 유발했는지 정확하게 파악할 수 있습니다. 그런 다음 이미지 품질 필터방향 보정을 적용하고 다시 처리할 수 있습니다. 신뢰 점수에 대한 자세한 내용은 신뢰 수준 사용법을 참조하세요.

장기적인 업무에서는 자신감만으로는 충분하지 않습니다. 엔진이 여전히 진행 중인지 여부도 알아야 하는데, 바로 이 부분에서 OcrProgress 이벤트가 발생합니다.

OCR 진행 상황을 실시간으로 모니터링하려면 어떻게 해야 하나요?

여러 페이지로 구성된 문서의 경우, 각 페이지가 완료된 후 IronTesseractOcrProgress 이벤트가 발생합니다. OcrProgressEventArgs 객체는 진행률, 경과 시간, 총 페이지 수 및 완료된 페이지 수를 표시합니다. 이 예시에서는 경영진 요약, 매출 분석 및 운영 지표를 포함하는 구조화된 비즈니스 문서인 3페이지 분량의 분기 보고서를 입력으로 사용합니다.

입력

2024년 1분기 재무 보고서(3페이지)가 LoadPdf를 통해 업로드되었습니다. 1페이지는 KPI 지표를 포함한 요약 보고서를, 2페이지는 제품 라인 및 지역별 매출표를, 3페이지는 운영 처리량을 다룹니다. 각 페이지 유형별로 페이지 처리 시간이 다르며, 이는 진행 상황 콜백에서 확인할 수 있습니다.

quarterly_report.pdf: 2024년 1분기 재무 보고서(3페이지, 요약, 매출 분석, 운영 지표)로, 페이지별 실시간 `OcrProgress` 콜백을 시연하는 데 사용됩니다.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-progress-monitoring.cs
using IronOcr;

var ocr = new IronTesseract();

ocr.OcrProgress += (sender, e) =>
{
    Console.WriteLine(
        $"[OCR] {e.ProgressPercent}% complete | " +
        $"Page {e.PagesComplete}/{e.TotalPages} | " +
        $"Elapsed: {e.Duration.TotalSeconds:F1}s"
    );
};

using var input = new OcrInput();
input.LoadPdf("quarterly_report.pdf");

OcrResult result = ocr.Read(input);
Console.WriteLine($"Finished in {result.Pages.Count()} pages, confidence: {result.Confidence:P1}");
$vbLabelText   $csharpLabel

산출

터미널 출력에는 3페이지 PDF 파일의 페이지별 OcrProgress 이벤트 콜백, 완료율 및 경과 시간이 표시됩니다.

이 이벤트를 로깅 인프라에 연결하여 OCR 작업 지속 시간을 추적하고 중단을 감지하세요. 경과 시간이 임계값을 초과했는데도 진행률이 증가하지 않으면 파이프라인에서 해당 작업을 조사 대상으로 표시할 수 있습니다. 이는 단일 잘못된 페이지가 전체 작업을 정지시킬 수 있는 배치 PDF 처리에 특히 유용합니다.

진행 상황 모니터링은 실행 상태를 보여주지만, 파일 수준 오류가 발생하면 이를 격리하지 않을 경우 전체 배치 작업이 중단될 수 있습니다.

일괄 OCR 파이프라인에서 오류를 어떻게 처리해야 하나요?

실제 운영 환경에서는 단일 파일 오류로 인해 전체 배치 처리가 중단되어서는 안 됩니다. 파일별로 오류를 분리하고, 실패 상황을 맥락과 함께 기록하며, 마지막에 요약 보고서를 생성합니다. 이 예제는 송장, 구매 주문서, 서비스 계약서가 포함된 스캔 문서 폴더 Plus 오류 경로를 발생시키기 위해 의도적으로 손상된 파일 하나를 처리합니다. 대표적인 예시는 아래와 같습니다.

입력

Directory.GetFiles로 전달된 PDF 폴더에는 송장, 구매 주문서, 서비스 계약서 및 의도적으로 손상된 파일 하나가 포함되어 있습니다. 아래의 두 가지 대표적인 샘플은 파이프라인이 단일 실행에서 처리하는 문서의 다양성을 보여줍니다.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-batch-pipeline.cs
using IronOcr;
using IronOcr.Exceptions;

var ocr = new IronTesseract();
Installation.LogFilePath = "batch_debug.log";
Installation.LoggingMode = Installation.LoggingModes.File;

string[] files = Directory.GetFiles("scans/", "*.pdf");
int succeeded = 0, failed = 0;
double totalConfidence = 0;
var failures = new List<(string File, string Error)>();

foreach (string file in files)
{
    try
    {
        using var input = new OcrInput();
        input.LoadPdf(file);

        OcrResult result = ocr.Read(input);
        totalConfidence += result.Confidence;
        succeeded++;

        Console.WriteLine($"OK: {Path.GetFileName(file)} — {result.Confidence:P1}");
    }
    catch (IronOcrInputException ex)
    {
        failed++;
        failures.Add((file, $"Input error: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.Message}");
    }
    catch (IronOcrProductException ex)
    {
        failed++;
        failures.Add((file, $"Engine error: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.Message}");
    }
    catch (Exception ex)
    {
        failed++;
        failures.Add((file, $"Unexpected: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.GetType().Name}: {ex.Message}");
    }
}

// Summary report
Console.WriteLine($"\n--- Batch Summary ---");
Console.WriteLine($"Total: {files.Length} | Passed: {succeeded} | Failed: {failed}");
if (succeeded > 0)
    Console.WriteLine($"Average confidence: {totalConfidence / succeeded:P1}");

foreach (var (f, err) in failures)
    Console.WriteLine($"  {Path.GetFileName(f)}: {err}");
$vbLabelText   $csharpLabel

산출

터미널 출력에는 파일별 문자 수, 신뢰도 점수, 손상된 PDF에서 발생한 오류 1개, 요약 정보가 포함된 배치 파이프라인 결과가 표시됩니다.

외부 예외 처리 블록은 공유 저장소의 네트워크 시간 초과, 권한 문제 또는 대용량 TIFF 파일의 메모리 부족 상황과 같은 예기치 않은 오류를 처리합니다. 각 오류는 파일 경로와 오류 메시지를 요약 보고서에 기록하며, 루프는 나머지 파일을 계속 처리합니다. batch_debug.log 경로에 있는 로그 파일에는 내부 진단을 트리거하는 모든 파일에 대한 엔진 수준의 세부 정보가 기록됩니다.

서비스 또는 웹 애플리케이션에서 비차단 실행을 위해 IronOCR 동일한 try-catch 구조를 사용하는 ReadAsync 지원합니다.

파이프라인이 오류 없이 실행되었지만 추출된 텍스트가 여전히 잘못된 경우, 근본 원인은 거의 항상 코드보다는 이미지 품질에 있습니다. 이 문제를 해결하는 방법은 다음과 같습니다.

OCR 정확도 문제를 어떻게 해결하나요?

신뢰도 점수가 지속적으로 낮다면 문제는 OCR 엔진이 아니라 원본 이미지에 있습니다. IronOCR 이러한 문제를 해결하기 위한 전처리 도구를 제공합니다.

배포 관련 문제의 경우, IronOCR Azure Functions , Docker 및 Linux , 그리고 일반적인 환경 설정 에 대한 전용 문제 해결 가이드를 제공합니다.

다음엔 어디로 가야 할까요?

이제 런타임 시 IronOCR 디버깅 방법을 이해했으니 다음을 살펴보세요.

프로덕션 사용을 위해, 워터마크 제거 및 전체 기능에 액세스하려면 라이센스 획득을 기억하세요.

A PHP Error was encountered

Severity: Warning

Message: Illegal string offset 'name'

Filename: sections/author_component.php

Line Number: 18

Backtrace:

File: /var/www/ironpdf.com/application/views/main/sections/author_component.php
Line: 18
Function: _error_handler

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 63
Function: view

File: /var/www/ironpdf.com/application/views/products/sections/three_column_docs_page_structure.php
Line: 64
Function: main_view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/views/products/how-to/index.php
Line: 2
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 552
Function: view

File: /var/www/ironpdf.com/application/controllers/Products/Howto.php
Line: 31
Function: render_products_view

File: /var/www/ironpdf.com/index.php
Line: 292
Function: require_once

A PHP Error was encountered

Severity: Warning

Message: Illegal string offset 'title'

Filename: sections/author_component.php

Line Number: 38

Backtrace:

File: /var/www/ironpdf.com/application/views/main/sections/author_component.php
Line: 38
Function: _error_handler

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 63
Function: view

File: /var/www/ironpdf.com/application/views/products/sections/three_column_docs_page_structure.php
Line: 64
Function: main_view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/views/products/how-to/index.php
Line: 2
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 552
Function: view

File: /var/www/ironpdf.com/application/controllers/Products/Howto.php
Line: 31
Function: render_products_view

File: /var/www/ironpdf.com/index.php
Line: 292
Function: require_once

A PHP Error was encountered

Severity: Warning

Message: Illegal string offset 'comment'

Filename: sections/author_component.php

Line Number: 48

Backtrace:

File: /var/www/ironpdf.com/application/views/main/sections/author_component.php
Line: 48
Function: _error_handler

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 63
Function: view

File: /var/www/ironpdf.com/application/views/products/sections/three_column_docs_page_structure.php
Line: 64
Function: main_view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/views/products/how-to/index.php
Line: 2
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 552
Function: view

File: /var/www/ironpdf.com/application/controllers/Products/Howto.php
Line: 31
Function: render_products_view

File: /var/www/ironpdf.com/index.php
Line: 292
Function: require_once

시작할 준비 되셨나요?
Nuget 다운로드 5,556,263 | 버전: 2026.3 방금 출시되었습니다
Still Scrolling Icon

아직도 스크롤하고 계신가요?

빠른 증거를 원하시나요? PM > Install-Package IronOcr
샘플을 실행하세요 이미지가 검색 가능한 텍스트로 바뀌는 것을 확인해 보세요.