문서 내 텍스트 분류

입력 파일을 특정 공통 문서 유형에 대한 스키마 정의 또는 사용자 지정 문서에 대한 스키마로 분류하세요. 문서를 사전 처리하면 분류된 문서의 텍스트를 보다 효율적으로 추출할 수 있습니다.

문서에 스키마 기반 키-값 쌍 추출을 사용하기 전에 텍스트 분류 REST API 요청 본문에서 여러 스키마를 정의하여 문서를 분류할 수 있습니다. 지원되는 사전 정의된 문서 유형 또는 사용자 정의 문서에 대한 스키마 조합을 제공할 수 있습니다. 문서를 미리 분류하면 제공된 스키마에 정의된 필드로만 추출 프로세스를 제한할 수 있습니다. 문서의 키-값 쌍 데이터가 스키마와 일치하지 않는 경우 텍스트 분류 API는 문서가 분류되지 않았음을 나타냅니다.

텍스트 분류 REST API를 사용하여 프로젝트에 저장된 입력 파일을 에셋으로 분류할 수 있습니다.

필수 권한: 문서를 분류하려면 프로젝트에서 관리자 또는 편집자 역할이 있어야 합니다.
필수 자격 증명: watsonx.ai 의 API를 인증하려면 자격 증명을 생성해야 합니다. 자세한 내용은 베어러 토큰 생성을 참조하십시오.

시작하기 전에

관리자는 문서를 처리하는 일련의 머신러닝 모델을 설치해야 합니다. 필요한 모델 집합의 ID는 입니다 wdu.
문서를 프로젝트에 추가하기 전에 다음과 같이 준비하세요:
- 문서에서 비밀번호 보호 기능을 제거하세요.
- PDF 문서가 디지털 인증된 경우, 해당 문서를 DOC 또는 DOCX 과 같은 다른 파일 형식으로 변환하십시오.
특정 사용 사례에 맞게 텍스트 분류 요청에 포함할 매개변수를 결정하세요. 자세한 내용은 텍스트 분류 매개변수를 참조하세요.

프로시저

REST API를 사용하여 비즈니스 문서를 분류하려면 다음의 높은 수준의 단계를 따르세요:

분류하려는 파일을 스토리지 자산에 추가하십시오. 텍스트 추출 프로세스의 결과를 저장할 저장소 자산을 지정할 수도 있습니다.

다음과 같은 저장소 유형을 사용할 수 있습니다:
연결된 저장 자산

문서를 프로젝트의 연결 자산으로 저장한 후, 연결 ID를 사용하여 API에서 해당 파일을 참조하십시오. 자격 증명에 액세스 키와 비밀 키 쌍을 사용하는 연결 자산만 지원됩니다. 자세한 내용은 API에서 참조할 파일 추가하기를 참조하세요.

프로젝트 또는 배포 공간 내 컨테이너
배포 공간 또는 프로젝트의 컨테이너에 입력 문서를 저장하려면, 자산 파일 API를 사용하여 입력 파일을 직접 업로드하십시오. 자세한 내용은 데이터 및 AI 공통 핵심 소프트웨어 API 문서를 참조하십시오.

입력 파일은 API에서 다음과 같은 파일 경로로 참조됩니다:
```
"document_reference": {
  "type": "container",
  "location": {
    "path": "dummy_path/ibm-annual-report-2024-pt1_1-20-1.pdf"
  }
},
"results_reference": {
  "type": "container",
  "location": {
    "path": "dummy_path/results/"
  }
}
```
텍스트 분류 요청 시작 API 메서드를 사용하여 분류 프로세스를 시작합니다. API 요청에 대한 자세한 내용은 REST API 요청 예시를 참조하세요.

metadata.id 필드에 반환되는 ID를 기록해 두세요. 이 ID를 사용하여 나중에 요청 상태를 확인할 수 있습니다.
요청 결과 가져오기 API 메서드를 사용하여 요청 상태를 확인할 수 있습니다.

상태를 확인해야만 어떤 이유로 프로세스가 실패했는지 확인할 수 있습니다.

상태가 completed 인 경우 results 필드에는 문서 분류 프로세스 결과의 세부 정보가 포함됩니다.

REST API 요청 예제

다음 명령은 프로젝트의 Cloud Object Storage 버킷에 저장된 retail_guidebook.pdf 파일에서 텍스트 추출 요청을 제출하고 추출된 결과를 results_data 폴더에 저장합니다.

curl -X POST \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/text/classifications?version=2025-10-08' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJraWQiOi...'

요청 본문은 다음과 같습니다:

{
    "project_id": "e40e5895-ce4d-42a3-b699-8ac764b89a09",
    "document_reference": {
      "type": "connection_asset",
      "connection": {
        "id": "5c0cefce-da57-408b-b47d-58f7785de3ee"
      },
      "location": {
        "bucket":"my-cloud-object-storage-bucket",
        "file_name": "retail_guidebook.pdf"
      }
    },
    "parameters": {
      "languages": [
        "en"
      ],
      "ocr_mode": "enabled",
      "classification_mode": "exact",
      "semantic_config": {
        "schemas": [ {
           "document_type": "Auto_Insurance_Application",
           "document_description": "A California Personal Auto Application form used to collect information necessary for initiating or updating an auto insurance policy. It includes agency, applicant, carrier, and policy details such as contact information, address, policy number, and effective/expiration dates.",
           "additional_prompt_instructions": "Return phone numbers and policy numbers exactly as they appear in the document.",
           "fields": {
              "agency_name": {
                "default": "",
                "example": "Spring Insurance",
                "description": "Name of the insurance agency handling the auto application."
              },
              "applicant_name": {
                "default": "",
                "example": "John Smith",
                "description": "Full name of the person applying for auto insurance."
              },
              "applicant_address": {
                "default": "",
                "example": "245 W 52nd St, Apt 8B, New York, NY 10019",
                "description": "Mailing address of the applicant including street, apartment, city, state, and ZIP code."
              },
              "applicant_phone": {
                "default": "",
                "example": "(917) 555-2843",
                "description": "Phone number for contacting the applicant."
              },
              "applicant_email": {
                "default": "",
                "example": "john.smith@gmail.com",
                "description": "Email address of the applicant."
              },
              "carrier_name": {
                "default": "",
                "example": "Tower Insurance Company",
                "description": "Name of the insurance carrier providing the policy."
              },
              "policy_number": {
                "default": "",
                "example": "10",
                "description": "Unique identifier for the insurance policy."
              },
              "effective_date": {
                "default": "",
                "example": "2023-01-01",
                "description": "Date when the insurance policy becomes effective."
              },
              "expiration_date": {
                "default": "",
                "example": "2024-01-01",
                "description": "Date when the insurance policy expires."
              }
           }
        } ]
      }
    }
  }

응답에서 results 속성의 응답에서 분류 결과를 찾을 수 있습니다:

"results": {
  "completed_at": "2025-10-08T09:05:42.880Z",
  "running_at": "2025-10-08T09:05:27.345Z",
  "status": "completed",
  "document_classified": "True",
  "document_type": "Auto_Insurance_Application"
}

다음에 수행할 내용

텍스트 분류 요청의 결과를 사용하여 키-값 쌍 스키마 정의를 사용하여 문서에서 텍스트를 더 효율적으로 추출하는 방법을 결정할 수 있습니다. 자세한 내용은 텍스트 추출을 참조하십시오.