Edit field extraction sample for clarity. Remove enable_face_identification flag. (#5)

bojunehsu · web-flow · commit 4dc1e8051738 · 2024-12-09T14:12:03.000-08:00
diff --git a/README.md b/README.md
@@ -35,7 +35,7 @@ You can run this repo virtually by using GitHub Codespaces, which will open a we
 
 Navigate to the `notebooks` directory and select the sample notebook you are interested in. Since Codespaces is pre-configured with the necessary environment, you can directly execute each step in the notebook.
 
-### Notes
+## Notes
 
 * **Trademarks** - This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third-party’s policies.
 
diff --git a/notebooks/field_extraction.ipynb b/notebooks/field_extraction.ipynb
@@ -4,23 +4,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Extract custom fields in your file"
+    "# Extract Custom Fields from Your File"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This notebook demonstrates how to use analyzers to extract custom fields from your input file."
+    "This notebook demonstrates how to use analyzers to extract custom fields from your input files."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Prerequisites\n",
-    "1. Follow steps in [README](../README.md#Configure-Azure-AI-Service-resource) to create `.env` file to configure your Azure AI Service.\n",
-    "1. Install packages needed to run the sample"
+    "1. Follow the steps in the [README](../README.md#Configure-Azure-AI-Service-resource) to create a `.env` file and configure your Azure AI Service.\n",
+    "2. Install the required packages to run the sample."
    ]
   },
   {
@@ -36,59 +36,65 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Analyzer template examples"
+    "## Analyzer Templates"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Below is a collection of analyzer template examples designed to extract fields from various input file types.\n",
+    "Below is a collection of analyzer templates designed to extract fields from various input file types.\n",
     "\n",
-    "These templates are highly customizable, allowing you to modify them to suit your specific needs. For additional verified templates from Microsoft, please visit [HERE](../analyzer_templates/README.md)."
+    "These templates are highly customizable, allowing you to modify them to suit your specific needs. For additional verified templates from Microsoft, please visit [here](../analyzer_templates/README.md)."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "extraction_samples = {\n",
-    "    \"sample_invoice\": ('../analyzer_templates/invoice.json', '../data/invoice.pdf'),\n",
-    "    \"sample_chart\": ('../analyzer_templates/image_chart.json', '../data/pieChart.jpg'),\n",
-    "    \"sample_call_transcript\": ('../analyzer_templates/call_transcript.json', '../data/callCenterRecording.mp3'),\n",
-    "    \"sample_marketing_video\": ('../analyzer_templates/marketing_video.json', '../data/video.mp4')\n",
+    "extraction_templates = {\n",
+    "    \"invoice\":         ('../analyzer_templates/invoice.json',         '../data/invoice.pdf'            ),\n",
+    "    \"chart\":           ('../analyzer_templates/image_chart.json',     '../data/pieChart.jpg'           ),\n",
+    "    \"call_transcript\": ('../analyzer_templates/call_transcript.json', '../data/callCenterRecording.mp3'),\n",
+    "    \"marketing_video\": ('../analyzer_templates/marketing_video.json', '../data/video.mp4'              )\n",
     "}"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Set the target to the sample analyzer that you want to try."
+    "Specify the analyzer template you want to use and provide a name for the analyzer to be created based on the template."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "target_sample = \"sample_invoice\""
+    "import uuid\n",
+    "\n",
+    "ANALYZER_TEMPLATE = \"invoice\"\n",
+    "ANALYZER_ID = \"field-extraction-sample-\" + str(uuid.uuid4())\n",
+    "\n",
+    "(analyzer_template_path, analyzer_sample_file_path) = extraction_templates[ANALYZER_TEMPLATE]"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Create Azure content understanding client\n",
-    ">The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is utility Class which contain the functions to interact with the Content Understanding server. Before Content Understanding SDK release, we can regard it as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service."
+    "## Create Azure AI Content Understanding Client\n",
+    "\n",
+    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK.\n"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -98,19 +104,22 @@
     "import sys\n",
     "from dotenv import find_dotenv, load_dotenv\n",
     "\n",
-    "# import utility package from python samples root directory\n",
+    "load_dotenv(find_dotenv())\n",
+    "logging.basicConfig(level=logging.INFO)\n",
+    "\n",
+    "AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n",
+    "AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n",
+    "AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2024-12-01-preview\")\n",
+    "\n",
+    "# Import utility package from python samples root directory\n",
     "py_samples_root_dir = os.path.abspath(os.path.join(os.getcwd(), \"..\"))\n",
     "sys.path.append(py_samples_root_dir)\n",
     "from python.content_understanding_client import AzureContentUnderstandingClient\n",
     "\n",
-    "load_dotenv(find_dotenv())\n",
-    "logging.basicConfig(level=logging.INFO)\n",
-    "\n",
     "client = AzureContentUnderstandingClient(\n",
-    "    endpoint=os.getenv(\"AZURE_AI_ENDPOINT\"),\n",
-    "    api_version=os.getenv(\"AZURE_AI_API_VERSION\", \"2024-12-01-preview\"),\n",
-    "    subscription_key=os.getenv(\"AZURE_AI_API_KEY\"),\n",
-    "    api_token=os.getenv(\"AZURE_AI_API_TOKEN\"),\n",
+    "    endpoint=AZURE_AI_ENDPOINT,\n",
+    "    subscription_key=AZURE_AI_API_KEY,\n",
+    "    api_version=AZURE_AI_API_VERSION,\n",
     "    x_ms_useragent=\"azure-ai-content-understanding-python/field_extraction\",\n",
     ")"
    ]
@@ -119,13 +128,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Create analyzer with defined schema\n",
-    "Before creating the custom fields analyzer, you should fill the constant ANALYZER_ID with a business-related name. Here we randomly generate a name for demo purpose."
+    "## Create Analyzer from the Template"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -188,20 +196,17 @@
     }
    ],
    "source": [
-    "import uuid\n",
-    "ANALYZER_ID = \"extraction-sample-\" + str(uuid.uuid4())\n",
-    "\n",
-    "response = client.begin_create_analyzer(ANALYZER_ID, analyzer_schema_path=extraction_samples[target_sample][0])\n",
+    "response = client.begin_create_analyzer(ANALYZER_ID, analyzer_template_path)\n",
     "result = client.poll_result(response)\n",
     "\n",
-    "logging.info(json.dumps(result, indent=2))"
+    "print(json.dumps(result, indent=2))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Use created analyzer to extract document content\n"
+    "## Extract Fields Using the Analyzer"
    ]
   },
   {
@@ -213,7 +218,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -362,19 +367,18 @@
     }
    ],
    "source": [
-    "response = client.begin_analyze(ANALYZER_ID, file_location=extraction_samples[target_sample][1])\n",
+    "response = client.begin_analyze(ANALYZER_ID, file_location=analyzer_sample_file_path)\n",
     "result = client.poll_result(response)\n",
     "\n",
-    "logging.info(json.dumps(result, indent=2))"
+    "json.dumps(result, indent=2)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Delete exist analyzer in Content Understanding Service\n",
-    "This snippet is not required, but it's only used to prevent the testing analyzer from residing in your service. The custom fields analyzer could be stored in your service for reusing by subsequent business in real usage scenarios.\n",
-    "\n"
+    "## Clean Up\n",
+    "Optionally, delete the sample analyzer from your resource. In typical usage scenarios, you would analyze multiple files using the same analyzer."
    ]
   },
   {
diff --git a/python/content_understanding_client.py b/python/content_understanding_client.py
@@ -12,7 +12,6 @@ def __init__(self,
                  api_version: str,
                  subscription_key: str = None,
                  api_token: str = None,
-                 enable_face_identification: bool = False,
                  x_ms_useragent: str = "cu-sample-code"):
         if not subscription_key and not api_token:
             raise ValueError(
@@ -25,8 +24,7 @@ def __init__(self,
         self._endpoint = endpoint.rstrip("/")
         self._api_version = api_version
         self._logger = logging.getLogger(__name__)
-        self._headers = self._get_headers(subscription_key, api_token,
-                                          enable_face_identification, x_ms_useragent)
+        self._headers = self._get_headers(subscription_key, api_token, x_ms_useragent)
 
     def _get_analyzer_url(self, endpoint, api_version, analyzer_id):
         return f"{endpoint}/contentunderstanding/analyzers/{analyzer_id}?api-version={api_version}"  # noqa
@@ -45,8 +43,7 @@ def _get_training_data_config(self, storage_container_sas_url,
             "prefix": storage_container_path_prefix,
         }
 
-    def _get_headers(self, subscription_key, api_token,
-                     enable_face_identification, x_ms_useragent):
+    def _get_headers(self, subscription_key, api_token, x_ms_useragent):
         """ Returns the headers for the HTTP requests. 
         Args:
             subscription_key (str): The subscription key for the service.
@@ -61,8 +58,6 @@ def _get_headers(self, subscription_key, api_token,
             "Authorization": f"Bearer {api_token}"
         }
         headers["x-ms-useragent"] = x_ms_useragent
-        if enable_face_identification:
-            headers["cogsvc-videoanalysis-face-identification-enable"] = "true"
         return headers
 
     def get_all_analyzers(self):
