本示例展示了如何使用 LangChain.js 和 Azure 构建基于检索增强生成（RAG）的无服务器 AI 聊天体验。该应用托管在 Azure 静态 Web 应用和 Azure Functions上，向量数据库则使用 Azure Cosmos DB for NoSQL。你可以将其作为构建更复杂 AI 应用程序的起点。

[!TIP] 你可以使用 Ollama 在本地免费测试此应用程序。请按照“本地开发”部分中的说明开始操作。

概述

构建 AI 应用程序可能既复杂又耗时，但借助 LangChain.js 和 Azure 的无服务器技术，可以大大简化这一过程。此应用程序是一个聊天机器人，它利用一组企业文档为用户查询生成响应。

我们提供了示例数据，使此示例可以直接试用，但你也可以自由替换为自己的数据。我们以一家名为 Contoso Real Estate 的虚构公司为例，其客户可以通过该体验就产品使用问题向客服提问。示例数据包括服务条款、隐私政策以及支持指南等文档。

该应用程序由多个组件构成：

• 一个使用 Lit 构建的单聊 Web 组件，并托管在 Azure 静态 Web 应用上的 Web 应用。代码位于 packages/webapp 文件夹中。

• 一个使用 Azure Functions 构建的无服务器 API，利用 LangChain.js 处理文档并为用户的聊天请求生成响应。代码位于 packages/api 文件夹中。

• 一个用于存储聊天会话、从文档中提取的文本以及 LangChain.js 生成的向量的数据库，使用的是 Azure Cosmos DB for NoSQL。

• 一个用于存储源文档的文件存储，使用的是 Azure Blob 存储。

我们使用 AI 聊天应用的 HTTP 协议来实现 Web 应用与 API 之间的通信。

特性

• 无服务器架构：采用 Azure Functions 和 Azure 静态 Web 应用，实现完全无服务器部署。
• 检索增强生成 (RAG)：结合 Azure Cosmos DB 和 LangChain.js 的强大功能，提供相关且准确的回复。
• 聊天记录历史：为每位用户维护个人聊天历史，方便他们回顾之前的对话。
• 可扩展且经济高效：利用 Azure 的无服务器服务，提供可扩展且经济高效的解决方案。
• 本地开发：支持使用 Ollama 进行本地开发，无需任何云成本即可进行测试。

开始使用

有多种方式可以开始使用该项目。

最快捷的方式是使用 GitHub Codespaces，它会为你提供一个预配置好的环境。或者，你也可以按照以下说明 设置本地环境。

[!IMPORTANT] 如果你想完全在本地使用 Ollama 运行此示例，必须按照“本地环境”部分中的说明操作。

使用本地环境

您需要在本地机器上安装以下工具：

• Node.js LTS
• Azure 开发者 CLI
• Git
• PowerShell 7+ (仅适用于 Windows 用户)
  • 重要提示：请确保可以从 PowerShell 命令行运行 pwsh.exe。如果无法运行，您可能需要升级 PowerShell。
  • 您也可以使用 Git Bash 或 WSL 来运行 Azure 开发者 CLI 命令，而无需使用 PowerShell。
• Azure Functions Core Tools (通常会随 NPM 自动安装，只有在 API 启动失败时才需手动安装)

然后您可以获取项目代码：

1. Fork 该项目以创建您自己的仓库副本。
2. 在您的分支仓库中，选择 Code 按钮，然后选择 Local 选项卡，并复制您分支仓库的 URL。

3. 打开终端并运行以下命令克隆仓库： git clone <your-repo-url>

使用 GitHub Codespaces

您可以通过 GitHub Codespaces 直接在浏览器中运行此项目，它将打开一个基于 Web 的 VS Code：

使用 VSCode 开发容器

与 Codespaces 类似的选项是 VS Code 开发容器，它将使用 Dev Containers 扩展在您本地的 VS Code 实例中打开项目。

您还需要在本地机器上安装 Docker 才能运行容器。

运行示例

有多种方式可以运行此示例：在本地使用 Ollama 或 Azure OpenAI 模型，或者将其部署到 Azure。

将示例部署到 Azure

Azure 前提条件

• Azure 账户。如果您是 Azure 新用户，可以 免费注册 Azure 账户，获得免费的 Azure 积分开始使用。如果是学生，还可以通过 Azure for Students 获取免费积分。
• 已启用 Azure OpenAI 服务访问权限的 Azure 订阅。您可以通过 此表格申请访问权限。
• Azure 账户权限：
  • 您的 Azure 账户必须具有 Microsoft.Authorization/roleAssignments/write 权限，例如 基于角色的访问控制管理员、用户访问管理员 或 所有者。如果您没有订阅级别的权限，必须为现有资源组授予 RBAC 权限，并 部署到该现有资源组。
  • 您的 Azure 账户还需具备订阅级别的 Microsoft.Resources/deployments/write 权限。

成本估算

有关在 Azure 上运行此示例的成本估算详情，请参阅 成本估算。

部署示例

1. 打开终端并导航到项目根目录。
2. 运行 azd auth login 进行 Azure 身份验证。
3. 运行 azd up 将应用程序部署到 Azure。此操作将预配 Azure 资源、部署示例，并根据 ./data 文件夹中的文件构建搜索索引。
   • 系统会提示您选择资源的基础位置。如果您不确定选择哪个位置，可以选择 eastus2。
   • 默认情况下，OpenAI 资源将部署到 eastus2。您可以通过 azd env set AZURE_OPENAI_RESOURCE_GROUP_LOCATION <location> 设置其他位置。目前仅支持少数几个位置，这些位置基于 OpenAI 模型可用性表，并且可能会随着可用性的变化而更新。

部署过程需要几分钟时间。完成后，您将在终端中看到 Web 应用程序的 URL。

现在您可以在浏览器中打开 Web 应用程序，并开始与机器人聊天。

增强安全性

在企业环境中部署示例时，您可能希望实施更严格的安全限制，以保护您的数据和资源。有关更多信息，请参阅 增强安全性 指南。

启用 CI/CD

如果您希望为您的分支仓库启用持续部署，需要先配置 Azure 管道：

1. 在您的分支项目的根目录下打开终端。
2. 运行 azd auth login 进行 Azure 身份验证。
3. 运行 azd pipeline config 配置从 GitHub Actions 连接到 Azure 所需的密钥和变量。
   • 此命令将设置必要的 Azure 服务主体，并配置 GitHub 仓库的密钥。
   • 按照提示完成配置。

配置完成后，每当您将更改推送到主分支时，GitHub Actions 工作流就会自动将您的应用程序部署到 Azure。

清理

要清理由此示例创建的所有 Azure 资源：

1. 运行 azd down --purge
2. 当系统询问您是否确定继续时，输入 y

资源组及所有资源将被删除。

在本地使用 Ollama 运行示例

如果你的机器资源足够，你可以完全在本地运行这个示例，而无需使用任何云资源。为此，你首先需要安装 Ollama，然后运行以下命令以在你的机器上下载模型：

ollama pull llama3.1:latest
ollama pull nomic-embed-text:latest

[!NOTE] llama3.1 模型会下载几 GB 的数据，因此根据你的网络连接速度，可能需要一些时间。

之后，你需要安装 NPM 依赖项：

npm install

然后，你可以通过运行以下命令来启动应用程序，这将同时在本地启动 Web 应用和 API：

npm start

接着，打开一个新的终端窗口并同时运行以下命令，将 /data 文件夹中的 PDF 文档上传到 API：

npm run upload:docs

这一步只需要执行一次，除非你想要添加更多文档。

现在，你可以在浏览器中打开 http://localhost:8000 来开始与机器人聊天。

[!NOTE] 虽然本地模型通常足以回答问题，但有时它们可能无法完全遵循关于引用和后续问题的高级格式化指令。这是预期的行为，也是使用较小本地模型的一个局限性。

在本地使用 Azure OpenAI 模型运行示例

首先，你需要预配运行示例所需的 Azure 资源。按照将示例部署到 Azure 部分的说明将示例部署到 Azure，然后你就可以使用已部署的 Azure 资源在本地运行示例。

部署完成后，你应该会在 packages/api 文件夹中看到一个 .env 文件。该文件包含使用 Azure 资源运行应用程序所需的环境变量。

要运行示例，你可以使用与 Ollama 设置相同的命令。这将同时在本地启动 Web 应用程序和 API：

npm start

打开浏览器中的 http://localhost:8000 URL，即可开始与机器人聊天。

请注意，当你使用 azd up 将示例部署到 Azure 时，文档会自动上传。

[!TIP] 你可以通过简单地删除 packages/api/.env 文件并重新启动应用程序，切换回使用 Ollama 模型。要重新生成 .env 文件，可以运行 azd env get-values > packages/api/.env。

资源

以下是一些资源，可以帮助你深入了解本示例中使用的技术：

• LangChain.js 文档
• 使用 JavaScript 的生成式 AI
• 面向初学者的生成式 AI
• Azure OpenAI 服务
• Azure Cosmos DB for NoSQL
• Ask YouTube：LangChain.js + Azure 快速入门示例
• 使用 Azure OpenAI 和 Azure AI Search 的聊天 + 企业数据
• 用聊天彻底革新你的企业数据：基于 Azure OpenAI 和 AI Search 的下一代应用

你还可以在这里找到更多 Azure AI 示例。

常见问题解答

你可以在常见问题解答中找到常见问题的答案。

故障排除

如果你在运行或部署此示例时遇到任何问题，请查看故障排除指南。如果仍然无法解决问题，请在此仓库中提交一个问题。

指导

有关如何使用此示例的更详细指导，请参阅教程。

获取帮助

如果你在构建 AI 应用时遇到困难或有任何疑问，请加入：

如果你在构建过程中有产品反馈或遇到错误，请访问：

贡献

本项目欢迎贡献和建议。大多数贡献都需要你同意一份贡献者许可协议 (CLA)，声明你有权且确实授予我们使用你贡献的权利。有关详情，请访问 https://cla.opensource.microsoft.com。

当你提交拉取请求时，CLA 机器人会自动判断你是否需要提供 CLA，并相应地标记 PR（例如状态检查、评论）。只需按照机器人提供的指示操作即可。对于使用我们 CLA 的所有仓库，你只需执行一次此操作。

本项目采用了微软开源行为准则。有关更多信息，请参阅行为准则常见问题解答，或如有其他疑问或意见，请联系 opencode@microsoft.com。

商标

本项目可能包含项目、产品或服务的商标或徽标。对微软商标或徽标的授权使用必须遵守并遵循微软商标与品牌指南。在本项目的修改版本中使用微软商标或徽标时，不得造成混淆或暗示微软的赞助。任何第三方商标或徽标的使用均受其各自政策的约束。

Serverless-chat-langchainjs 快速上手指南

本项目展示了如何使用 LangChain.js 和 Azure Serverless 技术构建一个基于检索增强生成（RAG）的无服务器 AI 聊天应用。它支持使用企业文档作为知识库，通过 Azure Cosmos DB 进行向量存储，并提供本地开发模式（使用 Ollama）以零成本进行测试。

环境准备

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

系统要求

• Node.js: LTS 版本 (>= 20)
• 操作系统: Windows, macOS 或 Linux
  • Windows 用户注意: 需要安装 PowerShell 7+ (确保 pwsh.exe 可用)，或者使用 Git Bash / WSL。

前置依赖工具

请安装以下工具：

1. Git: 下载地址
2. Azure Developer CLI (azd): 安装指南
3. Azure Functions Core Tools:
   • 通常随 NPM 自动安装，若 API 启动失败请手动安装。
   • 官方文档

提示: 若仅进行本地测试（不使用 Azure 云资源），您还需要安装 Ollama 并拉取模型（如 llama3.1）。

安装步骤

1. 获取代码

首先 Fork 项目到您的 GitHub 账户，然后克隆到本地：

git clone <your-repo-url>
cd serverless-chat-langchainjs

或者直接使用 GitHub Codespaces 在线开发（无需本地配置）：

2. 部署到 Azure (云端运行)

如果您希望使用 Azure OpenAI 和云服务运行完整应用：

前置条件：

• 拥有 Azure 账号及订阅。
• 订阅已启用 Azure OpenAI 服务访问权限。
• 账号具备 Microsoft.Authorization/roleAssignments/write 和 Microsoft.Resources/deployments/write 权限。

部署命令：

# 1. 登录 Azure
azd auth login

# 2. 部署应用（创建资源、部署代码、构建索引）
azd up

执行过程中会提示选择区域，推荐选择 eastus2。部署完成后，终端将显示 Web 应用的访问 URL。

3. 本地运行 (零成本测试)

如果您希望使用本地模型（Ollama）进行测试，无需 Azure 账号：

1. 确保已安装 Ollama 并运行模型：

   ollama pull llama3.1
   ollama serve
   

2. 在项目根目录按照 Local Development 相关说明配置环境变量（通常需设置 LLM_ENDPOINT 指向本地 Ollama 地址）。
3. 启动本地开发服务器（参考项目 package.json 中的脚本，通常为）：

   npm install
   npm run dev
   

基本使用

启动应用

完成上述“部署”或“本地运行”步骤后，应用将启动。

• 云端版: 在浏览器打开 azd up 输出的 URL。
• 本地版: 通常访问 http://localhost:8000 (具体端口视配置而定)。

体验功能

1. 对话交互: 在聊天界面输入问题，系统将基于 ./data 文件夹中的示例文档（Contoso Real Estate 公司的服务条款、隐私政策等）生成回答。
2. 上传文档: 您可以替换 ./data 文件夹中的内容为您自己的企业文档，重新运行索引构建流程（云端部署时自动执行，本地需参考相关脚本），即可构建专属知识库聊天机器人。
3. 历史记录: 应用会自动保存用户的聊天会话历史，方便回溯。

架构简述

• 前端: 基于 Lit 构建的 Web 组件，托管于 Azure Static Web Apps。
• 后端: 使用 Azure Functions 运行 LangChain.js 逻辑，处理文档摄入和问答生成。
• 存储: 使用 Azure Cosmos DB (NoSQL) 存储向量数据，Azure Blob Storage 存储源文件。