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:
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.
Requirements
You will need the following items to run the sample:
AI Service | Requirement |
---|---|
Azure OpenAI | - Access - Resource - Deployed models ( gpt-35-turbo and text-embedding-ada-002 ) - Endpoint - API key |
OpenAI | - Account - API key |
Instructions
Open PowerShell as an administrator.
NOTE: Ensure that you have PowerShell Core 6+ installed. This is different from the default PowerShell installed on Windows.
Setup your environment.
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.
AI_SERVICE
: AzureOpenAI
or OpenAI
.
API_KEY
: The API key
for Azure OpenAI or for OpenAI.
AZURE_OPENAI_ENDPOINT
: The Azure OpenAI resource Endpoint
address. Omit -Endpoint
if using OpenAI.
IMPORTANT: For
AzureOpenAI
, if you deployed modelsgpt-35-turbo
andtext-embedding-ada-002
with custom names (instead of each own's given name), also use the parameters:
Run Chat Copilot locally. This step starts both the backend API and frontend application.
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:
Open Bash as an administrator.
Configure environment.
Ubuntu/Debian Linux
NOTE: This script uses
apt
to installdotnet-sdk-7.0
,nodejs
, andyarn
.
macOS
NOTE: This script uses
homebrew
to installdotnet-sdk
,nodejs
, andyarn
.
Configure Chat Copilot.
For OpenAI
API_KEY
: The API key
for OpenAI.For Azure OpenAI
AZURE_OPENAI_ENDPOINT
: The Azure OpenAI resource Endpoint
address.API_KEY
: The API key
for Azure OpenAI.Run Chat Copilot locally. This step starts both the backend API and frontend application.
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:
By default, the webapi is configured to work without the memory pipeline for synchronous processing documents. 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.
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)"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
Bash
AI_SERVICE
: AzureOpenAI
or OpenAI
.API_KEY
: The API key
for Azure OpenAI or for OpenAI.AZURE_OPENAI_ENDPOINT
: The Azure OpenAI resource Endpoint
address. Omit -Endpoint
if using OpenAI.FRONTEND_APPLICATION_ID
: The Application (client) ID
associated with the application registration for the frontend.BACKEND_APPLICATION_ID
: The Application (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 to https://login.microsoftonline.com
.Run Chat Copilot locally. This step starts both the backend API and frontend application.
Powershell
Bash
Troubleshooting
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:
https://localhost:40443/healthz
Healthy
http://localhost:3000
or refresh the page to use the Chat Copilot application.Issue: Yarn is not working.
Explanation: You may have the wrong Yarn version installed such as v2.x+.
Solution: Use the classic version.
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:
Check out our other repos!
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:
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the MIT license.
# 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;
npm install -g yarn
yarn set version classic
./start.sh
.\Start.ps1
./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}
.\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}
./start-backend.sh
./start.sh
./configure.sh --aiservice AzureOpenAI \
--endpoint {AZURE_OPENAI_ENDPOINT} \
--apikey {API_KEY}
./configure.sh --aiservice OpenAI --apikey {API_KEY}
./install-brew.sh
./install-apt.sh
cd <path to chat-copilot>/scripts/
.\Start-Backend.ps1
.\Start.ps1
-CompletionModel {DEPLOYMENT_NAME} -EmbeddingModel {DEPLOYMENT_NAME} -PlannerModel {DEPLOYMENT_NAME}
.\Configure.ps1 -AIService {AI_SERVICE} -APIKey {API_KEY} -Endpoint {AZURE_OPENAI_ENDPOINT}
cd <path to chat-copilot>\scripts\
.\Install.ps1
Download Details:
Author: Microsoft
Official Github: https://github.com/microsoft/chat-copilot
License: MIT