创建用于键值对分类和提取的自定义模式

创建 JSON 模式，通过文本分类和提取 API 从结构化文档中提取特定字段。

要为文档构建自定义模式，必须先定义元数据，并为每个需要提取的字段编写有效的描述，然后才能验证和扩展该模式，以实现精确的键值对分类和提取。

您可以在 semantic_config 参数中的 schemas 设置中定义文档的自定义模式。

开始之前

查看您的文档并确定以下信息，这些信息将决定您在模式中定义的字段名称和描述：

要从文档中提取的数据类型
您要提取的数据的准确标签
每个项目在页面上的位置，如左上角标题或右侧栏

例如，请注意加州个人汽车保险申请文件中的以下信息：

包含多个字段（包括联系人姓名和电话）的 PDF 自动申请表截图

要提取的数据，如机构名称、申请人地址、承运人名称、保单号码。
准确的字段标签，如 "代理机构"、"申请人姓名和邮寄地址 "以及 "保单号"。引用文件中出现的标签有助于基础模型连接到正确的值。

过程

在模式顶部的元数据中，在 document_description 字段中对文档进行描述。该字 document_description 段被包含在基础模型用于键值对分类和提取的分类器提示中。

提示：通过包含关键字使文档描述具体化，以帮助分类模型正确识别文档。例如，在加州个人汽车保险申请文档的描述中使用 "加州"、"汽车 "和 "申请 "等关键词。

使用 additional_prompt_instructions 参数提供基础模型可应用于文档整个页面的指导。使用基础模型提示说明，如 "保留图像中的数字格式"、以提高提取精度。
```
{
   "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.",
}
```
对于模式中包含的每个字段，请定义以下三个元素：
- 字段名称 ：为字段选择一个唯一的键名。使用以下提示创建字段名称：
  - 使用下划线分隔单词。例如，用 applicant_name 代替 applicantName。
  - 名称要简短，但要有描述性。
  - 对于章节中的字段，使用格式 [section_name]_[field_name]。
  - 对于表格字段，请使用 fomat [table_name]_row_[row_number]_[column_name]。
- 示例值 ：提供示例值，帮助模型推断预期类型，如日期值或整数。提供范例可提高模型性能。
- 说明：简要说明字段的含义。该描述将传递给基础模型，以帮助模型理解在提取过程中需要查找的内容。字段描述提供的上下文有助于模型验证和关注文档中的正确信息。使用以下提示撰写说明：
  - 准确、清晰、具体地说明信息在文件中的位置。
  - 请勿包含改变数值格式（如日期或数字）的说明。
  - 提及任何标识该领域的标签或标题。
  - 注意任何特殊情况或变化。
例如，定义一个字段，从加利福尼亚州个人汽车保险申请文档中提取机构名称。
```
"agency_name": {
  "default": "",
  "example": "Spring Insurance",
  "description": "Name of the insurance agency shown in the Agency section (upper‑left of the page)."
}
```
您可以选择使用以下方法为输入文档中的字段和自定义字段定义自定义值，以捕获专门的数据结构：
可选字段要素
使用 available_options 参数为字段指定附加属性值。该参数用于文档中未明确提及，但可从上下文或视觉元素中推断出的字段。

例如，在发票中，货币价值可能会在文件的不同部分出现美元符号，但可能不会明确提及美元是发票的货币。在这种情况下，您可以提供一个封闭列表，列出模型可以返回的有效货币值，从而减少模型响应中的幻觉。
```
"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"]
}
```
表定义
将 type 参数设置为 array ，以便在模式中定义一个字段，代表输入文档中表格的数据。

下面的 JSON 示例在模式中定义了一个包含车库地址信息的表。表格中的列包含位置、街道、城市、县、州和邮政编码数据。
```
"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."
        }
      }
}
```
在文本提取请求中使用 JSON 模式之前，先在本地验证该模式，以确保其格式良好并符合预期结构。您可以使用以下工具：
- jsonlint.com 检查格式
- Python 脚本，用于加载和检查模式
- 你的集成开发环境内置的 JSON 插件

自定义模式的REST API请求示例

下面的命令通过使用完整的自定义模式提交提取文本的请求，该模式顶部包含所有必需的元数据，后面是一组带有相应定义的字段。每个字段都包含一个默认空值、一个示例和一个说明，以便在提取过程中为基础模型提供指导。

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

请求正文如下

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

故障诊断

下表介绍了使用自定义模式时的一些常见问题以及解决方法：

症状	原因	解决方案
没有返回值	描述过于模糊。	使描述更加具体。提及视觉位置或附近的标签。包括一项不更改格式就按原样返回文本的指令
提取的数值有误	名称 "等模糊字段名	使用限定名称，如 `agency_name` 或 `applicant_name`。

了解更多

watsonx.ai 应用程序接口参考文档