Criação de esquemas personalizados para classificação e extração de pares chave-valor

Antes de iniciar

Revise seu documento e determine as seguintes informações que determinarão os nomes e as descrições de campo que você definirá no esquema:

• Os tipos de dados que você deseja extrair do documento
• Os rótulos exatos dos dados que você deseja extrair
• O local de cada item na página, como o cabeçalho superior esquerdo ou a coluna da direita

Por exemplo, observe as seguintes informações no documento de Solicitação de Seguro de Automóvel Pessoal da Califórnia :

• Dados que você deseja extrair, como nome da agência, endereço do solicitante, nome da operadora, número da apólice.
• Os rótulos exatos dos campos, como "AGENCY" (Agência), "APPLICANT'S NAME AND MAILING ADDRESS" (Nome e endereço de correspondência do solicitante) e "POLICY #" (Número da apólice). Citar os rótulos como eles aparecem no documento ajuda o modelo básico a se conectar aos valores corretos.

Procedimento

1. Nos metadados na parte superior do esquema, forneça uma descrição do documento no campo document_description . O document_description campo está incluído no prompt do classificador para o modelo básico usado para classificação e extração de pares chave-valor.

   Dica:Torne a descrição do documento específica, incluindo palavras-chave para ajudar o modelo de classificação a identificar corretamente o documento. Por exemplo, use palavras-chave como "California", "Auto" e "Application" na descrição do documento California Personal Auto Insurance Application.

   Use o parâmetro additional_prompt_instructions para fornecer orientação que o modelo de base pode aplicar à página inteira do documento. Use as instruções do prompt do modelo básico, como "Preserve a formatação do número como visto na imagem", para melhorar a precisão da extração.

   {
      "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.",
   }
   

2. Para cada campo que você incluir no esquema, defina os três elementos a seguir:

   • Nome do campo : Escolha um nome de chave exclusivo para o campo. Use as dicas a seguir para criar um nome de campo:
     • Use sublinhados para separar palavras. Por exemplo, use applicant_name em vez de applicantName.
     • Mantenha os nomes curtos, mas descritivos.
     • Para campos em seções, use o formato [section_name]_[field_name].
     • Para campos de tabela, use o formato [table_name]_row_[row_number]_[column_name].
   • Valor de exemplo : Forneça um valor de exemplo para ajudar o modelo a inferir o tipo esperado, como um valor de data ou um número inteiro. O fornecimento de um exemplo melhora o desempenho do modelo.
   • Descrição : Escreva uma breve explicação do que o campo representa. A descrição é passada para o modelo de fundação para ajudar o modelo a entender o que procurar durante o processo de extração. A descrição do campo fornece um contexto que ajuda o modelo a validar e a se concentrar nas informações corretas do documento. Use as dicas a seguir para escrever uma descrição:
     • Seja preciso, não ambíguo e específico quanto à localização das informações no documento.
     • Não inclua instruções que alterem o formato dos valores, como datas ou números.
     • Mencione quaisquer rótulos ou títulos que identifiquem o campo.
     • Observe quaisquer casos especiais ou variações.

   Por exemplo, defina um campo para extrair o nome da agência do documento California Personal Auto Insurance Application.

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

   Opcionalmente, você pode usar os seguintes métodos para definir valores personalizados para campos e campos personalizados para capturar estruturas de dados especializadas no documento de entrada:

   Elementos de campo opcionais

   Especifique valores de atributos adicionais para um campo com o parâmetro available_options . Use o parâmetro para um campo que não seja explicitamente mencionado no documento, mas que possa ser deduzido do contexto ou dos elementos visuais.

   Por exemplo, em faturas, os valores monetários podem aparecer em várias partes do documento com um cifrão, mas podem não mencionar explicitamente que o dólar americano é a moeda da fatura. Nesses casos, você pode fornecer uma lista fechada de valores monetários válidos que o modelo pode retornar e reduzir as alucinações na resposta do modelo.

   "currency": {
     "default": "",
     "example": "USD",
     "description": "The currency used in the invoice.",
     "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"]
   }
   

   Definições da tabela

   Defina o parâmetro type como array para definir um campo em seu esquema que represente dados de tabelas no documento de entrada.

   O exemplo JSON a seguir define uma tabela em seu esquema que contém informações sobre endereços de garagens. A tabela tem colunas que contêm dados de localização, rua, cidade, condado, estado e código postal.

   "additional_garaging_addresses": {
         "type": "array",
         "description": "Additional locations where vehicles are regularly kept.",
         "columns": {
           "location": {
              "default": "",
              "example": "LOC1",
              "description": "Location identifier."
           },
           "street": {
              "default": "",
              "example": "456 Garage St",
              "description": "Street address of garaging location."
           },
           "city": {
              "default": "",
              "example": "Los Angeles",
              "description": "City of garaging location."
           },
           "county": {
              "default": "",
              "example": "Los Angeles",
              "description": "County of garaging location."
           },
           "state": {
              "default": "",
              "example": "CA",
              "description": "State abbreviation."
           },
           "zip_plus_4": {
              "default": "",
              "example": "90001-1234",
              "description": "ZIP code with +4 extension."
           }
         }
   }
   

3. Valide seu esquema JSON localmente antes de usá-lo em sua solicitação de extração de texto para garantir que ele esteja bem formado e corresponda à estrutura esperada. Você pode usar as seguintes ferramentas:

   • jsonlint.com para verificar a formatação
   • Um script Python para carregar e inspecionar o esquema
   • O interpretador JSON incorporado do seu IDE

Exemplo de solicitação REST API com esquema personalizado

O comando a seguir envia uma solicitação para extrair texto usando um esquema personalizado completo que inclui todos os metadados necessários na parte superior, seguidos por um conjunto de campos com as respectivas definições. Cada campo contém um valor padrão que está vazio, um exemplo e uma descrição para orientar o modelo de fundação durante o processo de extração.

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

O corpo da solicitação é o seguinte:

{
    "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",
      "kvp_mode": "generic_with_semantic",
      "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."
              }
              "additional_garaging_addresses": {
                "type": "array",
                "description": "Additional locations where vehicles are regularly kept.",
                "columns": {
                  "location": {
                     "default": "",
                     "example": "LOC1",
                     "description": "Location identifier."
                  },
                  "street": {
                     "default": "",
                     "example": "456 Garage St",
                     "description": "Street address of garaging location."
                  },
                  "city": {
                     "default": "",
                     "example": "Los Angeles",
                     "description": "City of garaging location."
                  },
                  "county": {
                     "default": "",
                     "example": "Los Angeles",
                     "description": "County of garaging location."
                  },
                  "state": {
                     "default": "",
                     "example": "CA",
                     "description": "State abbreviation."
                  },
                  "zip_plus_4": {
                     "default": "",
                     "example": "90001-1234",
                     "description": "ZIP code with +4 extension."
                  }
                }
              }
           }
        } ]
      }
    }
  }

Resolução de problemas

A tabela a seguir descreve alguns problemas comuns quando você usa um esquema personalizado e como resolvê-los:

Saiba mais

• watsonx.ai Documentação de referência da API