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 two components: a frontend React web app and a backend .NET web API service.
These quick-start instructions run the sample locally. To deploy the sample to Azure, please view Deploying Chat Copilot.
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 script)
- Node.js (via Setup script)
- Yarn (via Setup script)
- Azure account
- Azure AD Tenant
- AI Service
AI Service | Requirement |
---|---|
Azure OpenAI | - Access - Resource - Deployed models ( gpt-35-turbo and text-embedding-ada-002 ) - Endpoint - API key |
OpenAI | - Account - API key |
- Follow these instructions and use the values below:
Supported account types
: "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)"Redirect URI (optional)
: Single-page application (SPA) and use http://localhost:3000.
- Take note of the
Application (client) ID
. Chat Copilot will use this ID for authentication.
-
Open PowerShell as an administrator.
-
Setup your environment.
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} -ClientId {AZURE_APPLICATION_ID}
-
AI_SERVICE
:AzureOpenAI
orOpenAI
. -
API_KEY
: TheAPI key
for Azure OpenAI or for OpenAI. -
AZURE_OPENAI_ENDPOINT
: The Azure OpenAI resourceEndpoint
address. Omit-Endpoint
if using OpenAI. -
AZURE_APPLICATION_ID
: TheApplication (client) ID
associated with the registered application. -
(Optional): To set a specific Tenant Id, use the parameter:
-TenantId {TENANT_ID}
-
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:-CompletionModel {DEPLOYMENT_NAME} -EmbeddingModel {DEPLOYMENT_NAME} -PlannerModel {DEPLOYMENT_NAME}
-
-
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.
-
Open Bash as an administrator.
-
Configure environment.
cd <path to chat-copilot>/scripts/ chmod +x *.sh
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.
./Configure.sh --aiservice {AI_SERVICE} --apikey {API_KEY} --endpoint {AZURE_OPENAI_ENDPOINT} --clientid {AZURE_APPLICATION_ID}
-
AI_SERVICE
:AzureOpenAI
orOpenAI
. -
API_KEY
: TheAPI key
for Azure OpenAI or for OpenAI. -
AZURE_OPENAI_ENDPOINT
: The Azure OpenAI resourceEndpoint
address. Omit--endpoint
if using OpenAI. -
AZURE_APPLICATION_ID
: TheApplication (client) ID
associated with the registered application. -
(Optional): To set a specific Tenant Id, use the parameter:
--tenantid {TENANT_ID}
-
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:--completionmodel {DEPLOYMENT_NAME} --embeddingmodel {DEPLOYMENT_NAME} --plannermodel {DEPLOYMENT_NAME}
-
-
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.
-
Ensure you created the required application registration mentioned in Register an application
-
Create a second application registration to represent the web api
For more details on creating an application registration, go here.
-
Give the app registration a name
-
As Supported account type choose
Accounts in any organizational directory and personal Microsoft Accounts
-
Do not configure a Redirect Uri
-
-
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 with a generated for you -
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 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 My APIs
-
Choose the app registration representing the web api backend
-
Select permissions
access_as_user
-
Click Add permissions
-
-
Update frontend web app configuration
-
Open .env file
-
Set the value of
REACT_APP_AAD_API_SCOPE
to your application ID URI followed by the scopeaccess_as_user
, e.g.api://12341234-1234-1234-1234-123412341234/access_as_user
-
-
Update backend web api configuration
-
Open appsettings.json
-
Set the value of
Authorization:AzureAd:Audience
to your application ID URI
-
-
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;