Creación de esquemas personalizados para la extracción de pares clave-valor

Antes de empezar

Revise su documento y determine la siguiente información que guiará los nombres y descripciones de los campos que defina en el esquema:

• Los tipos de datos que desea extraer del documento
• Las etiquetas exactas de los datos que desea extraer
• La ubicación de cada elemento en la página, como la cabecera superior izquierda o la columna derecha

Por ejemplo, observe la siguiente información en el documento de solicitud de seguro de automóvil personal de California :

• Datos que desea extraer, como el nombre de la agencia, la dirección del solicitante, el nombre del transportista o el número de póliza.
• Las etiquetas exactas de los campos como "AGENCIA", "NOMBRE Y DIRECCIÓN POSTAL DEL SOLICITANTE" y "NÚMERO DE PÓLIZA". Citar las etiquetas tal y como aparecen en el documento ayuda a que el modelo base se conecte con los valores correctos.

Procedimiento

1. En los metadatos de la parte superior de su esquema, proporcione una descripción de su documento en el campo document_description . El campo document_description se incluye en la consulta del clasificador para el modelo de base utilizado para la extracción de pares clave-valor.

{
   "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. Determine qué campos incluir en el esquema. Para cada campo, defina los tres elementos siguientes:

   • Nombre del campo: elija un nombre de clave único para el campo.
   • Valor de ejemplo : Proporcione un valor de ejemplo para ayudar al modelo a inferir el tipo esperado, como un valor de fecha o un número entero. Proporcionar un ejemplo mejora el rendimiento del modelo.
   • Descripción : Escriba una breve explicación de lo que representa el campo. La descripción se transmite al modelo de cimentación para ayudarle a comprender qué debe buscar durante el proceso de extracción.
     Importante: La descripción del campo proporciona un contexto que ayuda al modelo a validar y centrarse en la información correcta del documento. La descripción debe ser precisa e inequívoca.

   Por ejemplo, defina un campo para extraer el nombre de la agencia del documento Solicitud de seguro de automóvil personal de California.

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

2. Especifique valores de atributo adicionales en su esquema con el parámetro available_options . Utilice el parámetro para un campo que no se mencione explícitamente en el documento, pero que pueda deducirse del contexto o de los elementos visuales. Por ejemplo, en las facturas, los valores monetarios pueden aparecer en varias partes del documento con un signo de dólar, pero no mencionar explícitamente que el dólar estadounidense es la moneda de la factura. En estos casos, puede proporcionar una lista cerrada de valores de moneda válidos que el modelo puede devolver y reducir las alucinaciones en la respuesta del modelo.

   "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. Opcional : Valide su esquema JSON localmente antes de utilizar el esquema en su solicitud de extracción de texto para asegurarse de que está bien formado y coincide con la estructura esperada. Puedes utilizar herramientas como:

   • jsonlint.com para comprobar el formato
   • Un script Python para cargar e inspeccionar el esquema
   • Linter JSON integrado en su IDE

Esquema personalizado y ejemplo de solicitud de API

El siguiente comando envía una solicitud para extraer texto utilizando un esquema personalizado completo que incluye todos los metadatos necesarios en la parte superior, seguidos de un conjunto de campos con sus correspondientes definiciones. Cada campo contiene un valor por defecto que está vacío, un ejemplo y una descripción para guiar al modelo durante el proceso de extracción.

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...'

El cuerpo de la solicitud es el siguiente

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

Mejores prácticas

Utilice las siguientes prácticas recomendadas para escribir esquemas eficaces:

Convenciones de denominación de campos

Utilice guiones bajos para separar las palabras. Por ejemplo, utilice applicant_name en lugar de applicantName. Los nombres deben ser cortos pero descriptivos. Para los campos de las secciones, utilice el formato [section_name]_[field_name] Para los campos de las tablas, utilice el fomato [table_name]_row_[row_number]_[column_name]

Redactar descripciones eficaces

Especifique en qué parte del documento se encuentra la información. No incluya instrucciones que cambien el formato de los valores, como fechas o números. Mencione cualquier etiqueta o encabezamiento que identifique el campo. Anote cualquier caso especial o variación.

Instrucciones adicionales Utilice las instrucciones del modelo de base para mejorar la precisión de la extracción para tipos de documentos específicos, como "Conservar el formato de los números como se ve en la imagen".

Resolución de problemas

En la siguiente tabla se describen algunos problemas habituales cuando se utiliza un esquema personalizado y cómo resolverlos:

Más información

• watsonx.ai Documentación de referencia de la API

Tema principal: Parámetros de extracción de texto