키-값 쌍 추출을 위한 사용자 지정 스키마 만들기

시작하기 전에

문서를 검토하고 스키마에서 정의하는 필드 이름과 설명을 안내할 다음 정보를 결정하세요:

• 문서에서 추출하려는 데이터 유형
• 추출하려는 데이터의 정확한 레이블
• 페이지에서 각 항목의 위치(예: 왼쪽 상단 헤더 또는 오른쪽 열)

예를 들어, 캘리포니아 개인 자동차 보험 신청서 문서에서 다음 정보를 참고하세요:

• 대행사 이름, 신청자 주소, 이동통신사 이름, 정책 번호 등 추출하려는 데이터를 입력합니다.
• "대행사", "신청자 이름 및 우편 주소", "정책 번호"와 같은 정확한 필드 레이블을 입력합니다. 문서에 표시된 레이블을 그대로 인용하면 기초 모델이 올바른 값에 연결하는 데 도움이 됩니다.

프로시저

1. 스키마 상단의 메타데이터에서 document_description 필드에 문서에 대한 설명을 입력합니다. document_description 필드는 키-값 쌍 추출에 사용되는 기초 모델에 대한 분류기 프롬프트에 포함됩니다.

{
   "document_type": "Auto_Insurance_Application",
   "document_description": "California Personal Auto Application form used to open or update an auto policy.",
   "additional_prompt_instructions": "Return phone numbers exactly as they appear in the document.",
}

1. 스키마에 포함할 필드를 결정합니다. 각 필드에 대해 다음 세 가지 요소를 정의합니다:

   • 필드 이름 : 필드의 고유한 키 이름을 선택합니다.
   • 예제 값입니다 : 모델이 날짜 값이나 정수와 같은 예상 유형을 추론하는 데 도움이 되는 샘플 값을 입력합니다. 예제를 제공하면 모델 성능이 향상됩니다.
   • 설명 : 필드가 나타내는 내용에 대한 간단한 설명을 작성합니다. 설명은 기초 모델에 전달되어 모델이 추출 프로세스 중에 무엇을 찾아야 하는지 이해하는 데 도움이 됩니다.
     중요: 필드 설명은 모델이 문서의 올바른 정보를 검증하고 집중하는 데 도움이 되는 컨텍스트를 제공합니다. 설명은 정확하고 모호하지 않아야 합니다.

   예를 들어 캘리포니아 개인 자동차 보험 신청서 문서에서 대리점 이름을 추출하는 필드를 정의합니다.

   "agency_name": {
     "default": "",
     "example": "Spring Insurance",
     "description": "Name of the insurance agency shown in the Agency section (upper‑left of the page)."
   }
   

2. available_options 매개변수를 사용하여 스키마에 추가 속성 값을 지정합니다. 문서에 명시적으로 언급되어 있지 않지만 문맥이나 시각적 요소에서 유추할 수 있는 필드에 매개변수를 사용합니다. 예를 들어 인보이스에서 통화 값은 문서의 여러 부분에 달러 기호와 함께 표시되지만 미국 달러가 인보이스 통화임을 명시적으로 언급하지 않을 수 있습니다. 이러한 경우 모델이 반환할 수 있는 유효한 통화 값의 닫힌 목록을 제공하여 모델 응답의 환상을 줄일 수 있습니다.

   "currency": {
     "default": "",
     "example": "USD",
     "available_options": ["USD", "EUR", "CNY", "JPY", "GBP", "AUD", "CAD", "CHF", "HKD", "SGD", "INR", "KRW", "MXN", "BRL", "ZAR", "SEK", "NOK", "DKK", "NZD", "TRY", "AED", "THB", "PLN", "IDR", "MYR", "PHP", "RUB", "CZK", "ILS"],
     "description": "The currency used in the invoice."
   }
   

3. 선택 사항입니다: 텍스트 추출 요청에 스키마를 사용하기 전에 로컬에서 JSON 스키마의 유효성을 검사하여 올바른 형식이고 예상 구조와 일치하는지 확인합니다. 다음과 같은 도구를 사용할 수 있습니다:

   • jsonlint.com 를 클릭하여 서식을 확인합니다
   • 스키마를 로드하고 검사하는 Python 스크립트
   • IDE에 내장된 JSON 린터

사용자 지정 스키마 및 API 요청 예시

다음 명령은 상단에 모든 필수 메타데이터가 포함된 완전한 사용자 정의 스키마를 사용하여 텍스트 추출 요청을 제출하고, 그 뒤에 정의가 포함된 필드 집합을 제출합니다. 각 필드에는 비어 있는 기본값, 예제 및 추출 프로세스 중에 모델을 안내하는 설명이 포함되어 있습니다.

curl -X POST \
  'https://{region}.ml.cloud.ibm.com/ml/v1/text/extractions?version=2024-10-18' \
  --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": "ca_auto_insurance_app.pdf"
      }
    },
    "results_reference": {
      "type": "connection_asset",
      "connection": {
        "id": "5c0cefce-da57-408b-b47d-58f7785de3ee"
      },
      "location": {
        "bucket":"my-cloud-object-storage-bucket",
        "file_name": "results_data"
      }
    },
    "parameters": {
      "requested_outputs": [
        "assembly",
        "md",
        "html",
        "plain_text",
        "page_images",
      ],
      "languages": [
        "en"
      ],
      "mode": "standard",
      "ocr_mode": "enabled",
      "create_embedded_images": "disabled",
      "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": "[email protected]",
                "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."
              }
           }
        } ]
      }
    }
  }

우수 사례

다음 모범 사례를 사용하여 효과적인 스키마를 작성하세요:

필드 이름 지정 규칙

밑줄을 사용하여 단어를 구분합니다. 예를 들어 applicantName 대신 applicant_name 을 사용합니다. 이름은 짧지만 설명이 포함된 이름을 사용하세요. 섹션의 필드에는 [section_name]_[field_name] 형식을 사용하고, 테이블 필드의 필드에는 [table_name]_row_[row_number]_[column_name]

효과적인 설명 작성

문서에서 정보가 있는 위치를 구체적으로 명시하세요. 날짜나 숫자와 같은 값의 형식을 변경하는 지침은 포함하지 마세요. 필드를 식별하는 레이블이나 제목을 언급합니다. 특별한 경우나 변동 사항이 있으면 기록해 두세요.

추가 프롬프트 지침 "이미지에 표시된 대로 숫자 서식을 유지하세요."와 같이 특정 문서 유형에 대한 추출 정확도를 높이려면 기초 모델 프롬프트 지침을 사용하세요.

문제점 해결

다음 표에서는 사용자 지정 스키마를 사용할 때 흔히 발생하는 몇 가지 문제와 그 해결 방법에 대해 설명합니다:

자세히 알아보기

• watsonx.ai API 참조 문서

상위 주제: 텍스트 추출 매개변수