Merge pull request #407 from microsoft/bk-ckm-readme-changes

docs: Refactor CKM documentation to align with new template

Author: brittneek

README.md

@@ -0,0 +1,213 @@
+# Deployment Guide
+
+## **Pre-requisites**
+
+To deploy this solution, ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the necessary permissions to create **resource groups, resources, app registrations, and assign roles at the resource group level**. This should include Contributor role at the subscription level and Role Based Access Control (RBAC) permissions at the subscription and/or resource group level. Follow the steps in [Azure Account Set Up](./AzureAccountSetUp.md).
+
+Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/?products=all&regions=all) page and select a **region** where the following services are available:
+
+- [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry)
+- [Azure AI Content Understanding Service](https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/)
+- [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/)
+- [GPT Model Capacity](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)
+- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/search-what-is-azure-search)
+- [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/sql-database-paas-overview)
+- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/introduction)
+- [Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/)
+- [Azure Container Registry](https://learn.microsoft.com/en-us/azure/container-registry/)
+- [Embedding Deployment Capacity](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embedding-models)
+- [Azure Semantic Search](./docs/AzureSemanticSearchRegion.md)
+
+Here are some example regions where the services are available: East US, East US2, Australia East, UK South, France Central.
+
+### **Important Note for PowerShell Users**
+
+If you encounter issues running PowerShell scripts due to the policy of not being digitally signed, you can temporarily adjust the `ExecutionPolicy` by running the following command in an elevated PowerShell session:
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+```
+
+This will allow the scripts to run for the current session without permanently changing your system's policy.
+
+## Deployment Options & Steps
+
+Pick from the options below to see step-by-step instructions for GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments.
+
+| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator) | 
+|---|---|
+
+<details>
+  <summary><b>Deploy in GitHub Codespaces</b></summary>
+
+### GitHub Codespaces
+
+You can run this solution 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):
+
+    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator)
+
+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](#deploying-with-azd).
+
+</details>
+
+<details>
+  <summary><b>Deploy in VS Code</b></summary>
+
+### VS Code Dev Containers
+
+You can run this solution in VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers):
+
+1. Start Docker Desktop (install it if not already installed).
+2. Open the project:
+
+    [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator)
+
+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](#deploying-with-azd).
+
+</details>
+
+<details>
+  <summary><b>Deploy in your local Environment</b></summary>
+
+### 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:
+    - [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.5) <small>(v7.0+)</small> - available for Windows, macOS, and Linux.
+    - [Azure Developer CLI (azd)](https://aka.ms/install-azd)
+    - [Python 3.9+](https://www.python.org/downloads/)
+    - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+    - [Git](https://git-scm.com/downloads)
+
+2. Clone the repository or download the project code via command-line:
+
+    ```shell
+    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](#deploying-with-azd).
+
+</details>
+
+<br/>
+
+Consider the following settings during your deployment to modify specific settings:
+
+<details>
+  <summary><b>Configurable Deployment Settings</b></summary>
+
+When you start the deployment, most parameters will have **default values**, but you can update the following settings:
+
+| **Setting** | **Description** | **Default value** |
+|------------|----------------|------------|
+| **Azure Region** | The region where resources will be created. | eastus | 
+| **Environment Name** | A **3-20 character alphanumeric value** used to generate a unique ID to prefix the resources. | kmtemplate |
+| **Azure AI Content Understanding Location** | Select from a drop-down list of values. | swedencentral |
+| **Secondary Location** | A **less busy** region for **Azure SQL and Azure Cosmos DB**, useful in case of availability constraints. | eastus2 |
+| **Deployment Type** | Select from a drop-down list. | GlobalStandard |
+| **GPT Model** | Choose from **gpt-4, gpt-4o, gpt-4o-mini** | gpt-4o-mini |  
+| **GPT Model Deployment Capacity** | Configure capacity for **GPT models**. | 30k |
+| **Embedding Model** | Default: **text-embedding-ada-002**. | text-embedding-ada-002 |
+| **Embedding Model Capacity** | Set the capacity for **embedding models**. | 80k |
+
+</details>
+
+<details>
+  <summary><b>[Optional] Quota Recommendations</b></summary>
+
+By default, the **Gpt-4o-mini model capacity** in deployment is set to **30k tokens**, so we recommend updating the following:
+
+> **For Global Standard | GPT-4o-mini - increase the capacity to at least 150k tokens post-deployment for optimal performance.**
+
+Depending on your subscription quota and capacity, you can [adjust quota settings](AzureGPTQuotaSettings.md) to better meet your specific needs. You can also [adjust the deployment parameters](CustomizingAzdParameters.md) for additional optimization.
+
+**⚠️ Warning:** Insufficient quota can cause deployment errors. Please ensure you have the recommended capacity or request additional capacity before deploying this solution.
+
+</details>
+
+### Deploying with AZD
+
+Once you've opened the project in [Codespaces](#github-codespaces), [Dev Containers](#vs-code-dev-containers), or [locally](#local-environment), you can deploy it to Azure by following these steps:
+
+1. Login to Azure:
+
+    ```shell
+    azd auth login
+    ```
+
+    #### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**:
+
+    ```sh
+    azd auth login --tenant-id <tenant-id>
+    ```
+
+2. Provision and deploy all the resources:
+
+    ```shell
+    azd up
+    ```
+
+3. Provide an `azd` environment name (e.g., "ckmapp").
+4. Select a subscription from your Azure account and choose a location that has quota for all the resources. 
+    -- This deployment will take *7-10 minutes* to provision the resources in your account and set up the solution with sample data.
+    - If you encounter an error or timeout during deployment, changing the location may help, as there could be availability constraints for the resources.
+
+5. Once the deployment has completed successfully, open the [Azure Portal](https://portal.azure.com/), go to the deployed resource group, find the App Service, and get the app URL from `Default domain`.
+
+6. If you are done trying out the application, you can delete the resources by running `azd down`.
+
+### Publishing Local Build Container to Azure Container Registry
+
+If you need to rebuild the source code and push the updated container to the deployed Azure Container Registry, follow these steps:
+
+1. Set the environment variable `USE_LOCAL_BUILD` to `True`:
+
+   - **Linux/macOS**:
+     ```bash
+     export USE_LOCAL_BUILD=True
+     ```
+
+   - **Windows (PowerShell)**:
+     ```powershell
+     $env:USE_LOCAL_BUILD = $true
+     ```
+2. Run the `az login` command
+   ```bash
+   az login
+   ```
+
+3. Run the `azd up` command again to rebuild and push the updated container:
+   ```bash
+   azd up
+   ```
+
+This will rebuild the source code, package it into a container, and push it to the Azure Container Registry associated with your deployment.
+
+## Post Deployment Steps
+
+1. **Add App Authentication**
+   
+    Follow steps in [App Authentication](./AppAuthentication.md) to configure authentication in app service. Note: Authentication changes can take up to 10 minutes 
+
+2. **Deleting Resources After a Failed Deployment**  
+
+     - Follow steps in [Delete Resource Group](./DeleteResourceGroup.md) if your deployment fails and/or you need to clean up the resources.
+
+## Sample Questions
+
+To help you get started, here are some **Sample Questions** you can ask in the app:
+
+- Total number of calls by date for the last 7 days
+- Show average handling time by topics in minutes
+- What are the top 7 challenges users reported?
+- Give a summary of billing issues
+- When customers call in about unexpected charges, what types of charges are they seeing?
+
+These questions serve as a great starting point to explore insights from the data.