diff --git a/sdk/formrecognizer/azure-ai-formrecognizer/MIGRATION_GUIDE.md b/sdk/formrecognizer/azure-ai-formrecognizer/MIGRATION_GUIDE.md index 5e6d43434949..700a4d7fae6d 100644 --- a/sdk/formrecognizer/azure-ai-formrecognizer/MIGRATION_GUIDE.md +++ b/sdk/formrecognizer/azure-ai-formrecognizer/MIGRATION_GUIDE.md @@ -21,9 +21,17 @@ A natural question to ask when considering whether to adopt a new version of the There are many benefits to using the new design of the `azure-ai-formrecognizer (3.2.x)` library. This new version of the library introduces two new clients `DocumentAnalysisClient` and the `DocumentModelAdministrationClient` with unified methods for analyzing documents and provides support for the new features added by the service in API version `2021-09-30-preview` and later. -New features provided by the `DocumentAnalysisClient` include one consolidated method for analyzing document layout, a general document model type, along with the same prebuilt models that were included previously (receipts, invoices, business cards, identity documents), and custom models. Moreover, the models introduced in the latest version of the library, such as `AnalyzeResult`, remove hierarchical dependencies between document elements and move them to a more top level and easily accessible position. The service has further improved how to define where elements are located on documents by moving towards `BoundingRegion` definitions allowing for cross-page elements. Document element fields are returned with more information, such as content and spans. - -When using the `DocumentModelAdministrationClient` to build, compose, or copy models, users can now assign their own model IDs and specify a description. Listing models on the administration client now includes both prebuilt and custom models. When using `get_model()`, users can get the field schema (field names and types that the model can extract) for the model they specified, including for prebuilt models. This client also provides functions for getting information from model operations. +New features provided by the `DocumentAnalysisClient` include: +- One consolidated method for analyzing document layout, a prebuilt general document model type, along with the same prebuilt models that were included previously (receipts, invoices, business cards, ID documents), and custom models. +- Models introduced in the latest version of the library, such as `AnalyzeResult`, remove hierarchical dependencies between document elements and move them to a more top level and easily accessible position. +- The Form Recognizer service has further improved how to define where elements are located on documents by moving towards `BoundingRegion` definitions allowing for cross-page elements. +- Document element fields are returned with more information, such as content and spans. + +New features provided by the `DocumentModelAdministrationClient` include: +- Users can now assign their own model IDs and specify a description when building, composing, or copying models. +- Listing models now includes both prebuilt and custom models. +- When using `get_model()`, users can get the field schema (field names and types that the model can extract) for the model they specified, including for prebuilt models. +- Ability to get information from model operations that occurred in the last 24 hours. The table below describes the relationship of each client and its supported API version(s): @@ -39,20 +47,20 @@ Please refer to the [README][readme] for more information on these new clients. ### Terminology -Some terminology has changed to reflect the enhanced capabilities of the newest Form Recognizer service APIs. While the service is still called "Form Recognizer", it is capable of much more than simple recognition and is not limited to documents that are "forms". As a result, we've made the following broad changes to the terminology used throughout the SDK: +Some terminology has changed to reflect the enhanced capabilities of the newest Form Recognizer service APIs. While the service is still called `Form Recognizer`, it is capable of much more than simple recognition and is not limited to documents that are `forms`. As a result, we've made the following broad changes to the terminology used throughout the SDK: -- The word "Document" has broadly replaced the word "Form." The service supports a wide variety of documents and data-extraction scenarios, not merely limited to "forms." -- The word "Analyze" has broadly replaced the word "Recognize." The document analysis operations execute a data extraction pipeline that supports more than just recognition. -- Distinctions between "custom" and "prebuilt" models have broadly been eliminated. Prebuilt models are simply models that were created by the Form Recognizer service team and that exist within every Form Recognizer resource. -- The concept of "model training" has broadly been replaced with "model creation", "building a model", or "model administration" (whatever is most appropriate in context), as not all model creation operations involve "training" a model from a data set. When referring to a model schema trained from a data set, we will use the term "document type" instead. +- The word `Document` has broadly replaced the word `Form.` The service supports a wide variety of documents and data-extraction scenarios, not merely limited to `forms.` +- The word `Analyze` has broadly replaced the word `Recognize.` The document analysis operation executes a data extraction pipeline that supports more than just recognition. +- Distinctions between `custom` and `prebuilt` models have broadly been eliminated. Prebuilt models are simply models that were created by the Form Recognizer service team and that exist within every Form Recognizer resource. +- The concept of `model training` has broadly been replaced with `model creation`, `building a model`, or `model administration` (whatever is most appropriate in context), as not all model creation operations involve `training` a model from a data set. When referring to a model schema trained from a data set, we will use the term `document type` instead. ### Client usage We continue to support API key and AAD authentication methods when creating the clients. Below are the differences between the two versions: - In `3.2.x`, we have added `DocumentAnalysisClient` and `DocumentModelAdministrationClient` which support API version `2021-09-30-preview` and later. -- `FormRecognizerClient` and `FormTrainingClient` will raise an error if called with an API version of `2021-09-30-preview` and later. -- In `DocumentAnalysisClient` all prebuilt model methods along with custom model, layout, and a general document analysis model are unified into two methods called +- `FormRecognizerClient` and `FormTrainingClient` will continue to work targeting API versions `2.1` and `2.0`. +- In `DocumentAnalysisClient` all prebuilt model methods along with custom model, layout, and a prebuilt general document analysis model are unified into two methods called `begin_analyze_document` and `begin_analyze_document_from_url`. - In `FormRecognizerClient` there are two methods (a stream and URL method) for each of the prebuilt models supported by the service. This results in two methods for business card, receipt, identity document, and invoice models, along with a pair of methods for recognizing custom documents and for recognizing content/layout. @@ -233,7 +241,7 @@ for idx, receipt in enumerate(receipts.documents): Analyzing document content with `3.1.x`: -> NOTE: With version `3.1.x` of the library this method was called with a `language` keyword argument to hint at the language for the document, whereas in version `3.2.x` of the library `locale` is used for this purpose. +> NOTE: With version `3.1.x` of the library this method had an optional `language` keyword argument to hint at the language for the document, whereas in version `3.2.x` of the library `locale` is used for this purpose. ```python with open(path_to_sample_forms, "rb") as f: @@ -589,7 +597,7 @@ print("-----------------------------------") Differences between the versions: - Files for building a new model for version `3.2.x` can be created using the labeling tool found [here][fr_labeling_tool]. - In version `3.1.x` the `use_training_labels` keyword argument was used to indicate whether to use labeled data when creating the custom model. -- In version `3.2.x` the `use_training_labels` keyword argument is not supported since training must be carried out with labeled training documents. Additionally train without labels is now replaced with the prebuilt model "prebuilt-document" which extracts entities, key-value pairs, and layout from a document. +- In version `3.2.x` the `use_training_labels` keyword argument is not supported since training must be carried out with labeled training documents. Additionally train without labels is now replaced with the prebuilt model `prebuilt-document` which extracts entities, key-value pairs, and layout from a document. Train a custom model with `3.1.x`: ```python