[formrecognizer] update samples to train a model where a model_id is …

…needed (#18789)

* update samples to use existing model ID or train a model option

* remove static environment variables

* switch to using getenv for model id

* fixes

* update docs

* fix links

* review feedback

sdk/formrecognizer/azure-ai-formrecognizer/samples/README.md

@@ -44,7 +44,7 @@ All of these samples need the endpoint to your Form Recognizer resource ([instru
 1. Install the Azure Form Recognizer client library for Python with [pip][pip]:
 
 ```bash
-pip install azure-ai-formrecognizer --pre
+pip install azure-ai-formrecognizer
 ```
 
 2. Clone or download this sample repository

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_authentication_async.py

@@ -28,7 +28,6 @@
     3) AZURE_CLIENT_ID - the client ID of your active directory application.
     4) AZURE_TENANT_ID - the tenant ID of your active directory application.
     5) AZURE_CLIENT_SECRET - the secret of your active directory application.
-    6) AZURE_FORM_RECOGNIZER_AAD_ENDPOINT - the endpoint to your Form Recognizer resource for using AAD.
 """
 
 import os
@@ -60,7 +59,7 @@ async def authentication_with_azure_active_directory_form_recognizer_client_asyn
         from azure.ai.formrecognizer.aio import FormRecognizerClient
         from azure.identity.aio import DefaultAzureCredential
 
-        endpoint = os.environ["AZURE_FORM_RECOGNIZER_AAD_ENDPOINT"]
+        endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
         credential = DefaultAzureCredential()
 
         form_recognizer_client = FormRecognizerClient(endpoint, credential)
@@ -89,7 +88,7 @@ async def authentication_with_azure_active_directory_form_training_client_async(
         from azure.ai.formrecognizer.aio import FormTrainingClient
         from azure.identity.aio import DefaultAzureCredential
 
-        endpoint = os.environ["AZURE_FORM_RECOGNIZER_AAD_ENDPOINT"]
+        endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
         credential = DefaultAzureCredential()
 
         form_training_client = FormTrainingClient(endpoint, credential)

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_copy_model_async.py

@@ -14,6 +14,9 @@
     to a target Form Recognizer resource. The resource id and the resource region can be found
     in the azure portal.
 
+    The model used in this sample can be created in the sample_train_model_with_labels_async.py using the
+    training files in https://aka.ms/azsdk/formrecognizer/sampletrainingfiles
+
 USAGE:
     python sample_copy_model_async.py
 
@@ -23,6 +26,9 @@
     3) AZURE_FORM_RECOGNIZER_TARGET_ENDPOINT - the endpoint to your target Form Recognizer resource.
     4) AZURE_FORM_RECOGNIZER_TARGET_KEY - your target Form Recognizer API key
     5) AZURE_SOURCE_MODEL_ID - the model ID from the source resource to be copied over to the target resource.
+        - OR -
+       CONTAINER_SAS_URL - The shared access signature (SAS) Url of your Azure Blob Storage container with your forms.
+       A model will be trained and used to run the sample.
     6) AZURE_FORM_RECOGNIZER_TARGET_REGION - the region the target resource was created in
     7) AZURE_FORM_RECOGNIZER_TARGET_RESOURCE_ID - the entire resource ID to the target resource
 """
@@ -33,15 +39,15 @@
 
 class CopyModelSampleAsync(object):
 
-    async def copy_model_async(self):
+    async def copy_model_async(self, custom_model_id):
         from azure.core.credentials import AzureKeyCredential
         from azure.ai.formrecognizer.aio import FormTrainingClient
 
         source_endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
         source_key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
         target_endpoint = os.environ["AZURE_FORM_RECOGNIZER_TARGET_ENDPOINT"]
         target_key = os.environ["AZURE_FORM_RECOGNIZER_TARGET_KEY"]
-        source_model_id = os.environ["AZURE_SOURCE_MODEL_ID"]
+        source_model_id = os.getenv("AZURE_SOURCE_MODEL_ID", custom_model_id)
         target_region = os.environ["AZURE_FORM_RECOGNIZER_TARGET_REGION"]
         target_resource_id = os.environ["AZURE_FORM_RECOGNIZER_TARGET_RESOURCE_ID"]
 
@@ -74,7 +80,27 @@ async def copy_model_async(self):
 
 async def main():
     sample = CopyModelSampleAsync()
-    await sample.copy_model_async()
+    model_id = None
+    if os.getenv("CONTAINER_SAS_URL"):
+
+        from azure.core.credentials import AzureKeyCredential
+        from azure.ai.formrecognizer.aio import FormTrainingClient
+
+        endpoint = os.getenv("AZURE_FORM_RECOGNIZER_ENDPOINT")
+        key = os.getenv("AZURE_FORM_RECOGNIZER_KEY")
+
+        if not endpoint or not key:
+            raise ValueError("Please provide endpoint and API key to run the samples.")
+
+        form_training_client = FormTrainingClient(
+            endpoint=endpoint, credential=AzureKeyCredential(key)
+        )
+        async with form_training_client:
+            model = await (await form_training_client.begin_training(
+                os.getenv("CONTAINER_SAS_URL"), use_training_labels=True)).result()
+            model_id = model.model_id
+
+    await sample.copy_model_async(model_id)
 
 
 if __name__ == '__main__':

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_differentiate_output_labeled_tables_async.py

@@ -12,9 +12,8 @@
 DESCRIPTION:
     This sample demonstrates the differences in output that arise when begin_recognize_custom_forms
     is called with custom models trained with fixed vs. dynamic table tags.
-    The models used in this sample can be created in the sample_train_model_with_labels.py using the
-    training files in
-    https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_forms/labeled_tables
+    The models used in this sample can be created in the sample_train_model_with_labels_async.py using the
+    training files in https://aka.ms/azsdk/formrecognizer/sampletabletrainingfiles
 
     Note that Form Recognizer automatically finds and extracts all tables in your documents whether the tables
     are tagged/labeled or not. Tables extracted automatically by Form Recognizer will be included in the
@@ -30,7 +29,13 @@
     1) AZURE_FORM_RECOGNIZER_ENDPOINT - the endpoint to your Cognitive Services resource.
     2) AZURE_FORM_RECOGNIZER_KEY - your Form Recognizer API key
     3) MODEL_ID_FIXED_ROW_TABLES - the ID of your custom model trained with labels on fixed row tables
+            -OR-
+       CONTAINER_SAS_URL_FIXED - The shared access signature (SAS) Url of your Azure Blob Storage container with
+       your labeled data containing a fixed row table. A model will be trained and used to run the sample.
     4) MODEL_ID_DYNAMIC_ROW_TABLES - the ID of your custom model trained with labels on dynamic row tables
+            -OR-
+       CONTAINER_SAS_URL_DYNAMIC - The shared access signature (SAS) Url of your Azure Blob Storage container with
+       your labeled data containing a dynamic row table. A model will be trained and used to run the sample.
 """
 
 import os
@@ -39,13 +44,13 @@
 
 class TestDifferentiateOutputLabeledTablesAsync(object):
 
-    async def test_recognize_tables_fixed_rows_async(self):
+    async def test_recognize_tables_fixed_rows_async(self, custom_model_id):
         from azure.core.credentials import AzureKeyCredential
         from azure.ai.formrecognizer.aio import FormRecognizerClient
 
         endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
         key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
-        model_id_fixed_rows_table = os.environ["MODEL_ID_FIXED_ROW_TABLES"]
+        model_id_fixed_rows_table = os.getenv("MODEL_ID_FIXED_ROW_TABLES", custom_model_id)
 
         form_recognizer_client = FormRecognizerClient(
             endpoint=endpoint, credential=AzureKeyCredential(key)
@@ -82,13 +87,13 @@ async def test_recognize_tables_fixed_rows_async(self):
                         field.confidence
                     ))
 
-    async def test_recognize_tables_dynamic_rows_async(self):
+    async def test_recognize_tables_dynamic_rows_async(self, custom_model_id):
         from azure.core.credentials import AzureKeyCredential
         from azure.ai.formrecognizer.aio import FormRecognizerClient
 
         endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
         key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
-        model_id_dynamic_rows_table = os.environ["MODEL_ID_DYNAMIC_ROW_TABLES"]
+        model_id_dynamic_rows_table = os.getenv("MODEL_ID_DYNAMIC_ROW_TABLES", custom_model_id)
 
         form_recognizer_client = FormRecognizerClient(
             endpoint=endpoint, credential=AzureKeyCredential(key)
@@ -128,8 +133,35 @@ async def test_recognize_tables_dynamic_rows_async(self):
 
 async def main():
     sample = TestDifferentiateOutputLabeledTablesAsync()
-    await sample.test_recognize_tables_fixed_rows_async()
-    await sample.test_recognize_tables_dynamic_rows_async()
+    fixed_model_id = None
+    dynamic_model_id = None
+    if os.getenv("CONTAINER_SAS_URL_FIXED") or os.getenv("CONTAINER_SAS_URL_DYNAMIC"):
+
+        from azure.core.credentials import AzureKeyCredential
+        from azure.ai.formrecognizer.aio import FormTrainingClient
+
+        endpoint = os.getenv("AZURE_FORM_RECOGNIZER_ENDPOINT")
+        key = os.getenv("AZURE_FORM_RECOGNIZER_KEY")
+        fixed = os.getenv("CONTAINER_SAS_URL_FIXED")
+        dynamic = os.getenv("CONTAINER_SAS_URL_DYNAMIC")
+
+        if not endpoint or not key:
+            raise ValueError("Please provide endpoint and API key to run the samples.")
+
+        form_training_client = FormTrainingClient(
+            endpoint=endpoint, credential=AzureKeyCredential(key)
+        )
+
+        async with form_training_client:
+            if fixed:
+                model = await (await form_training_client.begin_training(fixed, use_training_labels=True)).result()
+                fixed_model_id = model.model_id
+            if dynamic:
+                model = await (await form_training_client.begin_training(dynamic, use_training_labels=True)).result()
+                dynamic_model_id = model.model_id
+
+    await sample.test_recognize_tables_fixed_rows_async(fixed_model_id)
+    await sample.test_recognize_tables_dynamic_rows_async(dynamic_model_id)
 
 
 if __name__ == '__main__':

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_differentiate_output_models_trained_with_and_without_labels_async.py

@@ -13,6 +13,7 @@
     This sample demonstrates the differences in output that arise when begin_recognize_custom_forms
     is called with custom models trained with labels and without labels. The models used in this
     sample can be created in sample_train_model_with_labels_async.py and sample_train_model_without_labels_async.py
+    using the training files found here: https://aka.ms/azsdk/formrecognizer/sampletrainingfiles
 
     For a more general example of recognizing custom forms, see sample_recognize_custom_forms_async.py
 
@@ -26,7 +27,13 @@
     1) AZURE_FORM_RECOGNIZER_ENDPOINT - the endpoint to your Cognitive Services resource.
     2) AZURE_FORM_RECOGNIZER_KEY - your Form Recognizer API key
     3) ID_OF_MODEL_TRAINED_WITH_LABELS - the ID of your custom model trained with labels
+        -OR-
+       CONTAINER_SAS_URL_WITH_LABELS - The shared access signature (SAS) Url of your Azure Blob Storage container with
+       your labeled data. A model will be trained and used to run the sample.
     4) ID_OF_MODEL_TRAINED_WITHOUT_LABELS - the ID of your custom model trained without labels
+        -OR-
+       CONTAINER_SAS_URL_WITHOUT_LABELS - The shared access signature (SAS) Url of your Azure Blob Storage container with
+        your forms. A model will be trained and used to run the sample.
 """
 
 import os
@@ -41,14 +48,14 @@ def format_bounding_box(bounding_box):
 
 class DifferentiateOutputModelsTrainedWithAndWithoutLabelsSampleAsync(object):
 
-    async def recognize_custom_forms(self):
+    async def recognize_custom_forms(self, labeled_model_id, unlabeled_model_id):
         from azure.core.credentials import AzureKeyCredential
         from azure.ai.formrecognizer.aio import FormRecognizerClient
 
         endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
         key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
-        model_trained_with_labels_id = os.environ["ID_OF_MODEL_TRAINED_WITH_LABELS"]
-        model_trained_without_labels_id = os.environ["ID_OF_MODEL_TRAINED_WITHOUT_LABELS"]
+        model_trained_with_labels_id = os.getenv("ID_OF_MODEL_TRAINED_WITH_LABELS", labeled_model_id)
+        model_trained_without_labels_id = os.getenv("ID_OF_MODEL_TRAINED_WITHOUT_LABELS", unlabeled_model_id)
 
         path_to_sample_forms = os.path.abspath(os.path.join(os.path.abspath(__file__), "..", "..", "./sample_forms/forms/Form_1.jpg"))
         async with FormRecognizerClient(
@@ -120,7 +127,34 @@ async def recognize_custom_forms(self):
 
 async def main():
     sample = DifferentiateOutputModelsTrainedWithAndWithoutLabelsSampleAsync()
-    await sample.recognize_custom_forms()
+    labeled_model_id = None
+    unlabeled_model_id = None
+    if os.getenv("CONTAINER_SAS_URL_WITH_LABELS") or os.getenv("CONTAINER_SAS_URL_WITHOUT_LABELS"):
+
+        from azure.core.credentials import AzureKeyCredential
+        from azure.ai.formrecognizer.aio import FormTrainingClient
+
+        endpoint = os.getenv("AZURE_FORM_RECOGNIZER_ENDPOINT")
+        key = os.getenv("AZURE_FORM_RECOGNIZER_KEY")
+        labeled = os.getenv("CONTAINER_SAS_URL_WITH_LABELS")
+        unlabeled = os.getenv("CONTAINER_SAS_URL_WITHOUT_LABELS")
+
+        if not endpoint or not key:
+            raise ValueError("Please provide endpoint and API key to run the samples.")
+
+        form_training_client = FormTrainingClient(
+            endpoint=endpoint, credential=AzureKeyCredential(key)
+        )
+
+        async with form_training_client:
+            if labeled:
+                model = await (await form_training_client.begin_training(labeled, use_training_labels=True)).result()
+                labeled_model_id = model.model_id
+            if unlabeled:
+                model = await (await form_training_client.begin_training(unlabeled, use_training_labels=False)).result()
+                unlabeled_model_id = model.model_id
+
+    await sample.recognize_custom_forms(labeled_model_id, unlabeled_model_id)
 
 
 if __name__ == '__main__':

sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_get_bounding_boxes_async.py

@@ -12,13 +12,20 @@
 DESCRIPTION:
     This sample demonstrates how to get detailed information to visualize the outlines of
     form content and fields, which can be used for manual validation and drawing UI as part of an application.
+
+    The model used in this sample can be created in the sample_train_model_without_labels_async.py using the
+    training files in https://aka.ms/azsdk/formrecognizer/sampletrainingfiles
+
 USAGE:
     python sample_get_bounding_boxes_async.py
 
     Set the environment variables with your own values before running the sample:
     1) AZURE_FORM_RECOGNIZER_ENDPOINT - the endpoint to your Cognitive Services resource.
     2) AZURE_FORM_RECOGNIZER_KEY - your Form Recognizer API key
     3) CUSTOM_TRAINED_MODEL_ID - the ID of your custom trained model
+        -OR-
+       CONTAINER_SAS_URL - The shared access signature (SAS) Url of your Azure Blob Storage container with your forms.
+       A model will be trained and used to run the sample.
 """
 
 import os
@@ -35,13 +42,13 @@ def format_bounding_box(bounding_box):
 
 class GetBoundingBoxesSampleAsync(object):
 
-    async def get_bounding_boxes(self):
+    async def get_bounding_boxes(self, custom_model_id):
         from azure.core.credentials import AzureKeyCredential
         from azure.ai.formrecognizer.aio import FormRecognizerClient
 
         endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
         key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
-        model_id = os.environ["CUSTOM_TRAINED_MODEL_ID"]
+        model_id = os.getenv("CUSTOM_TRAINED_MODEL_ID", custom_model_id)
 
         form_recognizer_client = FormRecognizerClient(
             endpoint=endpoint, credential=AzureKeyCredential(key)
@@ -115,7 +122,26 @@ async def get_bounding_boxes(self):
 
 async def main():
     sample = GetBoundingBoxesSampleAsync()
-    await sample.get_bounding_boxes()
+    model_id = None
+    if os.getenv("CONTAINER_SAS_URL"):
+
+        from azure.core.credentials import AzureKeyCredential
+        from azure.ai.formrecognizer.aio import FormTrainingClient
+
+        endpoint = os.getenv("AZURE_FORM_RECOGNIZER_ENDPOINT")
+        key = os.getenv("AZURE_FORM_RECOGNIZER_KEY")
+
+        if not endpoint or not key:
+            raise ValueError("Please provide endpoint and API key to run the samples.")
+
+        form_training_client = FormTrainingClient(
+            endpoint=endpoint, credential=AzureKeyCredential(key)
+        )
+        async with form_training_client:
+            model = await (await form_training_client.begin_training(
+                os.getenv("CONTAINER_SAS_URL"), use_training_labels=False)).result()
+            model_id = model.model_id
+    await sample.get_bounding_boxes(model_id)
 
 
 if __name__ == '__main__':