入门：使用自己的数据聊天（Python 示例）

2025-06-26

本文介绍如何使用 Python 示例代码部署和运行使用你自己的数据的聊天示例。此示例聊天应用程序是使用 Python、Azure OpenAI 服务和通过 Azure AI 搜索检索扩充生成（RAG）生成的。

该应用提供有关虚构公司员工福利的用户问题的解答。它使用 Retrieval-Augmented 生成（RAG）来引用提供的 PDF 文件中的内容，这可能包括：

员工手册
权益概述文档
公司角色和期望列表

通过分析这些文档，应用可以使用准确的上下文相关答案响应自然语言查询。此方法演示如何使用自己的数据为 Azure OpenAI 和 Azure AI 搜索提供智能、特定于域的聊天体验。

你还将了解如何配置应用的设置以修改其响应行为。

完成本文中的步骤后，可以使用自己的代码开始自定义项目。本文是一系列教程的一部分，介绍如何使用 Azure OpenAI 服务和 Azure AI 搜索构建聊天应用。本系列中的其他文章包括：

注意

本文基于一个或多个 AI 应用模板，这些模板提供维护良好的参考实现。这些模板设计为易于部署并提供可靠的高质量起点，用于构建自己的 AI 应用程序。

示例应用体系结构

下图显示了聊天应用的简单体系结构。

此图显示了从客户端到后端聊天应用的示例架构以及数据源。

体系结构的关键组件包括：

托管交互式聊天界面（通常使用 Python Flask 或 JavaScript/React 构建）的 Web 应用程序，并将用户问题发送到后端进行处理。
Azure AI 搜索资源，用于对索引文档（PDF、Word 文件等）执行智能搜索，并返回相关文档摘录（区块）以用于响应。
一个 Azure OpenAI 服务实例，该实例：
- 将文档和用户问题转换为语义相似性搜索的矢量表示形式。
- 提取重要关键字以优化 Azure AI 搜索查询。
- 使用检索到的数据和用户查询合成最终响应。

聊天应用的典型流如下所示：

用户提交问题：用户通过 Web 应用界面输入自然语言问题。
Azure OpenAI 处理问题：后端使用 Azure OpenAI 来：
- 使用 text-embedding-ada-002 模型来生成问题的嵌入。
- （可选）提取关键字以优化搜索相关性
Azure AI 搜索检索相关数据：嵌入或关键字用于在 Azure AI 搜索中对索引内容（如 PDF）执行语义搜索。
将结果与问题相结合：最相关的文档摘录（区块）与用户的原始问题相结合。
Azure OpenAI 生成响应：组合输入将传递给 GPT 模型（例如 gpt-35-turbo 或 gpt-4），这将生成上下文感知答案。
响应将返回到用户：生成的答案显示在聊天界面中。

先决条件

开发容器环境中包含完成本文所需的所有依赖项。可以在 GitHub Codespaces（在浏览器中）或本地使用 Visual Studio Code 运行开发容器。

若要使用本文，需要满足以下先决条件：

GitHub Codespaces （建议）
Visual Studio Code

Azure 订阅。在开始之前，创建一个免费帐户。
Azure 帐户权限。 Azure 帐户必须具有 Microsoft.Authorization/roleAssignments/write 权限。用户访问管理员或所有者等角色满足此要求。
在 Azure 订阅中授予对 Azure OpenAI 的访问权限。在大多数情况下，可以使用对 Azure OpenAI 模型的常规访问权限创建自定义内容筛选器和管理严重性级别。常规访问不需要注册基于批准的访问。有关详细信息，请参阅 Azure AI 服务的受限访问功能。
内容筛选器或滥用修改（可选）。若要创建自定义内容筛选器、更改严重性级别或支持滥用监视，需要正式访问批准。可以通过完成必要的注册表单来申请访问权限。有关详细信息，请参阅注册修改后的内容筛选器和/或滥用监视。
支持和疑难解答访问。若要访问故障排除，请在 GitHub 存储库上提出支持问题。
GitHub 帐户。需要创建存储库分支，并使用 GitHub Codespace，或在本地克隆它。

示例资源的使用成本

此体系结构中使用的大多数资源都属于基本定价层或基于消耗的定价层。这意味着你只需为使用的内容付费，在开发或测试期间费用通常最低。

若要完成此示例，使用 Azure OpenAI、AI 搜索和存储等服务可能会产生少量成本。评估或部署应用后，可以删除所有预配的资源，以避免持续收费。

有关预期成本的详细细分，请参阅 GitHub 存储库中的成本估算示例。

开放开发环境

首先设置已安装所有依赖项的开发环境以完成本文。

GitHub Codespaces （建议）
Visual Studio Code

Azure 订阅。免费创建一个。
Azure 帐户权限。 Azure 帐户必须具有 Microsoft.Authorization/roleAssignments/write 权限。用户访问管理员或所有者等角色满足此要求。
GitHub 帐户。需要创建存储库分支，并使用 GitHub Codespace，或在本地克隆它。

打开开发环境

按照以下说明部署预配置开发环境，其中包含完成本文所需的所有依赖项。

GitHub Codespaces （建议）
Visual Studio Code

对于最简单的和最简化的设置，请使用 GitHub Codespaces。 GitHub Codespaces 运行由 GitHub 托管的开发容器，并为 Web 提供 Visual Studio Code 作为用户界面（UI）。此环境包括预安装的所有必需工具、SDK、扩展和依赖项，因此无需手动配置即可立即开始开发。

使用 Codespaces 可确保：

已安装正确的开发人员工具和版本。
无需在本地安装 Docker、VS Code 或扩展。
快速加入和可重现的环境设置。

重要

所有 GitHub 帐户每月最多可以使用 GitHub Codespaces 60 小时，其中包含 2 个核心实例。如果超出免费配额或使用更大的计算选项，则应用标准 GitHub Codespaces 计费费率。有关详细信息，请参阅 GitHub Codespaces - 每月包含的存储和核心小时数。

若要开始使用示例项目，请在 GitHub 存储库的main分支上Azure-Samples/azure-search-openai-demo创建新的 GitHub 代码空间。

右键单击存储库页面顶部的 “GitHub Codespaces - 打开 ”选项，然后在新窗口中选择“ 打开”链接。这可确保开发容器在全屏专用浏览器选项卡中启动，使你能够访问源代码和内置文档。
在 “创建新代码空间 ”页上，查看 codespace 配置设置，然后选择“ 创建代码空间：

等待 GitHub codespace 启动。启动过程可能需要几分钟时间。
GitHub codespace 打开后，在 codespace 的终端窗格中输入以下命令，使用 Azure 开发人员 CLI 登录到 Azure：
```
azd auth login
```
GitHub 在终端窗格中显示安全代码。
1. 复制终端窗格中的安全代码，然后选择 Enter。此时会打开浏览器窗口。
2. 在提示符下，将安全代码粘贴到浏览器字段中。
3. 按照说明使用 Azure 帐户进行身份验证。

你将在此开发容器的上下文中完成本文中剩余的 GitHub Codespaces 任务。

Visual Studio Code 的开发容器扩展要求在本地计算机上安装 Docker 。扩展使用 Docker 主机在本地托管开发容器，并预安装正确的开发人员工具和依赖项来完成本文。

在本地计算机上，创建名为 my-intelligent-app 的项目目录并更改为该目录：
```
mkdir my-intelligent-app
cd my-intelligent-app
```
在项目目录中打开 Visual Studio Code：
```
code .
```
在 Visual Studio Code 中，通过选择终端>新建终端或使用键盘快捷键Ctrl+Shift+`，打开终端窗格。
在 Visual Studio Code 终端窗格中运行以下命令，将 GitHub 存储库下载到本地计算机：
```
azd init -t azure-search-openai-demo
```
在提示符下，输入环境名称。该名称作为后缀添加到目录名称 my-intelligent-app。使用包含所有小写字母和短划线（-如 myenv）的短名称。不要使用大写字母、数字或特殊字符。环境名称用作资源组名称的一部分。

Visual Studio Code 在文件资源管理器视图中打开 my-intelligent-app 项目目录的内容：
在 活动栏上，选择“开发容器的 远程资源管理器” ，然后在 容器链接中选择重新打开当前文件夹 ：

项目目录可能需要一些时间才能在开发容器中打开。若要监视进度，请选择 “显示 进度”对话框的日志：

等待项目目录在 远程资源管理器 视图中打开，然后继续执行下一步。
在 Visual Studio Code 终端窗格中，使用 Azure 开发人员 CLI 登录到 Azure（azd）：
```
azd auth login
```
从终端窗格中复制代码并将其粘贴到浏览器中。按照系统说明使用 Azure 帐户进行身份验证。

在这个开发容器的环境下，你完成此项目中的剩余练习。

将聊天应用部署到 Azure

示例存储库包含将聊天与自己的数据应用程序部署到 Azure 所需的所有内容，包括：

应用程序源代码（Python）
基础结构即代码文件 (Bicep)
GitHub 集成和 CI/CD 的配置（可选）

使用以下步骤通过 Azure 开发人员命令行工具（azd）部署应用程序。

重要

在本部分中创建的 Azure 资源（尤其是 Azure AI 搜索）可以在预配时立即开始产生费用，即使部署在完成前中断也是如此。若要避免意外费用，请在测试后立即监视 Azure 使用情况并删除未使用的资源。

在 Visual Studio Code 终端窗格中，运行以下命令 azd ，创建 Azure 资源并部署源代码：
```
azd up
```
该过程会根据配置提示你输入以下一个或多个设置：
- 环境名称：此值用作资源组名称的一部分。输入小写字母和短划线（-如 myenv）的短名称。不支持大写字母、数字和特殊字符。
- 订阅：选择要创建资源的订阅。如果未看到所需的订阅，请使用箭头键滚动可用订阅的完整列表。
- 位置：此区域位置用于大多数资源，包括托管。选择离你地理位置较近的区域。
- OpenAI 模型或文档智能资源的位置：选择离您最近的地理位置。如果为位置选择的区域可用于此设置，请选择同一区域。
应用部署可能需要一些时间。等待部署完成，然后继续。
应用成功部署后，终端窗格会显示终结点 URL：
选择终结点 URL 以在浏览器中打开聊天应用程序：

使用聊天应用从 PDF 文件获取答案

聊天应用预加载了来自 PDF 文件的员工权益信息。可以使用聊天应用询问有关权益的问题。以下步骤将引导你完成使用聊天应用的过程。你的答案可能因基础模型更新而有所不同。

在聊天应用中，选择 性能评审中会发生什么情况？ 选项，或在聊天文本框中输入相同的文本。应用返回初始响应：
在答案框中，选择引文：

GitHub Codespaces 将打开右引文窗格，其中包含三个选项卡式区域，焦点位于 “引文 ”选项卡上：

GitHub Codespaces 提供了三个信息选项卡，可帮助你了解聊天应用如何生成答案：

选项卡	描述
思考过程	在聊天中显示问答交互的脚本。可以查看聊天应用 `system` 提供的内容、`user` 输入的问题，以及系统 `assistant` 做的说明。
支持内容	列出用于回答问题和源材料的信息。开发人员设置指定源材料引文数。默认引文数为 3。
引文	显示所选引文的原始来源内容。

完成后，在右窗格中选择当前选定的选项卡。右窗格关闭。

使用设置更改响应行为

特定的 OpenAI 模型确定聊天的智能以及用于与模型交互的设置。 “ 开发人员设置” 选项将打开“ 配置答案生成 ”窗格，可在其中更改聊天应用的设置：

设置	描述
替代提示模板	重写用于根据问题和搜索结果生成答案的提示。
温度	将请求的温度设置为生成答案的大型语言模型（LLM）。较高的温度会引发更多创造性的反应，但这些反应可能不那么有根据。
种子	设置种子以提高模型的响应的可重现性。种子可以是任意整数。
最低搜索分数	为从 Azure AI 搜索返回的搜索结果设置最低分数。分数范围取决于在检索模式设置中，您是使用混合（默认）、仅矢量还是仅文本。
最低重新排序器分数	为从语义重排器返回的搜索结果设置最小分数。分数始终介于 0-4 之间。分数越高，结果与问题在语义上越相关。
检索这么多搜索结果	设置要从 Azure AI 搜索检索的搜索结果数。更多的结果可以增加找到正确答案的可能性，但可能导致模型“在中间丢失”。可以在引用窗格的思想过程和支持内容选项卡中查看返回的源。
包括类别	指定要在生成搜索结果时包括的类别。使用下拉列表进行选择。默认操作是包括所有类别。
排除类别	指定要从搜索结果中排除的任何类别。默认数据集中没有使用任何类别。
使用语义排名器进行检索	启用 Azure AI 搜索语义排名器，该模型基于用户查询的语义相似性重新调用搜索结果。
使用语义字幕	向 LLM 发送语义标题，而不是完整的搜索结果。语义标题是在语义排名过程中从搜索结果中提取的。
建议后续问题	要求 LLM 根据用户的查询建议后续问题。
检索模式	设置 Azure AI 搜索查询的检索模式。默认作是矢量 + 文本（混合），它使用矢量搜索和全文搜索的组合。 Vectors 选项仅使用矢量搜索。 “ 文本 ”选项仅使用全文搜索。混合方法是最佳方法。
流式处理聊天完成响应	在生成内容时持续流式传输对聊天 UI 的响应。

以下步骤将引导你完成更改设置的过程。

在浏览器中，选择 “开发人员设置” 选项。
选中 “建议跟进问题 ”复选框以启用该选项，然后选择“ 关闭 ”以应用设置更改。
在聊天应用中，在问题框中输入文本以重新提问问题：
```
What happens in a performance review?
```
聊天应用答案现在包括建议的后续问题：
再次选择 “开发人员设置” 选项，然后取消选择 “使用语义排名器进行检索 ”选项。关闭设置。
再次询问相同的问题，并注意到聊天应用中答案的差异。

借助语义排序器：“在 Contoso Electronics 的绩效评估期间，主管将讨论你过去一年的工作表现，并就需要改进的领域提供反馈。你还将有机会讨论即将到来的一年的目标和目标。审查是经理和员工之间的双向对话，鼓励员工在过程中诚实和开放（1）。评审期间提供的反馈应该是积极和建设性的，旨在帮助员工发展和发展其角色。员工将收到绩效评审的书面摘要，其中包括对即将到来的一年（1）绩效、反馈和目标和目标的评分。

没有语义排名器的情况下：“在 Contoso Electronics 的绩效评估中，你的主管将讨论你过去一年的表现，并提供有关有待提高的方面的反馈。这是一个双向对话，鼓励你诚实和开放（1）。评审期间提供的反馈应该是积极和建设性的，旨在帮助你发展和发展你的角色。你将收到评论的书面摘要，包括你即将来年的绩效、反馈和目标评分（1）。