Custom KV templates

Introduction

A custom KV template is a feature for documents with fixed layouts, such as cards, certificates, and receipts. It lets you create a template by visually configuring a single sample document using a drag-and-drop interface. This process eliminates the need for data labeling and model training, allowing you to perform custom structured recognition and extraction for documents with the same layout. A well-configured template can achieve over 85% recognition accuracy. Additionally, the toolbox provides classifier management and field type management tools. These tools allow you to use a single API to automatically classify, route, and accurately process documents with different layouts.

Benefits

• Low cost: Create a template from a single sample image without data labeling.

• Low barrier to entry: Define templates in a visual, drag-and-drop interface, with no secondary development required.

• High efficiency: Configure a template in just 3 to 5 minutes.

Use cases

• Small-sample cold start: Ideal for quickly launching and validating a service with a small number of sample documents (fewer than 20).

• Fixed document layouts: Suitable for processing document types that have clearly identifiable fields and fixed key-value positions. This feature is widely used for structured recognition in scenarios like qualification reviews, financial reimbursements, and business data processing, which involve documents such as student IDs, marriage certificates, and bank transfer slips.

Procedure

The following video demonstrates how to create a custom KV template.

Create a custom KV template in four steps:

Step 1: Upload a template image

1. Go to the OCR Document Self-learning Platform, find custom KV template, and click Enable Now.

2. After the service is enabled, you are redirected to the OCR Document Self-learning Platform. Find custom KV template and click Create Task. On the Create Application page, configure the parameters, and then click OK.

   

3. On the My Applications page, find the application you created and click Enter Application. Click Start Creating Template. On the Upload Template Image page, click View Local Files to upload a clear and properly oriented template image. Configure the parameters based on your data, and then click Next.

   

   Tips

   1. How do I select a template image?

      1. For best results, use a scanned image that is clear, upright, free of reflections, and contains all required fields.

      2. For documents, you can upload a single-page PDF file up to 20 MB.

      3. For images, you can upload a JPG, JPEG, or PNG file up to 10 MB.

   2. How do I configure template parameters?

      1. Template parameters define your sample data's characteristics to help optimize data pre-processing and AI model matching.

      2. You can configure settings for language, character type, image processing, and red seal removal.

      3. Parameter settings are not applied in real time. They take effect during the template testing phase.

   3. What kind of data yields the best recognition results?

      1. For a single image, the longest side must not exceed 8,192 pixels, and the shortest side must be at least 15 pixels. If the longest side exceeds 1,024 pixels, the aspect ratio must not exceed 50:1.

      2. For best results, we recommend that individual characters be 10 to 50 pixels in size.

      3. Significant differences in angle and orientation between the template image and your actual business documents can affect recognition performance.

Step 2: Select anchor fields

1. From the toolbar on the left, select the Select tool. Use it to draw boxes around text areas with fixed content and position on the template image. These areas serve as anchor fields.

2. In the anchor field panel on the right, configure the parameters, and then click Next. The parameter is described as follows:

   Anchor field: An anchor field is a text area with fixed content and position. It is used to automatically correct and align incoming images with the template. It also affects the performance of the combined classifier if one is used.

   Tips

   1. How do I select anchor fields?

      1. Select at least four anchor fields and distribute them across the corners of the document if possible.

      2. Ensure the text content and position of the selected areas are fixed.

      3. A single field cannot span multiple lines.

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

      5. The text must contain only Chinese characters, English letters, or numbers, not symbols or patterns.

   2. What if I cannot find at least four anchor fields?

      1. You can skip this step. The underlying algorithm analyzes the document to identify anchors automatically. However, if you use a combined classifier for templates with very similar layouts, you must configure the fields carefully.

Step 3: Configure recognition fields

1. On the Configure recognition fields page, select the Select tool from the toolbar. Use it to draw boxes around the areas of the template image that you want to recognize.

2. In the panel on the right, enter a field name, verify the value, and choose the appropriate field type and advanced settings to improve recognition accuracy. Then, click Next. The parameters are described as follows:

   • Recognition field: A recognition field is an area in the image to be recognized. It represents the information that you want to extract for your business and is used to generate structured results. Each recognition field requires a name, value, and type. Advanced settings are optional.

   • Field name: The external name of the recognition field, which corresponds to the key in the API response. The field name must be globally unique.

   • Value: The content of the recognition field, which is automatically recognized and populated after you select the area. To perform post-processing on a specific field (such as normalizing dates, extracting only digits from amounts, or replacing symbols with a regular expression), you can use the field type and advanced settings. These settings are applied during the API call.

   Tips

   1. How do I select recognition fields?

      1. Individually select the text area for each field you want to extract.

      2. The selection box for a recognition field should cover the maximum possible area where the field's text might appear. This helps prevent incomplete recognition.

   2. How do I improve the accuracy of recognition fields?

      1. Choose an appropriate field type to improve recognition performance. You can select a generic field type or add your own custom field type. If no post-processing is needed, you can use the regular field type.

      2. You can use advanced settings to configure content replacement or set multi-line connectors.

      3. In advanced settings, the regular expression feature allows you to define a search pattern and a replacement string. See the following examples:

      Description	Input	Pattern	Replacement	Result
      Replace a string	abcdef	abc	hello	hellodef
      Remove extra spaces	ab de f	\s+		abdef
      Add a decimal point before the last two digits	12345	(\d+)(\d{2})$	\1.\2	123.45
      Remove content before the colon	Mobile:12345678	.+:(\d+)	\1	12345678
      Convert date format	2023-2-3	^(\d+)-(\d+)-(\d+)$	\1/\2/\3	2023/2/3

Step 4: Test and publish the template

After selecting all anchor and recognition fields, you can test and publish the template. Click View Local Files to upload an image with the same layout to test the template's performance. If you are satisfied with the results, click Publish template and start API calling. You can use the Re-upload button to test more documents and go back to previous steps to fine-tune the configuration.

Optimize and manage templates

Template management

After you publish a template, you can go to the project details page to view the project overview, which includes basic information, template configuration, and usage data. You can call published templates through APIs or use them online.

Related links

• OCR Document Self-learning: console

• Custom KV template developer guide: Online debugging, API reference, SDK documentation