diff --git a/notebooks/field_extraction.ipynb b/notebooks/field_extraction.ipynb index d9bf936..f76d462 100644 --- a/notebooks/field_extraction.ipynb +++ b/notebooks/field_extraction.ipynb @@ -19,8 +19,8 @@ "metadata": {}, "source": [ "## Prerequisites\n", - "1. Ensure Azure AI service is configured following [steps](../README.md#configure-azure-ai-service-resource)\n", - "2. Install the required packages to run the sample." + "1. Ensure the 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." ] }, { @@ -38,14 +38,14 @@ "source": [ "## 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. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service.\n", + "> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class providing functions to interact with the Content Understanding API. Prior to the official release of the Content Understanding SDK, it serves as a lightweight SDK. Fill in the constants **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, and **AZURE_AI_API_KEY** with your Azure AI Service credentials.\n", "\n", "> ⚠️ Important:\n", - "You must update the code below to match your Azure authentication method.\n", - "Look for the `# IMPORTANT` comments and modify those sections accordingly.\n", - "If you skip this step, the sample may not run correctly.\n", + "Update the sections below to match your Azure authentication method.\n", + "Look for the `# IMPORTANT` comments and modify those parts accordingly.\n", + "Skipping this step may cause the sample to fail.\n", "\n", - "> ⚠️ Note: Using a subscription key works, but using a token provider with Azure Active Directory (AAD) is much safer and is highly recommended for production environments." + "> ⚠️ Note: Using a subscription key works, but using a token provider with Azure Active Directory (AAD) is more secure and highly recommended for production environments." ] }, { @@ -65,9 +65,9 @@ "load_dotenv(find_dotenv())\n", "logging.basicConfig(level=logging.INFO)\n", "\n", - "# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n", + "# For authentication, you can use either token-based auth or subscription key; only one is required\n", "AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n", - "# IMPORTANT: Replace with your actual subscription key or set up in \".env\" file if not using token auth\n", + "# IMPORTANT: Replace with your actual subscription key or set it in your \".env\" file if not using token auth\n", "AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n", "AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\")\n", "\n", @@ -86,7 +86,7 @@ " token_provider=token_provider,\n", " # IMPORTANT: Uncomment this if using subscription key\n", " # subscription_key=AZURE_AI_API_KEY,\n", - " x_ms_useragent=\"azure-ai-content-understanding-python/field_extraction\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n", + " x_ms_useragent=\"azure-ai-content-understanding-python/field_extraction\", # This header is used for sample usage telemetry; comment out this line if you want to opt out.\n", ")" ] }, @@ -104,11 +104,11 @@ "This notebook demonstrates field extraction across multiple modalities using Azure AI Content Understanding. We'll 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 conversation 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 to the next modality." + "Each section will create an analyzer, process sample data, display results, and clean up the analyzer before moving on to the next modality." ] }, { @@ -117,29 +117,29 @@ "source": [ "### Understanding Analyzer Templates and Schemas\n", "\n", - "Before we create our first analyzer, it's important to understand the structure and schema of analyzer templates. Custom analyzers in Azure AI Content Understanding are defined using JSON templates that specify what fields to extract and how to process the content.\n", + "Before creating our first analyzer, it's important to understand the structure and schema of analyzer templates. Custom analyzers in Azure AI Content Understanding are defined using JSON templates that specify which fields to extract and how to process the content.\n", "\n", "**Key Schema Components:**\n", "\n", - "- **`baseAnalyzerId`**: This is crucial as it specifies which prebuilt analyzer to derive from (e.g., `prebuilt-documentAnalyzer`, `prebuilt-audioAnalyzer`, `prebuilt-videoAnalyzer`, `prebuilt-imageAnalyzer`, `prebuilt-callCenter`). This provides the foundation capabilities for your custom analyzer.\n", + "- **`baseAnalyzerId`**: Specifies which 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`**: Define the specific data points you want to extract. Each field has:\n", - " - **Field name**: The identifier for the extracted data (required and important for referencing results)\n", - " - **Description**: Optional but helpful for documentation and understanding the field's purpose\n", - " - **Method**: Can be `\"extract\"` (for extracting existing information from documents - currently only available for document analysis) or `\"generate\"` (for generating new insights using AI)\n", + "- **`fields`**: Define specific data points to extract. Each field has:\n", + " - **Field name**: The identifier for the extracted data (required and important for referencing results).\n", + " - **Description**: Optional but helpful for documentation and understanding the field's purpose.\n", + " - **Method**: `\"extract\"` (for extracting existing information from documents - currently available only for document analysis) or `\"generate\"` (for generating new insights using AI).\n", "\n", - "- **`method`**: The overall extraction approach - use `\"extract\"` for standard field extraction from documents or `\"generate\"` when you need AI to generate insights or summaries.\n", + "- **`method`**: The overall extraction approach - use `\"extract\"` for standard field extraction from documents or `\"generate\"` when leveraging AI to generate insights or summaries.\n", "\n", - "**Important Note**: The `\"extract\"` method is currently only available for document analysis (using `prebuilt-documentAnalyzer`). For other modalities like audio, video, and images, use the `\"generate\"` method.\n", + "**Important Note:** The `\"extract\"` method is currently supported only for document analysis (`prebuilt-documentAnalyzer`). For audio, video, and image modalities, use the `\"generate\"` method.\n", "\n", - "Let's examine the invoice template to see these concepts in action:" + "Let's take a look at the invoice template to see these concepts in action:" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "The following is the schema for document modality used to extract fields from an invoice PDF. This analyzer identifies key invoice elements such as vendor information, amounts, dates, and line items." + "The following is the schema for the document modality used to extract fields from an invoice PDF. This analyzer identifies key invoice elements such as vendor information, amounts, dates, and line items." ] }, { @@ -160,7 +160,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Below is an example schema for the video modality." + "Below is an example of the schema for the video modality." ] }, { @@ -181,7 +181,7 @@ "source": [ "# Document Analysis\n", "\n", - "Let's start with document analysis by extracting fields from invoices and receipts. This modality is excellent for processing structured documents and extracting key information like amounts, dates, vendor details, and line items." + "Let's begin with document analysis by extracting fields from invoices and receipts. This modality is ideal for processing structured documents and extracting key information like amounts, dates, vendor details, and line items." ] }, { @@ -190,7 +190,7 @@ "source": [ "## 1. Invoice Field Extraction\n", "\n", - "Let's extract fields from an invoice PDF. This analyzer identifies essential invoice elements such as vendor information, amounts, dates, and line items." + "Extract fields from an invoice PDF. This analyzer detects essential invoice elements such as vendor information, amounts, dates, and line items." ] }, { @@ -211,7 +211,7 @@ "source": [ "**Create and Run Invoice Analyzer**\n", "\n", - "Now let's create the invoice analyzer and process our sample invoice:" + "Now, let's create the invoice analyzer and process our sample invoice:" ] }, { @@ -257,7 +257,7 @@ "source": [ "**Clean Up Invoice Analyzer**\n", "\n", - "Clean up the analyzer to manage resources (in production, you would typically keep analyzers for reuse):" + "Clean up the analyzer to manage resources. In production, you would typically keep analyzers for reuse." ] }, { @@ -275,16 +275,16 @@ "source": [ "## 2. Invoice Field Extraction with Source Grounding\n", "\n", - "Now let's analyze the same invoice but with enhanced field source information and confidence scores. This provides additional context about where each extracted field was found in the document.\n", + "Now, let's analyze the same invoice with enhanced field source information and confidence scores. This provides additional context about where each extracted field was found in the document.\n", "\n", - "**Note**: This custom analyzer is for demo purposes only. In production, users should start from `prebuilt-invoice` for invoice processing.\n", + "**Note**: This custom analyzer is for demonstration purposes only. In production, users should start from `prebuilt-invoice` for invoice processing.\n", "\n", - "**Key Feature**: This analyzer template uses `estimateFieldSourceAndConfidence: true` in the 'config', which enables the service to provide detailed information about:\n", + "**Key Feature**: This analyzer template uses `estimateFieldSourceAndConfidence: true` in the configuration, which enables the service to provide detailed information about:\n", "- **Field source locations**: Exact coordinates and bounding boxes where each field was found\n", - "- **Confidence scores**: How confident the service is about each extracted field\n", + "- **Confidence scores**: The confidence level for each extracted field\n", "- **Enhanced metadata**: Additional context about the extraction process\n", "\n", - "This is particularly useful for applications that need to verify extraction accuracy or provide visual feedback about where information was found in the source document." + "This is particularly beneficial for applications that need to verify extraction accuracy or provide visual feedback indicating where information was sourced in the document." ] }, { @@ -305,7 +305,7 @@ "source": [ "**Create and Run Invoice Field Source Analyzer**\n", "\n", - "Now let's create the enhanced analyzer and process the invoice with source grounding:" + "Let's create the enhanced analyzer and process the invoice with source grounding:" ] }, { @@ -333,7 +333,7 @@ "source": [ "**Invoice Field Source Analysis Results**\n", "\n", - "Let's review the enhanced results, which include detailed field source locations and confidence scores. Pay special attention to the `confidence` and `source` attributes for each extracted field. The `source` attribute provides the page number and bounding box coordinates for the extracted data, offering precise context for verification and visualization." + "Review the enhanced results, which include detailed field source locations and confidence scores. Pay special attention to the `confidence` and `source` attributes for each extracted field. The `source` attribute specifies the page number and bounding box coordinates, offering precise context for verification and visualization." ] }, { @@ -369,7 +369,7 @@ "source": [ "## 3. Receipt Field Extraction\n", "\n", - "Let's extract information from a receipt image. This demonstrates how the same Content Understanding service can handle different document types and formats.\n", + "Extract information from a receipt image. This demonstrates how the Content Understanding service can handle different document types and formats.\n", "\n", "**Receipt Analyzer Template**\n", "\n", @@ -394,7 +394,7 @@ "source": [ "**Create and Run Receipt Analyzer**\n", "\n", - "Now let's create the receipt analyzer and process our sample receipt:" + "Now, let's create the receipt analyzer and process our sample receipt:" ] }, { @@ -458,7 +458,7 @@ "source": [ "# Audio Analysis\n", "\n", - "Now let's move to audio analysis. This modality allows us to extract insights from audio files such as call recordings, including summaries, sentiment analysis, topic identification, and entity extraction." + "Now, let's move on to audio analysis. This modality allows extraction of insights from audio files such as call recordings, including summaries, sentiment analysis, topic identification, and entity extraction." ] }, { @@ -467,7 +467,7 @@ "source": [ "## 4. Call Recording Analytics\n", "\n", - "Let's analyze a call center recording to extract insights such as summary, topics discussed, mentioned companies, and people involved in the conversation.\n", + "Analyze a call center recording to extract insights such as summary, topics discussed, companies mentioned, and people involved in the conversation.\n", "\n", "**Call Recording Analytics Template**\n", "\n", @@ -490,7 +490,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Create and run call recording analyzer" + "Create and run the call recording analyzer." ] }, { @@ -533,9 +533,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Clean up call recording analyzer\n", + "Clean up call recording analyzer.\n", "\n", - "Note: In production environments, you would typically keep analyzers for reuse rather than deleting them" + "Note: In production environments, you would typically keep analyzers for reuse rather than deleting them." ] }, { @@ -553,7 +553,7 @@ "source": [ "## 5. Conversational Audio Analytics\n", "\n", - "Let's analyze the same audio file but with a focus on conversational aspects like sentiment analysis and dialogue understanding.\n", + "Analyze the same audio file focusing on conversational aspects like sentiment analysis and dialogue understanding.\n", "\n", "Conversational audio analytics template:" ] @@ -574,7 +574,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Create and run conversational audio analyzer." + "Create and run the conversational audio analyzer." ] }, { @@ -617,9 +617,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Clean up conversational audio analyzer\n", + "Clean up conversational audio analyzer.\n", "\n", - "Note: In production environments, you would typically keep analyzers for reuse rather than deleting them" + "Note: In production environments, you would typically keep analyzers for reuse rather than deleting them." ] }, { @@ -637,7 +637,7 @@ "source": [ "# Video Analysis\n", "\n", - "Now let's explore video analysis capabilities. This modality can extract insights from video content including descriptions, sentiment analysis, and key scene identification." + "Explore video analysis capabilities. This modality extracts insights from video content including descriptions, sentiment analysis, and key scene identification." ] }, { @@ -646,7 +646,7 @@ "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", + "Analyze a marketing video to extract descriptions, sentiment, and key insights valuable for content understanding and marketing analytics.\n", "\n", "Marketing video analytics template:" ] @@ -667,7 +667,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Create and run marketing video analyzer" + "Create and run the marketing video analyzer." ] }, { @@ -704,9 +704,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Clean up marketing video analyzer\n", + "Clean up marketing video analyzer.\n", "\n", - "Note: In production environments, you would typically keep analyzers for reuse rather than deleting them" + "Note: In production environments, you would typically keep analyzers for reuse rather than deleting them." ] }, { @@ -724,7 +724,7 @@ "source": [ "# Image Analysis\n", "\n", - "Finally, let's explore image analysis capabilities. This modality can extract information from charts, diagrams, and other visual content." + "Finally, explore image analysis capabilities. This modality extracts information from charts, diagrams, and other visual content." ] }, { @@ -733,7 +733,7 @@ "source": [ "## 7. Chart and Image Analysis\n", "\n", - "Let's analyze a chart image to extract data points, trends, and insights from visual data representations." + "Analyze a chart image to extract data points, trends, and insights from visual data representations." ] }, { @@ -792,26 +792,26 @@ "source": [ "# Summary\n", "\n", - "🎉 **Congratulations!** You've successfully explored all the major modalities of Azure AI Content Understanding:\n", + "🎉 **Congratulations!** You have successfully explored 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", "\n", - "- **Multi-modal capabilities**: Content Understanding can process documents, audio, video, and images\n", - "- **Customizable templates**: Each analyzer template is designed for specific use cases but can be customized\n", - "- **Automatic cleanup**: Each analyzer was automatically cleaned up after use to manage resources\n", - "- **Structured output**: All results are returned in consistent JSON format for easy integration\n", + "- **Multi-modal capabilities**: Content Understanding can process documents, audio, video, and images.\n", + "- **Customizable templates**: Each analyzer template is designed for specific use cases but can be customized.\n", + "- **Automatic cleanup**: Each analyzer was cleaned up after use to manage resources.\n", + "- **Structured output**: All results are returned as consistent JSON for easy integration.\n", "\n", "## Next Steps\n", "\n", - "- Explore the analyzer templates in the `../analyzer_templates/` directory\n", - "- Modify existing templates or create custom ones for your specific use cases\n", - "- Check out other notebooks in this repository for advanced scenarios\n", - "- Visit the [Azure AI Content Understanding documentation](https://docs.microsoft.com/azure/ai-services/content-understanding/) for more information" + "- Explore the analyzer templates in the `../analyzer_templates/` directory.\n", + "- Modify existing templates or create custom ones for your specific use cases.\n", + "- Check other notebooks in this repository for advanced scenarios.\n", + "- Visit the [Azure AI Content Understanding documentation](https://docs.microsoft.com/azure/ai-services/content-understanding/) for more information." ] } ], @@ -836,4 +836,4 @@ }, "nbformat": 4, "nbformat_minor": 2 -} +} \ No newline at end of file