Creazione di schemi personalizzati per la classificazione e l'estrazione di coppie chiave-valore

Crea schemi JSON per estrarre campi specifici da documenti strutturati con l'API di classificazione ed estrazione del testo.

Per creare uno schema personalizzato per un documento, è necessario definire i metadati e scrivere descrizioni efficaci per ogni campo che si desidera estrarre prima di convalidare e ridimensionare lo schema per una classificazione e un'estrazione accurate delle coppie chiave-valore.

Lo schema personalizzato per il documento viene definito nell'impostazione schemas nel parametro semantic_config .

Prima di iniziare

Rivedere il documento e determinare le seguenti informazioni che determineranno i nomi dei campi e le descrizioni definite nello schema:

I tipi di dati che si desidera estrarre dal documento
Le etichette esatte dei dati che si desidera estrarre
La posizione di ciascun elemento nella pagina, ad esempio l'intestazione in alto a sinistra o la colonna di destra

Ad esempio, nel documento di richiesta di assicurazione auto personale della California sono riportate le seguenti informazioni:

Schermata di un modulo di autocandidatura in PDF con diversi campi, tra cui il nome e il telefono del contatto

I dati che si desidera estrarre sono il nome dell'agenzia, l'indirizzo del richiedente, il nome del vettore e il numero di polizza.
Le etichette esatte dei campi, come "AGENZIA", "NOME E INDIRIZZO DEL RICHIEDENTE" e "N. POLIZZA". La citazione delle etichette così come appaiono nel documento aiuta il modello di fondazione a collegarsi ai valori corretti.

Procedura

Nei metadati all'inizio dello schema, fornire una descrizione del documento nel campo document_description . Il document_description campo è incluso nel prompt del classificatore per il modello di base utilizzato per la classificazione e l'estrazione delle coppie chiave-valore.

Suggerimento:Rendere specifica la descrizione del documento includendo parole chiave che aiutino il modello di classificazione a identificare correttamente il documento. Ad esempio, utilizzate parole chiave come "California", "Auto" e "Applicazione" nella descrizione del documento California Personal Auto Insurance Application.

Utilizzare il parametro additional_prompt_instructions per fornire indicazioni che il modello di fondazione può applicare all'intera pagina del documento. Utilizzare le istruzioni di richiesta del modello di fondazione, ad esempio "Conservare la formattazione dei numeri come si vede nell'immagine", per migliorare l'accuratezza dell'estrazione.
```
{
   "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.",
}
```
Per ogni campo incluso nello schema, definire i tre elementi seguenti:
- Nome del campo : scegliere un nome chiave univoco per il campo. Utilizzare i seguenti suggerimenti per la creazione di un nome di campo:
  - Utilizzare i trattini bassi per separare le parole. Ad esempio, utilizzare applicant_name invece di applicantName.
  - Mantenete i nomi brevi ma descrittivi.
  - Per i campi delle sezioni, utilizzare il formato [section_name]_[field_name].
  - Per i campi delle tabelle, utilizzare il fomat [table_name]_row_[row_number]_[column_name].
- Valore di esempio : Fornire un valore di esempio per aiutare il modello a dedurre il tipo previsto, ad esempio un valore di data o un numero intero. La fornitura di un esempio migliora le prestazioni del modello.
- Descrizione : Scrivere una breve spiegazione di ciò che rappresenta il campo. La descrizione viene passata al modello di fondazione per aiutarlo a capire cosa cercare durante il processo di estrazione. La descrizione del campo fornisce un contesto che aiuta il modello a convalidare e a concentrarsi sulle informazioni corrette del documento. Utilizzate i seguenti suggerimenti per scrivere una descrizione:
  - Siate precisi, inequivocabili e specifici riguardo al punto del documento in cui si trovano le informazioni.
  - Non includere istruzioni che modifichino il formato dei valori, come date o numeri.
  - Indicare eventuali etichette o titoli che identificano il campo.
  - Annotare eventuali casi speciali o variazioni.
Ad esempio, definire un campo per estrarre il nome dell'agenzia dal 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)."
}
```
È possibile utilizzare facoltativamente i seguenti metodi per definire valori personalizzati per i campi e campi personalizzati per l'acquisizione di strutture dati specializzate nel documento di input:
Elementi di campo opzionali
Specificare valori di attributi aggiuntivi per un campo con il parametro available_options . Utilizzare il parametro per un campo che non è esplicitamente menzionato nel documento, ma che può essere dedotto dal contesto o dagli elementi visivi.

Ad esempio, nelle fatture, i valori delle valute possono apparire in varie parti del documento con il segno del dollaro, ma possono non indicare esplicitamente che il dollaro USA è la valuta della fattura. In questi casi, è possibile fornire un elenco chiuso di valori validi di valuta che il modello può restituire e ridurre le allucinazioni nella risposta del modello.
```
"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"]
}
```
Definizioni delle tabelle
Impostare il parametro type su array per definire un campo nello schema che rappresenta i dati delle tabelle del documento di input.

Il seguente esempio JSON definisce una tabella nello schema che contiene informazioni sugli indirizzi di rimessaggio. La tabella ha colonne che contengono i dati relativi a località, via, città, contea, stato e codice postale.
```
"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."
        }
      }
}
```
Convalidare lo schema JSON localmente prima di usarlo nella richiesta di estrazione del testo, per assicurarsi che sia ben formato e che corrisponda alla struttura prevista. È possibile utilizzare i seguenti strumenti:
- jsonlint.com per controllare la formattazione
- Uno script Python per caricare e ispezionare lo schema
- Il liner JSON integrato nell'IDE

Esempio di richiesta REST API con schema personalizzato

Il comando seguente invia una richiesta di estrazione di testo utilizzando uno schema personalizzato completo che include tutti i metadati richiesti in cima, seguiti da una serie di campi con le relative definizioni. Ogni campo contiene un valore predefinito vuoto, un esempio e una descrizione per guidare il modello di fondazione durante il processo di estrazione.

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

Il corpo della richiesta è il seguente:

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

Risoluzione dei problemi

La tabella seguente descrive alcuni problemi comuni quando si utilizza uno schema personalizzato e come risolverli:

Sintomo	Causa	Soluzione
Nessun valore restituito	La descrizione è troppo vaga.	Rendere la descrizione più specifica. Indicare la posizione visiva o le etichette vicine. Includere un'istruzione per restituire il testo così com'è senza modifiche alla formattazione
Valore errato estratto	Nomi di campo ambigui come "Nome"	Utilizzare nomi qualificati come `agency_name` o `applicant_name`.

Ulteriori informazioni

watsonx.ai Documentazione di riferimento dell'API