Merge pull request #188262 from laujan/vinod-release-preview2-branch

vinod-release-updates

Author: ShannonLeavitt

articles/applied-ai-services/form-recognizer/api-v2-0/includes/csharp-v3-0-0.md

@@ -382,7 +382,7 @@ Submodel Form Type: form-63c013e3-1cab-43eb-84b0-f4b20cb9214c
 
 ## Analyze forms with a custom model
 
-This section demonstrates how to extract key/value information and other content from your custom form types, using models you trained with your own forms.
+This section demonstrates how to extract key/value information and other content from your custom template types, using models you trained with your own forms.
 
 > [!IMPORTANT]
 > In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below.

articles/applied-ai-services/form-recognizer/api-v2-0/includes/java-v3-0-0.md

@@ -294,7 +294,7 @@ The model found field 'field-6' with label: VAT ID
 
 ## Analyze forms with a custom model
 
-This section demonstrates how to extract key/value information and other content from your custom form types, using models you trained with your own forms.
+This section demonstrates how to extract key/value information and other content from your custom template types, using models you trained with your own forms.
 
 > [!IMPORTANT]
 > In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. See the [Train a model](#train-a-model-without-labels) section.
@@ -314,7 +314,7 @@ The returned value is a collection of **RecognizedForm** objects: one for each p
 
 ```console
 Analyze PDF form...
------------ Recognized custom form info for page 0 -----------
+----------- Recognized custom template info for page 0 -----------
 Form type: form-0
 Field 'field-0' has label 'Address:' with a confidence score of 0.91.
 Field 'field-1' has label 'Invoice For:' with a confidence score of 1.00.

articles/applied-ai-services/form-recognizer/api-v2-0/includes/javascript-v3-0-0.md

@@ -260,7 +260,7 @@ Document errors: undefined
 
 ## Analyze forms with a custom model
 
-This section demonstrates how to extract key/value information and other content from your custom form types, using models you trained with your own forms.
+This section demonstrates how to extract key/value information and other content from your custom template types, using models you trained with your own forms.
 
 > [!IMPORTANT]
 > In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. See the [Train a model](#train-a-model-without-labels) section.

articles/applied-ai-services/form-recognizer/api-v2-0/includes/python-v3-0-0.md

@@ -268,7 +268,7 @@ Document errors: []
 
 ## Analyze forms with a custom model
 
-This section demonstrates how to extract key/value information and other content from your custom form types, using models you trained with your own forms.
+This section demonstrates how to extract key/value information and other content from your custom template types, using models you trained with your own forms.
 
 > [!IMPORTANT]
 > In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. See the [Train a model](#train-a-model-without-labels) section.

articles/applied-ai-services/form-recognizer/build-training-data-set.md

@@ -38,7 +38,7 @@ Follow these additional tips to further optimize your data set for training.
 
 ## Upload your training data
 
-When you've put together the set of form documents that you'll use for training, you need to upload it to an Azure blob storage container. If you don't know how to create an Azure storage account with a container, following the [Azure Storage quickstart for Azure portal](../../storage/blobs/storage-quickstart-blobs-portal.md). Use the standard performance tier.
+When you've put together the set of form documents that you'll use for training, you need to upload it to an Azure blob storage container. If you don't know how to create an Azure storage account with a container, follow the [Azure Storage quickstart for Azure portal](../../storage/blobs/storage-quickstart-blobs-portal.md). Use the standard performance tier.
 
 If you want to use manually labeled data, you'll also have to upload the *.labels.json* and *.ocr.json* files that correspond to your training documents. You can use the [Sample Labeling tool](label-tool.md) (or your own UI) to generate these files.
 

articles/applied-ai-services/form-recognizer/compose-custom-models.md

@@ -1,30 +1,28 @@
 ---
-title: "How to guide: use custom and composed models"
+title: "How to guide: create and compose custom models with Form Recognizer v2.1"
 titleSuffix: Azure Applied AI Services
-description: Learn how to create, use, and manage Form Recognizer custom and composed models
+description: Learn how to create, compose use, and manage custom models with Form Recognizer v2.1
 author: laujan
 manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: forms-recognizer
 ms.topic: how-to
-ms.date: 11/02/2021
+ms.date: 02/12/2022
 ms.author: lajanuar
 recommendations: false
-ms.custom: ignite-fall-2021
 ---
 
-# Use custom and composed models
+# Create and compose custom models 
+
+> [!NOTE]
+> This how-to guide references Form Recognizer v2.1 (GA). 
 
 Form Recognizer uses advanced machine-learning technology to detect and extract information from document images and return the extracted data in a structured JSON output. With Form Recognizer, you can train standalone custom models or combine custom models to create composed models.
 
 * **Custom models**. Form Recognizer custom models enable you to analyze and extract data from forms and documents specific to your business. Custom models are trained for your distinct data and use cases.
 
 * **Composed models**. A composed model is created by taking a collection of custom models and assigning them to a single model that encompasses your form types. When a document is submitted to a composed model, the service performs a classification step to decide which custom model accurately represents the form presented for analysis.
 
-***Model configuration window in Form Recognizer Studio***
-
-:::image type="content" source="media/studio/composed-model.png" alt-text="Screenshot: model configuration window in Form Recognizer Studio.":::
-
 In this article, you'll learn how to create Form Recognizer custom and composed models using our [Form Recognizer Sample Labeling tool](label-tool.md), [REST APIs](quickstarts/client-library.md?branch=main&pivots=programming-language-rest-api#train-a-custom-model), or [client-library SDKs](quickstarts/client-library.md?branch=main&pivots=programming-language-csharp#train-a-custom-model).
 
 ## Sample Labeling tool

articles/applied-ai-services/form-recognizer/concept-accuracy-confidence.md

@@ -1,23 +1,24 @@
 ---
-title:  Interpret and improve accuracy and confidence scores
+title:  Interpret and improve model accuracy and analysis confidence scores
 titleSuffix: Azure Applied AI Services
-description: Best practices for how to interpret the accuracy score from the train model operation and the confidence score from analysis operations.
+description: Best practices to interpret the accuracy score from the train model operation and the confidence score from analysis operations.
 author: laujan
 manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: forms-recognizer
 ms.topic: conceptual
-ms.date: 02/03/2022
+ms.date: 02/14/2022
 ms.author: vikurpad
 ---
 
 # Interpret and improve accuracy and confidence for custom models
 
 > [!NOTE]
+>
 > * **Custom models do not provide accuracy scores during training**.
 > * Confidence scores for structured fields such as tables are currently unavailable.
 
-Custom models generate an estimated accuracy score when trained. Documents analyzed with a Custom model produce a confidence score for extracted fields. In this document, you'll learn to interpret accuracy and confidence scores and best practices for using those scores to improve accuracy and confidence results.
+Custom models generate an estimated accuracy score when trained. Documents analyzed with a custom model produce a confidence score for extracted fields. In this article, you'll learn to interpret accuracy and confidence scores and best practices for using those scores to improve accuracy and confidence results.
 
 ## Accuracy scores
 

articles/applied-ai-services/form-recognizer/concept-composed-models.md

@@ -0,0 +1,69 @@
+---
+title: Form Recognizer composed models
+titleSuffix: Azure Applied AI Services
+description: Learn about composed custom models
+author: laujan
+manager: nitinme
+ms.service: applied-ai-services
+ms.subservice: forms-recognizer
+ms.topic: conceptual
+ms.date: 02/13/2022
+ms.author: vikurpad
+recommendations: false
+---
+
+# Composed custom models
+
+**Composed models**. A composed model is created by taking a collection of custom models and assigning them to a single model comprised of your form types. When a document is submitted for analysis to a composed model, the service performs a classification to decide which custom model accurately represents the form presented for analysis.
+
+With composed models, you can assign multiple custom models to a composed model called with a single model ID. It's useful when you've trained several models and want to group them to analyze similar form types. For example, your composed model might include custom models trained to analyze your supply, equipment, and furniture purchase orders. Instead of manually trying to select the appropriate model, you can use a composed model to determine the appropriate custom model for each analysis and extraction.
+
+* ```Custom form```and ```Custom document``` models can be composed together into a single composed model when they're trained with the same API version or an API version later than ```2021-01-30-preview```. For more information on composing custom template and custom neural models, see [compose model limits](#compose-model-limits).
+* With the model compose operation, you can assign up to 100 trained custom models to a single composed model. When you call Analyze with the composed model ID, Form Recognizer will first classify the form you submitted, choose the best matching assigned model, and then return results for that model.
+* For **_custom template models_**, the composed model can be created using variations of a custom template or different form types. This operation is useful when incoming forms may belong to one of several templates.
+* The response will include a ```docType``` property to indicate which of the composed models was used to analyze the document.
+
+## Compose model limits
+
+> [!NOTE]
+> With the addition of **_custom neural model_** , there are a few limits to the compatibility of models that can be composed together.
+
+### Composed model compatibility
+
+ |Custom model type | API Version |Custom form 2021-01-30-preview (v3.0)| Custom document 2021-01-30-preview(v3.0) | Custom form GA version (v2.1) or earlier|
+|--|--|--|--|--|
+|**Custom template** (updated custom form)| 2021-01-30-preview |  ✱| ✓ | X |
+|**Custom neural**| trained with current API version (2021-01-30-preview) |✓ |✓ | X |
+|**Custom form**| Custom form GA version (v2.1) or earlier | X | X|  ✓|
+
+**Table symbols**: ✔ — supported; **X** — not supported; ✱ — unsupported for this API version, but will be supported in a future API version.
+
+* To compose a model trained with a prior version of the API (2.1 or earlier), train a model with the 3.0 API using the same labeled dataset to ensure that it can be composed with other models.
+
+* Models composed with v2.1 of the API will continue to be supported, requiring no updates.
+
+* The limit for maximum number of custom models that can be composed is 100.
+
+## Development options
+
+The following resources are supported by Form Recognizer **v3.0** (preview):
+
+| Feature | Resources |
+|----------|-------------|
+|_**Custom model**_| <ul><li>[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</li><li>[REST API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-1/operations/BuildDocumentModel)</li><li>[C# SDK](quickstarts/try-v3-csharp-sdk.md)</li><li>[Java SDK](quickstarts/try-v3-java-sdk.md)</li><li>[JavaScript SDK](quickstarts/try-v3-javascript-sdk.md)</li><li>[Python SDK](quickstarts/try-v3-python-sdk.md)</li></ul>|
+| _**Composed model**_| <ul><li>[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</li><li>[REST API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-1/operations/ComposeDocumentModel)</li><li>[C# SDK](/dotnet/api/azure.ai.formrecognizer.documentanalysis.documentmodeladministrationclient.startcreatecomposedmodel?view=azure-dotnet-preview&preserve-view=true)</li><li>[Java SDK](/java/api/com.azure.ai.formrecognizer.administration.documentmodeladministrationclient.begincreatecomposedmodel?view=azure-java-preview&preserve-view=true)</li><li>[JavaScript SDK](/javascript/api/@azure/ai-form-recognizer/documentmodeladministrationclient?view=azure-node-preview#@azure-ai-form-recognizer-documentmodeladministrationclient-begincomposemodel&preserve-view=true)</li><li>[Python SDK](/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.formtrainingclient?view=azure-python-preview#azure-ai-formrecognizer-formtrainingclient-begin-create-composed-model&preserve-view=true)</li></ul>|
+
+The following resources are supported by Form Recognizer v2.1:
+
+| Feature | Resources |
+|----------|-------------------------|
+|_**Custom model**_| <ul><li>[Form Recognizer labeling tool](https://fott-2-1.azurewebsites.net)</li><li>[REST API](quickstarts/try-sdk-rest-api.md?pivots=programming-language-rest-api#analyze-forms-with-a-custom-model)</li><li>[Client library SDK](quickstarts/try-sdk-rest-api.md)</li><li>[Form Recognizer Docker container](containers/form-recognizer-container-install-run.md?tabs=custom#run-the-container-with-the-docker-compose-up-command)</li></ul>|
+| _**Composed model**_ |<ul><li>[Form Recognizer labeling tool](https://fott-2-1.azurewebsites.net/)</li><li>[REST API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/Compose)</li><li>[C# SDK](/dotnet/api/azure.ai.formrecognizer.training.createcomposedmodeloperation?view=azure-dotnet&preserve-view=true)</li><li>[Java SDK](/java/api/com.azure.ai.formrecognizer.models.createcomposedmodeloptions?view=azure-java-stable&preserve-view=true)</li><li>[JavaScript SDK](/javascript/api/@azure/ai-form-recognizer/begincreatecomposedmodeloptions?view=azure-node-latest&preserve-view=true)</li><li>[Python SDK](/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.formtrainingclient?view=azure-python#azure-ai-formrecognizer-formtrainingclient-begin-create-composed-model&preserve-view=true)</li></ul>|
+
+
+## Next steps
+
+Learn to create and compose custom models:
+
+> [!div class="nextstepaction"]
+> [**Form Recognizer v2.1 (GA)**](compose-custom-models.md)

articles/applied-ai-services/form-recognizer/concept-custom-neural.md

@@ -0,0 +1,127 @@
+---
+title: Form Recognizer custom neural model
+titleSuffix: Azure Applied AI Services
+description: Learn about custom neural (neural) model type, its features and how you train a model with high accuracy to extract data from structured and unstructured documents
+author: laujan
+manager: nitinme
+ms.service: applied-ai-services
+ms.subservice: forms-recognizer
+ms.topic: conceptual
+ms.date: 02/13/2022
+ms.author: vikurpad
+ms.custom: references_regions
+recommendations: false
+---
+
+# Form Recognizer custom neural model
+
+Custom document models or neural models are a deep learned model that combines layout and language features to accurately extract labeled fields from documents. The base custom neural model is trained on various document types that makes it suitable to be trained for extracting fields from structured, semi-structured and unstructured documents. The table below lists common document types for each category:
+
+|Documents | Examples |
+|---|--|
+|structured| surveys, questionnaires|
+|semi-structured | invoices, purchase orders |
+|unstructured | contracts, letters|
+
+Custom document models share the same labeling format and strategy as custom template models. Currently custom neural models only support a subset of the field types supported by custom template models. 
+
+## Model capabilities
+
+Custom document models currently only support key-value pairs and selection marks, future releases will include support for structured fields (tables) and signature.
+
+| Form fields | Selection marks | Tables | Signature | Region |
+|--|--|--|--|--|
+| Supported| Supported | Unsupported | Unsupported | Unsupported |
+
+## Supported regions
+
+In public preview custom neural models can only be trained in select Azure regions.
+
+* AustraliaEast
+* BrazilSouth
+* CanadaCentral
+* CentralIndia
+* CentralUS
+* EastUS
+* EastUS2
+* FranceCentral
+* JapanEast
+* JioIndiaWest
+* KoreaCentral
+* NorthEurope
+* SouthCentralUS
+* SoutheastAsia
+* UKSouth
+* WestEurope
+* WestUS
+* WestUS2
+* WestUS3
+
+You can copy a model trained in one of the regions listed above to any other region for use.
+
+## Best practices
+
+Custom document models differ from custom template models in a few different ways. 
+
+### Dealing with variations 
+
+Custom document models can generalize across different formats of a single document type. As a best practice, create a single model for all variations of a document type. Add at least five labeled samples for each of the different variations to the training dataset.
+
+### Field naming
+
+When you label the data, labeling the field relevant to the value will improve the accuracy of the key-value pairs extracted. For example, for a field value containing the supplier ID, consider naming the field "supplier_id". Field names should be in the language of the document.
+
+### Labeling contiguous values
+
+Value tokens/words of one field must be either
+
+* Consecutive sequence in natural reading order without interleaving with other fields
+* In a region that don't cover any other fields
+
+### Representative data
+
+Values in training cases should be diverse and representative. For example, if a field is named "date", values for this field should be a date. synthetic value like a random string can affect model performance.
+
+
+## Current Limitations
+
+* The model doesn't recognize values split across page boundaries.
+* Custom document models are only trained in English and model performance will be lower for documents in other languages.
+* If a dataset labeled for custom template models is used to train a custom neural model, the unsupported field types are ignored.
+* Custom document models are limited to 10 build operations per month. Open a support request if you need the limit increased.
+
+## Training a model
+
+Custom document models are only available in the [v3 API](v3-migration-guide.md).
+
+| Document Type | REST API | SDK | Label and Test Models|
+|--|--|--|--|
+| Custom document | [Form Recognizer 3.0 (preview)](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-1/operations/AnalyzeDocument)| [Form Recognizer Preview SDK](quickstarts/try-v3-python-sdk.md)| [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio)
+
+The build operation to train model supports a new ```buildMode``` property, to train a custom neural model, set the ```buildMode``` to ```neural```.
+
+```REST
+https://{endpoint}/formrecognizer/documentModels:build?api-version=2022-01-30-preview
+
+{
+  "modelId": "string",
+  "description": "string",
+  "buildMode": "neural",
+  "azureBlobSource":
+  {
+    "containerUrl": "string",
+    "prefix": "string"
+  }
+}
+```
+## Next steps
+
+* Train a custom model:
+
+  > [!div class="nextstepaction"]
+  > [Form Recognizer quickstart](quickstarts/try-v3-form-recognizer-studio.md#custom-models)
+
+* View the labeling guidelines:
+
+    > [!div class="nextstepaction"]
+    > [Form Recognizer API v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeWithCustomForm)