Skip to content

Review main-notebooks/management.ipynb #125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Review main-notebooks/management.ipynb #125

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 22 additions & 21 deletions notebooks/management.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
"metadata": {},
"source": [
"## Prerequisites\n",
"1. Ensure your Azure AI service is configured following the [configuration steps](../README.md#configure-azure-ai-service-resource).\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."
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]
    • change: Added "Please" and rephrased the sentence to "Please ensure your Azure AI service is configured by following the configuration steps."
    • rationale: Introducing "Please" makes the instruction more polite and approachable; restructuring the sentence improves readability and flow.
    • impact: Enhances the tone and clarity of the instruction, leading to better user engagement and understanding.

]
},
Expand All @@ -40,12 +40,12 @@
"\n",
"> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class that provides functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, this client serves as a lightweight SDK.\n",
"\n",
"> Fill the constants **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, and **AZURE_AI_API_KEY** with your Azure AI Service details.\n",
"> Please fill the constants **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, and **AZURE_AI_API_KEY** with your Azure AI Service details.\n",
"\n",
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Changed the instruction from "> Fill the constants ..." to "> Please fill the constants ..."
    • rationale: Adding "Please" makes the instruction more polite and clearer, improving the tone of the documentation.
    • impact: Enhances reader engagement and clarity by softening the directive, making the documentation more user-friendly.

"> ⚠️ Important:\n",
"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 might not run correctly.\n",
"Skipping this step might cause the sample not to run correctly.\n",
"\n",
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]
    • change: Reworded "If you skip this step, the sample might not run correctly." to "Skipping this step might cause the sample not to run correctly."
    • rationale: The revised sentence is more direct and concise, improving readability and making the consequence of skipping the step clearer.
    • impact: Enhances the user's understanding by providing a clearer warning, thereby improving the instructional quality of the documentation.

"> ⚠️ Note: Using a subscription key works, but using Azure Active Directory (AAD) token-based authentication is more secure and highly recommended for production environments."
]
Expand Down Expand Up @@ -112,20 +112,21 @@
"source": [
"## Configure Model Deployments for Prebuilt Analyzers\n",
"\n",
"> **💡 Note:** This step is only required **once per Azure Content Understanding resource**, unless the GPT deployment has been changed. You can skip this section if:\n",
"> **💡 Note:** This step is required **only once per Azure Content Understanding resource**, unless the GPT deployment has been changed.\n",
"You can skip this section if:\n",
"> - This configuration has already been run once for your resource, or\n",
"> - Your administrator has already configured the model deployments for you\n",
"> - Your administrator has already configured the model deployments for you.\n",
"\n",
"Before using prebuilt analyzers, you need to configure the default model deployment mappings. This tells Content Understanding which model deployments to use.\n",
"Before using prebuilt analyzers, please configure the default model deployment mappings. This tells Content Understanding which model deployments to use.\n",
"\n",
"**Model Requirements:**\n",
"- **GPT-4.1** - Required for most prebuilt analyzers (e.g., `prebuilt-invoice`, `prebuilt-receipt`, `prebuilt-idDocument`)\n",
"- **GPT-4.1-mini** - Required for RAG analyzers (e.g., `prebuilt-documentSearch`, `prebuilt-audioSearch`, `prebuilt-videoSearch`)\n",
"- **text-embedding-3-large** - Required for all prebuilt analyzers that use embeddings\n",
"- **GPT-4.1** - Required for most prebuilt analyzers (e.g., `prebuilt-invoice`, `prebuilt-receipt`, `prebuilt-idDocument`).\n",
"- **GPT-4.1-mini** - Required for RAG analyzers (e.g., `prebuilt-documentSearch`, `prebuilt-audioSearch`, `prebuilt-videoSearch`).\n",
"- **text-embedding-3-large** - Required for all prebuilt analyzers that use embeddings.\n",
"\n",
"**Prerequisites:**\n",
"1. Deploy **GPT-4.1**, **GPT-4.1-mini**, and **text-embedding-3-large** models in Azure AI Foundry\n",
"2. Set `GPT_4_1_DEPLOYMENT`, `GPT_4_1_MINI_DEPLOYMENT`, and `TEXT_EMBEDDING_3_LARGE_DEPLOYMENT` in your `.env` file with the deployment names"
"1. Deploy **GPT-4.1**, **GPT-4.1-mini**, and **text-embedding-3-large** models in Azure AI Foundry.\n",
"2. Set environment variables `GPT_4_1_DEPLOYMENT`, `GPT_4_1_MINI_DEPLOYMENT`, and `TEXT_EMBEDDING_3_LARGE_DEPLOYMENT` in your `.env` file with the respective deployment names."
]
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity, Formatting]

    • change: Split a long note into two separate sentences, moving "You can skip this section if:" outside the blockquote and removing redundant words such as "only once".
    • rationale: To improve readability and sentence flow, clarifying the conditions under which the section can be skipped.
    • impact: Makes the note clearer and easier to read, helping users better understand when the step is required.

  • categories: [Grammar]

    • change: Added missing periods at the end of bullet points in the note.
    • rationale: To maintain correct sentence punctuation within list items.
    • impact: Enhances professionalism and grammatical correctness of the documentation.

  • categories: [Clarity, Grammar]

    • change: Replaced "Before using prebuilt analyzers, you need to configure..." with "Before using prebuilt analyzers, please configure..."
    • rationale: Using "please" creates a more polite and less imperative tone.
    • impact: Improves user experience by making instructions more approachable.

  • categories: [Grammar, Consistency]

    • change: Added periods at the end of all model requirements bullet points.
    • rationale: Ensures consistent punctuation across all list items.
    • impact: Improves consistency and readability in the documentation.

  • categories: [Grammar, Clarity, Consistency]

    • change: Added periods at the end of prerequisite list items and clarified the second item to specify setting environment variables with deployment names in the .env file.
    • rationale: Maintaining consistent punctuation and clarifying the action required for environment variable setup.
    • impact: Enhances clarity and maintains uniform formatting, helping users correctly configure their environment.

},
{
Expand Down Expand Up @@ -154,12 +155,12 @@
" print(f\" - {deployment}\")\n",
" print(\"\\n Prebuilt analyzers require GPT-4.1, GPT-4.1-mini, and text-embedding-3-large deployments.\")\n",
" print(\" Please:\")\n",
" print(\" 1. Deploy all three models in Azure AI Foundry\")\n",
" print(\" 1. Deploy all three models in Azure AI Foundry.\")\n",
" print(\" 2. Add the following to notebooks/.env:\")\n",
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar]
    • change: Added a period at the end of the sentence "Deploy all three models in Azure AI Foundry".
    • rationale: To complete the sentence with appropriate punctuation.
    • impact: Enhances the grammatical correctness and professionalism of the printed instructions.

" print(\" GPT_4_1_DEPLOYMENT=<your-gpt-4.1-deployment-name>\")\n",
" print(\" GPT_4_1_MINI_DEPLOYMENT=<your-gpt-4.1-mini-deployment-name>\")\n",
" print(\" TEXT_EMBEDDING_3_LARGE_DEPLOYMENT=<your-text-embedding-3-large-deployment-name>\")\n",
" print(\" 3. Restart the kernel and run this cell again\")\n",
" print(\" 3. Restart the kernel and run this cell again.\")\n",
"else:\n",
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar]
    • change: Added a period at the end of the printed sentence "Restart the kernel and run this cell again."
    • rationale: The original sentence was missing a terminal punctuation mark, which is necessary for proper grammar and readability.
    • impact: This change improves the professionalism and clarity of the printed message, making it more polished for the user.

" print(f\"📋 Configuring default model deployments...\")\n",
" print(f\" GPT-4.1 deployment: {GPT_4_1_DEPLOYMENT}\")\n",
Expand All @@ -181,8 +182,8 @@
" except Exception as e:\n",
" print(f\"❌ Failed to configure defaults: {e}\")\n",
" print(f\" This may happen if:\")\n",
" print(f\" - One or more deployment names don't exist in your Azure AI Foundry project\")\n",
" print(f\" - You don't have permission to update defaults\")\n",
" print(f\" - One or more deployment names don't exist in your Azure AI Foundry project.\")\n",
" print(f\" - You don't have permission to update defaults.\")\n",
" raise\n"
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar]
    • change: Added a period at the end of two print statement messages.
    • rationale: Sentences in the print statements were missing terminal punctuation, affecting grammatical completeness.
    • impact: Enhances the professionalism and readability of the output messages by providing correct sentence punctuation.

]
},
Expand Down Expand Up @@ -211,7 +212,7 @@
" for model_name, deployment_name in model_deployments.items():\n",
" print(f\" {model_name}: {deployment_name}\")\n",
" else:\n",
" print(\"\\n No model deployments configured\")\n",
" print(\"\\n No model deployments configured.\")\n",
" \n",
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar]
    • change: Added a period at the end of the printed sentence "No model deployments configured."
    • rationale: Adding the period completes the sentence grammatically.
    • impact: Enhances the professionalism and readability of the output message.

"except Exception as e:\n",
" print(f\"⚠️ Error retrieving defaults: {e}\")\n",
Expand All @@ -224,7 +225,7 @@
"source": [
"## Create a Simple Analyzer\n",
"\n",
"> **💡 Note:** This section demonstrates analyzer creation for learning purposes only. For actual invoice field extraction, we recommend using the **`prebuilt-invoice`** analyzer, which is optimized for invoice processing. See the `field_extraction.ipynb` notebook for examples of using prebuilt analyzers.\n",
"> **💡 Note:** This section demonstrates analyzer creation for learning purposes only. For actual invoice field extraction, we recommend using the **`prebuilt-invoice`** analyzer, which is optimized for invoice processing. Please see the `field_extraction.ipynb` notebook for examples of using prebuilt analyzers.\n",
"\n",
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Added the word "Please" before "see the field_extraction.ipynb notebook for examples of using prebuilt analyzers."
    • rationale: Including "Please" makes the sentence more polite and reader-friendly, improving the tone of the instruction.
    • impact: Enhances the clarity and approachability of the note, encouraging users to refer to the notebook without sounding abrupt.

"First, we create an analyzer from a template to extract invoice fields."
]
Expand Down Expand Up @@ -347,7 +348,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"After successfully creating an analyzer, you can use it to analyze our input files. You can also list all analyzers available in your resource."
"After successfully creating an analyzer, you can use it to analyze your input files. You can also list all analyzers available in your resource."
]
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Changed "our input files" to "your input files" in the sentence.
    • rationale: The original phrasing used "our," which is inconsistent with the second-person perspective used elsewhere in the sentence ("you can use," "your resource"). Changing to "your" aligns the pronouns to maintain consistent voice.
    • impact: This change improves the grammatical consistency and clarity of the documentation, making it clearer and more professional for the reader.

},
{
Expand Down Expand Up @@ -387,7 +388,7 @@
"source": [
"## Get Analyzer Details by ID\n",
"\n",
"Keep track of the analyzer ID when you create it. Use the ID to retrieve detailed analyzer definitions later."
"Keep track of the analyzer ID when you create it. You can use the ID to retrieve detailed analyzer definitions later."
]
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Replaced "Use the ID to retrieve detailed analyzer definitions later." with "You can use the ID to retrieve detailed analyzer definitions later."
    • rationale: Adding "You can" softens the instruction, making it clearer that the action is optional and improving the sentence flow.
    • impact: Enhances readability and clarity, making the documentation easier to understand.

},
{
Expand All @@ -414,7 +415,7 @@
"metadata": {},
"source": [
"## Delete an Analyzer\n",
"If you no longer need an analyzer, delete it using its ID."
"If you no longer need an analyzer, you can delete it using its ID."
]
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Added "you can" to the sentence, changing "delete it using its ID" to "you can delete it using its ID."
    • rationale: The modification clarifies that deletion is an option rather than a requirement, improving the sentence's readability and correctness.
    • impact: Enhances user understanding by making the instruction less imperative and more informative, leading to clearer documentation.

},
{
Expand Down Expand Up @@ -452,4 +453,4 @@
},
"nbformat": 4,
"nbformat_minor": 2
}
}
Copy link
Collaborator Author

@chienyuanchang chienyuanchang Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Formatting]
    • change: Added a trailing newline after the closing brace }.
    • rationale: Ensures the file ends with a newline character, adhering to standard POSIX file formatting conventions.
    • impact: Improves compatibility with tools and editors that expect files to end with a newline, preventing potential issues in version control diffs or compilation.

Loading