NOTE: This is a sample application to help you understand how Semantic Kernel and AI can work in Web Applications. This sample is NOT FOR PRODUCTION deployments.
This sample allows you to build your own integrated large language model (LLM) chat copilot. The sample is built on Microsoft Semantic Kernel and has three components:
- A frontend application React web app
- A backend REST API .NET web API service
- A .NET worker service for processing semantic memory.
These quick-start instructions run the sample locally. They can also be found on the official Chat Copilot Microsoft Learn documentation page for getting started.
To deploy the sample to Azure, please view Deploying Chat Copilot after meeting the requirements described below.
IMPORTANT: This sample is for educational purposes only and is not recommended for production deployments.
IMPORTANT: Each chat interaction will call Azure OpenAI/OpenAI which will use tokens that you may be billed for.
You will need the following items to run the sample:
- .NET 7.0 SDK (via Setup install.* script)
- Node.js (via Setup install.* script)
- Yarn (via Setup install.* script)
- JQ (Install manually, only required in linux/macos env)
- Git
- AI Service (one of the following is required)
AI Service | Requirement |
---|---|
Azure OpenAI | - Access - Resource - Deployed models ( gpt-35-turbo and text-embedding-ada-002 ) - Endpoint - API key |
OpenAI | - Account - API key |
The Azure Developer CLI (azd
) is a developer-centric command-line interface (CLI) tool for creating Azure applications.
You need to install it before running and deploying with the Azure Developer CLI.
powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1' | Invoke-Expression"
curl -fsSL https://aka.ms/install-azd.sh | bash
After logging in with the following command, you will be able to use the azd
cli to quickly provision and deploy the application.
azd auth login
Then, execute the azd init
command to initialize the environment (You do not need to run this command if you already have the code or have opened this in a Codespace or DevContainer).
azd init -t microsoft/chat-copilot
Enter an environment name.
Next, run azd up
to provision all the resources to Azure and deploy the code to those resources.
azd up
Select your desired subscription
and location
. Then choose a resource group or create a new resource group. Wait a moment for the resource deployment to complete, click the Website endpoint and you will see the web app page.
You can also run the sample directly locally (See below).
-
Open PowerShell as an administrator.
NOTE: Ensure that you have PowerShell Core 6+ installed. This is different from the default PowerShell installed on Windows.
-
Clone this repository
git clone https://github.com/microsoft/chat-copilot
-
Setup your environment.
The following is a script to help you install the dependencies required. Feel free to install
dotnet
,nodejs
, andyarn
with your method of choice or use this script.cd <path to chat-copilot>\scripts\ .\Install.ps1
NOTE: This script will install
Chocolatey
,dotnet-7.0-sdk
,nodejs
, andyarn
.NOTE: If you receive an error that the script is not digitally signed or cannot execute on the system, you may need to change the execution policy (see list of policies and scopes) or unblock the script.
-
Configure Chat Copilot.
.\Configure.ps1 -AIService {AI_SERVICE} -APIKey {API_KEY} -Endpoint {AZURE_OPENAI_ENDPOINT}
-
AI_SERVICE
:AzureOpenAI
orOpenAI
. -
API_KEY
: TheAPI key
for Azure OpenAI or for OpenAI. -
AZURE_OPENAI_ENDPOINT
: The Azure OpenAI resourceEndpoint
address. This is only required when using Azure OpenAI, omit-Endpoint
if using OpenAI. -
IMPORTANT: For
AzureOpenAI
, if you deployed modelsgpt-35-turbo
andtext-embedding-ada-002
with custom names (instead of the default names), also use the parameters:-CompletionModel {DEPLOYMENT_NAME} -EmbeddingModel {DEPLOYMENT_NAME} -PlannerModel {DEPLOYMENT_NAME}
-PlannerModel name will be the same as -CompletionModel
Open the
.\Configure.ps1
script to see all of the available parameters.
-
-
Run Chat Copilot locally. This step starts both the backend API and frontend application.
.\Start.ps1
It may take a few minutes for Yarn packages to install on the first run.
NOTE: Confirm pop-ups are not blocked and you are logged in with the same account used to register the application.
-
(Optional) To start ONLY the backend:
.\Start-Backend.ps1
-
-
Open Bash as an Administrator.
-
Clone this repository
git clone https://github.com/microsoft/chat-copilot
-
Configure environment.
The following is a script to help you install the dependencies required. Feel free to install
dotnet
,nodejs
, andyarn
with your method of choice or use this script.cd <path to chat-copilot>/scripts/
Ubuntu/Debian Linux
./install-apt.sh
NOTE: This script uses
apt
to installdotnet-sdk-7.0
,nodejs
, andyarn
.macOS
./install-brew.sh
NOTE: This script uses
homebrew
to installdotnet-sdk
,nodejs
, andyarn
. -
Configure Chat Copilot.
-
For OpenAI
./configure.sh --aiservice OpenAI --apikey {API_KEY}
API_KEY
: TheAPI key
for OpenAI.
-
For Azure OpenAI
./configure.sh --aiservice AzureOpenAI \ --endpoint {AZURE_OPENAI_ENDPOINT} \ --apikey {API_KEY}
AZURE_OPENAI_ENDPOINT
: The Azure OpenAI resourceEndpoint
address.API_KEY
: TheAPI key
for Azure OpenAI.
IMPORTANT: If you deployed models
gpt-35-turbo
andtext-embedding-ada-002
with custom names (instead of the default names), you need to specify the deployment names with three additional parameters:./configure.sh --aiservice AzureOpenAI \ --endpoint {AZURE_OPENAI_ENDPOINT} \ --apikey {API_KEY} \ --completionmodel {DEPLOYMENT_NAME} \ --plannermodel {DEPLOYMENT_NAME} \ --embeddingmodel {DEPLOYMENT_NAME}
--plannermodel
will be the same name as--completionmodel
-
-
Run Chat Copilot locally. This step starts both the backend API and frontend application.
./start.sh
It may take a few minutes for Yarn packages to install on the first run.
NOTE: Confirm pop-ups are not blocked and you are logged in with the same account used to register the application.
-
(Optional) To start ONLY the backend:
./start-backend.sh
-
(Optional) Run the memory pipeline
By default, the webapi is configured to work without the memory pipeline for synchronous processing documents locally. To enable asynchronous document processing, you need to configure the webapi and the memory pipeline. Please refer to the webapi README and the memory pipeline README for more information.
Notes: If you run the sample using the Azure Developer CLI (azd), memory pipeline has been configured and deployed, no additional action is required.
By default, Chat Copilot runs locally without authentication, using a guest user profile. If you want to enable authentication with Azure Active Directory, follow the steps below.
-
Create an application registration for the frontend web app, using the values below
Supported account types
: "Accounts in this organizational directory only ({YOUR TENANT} only - Single tenant)"Redirect URI (optional)
: Single-page application (SPA) and use http://localhost:3000.
-
Create a second application registration for the backend web api, using the values below:
Supported account types
: "Accounts in this organizational directory only ({YOUR TENANT} only - Single tenant)"- Do not configure a
Redirect URI (optional)
NOTE: Other account types can be used to allow multitenant and personal Microsoft accounts to use your application if you desire. Doing so may result in more users and therefore higher costs.
Take note of the
Application (client) ID
for both app registrations as you will need them in future steps.
-
Expose an API within the second app registration
-
Select Expose an API from the menu
-
Add an Application ID URI
-
This will generate an
api://
URI -
Click Save to store the generated URI
-
-
Add a scope for
access_as_user
-
Click Add scope
-
Set Scope name to
access_as_user
-
Set Who can consent to Admins and users
-
Set Admin consent display name and User consent display name to
Access copilot chat as a user
-
Set Admin consent description and User consent description to
Allows the accesses to the Copilot chat web API as a user
-
-
Add the web app frontend as an authorized client application
-
Click Add a client application
-
For Client ID, enter the frontend's application (client) ID
-
Check the checkbox under Authorized scopes
-
Click Add application
-
-
-
Add permissions to web app frontend to access web api as user
-
Open app registration for web app frontend
-
Go to API Permissions
-
Click Add a permission
-
Select the tab APIs my organization uses
-
Choose the app registration representing the web api backend
-
Select permissions
access_as_user
-
Click Add permissions
-
-
Run the Configure script with additional parameters to set up authentication.
Powershell
.\Configure.ps1 -AiService {AI_SERVICE} -APIKey {API_KEY} -Endpoint {AZURE_OPENAI_ENDPOINT} -FrontendClientId {FRONTEND_APPLICATION_ID} -BackendClientId {BACKEND_APPLICATION_ID} -TenantId {TENANT_ID} -Instance {AZURE_AD_INSTANCE}
Bash
./configure.sh --aiservice {AI_SERVICE} --apikey {API_KEY} --endpoint {AZURE_OPENAI_ENDPOINT} --frontend-clientid {FRONTEND_APPLICATION_ID} --backend-clientid {BACKEND_APPLICATION_ID} --tenantid {TENANT_ID} --instance {AZURE_AD_INSTANCE}
AI_SERVICE
:AzureOpenAI
orOpenAI
.API_KEY
: TheAPI key
for Azure OpenAI or for OpenAI.AZURE_OPENAI_ENDPOINT
: The Azure OpenAI resourceEndpoint
address. This is only required when using Azure OpenAI, omit-Endpoint
if using OpenAI.FRONTEND_APPLICATION_ID
: TheApplication (client) ID
associated with the application registration for the frontend.BACKEND_APPLICATION_ID
: TheApplication (client) ID
associated with the application registration for the backend.TENANT_ID
: Your Azure AD tenant IDAZURE_AD_INSTANCE
(optional): The Azure AD cloud instance for the authenticating users. Defaults tohttps://login.microsoftonline.com
.
Notes: If you want to use the Azure Developer CLI (azd) to set up authentication, please run the following
azd env
commands.azd env set AZURE_AD_TENANT_ID 'YOUR_TENANT_ID' azd env set AZURE_BACKEND_APPLICATION_ID 'YOUR_BACKEND_APPLICATION_ID' azd env set AZURE_FRONTEND_APPLICATION_ID 'YOUR_FRONTEND_APPLICATION_ID'
-
Run Chat Copilot locally. This step starts both the backend API and frontend application.
Powershell
.\Start.ps1
Bash
./start.sh
Notes: If you want to use the Azure Developer CLI (azd) to run this project, please run the command
azd up
.
-
Issue: Unable to load chats.
Details: interactionin_progress: Interaction is currently in progress.
Explanation: The WebApp can display this error when the application is configured for a different AAD tenant from the browser, (e.g., personal/MSA account vs work/school account).
Solution: Either use a private/incognito browser tab or clear your browser credentials/cookies. Confirm you are logged in with the same account used to register the application.
-
Issue:: Challenges using text completion models, such as
text-davinci-003
Solution: For OpenAI, see model endpoint compatibility for the complete list of current models supporting chat completions. For Azure OpenAI, see model summary table and region availability.
-
Issue: Localhost SSL certificate errors / CORS errors
Explanation: Your browser may be blocking the frontend access to the backend while waiting for your permission to connect.
Solution:
- Confirm the backend service is running. Open a web browser and navigate to
https://localhost:40443/healthz
- You should see a confirmation message:
Healthy
- If your browser asks you to acknowledge the risks of visiting an insecure website, you must acknowledge this before the frontend can connect to the backend server.
- You should see a confirmation message:
- Navigate to
http://localhost:3000
or refresh the page to use the Chat Copilot application.
- Confirm the backend service is running. Open a web browser and navigate to
-
Issue: Yarn is not working.
Explanation: You may have the wrong Yarn version installed such as v2.x+.
Solution: Use the classic version.
npm install -g yarn yarn set version classic
-
Issue: Missing
/usr/share/dotnet/host/fxr
folder.Details: "A fatal error occurred. The folder [/usr/share/dotnet/host/fxr] does not exist" when running dotnet commands on Linux.
Explanation: When .NET (Core) was first released for Linux, it was not yet available in the official Ubuntu repo. So instead, many of us added the Microsoft APT repo in order to install it. Now, the packages are part of the Ubuntu repo, and they are conflicting with the Microsoft packages. This error is a result of mixed packages. (Source: StackOverflow)
Solution:
# Remove all existing packages to get to a clean state: sudo apt remove --assume-yes dotnet*; sudo apt remove --assume-yes aspnetcore*; sudo apt remove --assume-yes netstandard*; # Set the Microsoft package provider priority echo -e "Package: *\nPin: origin \"packages.microsoft.com\"\nPin-Priority: 1001" | sudo tee /etc/apt/preferences.d/99microsoft-dotnet.pref; # Update and install dotnet sudo apt update; sudo apt install --assume-yes dotnet-sdk-7.0;
-
Issue: Lack of permission to execute
webapp/add-redirecturl.sh
file.Details: "ERROR: failed deploying service 'web': failed invoking event handlers for 'postdeploy', 'postdeploy' hook failed with exit code: '126', Path: './add-redirecturl.sh'. : exit code: 126, stdout: , stderr: /bin/sh: 1: ./add-redirecturl.sh: Permission denied" when the
azd deploy
command is executed on Linux/macOS, the postdeploy hook of the web is triggered.Solution: Add execution permissions to files.
chmod +x webapp/add-redirecturl.sh
-
Issue: az command is not available.
Details: "The term 'az' is not recognized as a name of a cmdlet, function, script file, or executable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again" when running
azd deploy
with backend authentication enabled via Azure AD.Explanation: After enabling backend authentication via Azure AD, running
azd deploy
will trigger the postdeploy hook of the web. The hook will runwebapp/add-redirecturl.sh
orwebapp/add-redirecturl.ps1
script file, and the az command is used in the script.Solution: Install Azure CLI and execute the command
az login
.
Every release is associated with a release branch. For instance, release v0.9 is on a branch called 0.9. Once a release is out, its branch will no longer be updated. The exception to this is the latest release branch, which will only receive bug fixes. This is to provide some stability to those for whom breaking changes and being on the bleeding edge (with the bugs it can entail) is not a desirable option.
If you would like to learn more about Semantic Kernel and AI, you may also be interested in other repos the Semantic Kernel team supports:
Repo | Description |
---|---|
Semantic Kernel | A lightweight SDK that integrates cutting-edge LLM technology quickly and easily into your apps. |
Semantic Kernel Docs | The home for Semantic Kernel documentation that appears on the Microsoft learn site. |
Semantic Kernel Starters | Starter projects for Semantic Kernel to make it easier to get started. |
Semantic Memory | A service that allows you to create pipelines for ingesting, storing, and querying knowledge. |
We welcome your contributions and suggestions to the Chat Copilot Sample App! One of the easiest ways to participate is to engage in discussions in the GitHub repository. Bug reports and fixes are welcome!
To learn more and get started:
- Read the documentation
- Join the Discord community
- Contribute to the project
- Follow the team on our blog
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the MIT license.