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

Prima di iniziare

Rivedere il documento e determinare le seguenti informazioni che guideranno i nomi e le descrizioni dei campi definiti 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:

• 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

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

{
   "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. Determinare quali campi includere nello schema. Per ogni campo, definire i tre elementi seguenti:

   • Nome del campo : scegliere un nome chiave univoco per il campo.
   • 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.
     Importante: la descrizione del campo fornisce un contesto che aiuta il modello a convalidare e a concentrarsi sulle informazioni corrette del documento. La descrizione deve essere accurata e non ambigua.

   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)."
   }
   

2. Specificare i valori aggiuntivi degli attributi nello schema 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",
     "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. Opzionale : Convalidare lo schema JSON localmente prima di usarlo nella richiesta di estrazione del testo, per verificare che sia ben formato e che corrisponda alla struttura prevista. È possibile utilizzare strumenti come:

   • jsonlint.com per controllare la formattazione
   • Uno script Python per caricare e ispezionare lo schema
   • Il liner JSON integrato nell'IDE

Esempio di schema personalizzato e richiesta API

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 durante il processo di estrazione.

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

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

Best practice

Utilizzate le seguenti best practice per scrivere schemi efficaci:

Convenzioni di denominazione dei campi

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 formato [table_name]_row_[row_number]_[column_name]

Scrivere descrizioni efficaci

Indicate con precisione in quale punto del documento 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.

Istruzioni di prompt aggiuntive Utilizzare le istruzioni di prompt del modello di fondazione per migliorare l'accuratezza dell'estrazione per tipi di documenti specifici, ad esempio "Conserva la formattazione dei numeri come si vede nell'immagine".

Risoluzione dei problemi

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

Ulteriori informazioni

• watsonx.ai Documentazione di riferimento dell'API

Argomento principale: Parametri di estrazione del testo