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

Cree esquemas JSON para extraer campos específicos de documentos estructurados con la API de clasificación y extracción de texto.

Para crear un esquema personalizado para un documento, debe definir los metadatos y escribir descripciones eficaces para cada campo que desee extraer antes de validar y escalar el esquema para una clasificación y extracción precisas de los pares clave-valor.

Defina el esquema personalizado para su documento en la configuración schemas en el parámetro semantic_config .

Antes de empezar

Revise su documento y determine la siguiente información que determinará 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 :

Captura de pantalla de un formulario de solicitud automática en PDF con varios campos, incluidos el nombre y el teléfono de contacto

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

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

Sugerencia:Especifique la descripción del documento incluyendo palabras clave que ayuden al modelo de clasificación a identificar correctamente el documento. Por ejemplo, utilice palabras clave como "California", "Auto" y "Solicitud" en la descripción del documento Solicitud de seguro de auto personal de California.

Utilice el parámetro additional_prompt_instructions para proporcionar orientación que el modelo de base pueda aplicar a toda la página del documento. Utilice las instrucciones del modelo de fundación, como "Conservar el formato de los números como se ve en la imagen", para mejorar la precisión de la extracción.
```
{
   "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.",
}
```
Para cada campo que incluya en el esquema, defina los tres elementos siguientes:
- Nombre del campo: elija un nombre de clave único para el campo. Utilice los siguientes consejos para crear un nombre de campo:
  - 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 tabla, utilice el fomato [table_name]_row_[row_number]_[column_name].
- 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. La descripción del campo proporciona un contexto que ayuda al modelo a validar y centrarse en la información correcta del documento. Utilice los siguientes consejos para redactar una descripción:
  - Sea preciso, inequívoco y 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.
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)."
}
```
Puede utilizar opcionalmente los siguientes métodos para definir valores personalizados para campos y campos personalizados para capturar estructuras de datos especializadas en el documento de entrada:
Elementos de campo opcionales
Especifique valores de atributo adicionales para un campo 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",
  "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"]
}
```
Definiciones de tabla
Establezca el parámetro type en array para definir un campo en su esquema que represente los datos de las tablas del documento de entrada.

El siguiente ejemplo JSON define una tabla en su esquema que contiene información sobre direcciones de garaje. La tabla tiene columnas que contienen datos de ubicación, calle, ciudad, condado, estado y 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."
        }
      }
}
```
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 las siguientes herramientas:
- jsonlint.com para comprobar el formato
- Un script Python para cargar e inspeccionar el esquema
- Linter JSON integrado en su IDE

Ejemplo de solicitud REST API con esquema personalizado

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 de cimentación durante el proceso de extracción.

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

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

Resolución de problemas

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

Síntoma	Causa	Solución
No se devuelven valores	La descripción es demasiado vaga.	Haga la descripción más específica. Mencione la ubicación visual o las etiquetas cercanas. Incluir una instrucción para devolver el texto tal cual, sin cambios de formato
Valor erróneo extraído	Nombres de campo ambiguos como "Nombre	Utilice nombres cualificados como `agency_name` o `applicant_name`.

Más información

watsonx.ai Documentación de referencia de la API