Document Intelligence custom model lifecycle

Article
10/16/2024

This content applies to: v4.0 (preview) v3.1 (GA)

With the v3.1 (GA) and later APIs, custom models introduce a expirationDateTime property that is set for each model trained with the 3.1 API or later. Custom models are dependent on the API version of the Layout API version and the API version of the model build operation. For best results, continue to use the API version the model was trained with for all analyze requests. The guidance applies to all Document Intelligence custom models including extraction and classification models.

Models trained with GA API version

With the v3.1 API, custom models introduce a new model expiration property. The model expiration is set to two years from the date the model is built for all requests that use a GA API to build a model. To continue to use the model past the expiration date, you need to train the model with a current GA API version. The API version can be the one that the model was originally trained with or a later API version. The following figure illustrates the options when you need to retrain an expiring or expired model.

Screenshot showing how to choose an API version and retrain a model.

Models trained with preview API version

For build requests, using a preview API version, the expiration date is set to three months from the date the model is built. Models trained with a preview API shouldn't be used in production and should be retrained once the corresponding GA API version is available. Compatibility between preview API versions and GA API versions isn't always maintained. You should expect that models trained with a preview API version aren't useable once the preview API is retired.

Preview APIs are typically retired within three months of the corresponding GA API being available.

Viewing model expiration date

The GET model API returns the model details including the expirationDateTime property.

GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2021-09-24T12:54:35Z",
  "expirationDateTime": "2023-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}

Retrain a model

To retrain a model with a more recent API version, ensure that the layout results for the documents in your training dataset correspond to the API version of the build model request. For instance, if you plan to build the model with the v3.1:2023-07-31 API version, the corresponding *.ocr.json files in your training dataset should also be generated with the v3.1:2023-07-31 API version. The ocr.json files are generated by running layout on your training dataset. To validate the version of the layout results, check the apiVersion property in the analyzeResult of the ocr.json documents.

Next steps

Learn to create and compose custom models:

Build a custom model Compose custom models

Share via