---

page_type: sample languages:

• azdeveloper
• python
• bash
• bicep
• prompty products:
• azure
• azure-openai
• azure-cognitive-search
• azure-cosmos-db urlFragment: contoso-chat name: Contoso Chat - 基于 Azure AI Foundry 和 Prompty 的零售 RAG Copilot（Python 实现） description: 构建、评估并部署一个基于 RAG 的零售 Copilot，该 Copilot 能够根据零售商的产品和客户数据生成有据可依的回复，以回答客户的提问。

---

Contoso Chat：基于 Azure AI Foundry 和 Prompty 的零售 RAG Copilot

目录

• 概述
• 功能 · 架构图
• 先决条件
• 入门
  • GitHub Codespaces
  • VS Code Dev Containers
  • 本地环境
• 开发
• 测试
• 部署
• 指导 - 区域可用性 · 成本 · 安全性
• 研讨会 🆕 · 版本
• 资源 · 行为准则 · 负责任的 AI 指南

重要安全提示

本模板及其包含的应用程序代码和配置旨在展示 Microsoft Azure 的特定服务和工具。我们强烈建议客户在未实施或启用额外的安全功能之前，不要将此代码用于生产环境。

如需了解有关智能应用程序的更全面的最佳实践和安全建议，请访问我们的官方文档。

【警告】

本仓库中使用的部分功能处于预览阶段。 预览版不提供服务级别协议，也不建议用于生产工作负载。某些功能可能不受支持或功能受限。更多信息请参阅Microsoft Azure 预览版的补充使用条款。

本项目中包含示例应用程序代码。您可以使用或修改此应用代码，也可以将其移除并替换为自己的代码。

---

概述

Contoso Outdoor 是一家专注于户外爱好者的徒步与露营装备的在线零售商。其网站提供海量产品目录，因此客户需要产品信息和推荐来帮助他们做出合适的购买决策。

本示例实现了 Contoso Chat——一款专为 Contoso Outdoor 打造的零售 Copilot 解决方案，采用“检索增强生成”设计模式，使聊天机器人的回复能够基于零售商的产品和客户数据。客户可以在网站上用自然语言提出问题，并获得与自身购买历史相关的回复及潜在推荐——同时遵循负责任的 AI 实践，确保回复的质量与安全性。

本示例展示了使用 Azure AI 和 Prompty 以“代码优先”方式构建 RAG 基础 Copilot 的端到端工作流（GenAIOps）。通过探索并部署本示例，您将学会：

1. 使用 Prompty 快速构思并迭代应用程序原型
2. 部署并使用 Azure OpenAI 模型进行聊天、嵌入和评估
3. 使用 Azure AI Search（索引）和 Azure CosmosDB（数据库）存储您的数据
4. 利用 AI 辅助的评估流程对聊天回复质量进行评估
5. 将应用程序作为 FastAPI 端点托管在 Azure Container Apps 上
6. 使用 Azure Developer CLI 配置并部署解决方案
7. 通过内容安全与评估支持负责任的 AI 实践

功能

该项目模板提供以下功能：

• Azure OpenAI 用于嵌入、聊天和评估模型
• Prompty 用于创建和管理提示，以实现快速迭代
• Azure AI Search 用于执行语义相似度搜索
• Azure CosmosDB 用于在 NoSQL 数据库中存储客户订单
• Azure Container Apps 用于在 Azure 上托管聊天 AI 端点

此外，还附带：

• 用于快速原型设计的示例产品和客户数据
• 用于聊天和评估工作流的示例应用程序代码
• 使用 Prompty 资产的示例数据集和自定义评估器

架构图

先决条件

要部署并探索本示例，您需要：

1. 有效的 Azure 订阅——在此注册免费账户
2. 有效的 GitHub 账户——在此注册免费账户
3. 对 Azure OpenAI 服务的访问权限——了解有限访问权限
4. 对 Azure AI Search 的访问权限——使用语义排名器（高级功能）
5. 可用配额：text-embedding-ada-002、gpt-4o-mini 和 gpt-4

我们建议将部署区域选择为 eastus2 或 francecentral，因为这些区域可以支持所有上述模型。除此之外，您还需要具备以下能力：

• 配置 Azure Monitor（免费层）
• 配置 Azure Container Apps（免费层）
• 配置 Azure CosmosDB 用于 NoSQL（免费层）

从工具使用角度来看，熟悉以下内容会很有帮助：

• Visual Studio Code（以及相关扩展）
• GitHub Codespaces 和开发容器
• Python 和 Jupyter Notebook
• Azure CLI、Azure Developer CLI 以及命令行操作

入门指南

您有三种方式来搭建开发环境：

1. 使用 GitHub Codespaces——在云端预置的开发环境
2. 使用 Docker Desktop——在本地设备上预置的开发环境
3. 手动搭建——可完全掌控本地环境的各个配置细节

我们建议选择 GitHub Codespaces，因为它启动最快、维护开销最低。请从下方选择一种方式——点击以展开相应部分并查看详细信息。

GitHub Codespaces

1. 您可以通过 GitHub Codespaces 虚拟运行此模板。点击此按钮即可在浏览器中打开一个基于 Web 的 VS Code 实例：

   

2. 等待 Codespaces 环境准备就绪（可能需要几分钟），然后在该 VS Code 实例中打开一个新的终端——接着进入开发步骤。

VS Code 开发容器

另一种相关选项是使用 VS Code 开发容器，它会通过 Dev Containers 扩展 在您的_本地 Visual Studio Code 编辑器_中打开项目：

1. 如果尚未安装，请先安装 Docker Desktop，然后启动它。

2. 点击下方按钮，在本地 VS Code 中打开项目：

   

3. 等待 VS Code 窗口显示项目文件（可能需要几分钟），然后在该 VS Code 实例中打开一个新的终端——接着进入开发步骤。

本地环境

1. 在本地设备上安装所需工具：

   • Azure Developer CLI (azd)
   • Python 3.10+
   • Docker Desktop
   • Git

   Windows 用户请注意： 如果您_不使用容器来运行此示例_，请注意我们的部署后钩子会使用 Shell 脚本。尽管我们会针对不同的本地设备环境更新脚本，但我们仍建议使用 git bash 来正确运行示例。

2. 在本地设备上初始化项目：

   • 创建一个新文件夹 contoso-chat 并切换到该目录
   • 运行以下命令下载项目模板。请注意，此命令会初始化一个 Git 仓库，因此您无需再克隆该仓库。

     azd init -t contoso-chat
     

3. 手动安装项目依赖。如果您使用上述开发容器选项，则此步骤将自动为您完成。

       cd src/api
       pip install -r requirements.txt
   

现在您可以进入下一步——开发——我们将在此步骤中预配所需的 Azure 基础设施，并使用 azd 从模板部署应用程序。

开发

在完成项目的设置后（可通过 Codespaces、Dev Containers 或 本地环境 实现），您应该已打开 Visual Studio Code 编辑器，项目文件已加载，并且打开了一个用于运行命令的终端。现在让我们验证所有必需的工具是否已安装。

az version
azd version
prompty --version
python --version

接下来我们可以继续执行后续步骤——点击展开以查看详细说明。

1️⃣ | 使用 Azure 进行身份验证

1. 打开 VS Code 终端并使用 Azure CLI 进行身份验证。如果从 GitHub Codespaces 进行身份验证，请使用 --use-device-code 选项。按照提示完成身份验证流程。

   az login --use-device-code
   

2. 现在在同一终端中使用 Azure Developer CLI 进行身份验证。按照提示完成身份验证流程。

   azd auth login --use-device-code
   

3. 您应该会看到：已登录 Azure。 这将在您的项目目录下的 .azure/ 文件夹中创建一个用于存储此次部署配置的文件夹。如果您需要，还可以创建多个 azd 环境。

2️⃣ | 使用 AZD 预配并部署

1. 运行 azd up 命令，即可通过一条命令同时完成基础设施的预配与应用程序的部署。（如有需要，您也可以分别使用 azd provision 和 azd deploy）

   azd up
   

2. 系统将提示您选择用于预配资源的_订阅_、映射到资源组的_环境名称_以及部署的_位置_。请参考【区域可用性】指南，选择具有所需模型和配额的区域。

3. azd up 命令可能需要 15–20 分钟才能完成。成功完成后，控制台将显示 SUCCESS: ... 的消息。现在我们可以验证部署结果。

3️⃣ | 验证基础设施

1. 访问 Azure 门户，查找上面创建的 rg-ENVNAME 资源组。
2. 在“基本”部分中单击“部署”链接，等待所有部署完成。
3. 返回“概览”页面，您应该会看到：35 个部署，15 个资源。
4. 在列表中单击“Azure CosmosDB 资源”。
   • 进入该资源的详细信息页面，单击“数据资源管理器”。
   • 确认已创建名为“customers”的数据库，并且其中包含数据条目。
5. 在列表中单击“Azure AI Search 资源”。
   • 进入该资源的详细信息页面，单击“搜索资源管理器”。
   • 确认已创建名为“contoso-products”的索引，并且其中包含数据条目。
6. 在列表中单击“Azure 容器应用”资源。
   • 进入该资源的详细信息页面，单击“应用程序 URL”。
   • 确认您看到一个托管的端点，页面上显示“Hello World”消息。
7. 接下来，访问 Azure AI Foundry 门户。
   • 登录——系统应自动使用您现有的 Azure 凭据登录。
   • 单击“所有资源”，您应该会看到“AIServices”和“Hub”资源。
   • 单击 Hub 资源，您应该会看到列出的“AI Project”资源。
   • 单击该项目资源，进入“部署”页面以验证模型。
8. ✅ | 恭喜！ 您的 Azure 项目基础设施已准备就绪！

4️⃣ | 验证部署

1. azd up 过程还会将应用程序部署为 Azure 容器应用。
2. 进入 ACA 资源页面，单击“应用程序 URL”以查看端点。
3. 在默认部署路径后添加 /docs 后缀，以访问 Swagger API 测试页面。
4. 单击“试用”以解锁输入字段——您会看到“question”、“customer_id”、“chat_history”。
   • 输入“question” = “告诉我关于防水帐篷的信息”
   • 输入“customer_id” = 2
   • 输入“chat_history” = []
   • 单击“执行”以查看结果：您应该会看到一个有效的响应，其中包含产品目录中匹配的帐篷列表及更多详细信息。
5. ✅ | 恭喜！ 您的聊天 AI 部署已正常运行！

测试

我们可以从两个层面来考虑测试：手动_验证和_自动化_评估。前者是交互式的，通过单个测试提示在迭代过程中对原型进行验证；后者则是基于代码的，利用测试提示数据集来评估原型响应在多种不同提示输入下的质量和安全性，并根据内置或自定义的评估器，针对_连贯性、流畅性、_相关性_和_事实依据_等指标进行打分。

1️⃣ | 手动测试（交互式）

Contoso Chat 应用程序以 FastAPI 应用的形式实现，可部署到 Azure Container Apps 中的托管端点。API 实现位于 src/api/main.py 文件中，目前公开了两条路由：

• / —— 显示默认的“Hello World”消息
• /api/create_request —— 这是我们用于测试提示的聊天 AI 端点

要在本地进行测试，我们先运行 FastAPI 开发服务器，然后通过 /docs 路由上的 Swagger 端点，以与测试已部署版本相同的方式测试本地提供的端点。

• 切换到仓库的根文件夹
• 运行 fastapi dev ./src/api/main.py —— 应该会启动一个开发服务器
• 点击“在浏览器中打开”，在新标签页中预览开发服务器页面
  • 您应该会看到：“Hello, World”，路径为 /
• 在浏览器标签页的路径 URL 后加上 /docs
  • 您应该会看到：“FASTAPI”页面，列出两条路由
  • 点击 POST 路由，再点击“试用”以解锁输入
• 输入一个测试提示
  • 输入 question = “告诉我关于防水帐篷的信息”
  • 输入 customer_id = 2
  • 输入 chat_history = []
  • 点击执行查看结果：您应该会看到一条有效的响应，其中包含产品目录中匹配的帐篷列表及更多详细信息。

1. ✅ | 恭喜！ —— 您已成功在本地测试了该应用

2️⃣ | AI 辅助评估（基于代码）

仅测试一个提示有助于快速原型设计和创意构思。但一旦我们的应用程序设计完成，我们就希望针对多样化的测试提示，对响应的_质量和安全性_进行验证。本示例展示了如何使用 Prompty 实现的自定义评估器来进行AI 辅助评估。

• 访问 src/api/evaluators/ 文件夹
• 打开 evaluate-chat-flow.ipynb 笔记本——选择“内核”以激活
• 清空输入后，点击“全部运行”——将启动使用 data.jsonl 测试数据集的评估流程
• 评估完成后（需时 10 分钟以上），您应该会看到：
  • results.jsonl —— 聊天模型对测试输入的响应
  • evaluated_results.jsonl —— 评估模型对这些响应的评分
  • 表格形式的结果——包括连贯性、流畅性、相关性、事实依据等得分

想更深入地了解自定义评估器的工作原理吗？请查看 src/api/evaluators/custom_evals 文件夹，探索相关的 Prompty 资源及其模板说明。

Prompty 工具还支持内置的_追踪_功能，以提升可观测性。在评估运行期间，会生成一个 .runs/ 子文件夹，其中包含 .tracy 文件，记录了追踪数据。点击其中一个文件，即可在 Visual Studio Code 中查看_追踪视图_，帮助您深入分析或调试交互流程。这是一项新功能，敬请期待后续使用指南的更新。

部署

该解决方案使用 Azure Developer CLI 进行部署。azd up 命令实际上会依次调用 azd provision 和 azd deploy——让您只需一条命令即可完成基础设施的配置与应用程序的部署。之后再次运行 azd up（例如，在对应用程序进行修改后），应会更加迅速，仅在确有需要时才会重新部署应用程序并更新基础设施配置。随后，您可以按照前面所述的方式测试已部署的端点。

指导

区域可用性

本模板目前使用以下模型：gpt35-turbo、gpt-4 和 text-embedding-ada-002，这些模型可能并非在所有 Azure 区域都可用，或者在受支持的区域中您的订阅可能没有足够的配额。请查阅最新的区域可用性信息，并在部署时相应地选择区域。

我们建议使用 francecentral

成本

各项服务的定价可能因区域和使用情况而异，具体费用难以准确估算。您可以通过 Azure 定价计算器，结合以下服务，对本项目的架构成本进行_估算_：

• Azure OpenAI — 标准层，使用 gpt-4、gpt-4o-mini 和 text-embedding-ada-002 模型。参见定价
• Azure AI Search — 基础层，启用语义排名器。参见定价
• Azure Cosmos DB for NoSQL — 无服务器，免费层。参见定价
• Azure Monitor — 无服务器，免费层。参见定价
• Azure Container Apps — 无服务器，免费层。参见定价

安全性

本模板使用托管身份来认证关键 Azure 服务，包括 Azure OpenAI、Azure AI Search 和 Azure Cosmos DB。应用程序可通过托管身份获取 Microsoft Entra 令牌，而无需管理任何凭据。这不仅免去了开发者自行管理这些凭据的麻烦，也降低了操作复杂度。

此外，我们还添加了一个GitHub Action 工具，用于扫描基础设施即代码文件，并生成一份包含所有检测到问题的报告。为确保最佳实践，我们建议所有基于我们的模板创建解决方案的人员，务必在您的仓库中启用Github 秘密扫描设置。

研讨会

本示例提供了一个 docs/workshop 文件夹，其中包含面向开发者的分步指导，帮助您拆解代码库，理解如何自行配置、构思、构建、评估和部署应用程序，并使用您自己的数据。

• 研讨会可以作为_讲师引导的选项_提供（例如，在Microsoft AI Tour上）
• 研讨会也可以在家以自主进度的实验课形式完成，使用您自己的订阅。

实验室指南

1. 在线查看研讨会 - 在浏览器中查看预先构建的研讨会版本
2. 本地查看研讨会 - 该研讨会使用 Mkdocs 构建。要本地预览，
   • 安装 mkdocs：pip install mkdocs-material
   • 切换到文件夹：cd docs/workshop
   • 启动预览：mkdocs serve
   • 打开浏览器并访问指定的预览 URL

在使用研讨会时遇到问题或疑问？请提交带有 documentation 标签的新问题。

资源

1. Prompty 文档
2. Azure AI Foundry 文档
3. 使用 Azure AI 服务开发 AI 应用程序
4. 结合 Azure 开发者 CLI 的 Azure AI 模板

行为准则

本项目已采纳Microsoft 开源行为准则。了解更多信息：

• Microsoft 开源行为准则
• Microsoft 行为准则常见问题解答
• 如有任何问题或疑虑，请联系 opencode@microsoft.com

如需更多信息，请参阅行为准则常见问题解答，或如有其他问题或意见，请联系 opencode@microsoft.com。

责任AI指南

本项目遵循以下责任AI指南与最佳实践，请在使用本项目前仔细阅读：

• Microsoft 责任AI指南
• 适用于 Azure OpenAI 模型的责任AI实践
• 安全评估透明度说明

---

Contoso Chat 快速上手指南

---

环境准备

系统要求

• 操作系统：Windows、Linux 或 macOS（推荐使用 Linux 或 macOS）
• Python 3.10+
• Docker Desktop（用于本地开发或容器环境）
• Azure 账户（免费注册）
• GitHub 账户（免费注册）

前置依赖

• Azure CLI (az)
• Azure Developer CLI (azd)
• Prompty 工具
• Git

提示：如果你在中国，可以使用国内镜像源加速安装过程。例如，使用 清华源 安装 Python 包。

---

安装步骤

1. 克隆项目

你可以通过以下命令在本地初始化项目：

azd init -t contoso-chat

这将创建一个名为 contoso-chat 的文件夹，并下载项目模板。

进入项目目录：

cd contoso-chat

2. 安装依赖

进入 API 目录并安装 Python 依赖项：

cd src/api
pip install -r requirements.txt

如果你使用的是国内网络，建议配置 pip 使用国内镜像源，如：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

3. 配置 Azure 认证

在终端中运行以下命令登录 Azure：

az login --use-device-code

接着，使用 Azure Developer CLI 登录：

azd auth login --use-device-code

---

基本使用

1. 初始化 Azure 环境

运行以下命令来部署基础设施并启动应用：

azd up

该命令会提示你选择以下内容：

• Azure 订阅
• 环境名称（对应资源组）
• 部署区域（推荐使用 eastus2 或 francecentral）

注意：部分功能为预览版，不适用于生产环境。

2. 启动本地服务（可选）

如果需要在本地运行服务，可以在 src/api 目录下启动 FastAPI 应用：

uvicorn main:app --reload

然后访问 http://localhost:8000 查看 API 文档。

---

总结

通过以上步骤，你可以快速搭建并运行 Contoso Chat 项目，体验基于 RAG（检索增强生成）的零售助手功能。更多高级功能和细节，请参考完整文档。