Training a Semi-structured Model

• Updated on May 16, 2025

• Published on Oct 10, 2024

• 14 minute(s) read

Hyperscience extracts data from documents and converts them into a machine-readable format. We support Structured, Semi-structured, and Additional documents. To learn how to differentiate between the document types, see Understand Document Types.

Use Semi-structured layouts for documents where field positions might vary. They’re suitable for documents like invoices, pay stubs, and checks.

In this article, you’ll learn how to build a robust Semi-structured model corresponding to your business needs by using our Training Data Management tools.

Step 1 - Sampling Documents

Review your documents

Having a diverse, representative training set is crucial for a high-quality identification model. Selecting the appropriate documents for training will optimize your Semi-structured model’s performance.

• Determine the common types of documents you'll be processing, and ensure you have at least 20 of each of them.

• Become familiar with the edge cases (i.e., documents that are completely different from the main ones) and determine their variety. Exclude them if they are not suitable for your use case.

• Remove documents that would reduce model performance (e.g., documents containing unrelated information, highly distorted pages, duplicates).

• Choose at least 50-100 documents for testing purposes. Note that these documents should be representative of the data you expect in production.

Review your fields and columns

• Your fields and columns should be representative of the information you want to extract.
• Ensure they are present in your documents to achieve a high-performance model.
• Make sure to review any interchangeable fields or columns, as this might result in poor model performance.

Step 2 - Build your layout and add it to a release

Build your layout

Once you’ve determined the information you want to extract, you need to build your Semi-structured layout. To learn more about Semi-Structured Layouts, see Determining Layout Type.

1. Create your layout by following the steps in Creating Semi-Structured Layouts.

• Use unique names for your fields or columns to avoid model training failure and simplify the annotation process.

• Make sure to set the proper type for each field or column you create.

• Ensure your configurations are suitable for the fields and columns for extraction:

  • Check Multiple Occurrences if your fields have more than one occurrence.
  • Enable the Multiline setting if required.
  • Set Identification Supervision to Always for each field you want to guarantee a manual review for.
  • Set Transcription Supervision to Always if there are issues in the document that could prevent the machine from reading the field or the column.

Assign to a release

1. Add your layout to a release by following the steps described in Adding a New Release.

2. Follow the steps in Assigning a Release to a Flow to match your release to the flow you are using.

Step 3 - Training Data Management

Using Training Data Management

Ground truth is manually annotated data used to train our machine-learning models.

Use the tools in TDM to control, manage, and adjust the ground truth of your training sets for Identification and Classification models. In this section, you will learn how to upload your data using TDM:

• See the training requirements in Requirements for Training a New Model.
• Make sure to keep 50-100 documents for testing purposes.

Upload your documents

1. Go to the Model Management page for your layout ( Library > Models).
2. Click Upload Training Documents and upload each document as its own file.
3. Click Upload in the dialog box.

All uploaded documents will appear on the Training Documents card. Switch between the Field Identification and Table Identification tabs, depending on the type of model you want to train.

Step 4 - Analyze your data

Training Data Analysis allows you to group your training documents and receive recommendations to improve the quality of your dataset.

Analyze your data

Receive insights for improving your training data by clicking the Analyze Data button, located in the Training Data Health card.

Analysis results

The results show you the eligibility and importance of each document:

• Groups - Training data analysis groups your training set by visual similarity.
• Importance - The Training Data Curator labels each training document as having high or low importance.
• Eligibility - With Document Eligibility Filtering, you can see which documents are incompatible with training and why.
• Detect anomalies - Re-analyze your data and find inconsistencies across your annotations.

Step 5 - Annotate your documents

Consistent annotations are crucial for a high-performance locator model.

Best practices

Learn how to annotate your documents by following the best practices listed below:

General guidelines

1. Once you analyze the data, you’ll be able to annotate by group.
2. After annotating 2-3 documents per group, you’ll be able to use guided data labeling.
3. Follow the general rule for annotating: left to right, top to bottom.
4. Make sure to maintain consistent annotations for your fields or columns.
5. Always use the machine predictions when drawing the bounding box.
6. Adjust the machine predictions ONLY if the bounding boxes are overlapping.
7. Do NOT interchange fields or columns.
8. If a field or a cell is not present, do not replace it with a similar value.
9. If you don’t see a box made of dashed lines around a value, do NOT annotate it.

Field Identification

1. Annotate fields with Multiple Occurrences only when multiple instances of a field are present.
2. Use multiple bounding boxes when a text is logically connected.
3. If you don’t see a value for a field, do NOT annotate it.

Table Identification

1. When annotating a table, make sure to select a row where all data is present.
2. Always find the first and the last rows of your table and make sure they are properly annotated.
3. Draw one large bounding box capturing all rows of your table, and use the Split tool to define or correct the rows of your table.

Next steps

• Check if all training documents are eligible for training.
• Ensure you have the required number of training documents.

Step 6 - Review your flow’s settings and train your model

Review the flow’s configurations:

For more precise control over the process, you can configure your flow’s settings.

• Set your Target Accuracy to achieve better performance.

Run Training

Initiate a model training by clicking the Run Training button.

Step 7 - Evaluate the training results

Deploy your model

Once the model training is complete, you’ll find the candidate model on the model details page. To deploy it, click on your candidate model, then click Deploy Model. The model is now live and ready for document processing.

Evaluate the performance

Use the documents you’ve chosen for testing purposes to evaluate the performance of your model.

Upload your testing documents

1. Go to Submissions.
2. Click Create Submission.
3. Upload the testing documents.
4. Click Next.
5. Choose the flow you’re using for the model.
6. Choose the layout used for the model.
7. Click Upload.

Results

Observe the results based on your flow settings on the Document Output page.

If the model is performing poorly, we suggest going over the training documents to check for potential annotation errors and inconsistencies and fixing them.