.NET에서 PDF 파일 분류: 튜토리얼 및 샘플 코드

.NET에서 PDF 파일을 분류하는 것은 문서 워크플로를 자동화하고, 인사이트를 추출하며, 수동 검토 없이 콘텐츠를 라우팅하는 데 필수적입니다. GroupDocs.Classification Cloud SDK for .NET은 PDF 분류를 쉽고 확장 가능하게 만드는 강력한 API를 제공합니다. 이 튜토리얼에서는 프로젝트 설정 및 분류 체계 구성부터 배치 처리, 스캔된 PDF에 대한 OCR 처리, 성능 튜닝까지 완전한 PDF 분류 워크플로를 배우게 되며, 바로 실행할 수 있는 코드 예제가 제공됩니다.

.NET에서 PDF 파일 분류 단계

NuGet 패키지 추가 - dotnet add package GroupDocs.Classification-Cloud 명령을 실행하여 라이브러리를 프로젝트에 포함합니다.
API 클라이언트 생성 및 구성 - ClassificationApi를 클라이언트 ID와 비밀 키로 초기화합니다.
PDF 업로드 - UploadFile 엔드포인트를 사용해 문서를 클라우드 스토리지에 전송합니다.
분류 체계 정의 - 카테고리를 키워드에 매핑하는 JSON 파일을 제공하여 분류 엔진을 안내합니다.
분류 메서드 호출 - 파일 ID, 분류 체계 및 선택적 신뢰 임계값과 함께 ClassifyDocument를 호출합니다.
결과 처리 - ClassificationResult 객체를 반복하면서 Confidence 속성을 확인해 신뢰도가 낮은 라벨을 필터링합니다.

요청 객체에 대한 자세한 내용은 API reference를 참조하십시오.

PDF 파일을 효율적으로 분류하기 (.NET) - 전체 코드 예제

다음 예제는 오류 처리와 결과 처리를 포함하여 단일 PDF 파일에 대한 완전한 엔드‑투‑엔드 분류를 보여줍니다.

Note: 이 코드 예제는 핵심 기능을 보여줍니다. 프로젝트에서 사용하기 전에 파일 경로(sample.pdf, taxonomy.json)를 업데이트하고, 자리 표시자 자격 증명을 실제 YOUR_CLIENT_ID 및 YOUR_CLIENT_SECRET으로 교체한 뒤 개발 환경에서 충분히 테스트하십시오. 문제가 발생하면 공식 문서를 참조하거나 지원 팀에 문의하십시오.

cURL을 사용한 REST API를 통한 PDF 분류

SDK는 REST API를 통해 작동하므로 cURL을 사용하여 직접 호출할 수도 있습니다. 아래는 일반적인 단계입니다.

액세스 토큰 얻기

curl -X POST "https://api.groupdocs.cloud/v1.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","grant_type":"client_credentials"}'

PDF 파일 업로드

curl -X POST "https://api.groupdocs.cloud/v1.0/storage/file/upload" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@sample.pdf"

문서 분류

curl -X POST "https://api.groupdocs.cloud/v1.0/classification/classify" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileId": "sample.pdf",
           "taxonomy": "{\"categories\":[{\"name\":\"Invoice\",\"keywords\":[\"amount\",\"total\",\"invoice\"]}]}",
           "confidenceThreshold": 0.6
         }'

결과 다운로드 (필요한 경우) - API는 JSON을 직접 반환합니다; 파일로 파이프할 수 있습니다.

자세한 내용은 공식 API 문서를 참조하십시오.

.NET에서 설치 및 설정

NuGet 패키지 설치

dotnet add package GroupDocs.Classification-Cloud

최신 바이너리 다운로드 (선택 사항) release page에서.
임시 라이선스 추가 (개발 전용) 라이선스 파일을 복사하고 코드 예제에 표시된 대로 Configuration 객체를 초기화합니다.
연결 확인 - GetSupportedFileTypes 호출을 간단히 실행하여 클라이언트가 서비스에 접근할 수 있는지 확인합니다.

.NET에서 PDF 분류를 위한 GroupDocs.Classification Cloud SDK 사용

SDK는 HTTP 처리, 직렬화 및 오류 매핑을 추상화하여 비즈니스 로직에 집중할 수 있도록 합니다. 지원되는 기능은 다음과 같습니다:

다중 언어 - API는 언어에 구애받지 않으며; .NET 클라이언트는 동일한 계약을 따릅니다.
분류 체계 기반 분류 - 카테고리를 한 번 정의하면 프로젝트 전반에 걸쳐 재사용할 수 있습니다.
신뢰도 점수 - 각 라벨에는 신뢰도 값이 포함되어 있어 임계값 기반 필터링을 가능하게 합니다.

이러한 기능을 이해하면 견고한 PDF 분류 워크플로를 설계하는 데 도움이 됩니다.

GroupDocs.Classification Cloud SDK 이 작업에 중요한 기능

배치 처리 - 단일 요청으로 수천 개의 PDF를 분류합니다.
OCR 통합 - 분류하기 전에 스캔된 PDF에서 텍스트를 자동으로 추출합니다.
맞춤 분류 체계 지원 - 도메인에 맞게 JSON 또는 XML 분류 체계를 업로드합니다.
상세 로깅 - 문제 해결 및 감사 추적을 위해 요청 ID를 검색합니다.

분류 체계 및 신뢰 임계값 구성

카테고리를 설명하는 taxonomy.json 파일을 생성합니다:

{
  "categories": [
    {
      "name": "Invoice",
      "keywords": ["invoice", "amount", "total", "due"]
    },
    {
      "name": "Resume",
      "keywords": ["experience", "education", "skills", "profile"]
    }
  ]
}

ClassifyDocumentRequest를 빌드할 때 ConfidenceThreshold 속성을 설정하십시오(예: 0.6). 이는 불확실한 예측을 필터링합니다. 도메인의 false positive 허용 수준에 따라 이 값을 조정하십시오.

대용량 PDF 배치 성능 최적화

Chunk the batch - 대용량 컬렉션을 100‑200개의 파일 그룹으로 나누어 타임아웃을 방지합니다.
Enable async processing - SubmitJob 엔드포인트를 사용하고 GetJobStatus를 폴링하여 스레드를 해제합니다.
Reuse the same taxonomy - 분류 체계를 한 번 로드하고 모든 요청에 동일한 JSON 문자열을 재사용합니다.
Parallel uploads - Task.WhenAll을 사용해 파일을 동시에 업로드하여 네트워크 지연을 줄입니다.

시나리오	권장 접근 방식
< 100 PDF	동기식 단일 요청
100‑1,000 PDF	청크된 동기식 배치
> 1,000 PDF	비동기 작업 제출 + 폴링

스캔된 PDF 처리 및 OCR 통합

스캔된 문서는 선택 가능한 텍스트 대신 이미지로 구성됩니다. 이를 분류하려면:

요청에서 ocr 플래그를 true 로 설정합니다.
선택적으로 ocrLanguage를 지정합니다 (예: 영어는 "en").
서비스는 분류 규칙을 적용하기 전에 OCR을 내부적으로 실행합니다.

이 두 단계 프로세스는 이미지 전용 PDF가 분류 시 기본 PDF와 동일하게 처리되도록 보장합니다.

일반적인 분류 오류 해결

401 Unauthorized - ClientId와 ClientSecret이 올바른지, 토큰 요청이 성공했는지 확인하십시오.
400 Bad Request (Invalid Taxonomy) - 분류 체계 JSON이 올바르게 형식화되었는지 확인하십시오; 괄호가 누락되면 이 오류가 발생합니다.
404 Not Found (File ID) - 파일이 성공적으로 업로드되었는지, fileId가 저장 경로와 일치하는지 확인하십시오.
Low confidence scores - 분류 체계 키워드를 검토하고, 보다 대표적인 용어를 추가하거나 학습 세트를 늘리십시오.

전체 오류 코드 목록은 API 참조를 참조하십시오.

.NET에서 PDF 분류를 위한 모범 사례

분류 체계를 작고 집중적으로 유지 - 겹치는 키워드가 너무 많으면 정확도가 떨어집니다.
버전 관리된 분류 체계 파일 사용 - 변경 사항을 추적하기 위해 소스 제어에 저장합니다.
적절한 신뢰도 임계값 설정 - 0.6부터 시작하고 검증 결과에 따라 조정합니다.
작업 상태 모니터링 - 성능 분석을 위해 요청 ID와 응답 시간을 기록합니다.
자격 증명 보안 - ClientId와 ClientSecret을 환경 변수 또는 Azure Key Vault에 저장합니다.

결론

.NET에서 PDF 파일을 분류하는 것이 GroupDocs.Classification Cloud SDK for .NET을 사용하면 간단해집니다. 위에서 설명한 단계대로 SDK를 설정하고, 명확한 분류 체계를 정의하며, 스캔된 PDF에 대한 OCR을 처리하고, 배치 성능을 최적화하면 문서‑집중형 애플리케이션에 대해 신뢰할 수 있고 확장 가능한 분류 서비스를 구축할 수 있습니다. 프로덕션 사용을 위해 적절한 라이선스를 확보하는 것을 기억하세요; 임시 라이선스 페이지에서 임시 라이선스로 시작한 후 필요에 따라 전체 구독으로 업그레이드할 수 있습니다.

FAQ

Q: .NET에서 PDF 파일을 높은 신뢰도로 분류하려면 어떻게 해야 하나요?
A: 요청에 ConfidenceThreshold를 설정하여 신뢰도가 낮은 결과를 필터링합니다. SDK는 각 레이블에 대한 신뢰도 점수를 반환하므로 선택한 수준 이상의 예측만 유지할 수 있습니다. 자세한 내용은 공식 문서를 참조하세요.

Q: SDK가 스캔된 PDF에 대한 OCR을 지원하나요?
A: 예. 분류 요청에서 ocr 플래그를 설정하여 OCR을 활성화합니다. 서비스는 분류 체계를 적용하기 전에 이미지 기반 PDF에서 텍스트를 추출하여 스캔 문서의 정확성을 향상시킵니다.

Q: 수천 개의 PDF를 처리하는 가장 좋은 방법은 무엇인가요?
A: 비동기 작업을 사용한 배치 분류를 이용하세요. 큰 세트를 관리 가능한 청크로 나누고 SubmitJob을 통해 제출한 다음, 완료될 때까지 GetJobStatus를 폴링합니다. 이 접근 방식은 시간 초과를 방지하고 처리량을 최대로 합니다.

Q: 개발용 임시 라이선스는 어디서 받을 수 있나요?
A: 임시 라이선스 페이지를 방문하여 30‑일 라이선스 키를 생성하세요. API 호출을 하기 전에 Configuration에 적용하십시오.

.NET에서 PDF 파일 분류 단계#

PDF 파일을 효율적으로 분류하기 (.NET) - 전체 코드 예제#

cURL을 사용한 REST API를 통한 PDF 분류#

.NET에서 설치 및 설정#

.NET에서 PDF 분류를 위한 GroupDocs.Classification Cloud SDK 사용#

GroupDocs.Classification Cloud SDK 이 작업에 중요한 기능#

분류 체계 및 신뢰 임계값 구성#

대용량 PDF 배치 성능 최적화#

스캔된 PDF 처리 및 OCR 통합#

일반적인 분류 오류 해결#

.NET에서 PDF 분류를 위한 모범 사례#

결론#

FAQ#

자세히 읽기#