Custom KV Template

Feature Overview

The custom KV template is a tailored solution for structured data extraction from fixed-layout documents such as ID cards and invoices. With just one sample image, you can configure a template visually using a drag-and-drop interface to extract structured key-value pairs from documents that have the same layout. This process does not require data annotation or model training. Properly tuned templates achieve over 85% recognition accuracy. The Toolbox also includes a classifier management tool and a field type management tool. These tools enable automatic classification routing and high-accuracy recognition of multiple layouts through a single API call.

Benefits

• Low cost: You can build a template with just one sample image. No annotation is needed.

• Low barrier to entry: You can define templates visually using a drag-and-drop interface. No custom development is required.

• High efficiency: You can configure a template in 3 to 5 minutes.

Scenarios

• Few-shot cold start: This feature is ideal when you have few data samples (fewer than 20 images) and need to validate your solution quickly.

• Fixed document layout: This feature is suitable for applications that process many document types, where each type has clearly identifiable fields with fixed key-value positions. Common scenarios include structured data extraction for student ID verification, marriage certificate processing, bank transfer slips, qualification verification, expense reimbursement, and business data handling.

User Guide

The following demo shows how to use a custom KV template:

The diagram below shows the four-step process to create a custom KV template.

Step 1: Upload a template image

1. Go to the OCR Document Self-Learning Platform, locate Custom KV Template, and click Activate Now.

2. After the service is activated, you are redirected to the OCR Document Self-Learning Platform. Find Custom KV Template and click Create Task. On the Create Application page, set the required parameters and click Confirm.

   

3. On the My Applications page, find your new application, click Enter Application, and then click Start Creating Template. On the Upload Template Image page, click Select Local File, upload a clear, non-rotated template image, configure the parameters based on your data characteristics, and click Next.

   

   Tips

   1. How do I choose a template image?

      1. For best results, use a scanned image that is clear, properly aligned, glare-free, and contains all fields.

      2. Documents: Single-page PDF files up to 20 MB.

      3. Images: JPG, JPEG, or PNG files up to 10 MB.

   2. How do I configure template parameters?

      1. Template parameters define the characteristics of a sample to enable preprocessing and AI model matching, which improves the processing results.

      2. Supported settings include language, text type, image editing, and red seal handling.

      3. Parameter changes do not take effect immediately in the editor but are applied during template testing.

   3. What type of data yields better recognition results?

      1. Image dimensions: The longest side must be less than or equal to 8,192 pixels, and the shortest side must be greater than or equal to 15 pixels. If the long side exceeds 1,024 pixels, the aspect ratio must not exceed 50:1.

      2. For optimal recognition, keep individual characters between 10 and 50 pixels in height.

      3. Large differences in the shooting angle or orientation between the template and real-world documents may reduce accuracy.

Step 2: Select reference fields

1. On the left toolbar, click the Select button and draw boxes around text regions in the template image where the content and position remain fixed. These regions become your reference fields.

2. In the reference field panel on the right, configure the parameters as needed and click Next. The parameters are described as follows:

   Reference fields: These are fixed text regions used to automatically align and anchor incoming documents that have the same layout. They also affect classifier performance if a classifier is used.

   Tips

   1. How do I select reference fields?

      1. Select at least four reference fields, ideally spread across all four corners.

      2. Ensure that the selected text content and position never change.

      3. A field must be on a single line.

      4. Select unique text that does not repeat elsewhere in the image.

      5. Only Chinese, English, and digits are supported. Symbols and graphics are not supported.

   2. What if I cannot find four suitable reference fields?

      1. You can skip this step. The underlying algorithm automatically analyzes the layout. However, if you are using a classifier, you must carefully configure templates that have very similar layouts.

Step 3: Configure recognition fields

1. On the recognition field configuration page, use the Select button in the left toolbar to draw a box around the areas that you want to extract.

2. In the right panel, enter a Field Name, verify the auto-filled Value, select a Field Type, and optionally adjust the Advanced Configuration settings to improve accuracy. Then, click Next. Parameter details:

   • Recognition fields: These are the regions to extract for structured output. Each field includes a required field name, value, and field type, in addition to optional advanced settings.

   • Field name: The public name of the field, used as the key in API responses. It must be globally unique within the template.

   • Value: The extracted content. The value is automatically filled after you select a region. For post-processing, such as date normalization, numeric-only amount extraction, or symbol replacement using regular expressions, you can use the field type and advanced configuration settings. These rules are applied when the API is called.

   Tips

   1. How do I select recognition fields?

      1. Draw a box around each target field individually.

      2. Make the boxes large enough to cover the maximum possible area where the text might appear. This prevents incomplete extraction.

   2. How do I improve recognition accuracy?

      1. Select an appropriate field type. You can select a built-in type or a custom type that you define. Use the default type if no post-processing is required.

      2. Use advanced configuration for content replacement or multi-line joining.

      3. The advanced configuration settings support regular expressions to define find-and-replace rules. For example:

      Note	Input	Original content	Replacement	Result
      Replace string	abcdef	abc	hello	hellodef
      Remove extra spaces	ab de f	\s+	-	ab de f
      Add a decimal point two places from the right.	12345	(\d+)(\d{2})$	\1.\2	123.45
      Remove content before colon	Mobile:12345678	.+:(\d+)	\1	12345678
      Convert date format	2023-2-3	^(\d+)-(\d+)-(\d+)$	\1-\2-\3	February 3, 2023

Step 4: Test and publish the template

After selecting all reference and recognition fields, test your template by clicking Select Local File and uploading an image with the same layout. If the results are satisfactory, click Publish Template and Start API Calls. Click the Re-upload button to test multiple samples, or go back to refine your settings.

Template Tuning and Management

Template management

After you publish a template, you can go to the project overview page to view template details and usage metrics. Published templates support both API calls and online use.

Related links

• OCR Document Self-Learning: Console

• Custom KV Template Developer Guide: Online Debugging, API Reference, SDK Documentation