Improve Segmentation Description and Adjust Timeout (#104)

Author: chienyuanchang

notebooks/build_person_directory.ipynb

@@ -22,6 +22,26 @@
     "| ![PD_enrollment.png](https://media.githubusercontent.com/media/Azure-Samples/azure-ai-content-understanding-python/refs/heads/zhizho/face/data/face/PD_enrollment.png) | ![PD_searching.png](https://media.githubusercontent.com/media/Azure-Samples/azure-ai-content-understanding-python/refs/heads/zhizho/face/data/face/PD_searching.png) |"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "3f0b1227",
+   "metadata": {},
+   "source": [
+    "## Prerequisites\n",
+    "1. Please ensure your Azure AI service is configured by following the [configuration steps](../README.md#configure-azure-ai-service-resource).\n",
+    "2. Please install the required packages to run this sample."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "08b48760",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install -r ../requirements.txt"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "80a375ca",

notebooks/field_extraction.ipynb

@@ -20,7 +20,7 @@
    "source": [
     "## Prerequisites\n",
     "1. Please ensure your Azure AI service is configured by following the [configuration steps](../README.md#configure-azure-ai-service-resource).\n",
-    "2. Install the required packages to run this sample."
+    "2. Please install the required packages to run this sample."
    ]
   },
   {
@@ -38,12 +38,12 @@
    "source": [
     "## Create Azure AI Content Understanding Client\n",
     "\n",
-    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class providing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it acts as a lightweight SDK. Please fill in the constants **AZURE_AI_ENDPOINT** and **AZURE_AI_API_VERSION** with your Azure AI Service information. Optionally, you may provide **AZURE_AI_API_KEY** if your setup requires key-based authentication.\n",
+    "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class providing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, this acts as a lightweight SDK. Please fill in the constants **AZURE_AI_ENDPOINT** and **AZURE_AI_API_VERSION** with your Azure AI Service information. Optionally, you may provide **AZURE_AI_API_KEY** if your setup requires key-based authentication.\n",
     "\n",
     "> ⚠️ Important:\n",
     "Please update the code below to match your Azure authentication method.\n",
     "Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
-    "Skipping this step may cause the sample to not run correctly.\n",
+    "Skipping this step may prevent the sample from running correctly.\n",
     "\n",
     "> ⚠️ Note: Using a subscription key works, but using a token provider with Azure Active Directory (AAD) is safer and highly recommended for production environments."
    ]
@@ -105,11 +105,11 @@
     "This notebook demonstrates field extraction across multiple modalities using Azure AI Content Understanding. We will walk through each modality step-by-step:\n",
     "\n",
     "1. **Document Analysis** - Extract fields from invoices and receipts\n",
-    "2. **Audio Analysis** - Process call recordings and conversational audio  \n",
+    "2. **Audio Analysis** - Process call recordings and conversational audio\n",
     "3. **Video Analysis** - Analyze marketing videos and extract insights\n",
     "4. **Image Analysis** - Extract information from charts and images\n",
     "\n",
-    "Each section will create an analyzer, process sample data, display results, and clean up the analyzer before moving on to the next modality."
+    "Each section will create an analyzer, process sample data, display results, and clean up the analyzer before moving to the next modality."
    ]
   },
   {
@@ -122,7 +122,7 @@
     "\n",
     "**Key Schema Components:**\n",
     "\n",
-    "- **`baseAnalyzerId`**: Crucial setting that specifies the prebuilt analyzer to derive from (e.g., `prebuilt-documentAnalyzer`, `prebuilt-audioAnalyzer`, `prebuilt-videoAnalyzer`, `prebuilt-imageAnalyzer`, `prebuilt-callCenter`). This provides foundational capabilities for your custom analyzer.\n",
+    "- **`baseAnalyzerId`**: Crucial setting specifying the prebuilt analyzer to derive from (e.g., `prebuilt-documentAnalyzer`, `prebuilt-audioAnalyzer`, `prebuilt-videoAnalyzer`, `prebuilt-imageAnalyzer`, `prebuilt-callCenter`). This provides foundational capabilities for your custom analyzer.\n",
     "\n",
     "- **`fields`**: Defines specific data points to extract. Each field includes:\n",
     "  - **Field name**: Identifier for the extracted data (required and important for referencing results)\n",
@@ -256,7 +256,7 @@
    "source": [
     "**Clean Up Invoice Analyzer**\n",
     "\n",
-    "Optionally clean up the analyzer to manage resources (in production, analyzers are typically kept for reuse):"
+    "Optionally, clean up the analyzer to manage resources (typically, analyzers are kept for reuse in production):"
    ]
   },
   {
@@ -276,7 +276,7 @@
     "\n",
     "Now, let's analyze the same invoice but with enhanced field source information and confidence scores. This provides additional context about the location of each extracted field within the document.\n",
     "\n",
-    "**Note**: This custom analyzer is for demonstration purposes only. In production, please start from `prebuilt-invoice` for invoice processing.\n",
+    "**Note**: This custom analyzer is for demonstration purposes only. For production, please start from `prebuilt-invoice` for invoice processing.\n",
     "\n",
     "**Key Feature**: This analyzer template uses `estimateFieldSourceAndConfidence: true` in the 'config', enabling the service to provide detailed information about:\n",
     "- **Field source locations**: Exact coordinates and bounding boxes indicating where each field was found\n",
@@ -350,7 +350,7 @@
    "source": [
     "**Clean Up Invoice Field Source Analyzer**\n",
     "\n",
-    "Optionally clean up the field source analyzer:"
+    "Optionally, clean up the field source analyzer:"
    ]
   },
   {
@@ -439,7 +439,7 @@
    "source": [
     "**Clean Up Receipt Analyzer**\n",
     "\n",
-    "Optionally clean up the receipt analyzer:"
+    "Optionally, clean up the receipt analyzer:"
    ]
   },
   {
@@ -552,7 +552,7 @@
    "source": [
     "## 5. Conversational Audio Analytics\n",
     "\n",
-    "Let's analyze the same audio file with a focus on conversational aspects like sentiment analysis and dialogue understanding.\n",
+    "Let's analyze the same audio file focusing on conversational aspects such as sentiment analysis and dialogue understanding.\n",
     "\n",
     "Conversational audio analytics template:"
    ]
@@ -645,23 +645,25 @@
    "source": [
     "## 6. Marketing Video Analysis\n",
     "\n",
-    "Let's analyze a marketing video to extract descriptions, sentiment, and key insights that could be valuable for content understanding and marketing analytics.\n",
+    "Let's analyze a marketing video to extract descriptions, sentiment, and key insights valuable for content understanding and marketing analytics.\n",
     "\n",
     "Content Understanding offers three segmentation options to slice a video, enabling you to get output for entire videos or short clips. You can specify these by setting the `segmentationMode` property in your custom analyzer:\n",
-    "- Whole-video – `\"segmentationMode\": \"noSegmentation\"`  \n",
-    "  The service treats the entire video file as a single segment and extracts metadata across its full duration.  \n",
+    "- Whole-video – `\"segmentationMode\": \"noSegmentation\"`\n",
+    "  The service treats the entire video file as a single segment and extracts metadata across its full duration.\n",
     "  Examples:\n",
     "    - Compliance checks looking for specific brand-safety issues anywhere in an ad\n",
     "    - Full-length descriptive summaries\n",
-    "- Automatic segmentation – `\"segmentationMode\": \"auto\"`  \n",
-    "  The service analyzes the timeline, automatically segmenting the video. It groups successive shots into coherent scenes, capped at one minute each.  \n",
+    "- Automatic segmentation – `\"segmentationMode\": \"auto\"`\n",
+    "  The service analyzes the timeline, automatically segmenting the video. It groups successive shots into coherent scenes, capped at one minute each.\n",
     "  Examples:\n",
     "    - Creating storyboards from a show\n",
     "    - Inserting mid-roll ads at logical pauses\n",
-    "- Custom segmentation – `\"segmentationMode\": \"custom\"`  \n",
-    "  You describe the segmentation logic in natural language, and the model creates segments accordingly. Set `segmentationDefinition` with a string describing your desired segmentation. Custom segmentation allows segments of varying length from seconds to minutes.  \n",
+    "- Custom segmentation – `\"segmentationMode\": \"custom\"`\n",
+    "  You describe the segmentation logic in natural language, and the model creates segments accordingly. Set `segmentationDefinition` with a string describing your desired segmentation. Custom segmentation allows segments of varying length from seconds to minutes.\n",
     "  Example:\n",
-    "    - Breaking a news broadcast into distinct stories"
+    "    - Breaking a news broadcast into distinct stories\n",
+    "\n",
+    "> Important: The defined fields for segment analysis must be declared under `fieldSchema` → `fields` → `Segments` when setting `\"segmentationMode\"` as `\"auto\"` or `\"custom\"`. We will use the same set of fields for each video segment. You won't be able to create the analyzer successfully if other fields are set under `fieldSchema` → `fields`. In other words, whole video analysis cannot be combined with segment analysis."
    ]
   },
   {
@@ -754,9 +756,9 @@
    "source": [
     "### 6-2 Analyze With Automatic Segmentation\n",
     "\n",
-    "In this example, we use automatic segmentation for marketing video analytics.  \n",
+    "In this example, we use automatic segmentation for marketing video analytics.\n",
     "- Please set `segmentationMode` to `auto` in the analyzer schema `config` to enable automatic segmentation.\n",
-    "- The defined fields for segment analysis must be declared under `fieldSchema` → `Segments`."
+    "- The defined fields for segment analysis must be declared under `fieldSchema` → `fields` → `Segments`."
    ]
   },
   {
@@ -803,7 +805,7 @@
    "metadata": {},
    "source": [
     "Marketing video analysis result:\n",
-    "- The output includes automatically segmented clips with descriptions in the markdown content.  \n",
+    "- The output includes automatically segmented clips with descriptions in the markdown content.\n",
     "- The analyzer generates the fields defined in the schema separately for each segment."
    ]
   },
@@ -840,10 +842,10 @@
    "source": [
     "### 6-3 Analyze With Custom Segmentation\n",
     "\n",
-    "In this example, we use custom segmentation for marketing video analytics.  \n",
-    "- Please set `segmentationMode` to `custom`.  \n",
+    "In this example, we use custom segmentation for marketing video analytics.\n",
+    "- Please set `segmentationMode` to `custom`.\n",
     "- Provide a `segmentationDefinition` string describing how you'd like the video to be segmented.\n",
-    "- The defined fields for segment analysis must be declared under `fieldSchema` → `Segments`."
+    "- The defined fields for segment analysis must be declared under `fieldSchema` → `fields` → `Segments`."
    ]
   },
   {
@@ -890,8 +892,8 @@
    "metadata": {},
    "source": [
     "Marketing video analysis result:\n",
-    "- The video is segmented according to your custom definition, with segment descriptions included in the markdown content.  \n",
-    "- The segmentation may differ from automatic segmentation results.  \n",
+    "- The video is segmented according to your custom definition, with segment descriptions included in the markdown content.\n",
+    "- The segmentation may differ from automatic segmentation results.\n",
     "- The analyzer generates the fields defined in the schema separately for each segment."
    ]
   },
@@ -1021,9 +1023,9 @@
     "\n",
     "🎉 **Congratulations!** You have successfully explored all the major modalities of Azure AI Content Understanding:\n",
     "\n",
-    "✅ **Document Analysis**: Extracted fields from invoices and receipts  \n",
-    "✅ **Audio Analysis**: Analyzed call recordings and conversational audio  \n",
-    "✅ **Video Analysis**: Processed marketing videos for insights  \n",
+    "✅ **Document Analysis**: Extracted fields from invoices and receipts\n",
+    "✅ **Audio Analysis**: Analyzed call recordings and conversational audio\n",
+    "✅ **Video Analysis**: Processed marketing videos for insights\n",
     "✅ **Image Analysis**: Extracted information from charts and visual content\n",
     "\n",
     "## Key Takeaways\n",
@@ -1058,9 +1060,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.13"
+   "version": "3.11.12"
   }
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

python/content_understanding_client.py

@@ -20,7 +20,7 @@
 from azure.storage.blob.aio import ContainerClient
 
 
-POLL_TIMEOUT_SECONDS = 120
+POLL_TIMEOUT_SECONDS = 180
 
 
 @dataclass

tools/test_notebooks/test_notebooks.py

@@ -98,9 +98,9 @@ def run_all_notebooks(
 if __name__ == "__main__":
     args: List[str] = sys.argv[1:]
 
-    # NOTE: Define skip list (can use full paths or substrings)
+    # NOTE: Define skip list (can use full paths or substrings, e.g., "notebook_name.ipynb")
     skip_list = [
-        "build_person_directory.ipynb",  # Skip due to "new_face_image_path" needed to be added manually
+        "build_person_directory.ipynb",  # Skip due to face API limit wasn't lifted
     ]
 
     if not args: