Merge pull request #229853 from laujan/229508-vinod-feb-2023-release

update files for 2-28-2023 release

Author: v-dirichards

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

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: forms-recognizer
 ms.topic: conceptual
-ms.date: 02/28/2023
+ms.date: 03/08/2023
 ms.author: lajanuar
 recommendations: false
 ---
@@ -38,7 +38,11 @@ With composed models, you can assign multiple custom models to a composed model
 
 * For ```Custom neural``` models the best practice is to add all the different variations of a single document type into a single training dataset and train on custom neural model. Model compose is best suited for scenarios when you have documents of different types being submitted for analysis.
 
-* Pricing is the same whether you're using a composed model or selecting a specific model. One model analyzes each document. With composed models, the system performs a classification to check which of the composed custom models should be invoked and invokes the single best model for the document.
+::: moniker-end
+
+::: moniker range="form-recog-3.0.0"
+
+With the introduction of [****custom classifier models****](./concept-custom-classifier.md), you can choose to use [**composed models**](./concept-composed-models.md) or the classifier model as an explicit step before analysis. For a deeper understanding  of when to use a classifier or composed model, _see_ [**Custom classifier models**](concept-custom-classifier.md).
 
 ## Compose model limits
 
@@ -57,7 +61,7 @@ With composed models, you can assign multiple custom models to a composed model
 
 * To compose a model trained with a prior version of the API (v2.1 or earlier), train a model with the v3.0 API using the same labeled dataset. That addition ensures that the v2.1 model can be composed with other models.
 
-* Models composed with v2.1 of the API continue to be supported, requiring no updates.
+* Models composed with v2.1 of the API continues to be supported, requiring no updates.
 
 * The limit for maximum number of custom models that can be composed is 100.
 
@@ -90,4 +94,4 @@ Learn to create and compose custom models:
 
 > [!div class="nextstepaction"]
 > [**Build a custom model**](how-to-guides/build-a-custom-model.md)
-> [**Compose custom models**](how-to-guides/compose-custom-models.md)
+> [**Compose custom models**](how-to-guides/compose-custom-models.md)

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

@@ -0,0 +1,135 @@
+---
+title: Custom classifier model - Form Recognizer
+titleSuffix: Azure Applied AI Services
+description: Use the custom classifier model to train a model to identify and split the documents you process within your application.
+author: vkurpad
+manager: nitinme
+ms.service: applied-ai-services
+ms.subservice: forms-recognizer
+ms.topic: conceptual
+ms.date: 03/08/2023
+ms.author: lajanuar
+ms.custom: references_regions
+monikerRange: 'form-recog-3.0.0'
+recommendations: false
+---
+
+# Custom classifier model
+
+**This article applies to:** ![Form Recognizer v3.0 checkmark](media/yes-icon.png) **Form Recognizer v3.0**.
+
+Custom classifier models are deep-learning-model types that combine layout and language features to accurately detect and identify documents you process within your application. Custom classifier models can classify each page in an input file to identify the document(s) within and can also identify multiple documents or multiple instances of a single document within an input file.
+
+## Model capabilities
+
+Custom classifier models can analyze a single- or multi-file documents to identify if any of the trained document types are contained within an input file. Here are the currently supported scenarios:
+
+* A single file containing one document. For instance, a loan application form.
+
+* A single file containing multiple documents. For instance, a loan application package containing a loan application form, payslip, and bank statement.
+
+* A single file containing multiple instances of the same document. For instance, a collection of scanned invoices.
+
+Training a custom classifier model requires at least two distinct classes and a minimum of five samples per class.
+
+### Compare custom classifier and composed models
+
+A custom classifier model can replace [a composed model](concept-composed-models.md) in some scenarios but there are a few differences to be aware of:
+
+| Capability | Custom classifier process | Composed model process |
+|--|--|--|
+|Analyze a single document of unknown type belonging to one of the types trained for extraction model processing.| &#9679; Requires multiple calls. </br> &#9679; Call the classifier models based on the document class. This step allows for a confidence-based check before invoking the extraction model analysis.</br> &#9679; Invoke the extraction model. | &#9679; Requires a single call to a composed model containing the model corresponding to the input document type. |
+ |Analyze a single document of unknown type belonging to several types trained for extraction model processing.| &#9679;Requires multiple calls.</br> &#9679; Make a call to the classifier that ignores documents not matching a designated type for extraction.</br> &#9679; Invoke the extraction model. | &#9679;  Requires a single call to a composed model. The service selects a custom model within the composed model with the highest match.</br> &#9679; A composed model can't ignore documents.|
+|Analyze a file containing multiple documents of known or unknown type belonging to one of the types trained for extraction model processing.| &#9679; Requires multiple calls. </br> &#9679; Call the extraction model for each identified document in the input file.</br> &#9679; Invoke the extraction model. | &#9679;  Requires a single call to a composed model.</br> &#9679; The composed model invokes the component model once on the first instance of the document. </br> &#9679;The remaining documents are ignored. |
+
+## Language support
+
+Classifier models currently only support English language documents.
+
+## Best practices
+
+Custom classifier models require a minimum of five samples per class to train. If the classes are similar, adding extra training samples improves model accuracy.
+
+## Training a model
+
+Custom classifier models are only available in the [v3.0 API](v3-migration-guide.md) starting with API version ```2023-02-28-preview```. [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio) provides a no-code user interface to interactively train a custom classifier.
+
+When using the REST API, if you've organized your documents by folders, you can use the ```azureBlobSource``` property of the request to train a classifier model.
+
+```rest
+https://{endpoint}/formrecognizer/documentClassifiers:build?api-version=2023-02-28-preview
+
+{
+  "classifierId": "demo2.1",
+  "description": "",
+  "docTypes": {
+    "car-maint": {
+        "azureBlobSource": {
+            "containerUrl": "SAS URL to container",
+            "prefix": "sample1/car-maint/"
+            }
+    },
+    "cc-auth": {
+        "azureBlobSource": {
+            "containerUrl": "SAS URL to container",
+            "prefix": "sample1/cc-auth/"
+            }
+    },
+    "deed-of-trust": {
+        "azureBlobSource": {
+            "containerUrl": "SAS URL to container",
+            "prefix": "sample1/deed-of-trust/"
+            }
+    }
+  }
+}
+
+```
+
+Alternatively, if you have a flat list of files or only plan to use a few select files within each folder to train the model, you can use the ```azureBlobFileListSource``` property to train the model. This step requires a ```file list``` in [JSON Lines](https://jsonlines.org/) format. For each class, add a new file with a list of files to be submitted for training.
+
+```rest
+{
+  "classifierId": "demo2",
+  "description": "",
+  "docTypes": {
+    "car-maint": {
+      "azureBlobFileListSource": {
+        "containerUrl": "SAS URL to container",
+        "fileList": "sample1/car-maint.jsonl"
+      }
+    },
+    "cc-auth": {
+      "azureBlobFileListSource": {
+        "containerUrl": "SAS URL to container",
+        "fileList": "sample1/cc-auth.jsonl"
+      }
+    },
+    "deed-of-trust": {
+      "azureBlobFileListSource": {
+        "containerUrl": "SAS URL to container",
+        "fileList": "sample1/deed-of-trust.jsonl"
+      }
+    }
+  }
+}
+
+```
+
+File list `car-maint.jsonl` contains the following files.
+
+```json
+{"file":"sample1/car-maint/Commercial Motor Vehicle - Adatum.pdf"}
+{"file":"sample1/car-maint/Commercial Motor Vehicle - Fincher.pdf"}
+{"file":"sample1/car-maint/Commercial Motor Vehicle - Lamna.pdf"}
+{"file":"sample1/car-maint/Commercial Motor Vehicle - Liberty.pdf"}
+{"file":"sample1/car-maint/Commercial Motor Vehicle - Trey.pdf"}
+```
+
+## Next steps
+
+Learn to create custom classifier models:
+
+> [!div class="nextstepaction"]
+> [**Build a custom classifier model**](how-to-guides/build-a-custom-classifier.md)
+> [**Custom models overview**](concept-custom.md)

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

@@ -21,7 +21,7 @@ This article highlights the best methods for labeling custom model datasets in t
 
 * The following video is the second of two presentations intended to help you build custom models with higher accuracy (the first presentation explores [How to create a balanced data set](concept-custom-label.md#video-custom-label-tips-and-pointers)).
 
-* Here, we'll examine best practices for labeling your selected documents. With semantically relevant and consistent labeling, you should see an improvement in model performance.</br></br>
+* Here, we examine best practices for labeling your selected documents. With semantically relevant and consistent labeling, you should see an improvement in model performance.</br></br>
 
   > [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE5fZKB ]
 

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

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: forms-recognizer
 ms.topic: conceptual
-ms.date: 01/30/2023
+ms.date: 03/09/2023
 ms.author: vikurpad
 ms.custom: references_regions
 monikerRange: 'form-recog-3.0.0'
@@ -22,9 +22,9 @@ Custom models (template and neural) require a labeled dataset of at least five d
 
 A labeled dataset consists of several files:
 
-* You'll provide a set of sample documents (typically PDFs or images). A minimum of five documents is needed to train a model.
+* You provide a set of sample documents (typically PDFs or images). A minimum of five documents is needed to train a model.
 
-* Additionally, the labeling process will generate the following files:
+* Additionally, the labeling process generates the following files:
 
   * A `fields.json` file is created when the first field is added. There's one `fields.json` file for the entire training dataset, the field list contains the field name and associated sub fields and types.
 
@@ -36,19 +36,19 @@ A labeled dataset consists of several files:
 
 * The following video is the first of two presentations intended to help you build custom models with higher accuracy (The second presentation examines [Best practices for labeling documents](concept-custom-label-tips.md#video-custom-labels-best-practices)).
 
-* Here, we'll explore how to create a balanced data set and select the right documents to label. This process will set you on the path to higher quality models.</br></br>
+* Here, we explore how to create a balanced data set and select the right documents to label. This process sets you on the path to higher quality models.</br></br>
 
   > [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RWWHru]
 
 ## Create a balanced dataset
 
-Before you start labeling, it's a good idea to look at a few different samples of the document to identify which samples you want to use in your labeled dataset. A balanced dataset represents all the typical variations you would expect to see for the document. Creating a balanced dataset will result in a model with the highest possible accuracy. A few examples to consider are:
+Before you start labeling, it's a good idea to look at a few different samples of the document to identify which samples you want to use in your labeled dataset. A balanced dataset represents all the typical variations you would expect to see for the document. Creating a balanced dataset results in a model with the highest possible accuracy. A few examples to consider are:
 
 * **Document formats**: If you expect to analyze both digital and scanned documents, add a few examples of each type to the training dataset
 
 * **Variations (template model)**:  Consider splitting the dataset into folders and train a model for each of variation. Any variations that include either structure or layout should be split into different models. You can then compose the individual models into a single [composed model](concept-composed-models.md).
 
-* **Variations (Neural models)**: When your dataset has a manageable set of variations, about 15 or fewer, create a single dataset with a few samples of each of the different variations to train a single model. If the number of template variations is larger than 15, you'll train multiple models and [compose](concept-composed-models.md) them together.
+* **Variations (Neural models)**: When your dataset has a manageable set of variations, about 15 or fewer, create a single dataset with a few samples of each of the different variations to train a single model. If the number of template variations is larger than 15, you train multiple models and [compose](concept-composed-models.md) them together.
 
 * **Tables**: For documents containing tables with a variable number of rows, ensure that the training dataset also represents documents with different numbers of rows.
 
@@ -70,12 +70,12 @@ Use the following guidelines to define the fields:
 
 * For tabular fields spanning multiple pages, define and label the fields as a single table.
 
-. [!NOTE] 
+> [!NOTE]
 > Custom neural 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 neural models currently only support key-value pairs, structured fields (tables), and selection marks. 
+Custom neural models currently only support key-value pairs, structured fields (tables), and selection marks.
 
 | Model type | Form fields | Selection marks | Tabular fields | Signature | Region |
 |--|--|--|--|--|--|
@@ -100,7 +100,7 @@ Tabular fields are also useful when extracting repeating information within a do
 
 * **Consistent labeling**. If a value appears in multiple contexts withing the document, consistently pick the same context across documents to label the value.
 
-* **Visually repeating data**. Tables support visually repeating groups of information not just explicit tables. Explicit tables will be identified in tables section of the analyzed documents as part of the layout output and don't need to be labeled as tables. Only label a table field if the information is visually repeating and not identified as a table as part of the layout response. An example would be the repeating work experience section of a resume.
+* **Visually repeating data**. Tables support visually repeating groups of information not just explicit tables. Explicit tables are identified in tables section of the analyzed documents as part of the layout output and don't need to be labeled as tables. Only label a table field if the information is visually repeating and not identified as a table as part of the layout response. An example would be the repeating work experience section of a resume.
 
 * **Region labeling (custom template)**. Labeling specific regions allows you to define a value when none exists. If the value is optional, ensure that you leave a few sample documents with the region not labeled. When labeling regions, don't include the surrounding text with the label.
 

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

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: forms-recognizer
 ms.topic: conceptual
-ms.date: 12/15/2022
+ms.date: 03/08/2023
 ms.author: lajanuar
 ms.custom: references_regions
 monikerRange: 'form-recog-3.0.0'
@@ -30,19 +30,32 @@ Custom neural models share the same labeling format and strategy as [custom temp
 
 ## Model capabilities
 
-Custom neural models currently only support key-value pairs and selection marks and structured fields (tables), future releases will include support for signatures.
+Custom neural models currently only support key-value pairs and selection marks and structured fields (tables), future releases include support for signatures.
 
 | Form fields | Selection marks | Tabular fields | Signature | Region |
 |:--:|:--:|:--:|:--:|:--:|
 | Supported | Supported | Supported | Unsupported | Supported <sup>1</sup> |
 
-<sup>1</sup> Region labels in custom neural models will use the results from the Layout API for specified region. This feature is different from template models where, if no value is present, text is generated at training time.
+<sup>1</sup> Region labels in custom neural models use the results from the Layout API for specified region. This feature is different from template models where, if no value is present, text is generated at training time.
 
 ### Build mode
 
 The build custom model operation has added support for the *template* and *neural* custom models. Previous versions of the REST API and SDKs only supported a single build mode that is now known as the *template* mode.
 
-Neural models support documents that have the same information, but different page structures. Examples of these documents include United States W2 forms, which share the same information, but may vary in appearance across companies. Neural models currently only support English text. For more information, *see* [Custom model build mode](concept-custom.md#build-mode).
+Neural models support documents that have the same information, but different page structures. Examples of these documents include United States W2 forms, which share the same information, but may vary in appearance across companies. For more information, *see* [Custom model build mode](concept-custom.md#build-mode).
+
+## Language support
+
+1. Neural models now support added languages in the ```2023-02-28-preview``` API.
+
+| Languages | API version |
+|:--:|:--:|
+| English | `2022-08-31` (GA), `2023-02-28-preview`|
+| German |  `2023-02-28-preview`|
+| Italian |  `2023-02-28-preview`|
+| French |  `2023-02-28-preview`|
+| Spanish |  `2023-02-28-preview`|
+| Dutch |  `2023-02-28-preview`|
 
 ## Tabular fields
 
@@ -98,7 +111,7 @@ Custom neural models can generalize across different formats of a single documen
 
 ### 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.
+When you label the data, labeling the field relevant to the value improves 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
 
@@ -114,7 +127,7 @@ Values in training cases should be diverse and representative. For example, if a
 ## Current Limitations
 
 * The model doesn't recognize values split across page boundaries.
-* Custom neural models are only trained in English and model performance will be lower for documents in other languages.
+* Custom neural models are only trained in English. Model performance is 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 neural models are limited to 10 build operations per month. Open a support request if you need the limit increased.