注意：这是一个示例应用程序，旨在帮助您了解语义知识库和人工智能如何在 Web 应用程序中协同工作。此示例不适用于生产环境部署。

聊天助手示例应用程序

本示例允许您构建自己的集成大型语言模型（LLM）聊天助手。该示例基于 Microsoft 的 Semantic Kernel 构建，包含三个组件：

1. 前端应用 React Web 应用
2. 后端 REST API .NET Web API 服务
3. 用于处理语义记忆的 .NET 工作器服务。

这些快速入门指南可在本地运行该示例。您也可以在 Chat Copilot 的 Microsoft Learn 官方文档页面上找到入门内容。

如需将示例部署到 Azure，请在满足下方要求后查看部署 Chat Copilot。

重要提示：本示例仅用于教育目的，不建议用于生产环境部署。

重要提示：每次聊天交互都会调用 Azure OpenAI/OpenAI，这将消耗可能产生费用的令牌。

要求

运行本示例需要以下内容：

• .NET 8.0 SDK (通过 Setup install.* 脚本安装)
• Node.js (通过 Setup install.* 脚本安装)
• Yarn (通过 Setup install.* 脚本安装)
• Git
• AI 服务（必须选择以下之一）

AI 服务	要求
Azure OpenAI	- 访问权限 - 资源 - 已部署的模型 (gpt-4o 和 text-embedding-ada-002) - 终结点 - API 密钥
OpenAI	- 账户 - API 密钥

指令

Windows

1. 以管理员身份打开 PowerShell。

   注意：请确保已安装 PowerShell Core 6+。这与 Windows 上默认安装的 PowerShell 不同。

2. 克隆此仓库

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

3. 设置您的环境。

   下面是一个帮助您安装所需依赖项的脚本。您可以选择自己喜欢的方式安装 dotnet、nodejs 和 yarn，也可以使用此脚本。

   cd <chat-copilot 路径>\scripts\
   .\Install.ps1
   

   注意：此脚本将安装 Chocolatey、dotnet-8.0-sdk、nodejs 和 yarn。

   注意：如果您收到脚本未经过数字签名或无法在系统上执行的错误，您可能需要 更改执行策略（请参阅 策略列表 和 作用域），或者 取消阻止该脚本。

4. 配置 Chat Copilot。

   .\Configure.ps1 -AIService {AI_SERVICE} -APIKey {API_KEY} -Endpoint {AZURE_OPENAI_ENDPOINT}
   

   • AI_SERVICE：AzureOpenAI 或 OpenAI。

   • API_KEY：Azure OpenAI 或 OpenAI 的 API 密钥。

   • AZURE_OPENAI_ENDPOINT：Azure OpenAI 资源的端点地址。仅在使用 Azure OpenAI 时需要此参数；如果使用 OpenAI，则省略 -Endpoint。

   • 重要提示：对于 AzureOpenAI，如果您以自定义名称部署了模型 gpt-4o 和 text-embedding-ada-002（而非默认名称），还需使用以下参数：

     -CompletionModel {DEPLOYMENT_NAME} -EmbeddingModel {DEPLOYMENT_NAME}
     

     打开 .\Configure.ps1 脚本即可查看所有可用参数。

5. 在本地运行 Chat Copilot。此步骤将同时启动后端 API 和前端应用。

   .\Start.ps1
   

   第一次运行时，Yarn 包可能需要几分钟才能完成安装。

   注意：请确认弹出窗口未被阻止，并且您已使用注册应用程序时所用的同一账户登录。

   • （可选）仅启动后端：

     .\Start-Backend.ps1
     

Linux/macOS

1. 以管理员身份打开 Bash。

2. 克隆此仓库

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

3. 配置环境。

   下面是一个帮助您安装所需依赖项的脚本。您可以选择自己喜欢的方式安装 dotnet、nodejs 和 yarn，也可以使用此脚本。

   cd <chat-copilot 路径>/scripts/
   

   Ubuntu/Debian Linux

   ./install-apt.sh
   

   注意：此脚本使用 apt 安装 dotnet-sdk-8.0、nodejs 和 yarn。

   macOS

   ./install-brew.sh
   

   注意：此脚本使用 homebrew 安装 dotnet-sdk、nodejs 和 yarn。

4. 配置 Chat Copilot。

   1. 对于 OpenAI

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

      • API_KEY：OpenAI 的 API 密钥。

   2. 对于 Azure OpenAI

      ./configure.sh --aiservice AzureOpenAI \
                     --endpoint {AZURE_OPENAI_ENDPOINT} \
                     --apikey {API_KEY}
      

      • AZURE_OPENAI_ENDPOINT：Azure OpenAI 资源的端点地址。
      • API_KEY：Azure OpenAI 的 API 密钥。

      重要提示：如果您以自定义名称部署了模型 gpt-4o 和 text-embedding-ada-002（而非默认名称），则需要通过三个额外的参数指定部署名称：

      ./configure.sh --aiservice AzureOpenAI \
                     --endpoint {AZURE_OPENAI_ENDPOINT} \
                     --apikey {API_KEY} \
                     --completionmodel {DEPLOYMENT_NAME} \
                     --embeddingmodel {DEPLOYMENT_NAME}
      

5. 在本地运行 Chat Copilot。此步骤将同时启动后端 API 和前端应用。

   ./start.sh
   

   第一次运行时，Yarn 包可能需要几分钟才能完成安装。

   注意：请确认弹出窗口未被阻止，并且您已使用注册应用程序时所用的同一账户登录。

   • （可选）仅启动后端：

     ./start-backend.sh
     

（可选）运行 内存管道

默认情况下，Web API 配置为不使用内存管道进行同步文档处理。要启用异步文档处理，您需要配置 Web API 和内存管道。有关更多信息，请参阅 Web API README 和 内存管道 README。

（可选）通过 Azure AD 启用后端身份验证

默认情况下，Chat Copilot 在本地运行时不进行身份验证，使用来宾用户配置文件。如果您希望启用 Azure Active Directory 身份验证，请按照以下步骤操作。

要求

• Azure 帐户
• Azure AD 租户

指令

1. 为前端 Web 应用创建一个应用程序注册，使用以下值：

   • 支持的帐户类型：仅此组织目录中的帐户（仅限 {YOUR TENANT} - 单租户）
   • 重定向 URI（可选）：单页应用程序（SPA），并使用 http://localhost:3000。

2. 为后端 Web API 创建第二个应用程序注册，使用以下值：

   • 支持的帐户类型：仅此组织目录中的帐户（仅限 {YOUR TENANT} - 单租户）
   • 请勿配置 重定向 URI（可选）

   注意：如果您希望允许多租户和个人 Microsoft 帐户使用您的应用程序，也可以使用其他帐户类型。这样做可能会带来更多的用户，从而增加成本。

   请记下两个应用程序注册的 应用程序（客户端）ID，您将在后续步骤中需要它们。

3. 在第二个应用程序注册中公开 API

   1. 从菜单中选择 公开 API

   2. 添加 应用程序 ID URI

      1. 这将生成一个 api:// URI

      2. 单击 保存 以存储生成的 URI

   3. 为 access_as_user 添加范围

      1. 单击 添加范围

      2. 将 范围名称 设置为 access_as_user

      3. 将 谁可以同意 设置为 管理员和用户

      4. 将 管理员同意显示名称 和 用户同意显示名称 设置为 以用户身份访问 Copilot 聊天

      5. 将 管理员同意描述 和 用户同意描述 设置为 允许以用户身份访问 Copilot 聊天 Web API

   4. 将 Web 应用前端添加为授权的客户端应用程序

      1. 单击 添加客户端应用程序

      2. 对于 客户端 ID，输入前端的应用程序（客户端）ID

      3. 勾选 授权范围 下的复选框

      4. 单击 添加应用程序

4. 为 Web 应用前端添加以用户身份访问 Web API 的权限

   1. 打开 Web 应用前端的应用程序注册

   2. 转到 API 权限

   3. 点击 添加权限

   4. 选择 我的组织使用的 API 选项卡

   5. 选择代表 Web API 后端的应用程序注册

   6. 选择权限 access_as_user

   7. 点击 添加权限

5. 使用附加参数运行配置脚本以设置身份验证。

   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 或 OpenAI。
   • API_KEY：用于 Azure OpenAI 或 OpenAI 的 API 密钥。
   • AZURE_OPENAI_ENDPOINT：Azure OpenAI 资源的 Endpoint 地址。仅在使用 Azure OpenAI 时需要此参数；如果使用 OpenAI，则省略 -Endpoint。
   • FRONTEND_APPLICATION_ID：与前端应用程序注册关联的 应用程序（客户端）ID。
   • BACKEND_APPLICATION_ID：与后端应用程序注册关联的 应用程序（客户端）ID。
   • TENANT_ID：您的 Azure AD 租户 ID。
   • AZURE_AD_INSTANCE (可选)：用于身份验证用户的 Azure AD 云实例。默认为 https://login.microsoftonline.com。

6. 在本地运行 Chat Copilot。此步骤将同时启动后端 API 和前端应用程序。

   PowerShell

   .\Start.ps1
   

   Bash

   ./start.sh
   

可选配置：带有 On-Behalf-Of 流程的 Ms Graph API 插件

此原生插件允许使用委托权限通过 On-Behalf-Of（OBO）流程执行 Microsoft Graph API。

OBO 流程用于确保后端 API 以用户的标识调用，而不是中间层应用程序（本例中为 WebApi）的托管标识或服务主体。

此外，这还确保已获得同意，以便客户端应用（WebApp）可以调用中间层应用（WebApi），而中间层应用则有权调用后端资源（MSGraph）。

此示例未在 UI 中实现增量同意，因此所有要使用的 Graph 范围都必须在中间层应用程序注册中获得“管理员同意”。

更多信息请参阅 OBO readme.md。

要求

必须启用通过 Azure AD 的后端身份验证。启用后端身份验证的详细说明如下。

限制

• 目前，该插件仅支持 GET 操作。未来更新可能会增加对其他类型操作的支持。
• 返回大量结果的 Graph 查询可能会达到 AI 模型的令牌限制，从而导致错误。
• 此示例未实现增量同意。

故障排除

1. 问题: 无法加载聊天。

   详情: interactionin_progress: 交互当前正在进行中。

   解释: 当应用程序配置为与浏览器不同的 AAD 租户时（例如，个人/MSA 帐户与工作/学校帐户），WebApp 可能会显示此错误。

   解决方案: 使用隐私/无痕浏览器标签页，或清除浏览器凭据/Cookie。请确认您使用的是注册应用程序时所用的同一帐户登录。

2. 问题: 使用文本补全模型时遇到困难，例如 text-davinci-003。

   解决方案: 对于 OpenAI，请参阅 模型端点兼容性，以获取支持聊天补全的当前模型完整列表。对于 Azure OpenAI，请参阅 模型摘要表及区域可用性。

3. 问题: localhost SSL 证书错误 / CORS 错误

   

   解释: 您的浏览器可能正在阻止前端访问后端，同时等待您授权连接。

   解决方案:

   1. 确认后端服务正在运行。打开网页浏览器并导航至 https://localhost:40443/healthz
      • 您应看到确认消息：Healthy
      • 如果浏览器提示您确认访问不安全网站的风险，您必须先确认，前端才能连接到后端服务器。
   2. 导航至 http://localhost:3000 或刷新页面，以使用 Chat Copilot 应用程序。

4. 问题: Yarn 无法正常工作。

   解释: 您可能安装了错误版本的 Yarn，例如 v2.x+。

   解决方案: 使用经典版本。

   npm install -g yarn
   yarn set version classic
   

5. 问题: 缺少 /usr/share/dotnet/host/fxr 文件夹。

   详情: 在 Linux 上运行 dotnet 命令时，“发生严重错误。文件夹 [/usr/share/dotnet/host/fxr] 不存在”。

   解释: .NET (Core) 最初发布用于 Linux 时，并未在官方 Ubuntu 软件源中提供。因此，许多人添加了 Microsoft 的 APT 软件源来安装它。现在，这些软件包已包含在 Ubuntu 软件源中，但与 Microsoft 提供的软件包存在冲突。此错误是由于混合安装的软件包导致的。（来源: StackOverflow)

   解决方案:

   # 移除所有现有软件包，以达到干净状态：
   sudo apt remove --assume-yes dotnet*;
   sudo apt remove --assume-yes aspnetcore*;
   sudo apt remove --assume-yes netstandard*;
   
   # 设置 Microsoft 软件源的优先级
   echo -e "Package: *\nPin: origin \"packages.microsoft.com\"\nPin-Priority: 1001" | sudo tee /etc/apt/preferences.d/99microsoft-dotnet.pref;
   
   # 更新并安装 dotnet
   sudo apt update;
   sudo apt install --assume-yes dotnet-sdk-8.0;
   

关于分支的说明

每个版本都与一个发布分支相关联。例如，版本 v0.9 位于名为 0.9 的分支上。 一旦发布完成，该分支将不再更新。唯一的例外是最新发布的分支，它只会接收错误修复。 这样做是为了给那些不希望频繁出现破坏性更改、不愿处于技术前沿（以及伴随而来的各种问题）的人们提供一定的稳定性。

请查看我们的其他仓库！

如果您想深入了解 Semantic Kernel 和人工智能，您可能也会对 Semantic Kernel 团队支持的其他仓库感兴趣：

仓库	描述
Semantic Kernel	一个轻量级 SDK，可快速且轻松地将尖端的 LLM 技术集成到您的应用程序中。
Semantic Kernel 文档	Semantic Kernel 文档的主页，这些文档也出现在 Microsoft Learn 网站上。
Semantic Kernel 入门项目	用于 Semantic Kernel 的入门项目，帮助您更轻松地开始使用。
Semantic Memory	一项服务，允许您创建用于摄取、存储和查询知识的管道。

加入社区

我们欢迎您对 Chat Copilot 示例应用的贡献和建议！参与最简单的方式之一就是在 GitHub 仓库中参与讨论。 欢迎提交错误报告和修复！

要了解更多信息并开始使用：

• 阅读 文档
• 加入 Discord 社区
• 贡献 到该项目
• 在我们的 博客 上关注团队

行为准则

本项目已采用 Microsoft 开源行为准则。 如需更多信息，请参阅 行为准则常见问题解答 或发送电子邮件至 opencode@microsoft.com 以提出任何其他问题或意见。

许可证

版权所有 © 微软公司。保留所有权利。

根据 MIT 许可证 授权。

Chat Copilot 快速上手指南

Chat Copilot 是一个基于 Microsoft Semantic Kernel 构建的示例应用，旨在帮助开发者理解如何在 Web 应用中集成大型语言模型（LLM）。该应用包含 React 前端、.NET 后端 API 以及用于处理语义记忆的 .NET 工作服务。

注意：本项目仅用于教育和演示目的，不建议用于生产环境。使用时会调用 Azure OpenAI 或 OpenAI 服务，可能产生 Token 费用。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

系统要求

• 操作系统：Windows (PowerShell Core 6+)、Linux (Ubuntu/Debian) 或 macOS
• 版本控制：Git

核心依赖

您需要安装以下运行时环境（可通过后续脚本自动安装，也可手动安装）：

• .NET 8.0 SDK
• Node.js
• Yarn

AI 服务账号（二选一）

您必须拥有以下任一服务的访问权限及密钥：

服务提供商	必备资源
Azure OpenAI	- 访问权限 - 已部署的资源 - 已部署的模型：gpt-4o 和 text-embedding-ada-002 - Endpoint 地址 - API Key
OpenAI	- 账户 - API Key

---

2. 安装步骤

第一步：克隆项目

打开终端（Windows 请使用管理员身份的 PowerShell），执行以下命令克隆仓库：

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

第二步：安装依赖

项目提供了自动化脚本来安装 .NET、Node.js 和 Yarn。

Windows 用户

在 chat-copilot 根目录下运行：

cd scripts
.\Install.ps1
cd ..

注：该脚本会自动安装 Chocolatey 包管理器及相关依赖。若遇到执行策略错误，请参考 PowerShell 官方文档调整执行策略或使用 Unblock-File 解锁脚本。

Linux (Ubuntu/Debian) 用户

cd scripts
./install-apt.sh
cd ..

macOS 用户

cd scripts
./install-brew.sh
cd ..

第三步：配置 AI 服务

根据您的 AI 服务提供商运行配置脚本。

场景 A：使用 OpenAI

将 {API_KEY} 替换为您的实际密钥。

Windows:

.\Configure.ps1 -AIService OpenAI -APIKey {API_KEY}

Linux/macOS:

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

场景 B：使用 Azure OpenAI

将 {API_KEY} 和 {AZURE_OPENAI_ENDPOINT} 替换为您的实际信息。如果您部署模型时使用了自定义名称（非默认的 gpt-4o 等），还需指定 -CompletionModel 和 -EmbeddingModel 参数。

Windows:

.\Configure.ps1 -AIService AzureOpenAI -APIKey {API_KEY} -Endpoint {AZURE_OPENAI_ENDPOINT}
# 若使用自定义模型名称，追加参数：
# -CompletionModel {DEPLOYMENT_NAME} -EmbeddingModel {DEPLOYMENT_NAME}

Linux/macOS:

./configure.sh --aiservice AzureOpenAI \
               --endpoint {AZURE_OPENAI_ENDPOINT} \
               --apikey   {API_KEY}
# 若使用自定义模型名称，追加参数：
# --completionmodel {DEPLOYMENT_NAME} --embeddingmodel {DEPLOYMENT_NAME}

---

3. 基本使用

配置完成后，启动本地服务。该命令会同时启动后端 API 和前端 React 应用。

启动应用

Windows:

.\Start.ps1

Linux/macOS:

./start.sh

提示：首次运行时，Yarn 安装前端包可能需要几分钟时间。请确保浏览器未拦截弹出窗口，并使用注册应用时相同的账户登录。

访问界面

启动成功后，浏览器会自动打开或在控制台显示访问地址（通常为 http://localhost:3000）。您现在可以在网页中与集成的 LLM 进行对话测试。

（可选）仅启动后端

如果您只想运行后端 API 进行调试：

Windows:

.\Start-Backend.ps1

Linux/macOS:

./start-backend.sh