Repository files navigation

This sample allows you to build your own integrated large language model (LLM) chat copilot. The sample is built on MicrosoftSemantic Kernel and has three components:

1. A frontend applicationReact web app
2. A backend REST API.NET web API service
3. 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 forgetting started.

To deploy the sample to Azure, please viewDeploying Chat Copilot after meeting therequirements 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)
• Git
• AI Service (one of the following is required)

1. Open PowerShell as an administrator.

   NOTE: Ensure that you havePowerShell Core 6+ installed. This is different from the default PowerShell installed on Windows.

2. Clone this repository

   git clone https://github.com/microsoft/chat-copilot

3. Setup your environment.

   The following is a script to help you install the dependencies required. Feel free to installdotnet,nodejs, andyarn with your method of choice or use this script.

   cd<path to chat-copilot>\scripts\.\Install.ps1

   NOTE: This script will installChocolatey,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 tochange the execution policy (see list ofpolicies andscopes) orunblock the script.

4. 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: ForAzureOpenAI, 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.

5. 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

1. Open Bash as an Administrator.

2. Clone this repository

   git clone https://github.com/microsoft/chat-copilot

3. Configure environment.

   The following is a script to help you install the dependencies required. Feel free to installdotnet,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 usesapt to installdotnet-sdk-7.0,nodejs, andyarn.

   macOS

   ./install-brew.sh

   NOTE: This script useshomebrew to installdotnet-sdk,nodejs, andyarn.

4. Configure Chat Copilot.

   1. For OpenAI

      ./configure.sh --aiservice OpenAI --apikey {API_KEY}

      • API_KEY: TheAPI key for OpenAI.

   2. 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 modelsgpt-35-turbo andtext-embedding-ada-002with custom names (instead of the default names), you need to specifythe 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

5. 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

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 thewebapi README and thememory 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.

• Azure account
• Azure AD Tenant

1. Create anapplication 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 usehttp://localhost:3000.

2. Create a secondapplication registration for the backend web api, using the values below:

   • Supported account types: "Accounts in this organizational directory only ({YOUR TENANT} only - Single tenant)"
   • Donot configure aRedirect 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 theApplication (client) ID for both app registrations as you will need them in future steps.

3. Expose an API within the second app registration

   1. SelectExpose an API from the menu

   2. Add anApplication ID URI

      1. This will generate anapi:// URI

      2. ClickSave to store the generated URI

   3. Add a scope foraccess_as_user

      1. ClickAdd scope

      2. SetScope name toaccess_as_user

      3. SetWho can consent toAdmins and users

      4. SetAdmin consent display name andUser consent display name toAccess copilot chat as a user

      5. SetAdmin consent description andUser consent description toAllows the accesses to the Copilot chat web API as a user

   4. Add the web app frontend as an authorized client application

      1. ClickAdd a client application

      2. ForClient ID, enter the frontend's application (client) ID

      3. Check the checkbox underAuthorized scopes

      4. ClickAdd application

4. Add permissions to web app frontend to access web api as user

   1. Open app registration for web app frontend

   2. Go toAPI Permissions

   3. ClickAdd a permission

   4. Select the tabAPIs my organization uses

   5. Choose the app registration representing the web api backend

   6. Select permissionsaccess_as_user

   7. ClickAdd permissions

5. 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 ID
   • AZURE_AD_INSTANCE(optional): The Azure AD cloud instance for the authenticating users. Defaults tohttps://login.microsoftonline.com.

6. Run Chat Copilot locally. This step starts both the backend API and frontend application.

   Powershell

   .\Start.ps1

   Bash

   ./start.sh

1. 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.

2. Issue:: Challenges using text completion models, such astext-davinci-003

   Solution: For OpenAI, seemodel endpoint compatibility forthe complete list of current models supporting chat completions. For Azure OpenAI, seemodel summary table and region availability.

3. 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:

   1. Confirm the backend service is running. Open a web browser and navigate tohttps://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.
   2. Navigate tohttp://localhost:3000 or refresh the page to use the Chat Copilot application.

4. 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 yarnyarnset version classic

5. 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 priorityecho -e"Package: *\nPin: origin\"packages.microsoft.com\"\nPin-Priority: 1001"| sudo tee /etc/apt/preferences.d/99microsoft-dotnet.pref;# Update and install dotnetsudo apt update;sudo apt install --assume-yes dotnet-sdk-7.0;

Every release is associated with a release branch. For instance, releasev0.9 is on a branch called0.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:

We welcome your contributions and suggestions to the Chat Copilot Sample App! One of the easiestways to participate is to engage in discussions in the GitHub repository.Bug reports and fixes are welcome!

To learn more and get started:

• Read thedocumentation
• Join theDiscord community
• Contribute to the project
• Follow the team on ourblog

This project has adopted theMicrosoft Open Source Code of Conduct.For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any additional questions or comments.

Copyright (c) Microsoft Corporation. All rights reserved.

Licensed under theMIT license.