Conversation knowledge mining solution accelerator

MENU: USER STORY | QUICK DEPLOY | SUPPORTING DOCUMENTATION

User story

Overview

This solution accelerator enables customers with large amounts of conversational data to improve decision-making by leveraging intelligence to uncover insights, relationships, and patterns from customer interactions. It empowers users to gain valuable knowledge and drive targeted business impact.

It leverages Azure AI Foundry, AI Content Understanding, Azure OpenAI, and Azure AI Search to transform large volumes of conversational data into actionable insights through topic modeling, key phrase extraction, speech-to-text transcription, and interactive chat experiences.

Technical key features

Below is an image of the solution accelerator.

Use case / scenario

An analyst managing large volumes of conversational data needs a solution to visualize key insights and uncover patterns using natural language. An interactive dashboard enables them to explore rich, actionable insights for faster, and more informed decision-making.

This solution empowers analysts with tools to ask questions and receive real-time, contextualized responses. It streamlines problem-solving, enhances collaboration, and fosters innovation by making data-driven insights accessible and shareable.

The sample data used in this repository is synthetic and generated using Azure Open AI service. The data is intended for use as sample data only.

Solution architecture

QUICK DEPLOY

Prerequisites

To deploy this solution accelerator, you will need access to an Azure subscription with permission to create resource groups and resources.

Please check the link Azure Products by Region and choose a region where Azure AI Foundry, Azure OpenAI Services, Azure AI Search, Azure AI Content Understanding, Embedding Deployment Capacity and GPT Model Capacity are available. Recommended regions are eastus, eastus2.

When you start the deployment using one of the options below, most parameters will have a default name set already. You can update the following settings:

• Azure region where the resources will be created in

• Environment name, a 3-10 characters alphanumeric value that will be used to prefix resources

• Content Understanding location from the drop-down list of values

• Secondary location, a less busy location for Azure SQL and CosmoDB resources if you run into any availability constraints

• Deployment type from the drop-down list of values

• GPT model from the drop-down list of values

• GPT model deployment capacity

• Embedding model from the drop-down list of values

• Embedding model capacity

[Optional]: Quota Recommendations

• The default for the GPT model capacity in deployment is 30k tokens.
  • For optimal performance, it is recommended to increase to 100k tokens.
• Navigate to the Azure AI Foundry portal
• Select the AI Project you are using for this accelerator if you are not already in the project.
• Select Management center from the bottom left navigation menu
• Select Quota, click the GlobalStandard dropdown and select the GPT model and region you are using for this accelerator to see your available quota.
• Request more quota or delete any unused model deployments as needed.

Options

Pick from the options below to see step-by-step instructions for: GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments.

Deploy in GitHub Codespaces

GitHub Codpespaces

You can run this solution accelerator virtually by using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:

1. Open the solution accelerator (this may take several minutes):

   

2. Accept the default values on the create Codespaces page

3. Open a terminal window if it is not already open

4. Continue with the deploying steps

Deploy in VS Code

VS Code Dev Containers

A related option is VS Code Dev Containers, which will open the project in your local VS Code using the Dev Containers extension:

1. Start Docker Desktop (install it if not already installed)

2. Open the project:

   

3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.

4. Continue with the deploying steps

Deploy in your local environment

Local environment

If you're not using one of the above options for opening the project, then you'll need to:

1. Make sure the following tools are installed:

   • Azure Developer CLI (azd)
   • Python 3.9+
   • Docker Desktop
   • Git

2. Download the project code:

   azd init -t microsoft/Conversation-Knowledge-Mining-Solution-Accelerator/

3. Open the project folder in your terminal or editor.

4. Continue with the deploying steps.

Deploy with Bicep/ARM template

Quick Deploy (Bicep)

1. Deploy Azure resources
   Click the following deployment button to create the required resources for this accelerator directly in your Azure Subscription.

   

Deploying

Once you've opened the project in Codespaces, in Dev Containers, or locally,

you can deploy it to Azure.

Azure account setup

1. Sign up for a free Azure account and create an Azure Subscription.
2. Check that you have the necessary permissions:
   • Your Azure account must have Microsoft.Authorization/roleAssignments/write permissions, such as Role Based Access Control Administrator, User Access Administrator, or Owner.
   • Your Azure account also needs Microsoft.Resources/deployments/write permissions on the subscription level.

You can view the permissions for your account and subscription by following the steps below:

• Navigate to the Azure Portal and click on Subscriptions under 'Navigation'
• Select the subscription you are using for this accelerator from the list.
  • If you try to search for your subscription and it does not come up, make sure no filters are selected.
• Select Access control (IAM) and you can see the roles that are assigned to your account for this subscription.
  • If you want to see more information about the roles, you can go to the Role assignments tab and search by your account name and then click the role you want to view more information about.

[Optional]: Customizing resource names

By default this template will use the environment name as the prefix to prevent naming collisions within Azure. The parameters below show the default values. You only need to run the statements below if you need to change the values.

To override any of the parameters, run azd env set <key> <value> before running azd up. On the first azd command, it will prompt you for the environment name. Be sure to choose 3-10 charaters alphanumeric unique name.

Change the Content Understanding Location (allowed values: West US, Sweden Central, Australia East)

azd env set AZURE_ENV_CU_LOCATION 'West US'

Change the Secondary Location (example: eastus2, westus2, etc.)

azd env set AZURE_ENV_SECONDARY_LOCATION eastus2

Change the Model Deployment Type (allowed values: Standard, GlobalStandard)

azd env set AZURE_ENV_MODEL_DEPLOYMENT_TYPE GlobalStandard

Set the Model Name (allowed values: gpt-4o-mini, gpt-4o, gpt-4)

azd env set AZURE_ENV_MODEL_NAME gpt-4o-mini

Change the Model Capacity (choose a number based on available GPT model capacity in your subscription)

azd env set AZURE_ENV_MODEL_CAPACITY 30

Change the Embedding Model

azd env set AZURE_ENV_EMBEDDING_MODEL_NAME text-embedding-ada-002

Change the Embedding Deployment Capacity (choose a number based on available embedding model capacity in your subscription)

azd env set AZURE_ENV_EMBEDDING_MODEL_CAPACITY 80

Deploying with azd

1. Login to Azure:

   azd auth login

2. Provision and deploy all the resources:

   azd up

3. Provide an azd environment name (like "ckmapp")

4. Select a subscription from your Azure account, and select a location which has quota for all the resources.

   • Then it will provision the resources in your account and deploy the latest code. If you get an error or timeout with deployment, changing the location can help, as there may be availability constraints for the resources.

5. Open the Azure Portal, go to the deployed resource group, find the App Service and get the app URL from Default domain.

6. You can now proceed to run the development server to test the app locally, or if you are done trying out the app, you can delete the resources by running azd down.

Additional Steps

1. Add Azure Function Users to Database

   This script automates the process of adding Azure Function identities as users in a database and assigning them appropriate roles.

   Prerequisites

   Before running the script, ensure you have:

   • Azure CLI installed.
   • Python 3 installed.
   • Microsoft ODBC Driver 17 for SQL Server installed.

   Usage

   1. Clone the repository:

      git clone https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator.git
      

   2. Navigate to script directory

      cd infra\scripts\add_user_scripts
      

   3. Run the script

      chmod +x ./add_user.sh
      ./add_user.sh <resourcegroupname> <solution_prefix>
      

2. Add App Authentication

   Follow steps in App Authentication to configure authenitcation in app service.

   Note: Authentication changes can take up to 10 minutes

Responsible AI Transparency FAQ

Please refer to Transparency FAQ for responsible AI transparency details of this solution accelerator.

Supporting documentation

Costs

Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage. The majority of the Azure resources used in this infrastructure are on usage-based pricing tiers. However, Azure Container Registry has a fixed cost per registry per day.

You can try the Azure pricing calculator for the resources:

• Azure AI Foundry: Free tier. Pricing
• Azure AI Search: Standard tier, S1. Pricing is based on the number of documents and operations. Pricing
• Azure Storage Account: Standard tier, LRS. Pricing is based on storage and operations. Pricing
• Azure Key Vault: Standard tier. Pricing is based on the number of operations. Pricing
• Azure AI Services: S0 tier, defaults to gpt-4o-mini and text-embedding-ada-002 models. Pricing is based on token count. Pricing
• Azure Container App: Consumption tier with 0.5 CPU, 1GiB memory/storage. Pricing is based on resource allocation, and each month allows for a certain amount of free usage. Pricing
• Azure Container Registry: Basic tier. Pricing
• Log analytics: Pay-as-you-go tier. Costs based on data ingested. Pricing
• Azure SQL Server: General Purpose Tier. Pricing
• Azure Cosmos DB: Pricing
• Azure functions: Consumption tier Pricing

⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use, either by deleting the resource group in the Portal or running azd down.

Security guidelines

This template uses Azure Key Vault to store all connections to communicate between resources.

This template also uses Managed Identity for local development and deployment.

To ensure continued best practices in your own repository, we recommend that anyone creating solutions based on our templates ensure that the Github secret scanning setting is enabled.

You may want to consider additional security measures, such as:

• Enabling Microsoft Defender for Cloud to secure your Azure resources.
• Protecting the Azure Container Apps instance with a firewall and/or Virtual Network.

How to customize

If you'd like to customize the solution accelerator, here are some ways you might do that:

• Ingest your own audio conversation files by uploading them into the storage account and run the process data scripts.
• You can also scale the solution and process large volumes of data by deploying this to Microsoft Fabric by following the steps in Fabric_deployment.md

Additional resources

• Azure AI Foundry documentation
• Azure AI Content Understanding documentation
• Azure OpenAI Service
• Azure AI Search
• Azure Functions
• Azure App Service
• Azure SQL Database
• Azure Cosmos DB
• Microsoft Fabric

---

Disclaimers

To the extent that the Software includes components or code used in or derived from Microsoft products or services, including without limitation Microsoft Azure Services (collectively, “Microsoft Products and Services”), you must also comply with the Product Terms applicable to such Microsoft Products and Services. You acknowledge and agree that the license governing the Software does not grant you a license or other right to use Microsoft Products and Services. Nothing in the license or this ReadMe file will serve to supersede, amend, terminate or modify any terms in the Product Terms for any Microsoft Products and Services.

You must also comply with all domestic and international export laws and regulations that apply to the Software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit https://aka.ms/exporting.

You acknowledge that the Software and Microsoft Products and Services (1) are not designed, intended or made available as a medical device(s), and (2) are not designed or intended to be a substitute for professional medical advice, diagnosis, treatment, or judgment and should not be used to replace or as a substitute for professional medical advice, diagnosis, treatment, or judgment. Customer is solely responsible for displaying and/or obtaining appropriate consents, warnings, disclaimers, and acknowledgements to end users of Customer’s implementation of the Online Services.

You acknowledge the Software is not subject to SOC 1 and SOC 2 compliance audits. No Microsoft technology, nor any of its component technologies, including the Software, is intended or made available as a substitute for the professional advice, opinion, or judgement of a certified financial services professional. Do not use the Software to replace, substitute, or provide professional financial advice or judgment.

BY ACCESSING OR USING THE SOFTWARE, YOU ACKNOWLEDGE THAT THE SOFTWARE IS NOT DESIGNED OR INTENDED TO SUPPORT ANY USE IN WHICH A SERVICE INTERRUPTION, DEFECT, ERROR, OR OTHER FAILURE OF THE SOFTWARE COULD RESULT IN THE DEATH OR SERIOUS BODILY INJURY OF ANY PERSON OR IN PHYSICAL OR ENVIRONMENTAL DAMAGE (COLLECTIVELY, “HIGH-RISK USE”), AND THAT YOU WILL ENSURE THAT, IN THE EVENT OF ANY INTERRUPTION, DEFECT, ERROR, OR OTHER FAILURE OF THE SOFTWARE, THE SAFETY OF PEOPLE, PROPERTY, AND THE ENVIRONMENT ARE NOT REDUCED BELOW A LEVEL THAT IS REASONABLY, APPROPRIATE, AND LEGAL, WHETHER IN GENERAL OR IN A SPECIFIC INDUSTRY. BY ACCESSING THE SOFTWARE, YOU FURTHER ACKNOWLEDGE THAT YOUR HIGH-RISK USE OF THE SOFTWARE IS AT YOUR OWN RISK.