Azure OpenAI 嵌入问答

一个基于 OpenAI 的简单文档搜索 Web 应用程序。此仓库使用 Azure OpenAI 服务从文档中创建嵌入向量。为了回答用户的问题，它会检索最相关的文档，然后使用 GPT-3 提取与问题匹配的答案。

深入了解企业级问答系统

企业级问答系统基于人工智能社区称为“检索增强生成”（RAG）的模式构建。除了本仓库提供在 Azure 上实现该模式的参考架构外，以下资源可以帮助您熟悉 RAG 中的相关概念，并通过示例学习各个基础产品的 API：

资源	链接	目的	亮点
参考架构	GitHub（本仓库）	企业级开发的入门模板。 - 易于部署且遵循最佳实践的参考架构。	- 前端由 Langchain 协调的 Azure OpenAI 聊天组成。 - 将表单识别器、Azure 搜索和 Redis 组合在一个端到端设计中。 - 支持与 Azure 搜索、Redis 集成。
教育博客文章	Microsoft 博客, GitHub	学习 RAG 解决方案中的构建模块。	- 介绍 RAG 架构中的关键元素。 - 理解向量搜索在 RAG 场景中的作用。 - 了解 Azure 搜索如何支持这一模式。 - 理解提示词和像 Langchain 这样的编排器的作用。
Azure OpenAI API 示例	GitHub	开始使用 Azure OpenAI 功能。	- 示例代码可创建一个作为网页的交互式聊天客户端。 - 帮助您快速上手最新的 Azure OpenAI API
业务流程自动化示例	GitHub	展示使用表单识别器和 Azure 服务实现的多种 BPA 场景。	- 将多个与 BPA 和文档理解相关的示例整合到一个仓库中。 - 包括一个端到端应用，带有用于创建和自定义集成多个 Azure 认知服务管道的 GUI。 - 示例涵盖文档智能和搜索。

重要提示（由 OpenAI 生成）

我们在本仓库的最新更新中对数据格式进行了一些更改。
新格式更加高效，并且兼容最新的标准和库。然而，我们理解有些用户可能已有依赖旧格式的应用程序，暂时无法迁移到新格式。

因此，我们提供了一种方法，让您可以在正在运行的应用程序中继续使用旧格式。您只需将您的 Web 应用程序标签设置为 fruocco/oai-embeddings:2023-03-27_25。这将确保您的应用程序使用 2023 年 3 月 27 日可用的数据格式。我们强烈建议您尽快将应用程序更新为使用新格式。

如果您想切换到新格式，请前往：

• “添加文档” -> “批量添加文档”，然后点击“转换所有文件并添加嵌入”以重新处理您的文档。

使用基于聊天的部署方式（gpt-35-turbo 或 gpt-4-32k 或 gpt-4）运行本仓库

默认情况下，本仓库使用基于指令的模型（如 text-davinci-003）来进行问答和聊天体验。
如果您想使用基于聊天的部署方式（gpt-35-turbo 或 gpt-4-32k 或 gpt-4），请按照此处所述更改环境变量。

运行本仓库

您有多种方式可以运行代码：

• 在 Azure 上部署（WebApp + 批量处理）并结合 Azure 认知搜索
• 在 Azure 上部署（WebApp + Azure Cache for Redis + 批量处理）
• 在 Azure/Azure China 上部署（WebApp + Redis Stack + 批量处理）
• 在 Azure/Azure China 上部署（WebApp + Azure PostgreSQL + 批量处理）
• 在本地 Docker 中运行全部组件（WebApp + Redis Stack + 批量处理）
• 仅在本地 Python 中使用 Conda 运行 WebApp
• 在本地 Python 中使用 venv 运行全部组件
• 在本地 Docker 中运行 WebApp，并连接到现有的 Redis 部署

在 Azure 上部署（WebApp + 批量处理）并结合 Azure 认知搜索

点击“部署到 Azure”按钮，并按照环境变量部分的说明在 Azure 门户中配置您的设置。

请注意，您需要：

• 一个已有的 Azure OpenAI 资源，其中包含模型部署（例如指令模型 text-davinci-003 和嵌入模型 text-embedding-ada-002）

注册 Azure 认知搜索中的向量搜索私有预览版

Azure 认知搜索支持纯向量搜索、纯文本搜索，以及将两者结合的混合模式。对于基于向量的场景，您需要注册向量搜索私有预览版。要注册，请填写此表格：https://aka.ms/VectorSearchSignUp。

预览功能受补充使用条款约束，不提供服务级别协议，不建议用于生产工作负载。

在 Azure 上部署（Web 应用 + Azure Cache for Redis Enterprise + 批量处理）

点击“部署到 Azure”按钮，即可在 Azure 上自动部署一个模板，其中包含运行此示例所需的资源。该选项将预配一个安装了 RediSearch 的 Azure Cache for Redis 实例，用于存储向量并执行相似度搜索。

请注意，您仍然需要：

• 一个已存在的 Azure OpenAI 资源，并已部署模型（例如指令模型 text-davinci-003 和嵌入模型 text-embedding-ada-002）
• 一个已存在的表单识别器资源
• 一个已存在的翻译服务资源
• Azure 市场访问权限。（Azure Cache for Redis Enterprise 使用市场进行 IP 计费）

您需要在部署模板时提供这些资源的终结点和访问密钥信息。

在 Azure/Azure 中国区上部署（Web 应用 + Redis Stack + 批量处理）

点击“部署到 Azure”按钮，并按照 环境变量 部分的说明在 Azure 门户中配置您的设置。

请注意，您需要：

• 一个已存在的 Azure OpenAI 资源，并已部署模型（例如指令模型 text-davinci-003 和嵌入模型 text-embedding-ada-002）
• 一个可选的已存在的表单识别器资源（如果您希望从文档中提取文本）
• 一个可选的已存在的翻译服务资源（如果您希望翻译文档）

在 Azure/Azure 中国区上部署（Web 应用 + Azure PostgreSQL + 批量处理）

点击“部署到 Azure”按钮，并按照 环境变量 部分的说明在 Azure 门户中配置您的设置。

在本地使用 Docker 运行所有组件（Web 应用 + Redis Stack + 批量处理）

首先，克隆仓库：

git clone https://github.com/ruoccofabrizio/azure-open-ai-embeddings-qna
cd azure-open-ai-embeddings-qna

接下来，按照 环境变量 中的说明配置 .env 文件：

cp .env.template .env
vi .env # 或者使用您熟悉的编辑器

最后，运行应用程序：

docker compose up

打开浏览器访问 http://localhost:8080。

这将启动三个 Docker 容器：

• Web 应用本身
• 用于存储嵌入的 Redis Stack
• 批量处理的 Azure 函数

注意：批量处理的 Azure 函数使用 Azure 存储账户来排队待处理的文档。请在用于 AzureWebJobsStorage 环境变量设置的存储账户中创建一个名为 “doc-processing” 的队列。

在本地使用 Python 和 Conda 运行所有组件（仅 Web 应用）

这需要 Redis 在某个地方运行，并且假设您已按照上述说明设置了 .env 文件。在这种情况下，请将 REDIS_ADDRESS 指向您的 Redis 部署。

您可以通过以下命令运行本地 Redis 实例：

 docker run -p 6379:6379 redis/redis-stack-server:latest

您还可以运行本地的批量处理 Azure 函数：

 docker run -p 7071:80 fruocco/oai-batch:latest

创建 Python 的 conda 环境：

conda env create -f code/environment.yml
conda activate openai-qna-env

按照 环境变量 中的说明配置 .env 文件。

运行 Web 应用程序：

cd code
streamlit run OpenAI_Queries.py

在本地使用 Python 和 venv 运行所有组件

这同样需要 Redis 在某个地方运行，并且假设您已按照上述说明设置了 .env 文件。在这种情况下，请将 REDIS_ADDRESS 指向您的 Redis 部署。

您可以通过以下命令运行本地 Redis 实例：

 docker run -p 6379:6379 redis/redis-stack-server:latest

您还可以运行本地的批量处理 Azure 函数：

 docker run -p 7071:80 fruocco/oai-batch:latest

请确保已安装 Python 3.9 或更高版本。

创建 Python 的 venv 环境：

python -m venv .venv
.venv\Scripts\activate

安装 PIP 依赖项：

pip install -r code\requirements.txt

按照 环境变量 中的说明配置 .env 文件。

运行 Web 应用程序：

cd code
streamlit run OpenAI_Queries.py

在本地使用 Docker 运行 Web 应用，并连接到现有的 Redis 部署

选项 1 - 运行预构建的 Docker 镜像

按照 环境变量 中的说明配置 .env 文件。

然后运行：

docker run --env-file .env -p 8080:80 fruocco/oai-embeddings:latest

选项 2 - 自己构建 Docker 镜像

按照 环境变量 中的说明配置 .env 文件。

docker build . -f Dockerfile -t your_docker_registry/your_docker_image:your_tag
docker run --env-file .env -p 8080:80 your_docker_registry/your_docker_image:your_tag

注意：您可以使用

• WebApp.Dockerfile 来构建 Web 应用程序
• BatchProcess.Dockerfile 来构建批量处理的 Azure 函数

从后端使用 QnA API

您可以在由 Azure Function for Batch Processing 公开的数据上使用 QnA API。

POST https://YOUR_BATCH_PROCESS_AZURE_FUNCTION_URL/api/apiQnA
请求体：
    question: str
    history: (str,str) -- 可选
    custom_prompt: str -- 可选
    custom_temperature: float --可选

返回：
{'context': 'Azure 认知搜索简介 - Azure 认知搜索（以前称为“Azure 搜索”）是一项云搜索服务，为开发人员提供基础设施、API 和工具，用于在 Web、移动和企业应用程序中对私有、异构内容构建丰富的搜索体验...'
            '...'
            '...',

 'question': '什么是 ACS？',

 'response': 'ACS 是 Azure 认知搜索的缩写，它是一项云搜索服务，提供基础设施、API 和工具，用于在 Web、移动和企业应用程序中对私有、异构内容构建丰富的搜索体验...'
             '...'
             '...',
             
 'sources': '[https://learn.microsoft.com/en-us/azure/search/search-what-is-azure-search](https://learn.microsoft.com/en-us/azure/search/search-what-is-azure-search)'}

在无历史记录的情况下调用 API 进行 QnA 模式

import requests

r = requests.post('http://YOUR_BATCH_PROCESS_AZURE_FUNCTION_URL/api/apiQnA', json={
    'question': '意大利的首都是哪里？'
    })

在有历史记录的情况下调用 API 进行聊天模式

r = requests.post('YOUR_BATCH_PROCESS_AZURE_FUNCTION_URL/api/apiQnA', json={
    'question': '我可以使用 Python SDK 吗？',
    'history': [
        ("什么是 ACS？", 
        'ACS 是 Azure 认知搜索的缩写，它是一项云搜索服务，提供基础设施、API 和工具，用于在 Web、移动和企业应用程序中对私有、异构内容构建丰富的搜索体验。它包括用于全文搜索的搜索引擎、带有词汇分析和 AI 增强功能的丰富索引，以实现内容提取和转换；丰富的查询语法，支持文本搜索、模糊搜索、自动补全、地理搜索等。ACS 可以通过门户、REST API、.NET SDK 或其他 SDK 创建、加载和查询。此外，它还包含索引层的数据集成、与 Azure 认知服务的 AI 和机器学习集成，以及与 Azure Active Directory 和 Azure Private Link 的安全集成。'
        )
        ]
    })

环境变量

以下是参数说明：

应用设置	值	备注
OPENAI_ENGINE	text-davinci-003	在您的 Azure OpenAI 资源中部署的引擎。例如，基于指令的模型：text-davinci-003；基于聊天的模型：gpt-35-turbo、gpt-4-32k 或 gpt-4。请使用部署名称，而非模型名称。
OPENAI_DEPLOYMENT_TYPE	Text	对于基于指令的引擎（text-davinci-003），填写“Text”；对于基于聊天的部署（gpt-35-turbo、gpt-4-32k 或 gpt-4），填写“Chat”。
OPENAI_EMBEDDINGS_ENGINE_DOC	text-embedding-ada-002	在您的 Azure OpenAI 资源中部署的文档嵌入引擎
OPENAI_EMBEDDINGS_ENGINE_QUERY	text-embedding-ada-002	在您的 Azure OpenAI 资源中部署的查询嵌入引擎
OPENAI_API_BASE	https://YOUR_AZURE_OPENAI_RESOURCE.openai.azure.com/	您的 Azure OpenAI 资源名称。可在 Azure 门户 中获取
OPENAI_API_KEY	YOUR_AZURE_OPENAI_KEY	您的 Azure OpenAI API 密钥。可在 Azure 门户 中获取
OPENAI_TEMPERATURE	0.1	Azure OpenAI 温度参数
OPENAI_MAX_TOKENS	-1	Azure OpenAI 最大令牌数
AZURE_CLOUD	AzureCloud	要使用的 Azure 云环境。AzureCloud 用于全球 Azure，AzureChinaCloud 用于中国 Azure
VECTOR_STORE_TYPE	PGVector	向量存储类型。使用 AzureSearch 进行 Azure 认知搜索，PGVector 用于 Azure PostgreSQL，留空则表示 Redis 或 Azure Cache for Redis Enterprise
AZURE_SEARCH_SERVICE_NAME	YOUR_AZURE_SEARCH_SERVICE_URL	您的 Azure 认知搜索服务名称。可在 Azure 门户 中获取
AZURE_SEARCH_ADMIN_KEY	AZURE_SEARCH_ADMIN_KEY	您的 Azure 认知搜索管理员密钥。可在 Azure 门户 中获取
PGVECTOR_HOST	Your_PG_NAME.postgres.database.azure.com 或 Your_PG_NAME.postgres.database.chinacloudapi.cn
PGVECTOR_PORT	5432
PGVECTOR_DATABASE	YOUR_PG_DATABASE
PGVECTOR_USER	YOUR_PG_USER
PGVECTOR_PASSWORD	YOUR_PG_PASSWORD
REDIS_ADDRESS	api	Redis Stack 的 URL：“api”用于 Docker Compose
REDIS_PORT	6379	Redis 的端口
REDIS_PASSWORD	redis-stack-password	可选——您的 Redis Stack 密码
REDIS_ARGS	--requirepass redis-stack-password	可选——您的 Redis Stack 密码
REDIS_PROTOCOL	redis://
CHUNK_SIZE	500	可选：用于将长文档拆分为多个子文档的分块大小。默认值：500
CHUNK_OVERLAP	100	可选：文档拆分时各分块之间的重叠量。默认：100
CONVERT_ADD_EMBEDDINGS_URL	http://batch/api/BatchStartProcessing	批处理函数的 URL：“http://batch/api/BatchStartProcessing”适用于 Docker Compose
AzureWebJobsStorage	AZURE_BLOB_STORAGE_CONNECTION_STRING FOR_AZURE_FUNCTION_EXECUTION	用于 Azure 函数——批处理的 Azure Blob 存储连接字符串

用于附加功能的可选参数（例如，使用 OCR 提取文档文本）：

应用设置	值	备注
BLOB_ACCOUNT_NAME	YOUR_AZURE_BLOB_STORAGE_ACCOUNT_NAME	可选——如果您想使用文档提取功能，请在 Azure 门户 中获取
BLOB_ACCOUNT_KEY	YOUR_AZURE_BLOB_STORAGE_ACCOUNT_KEY	可选——如果您想使用文档提取功能，请在 Azure 门户 中获取
BLOB_CONTAINER_NAME	YOUR_AZURE_BLOB_STORAGE_CONTAINER_NAME	可选——如果您想使用文档提取功能，请在 Azure 门户 中获取
FORM_RECOGNIZER_ENDPOINT	YOUR_AZURE_FORM_RECOGNIZER_ENDPOINT	可选——如果您想使用文档提取功能，请在 Azure 门户 中获取
FORM_RECOGNIZER_KEY	YOUR_AZURE_FORM_RECOGNIZER_KEY	可选——如果您想使用文档提取功能，请在 Azure 门户 中获取
PAGES_PER_EMBEDDINGS	用于创建嵌入的页数。请注意，每个嵌入的令牌数应少于 3K。	默认：每 2 页创建一个新的嵌入。
TRANSLATE_ENDPOINT	YOUR_AZURE_TRANSLATE_ENDPOINT	可选——如果您想使用翻译功能，请在 Azure 门户 中获取
TRANSLATE_KEY	YOUR_TRANSLATE_KEY	可选——如果您想使用翻译功能，请在 Azure 门户 中获取
TRANSLATE_REGION	YOUR_TRANSLATE_REGION	可选——如果您想使用翻译功能，请在 Azure 门户 中获取
VNET_DEPLOYMENT	false	布尔变量，若要在 VNET 中部署解决方案，则设置为“true”。请同时检查您的 Azure Form Recognizer 和 Azure Translator 端点。

免责声明

本演示文稿、演示及演示模型仅用于信息目的，并且 (1) 不受 SOC 1 和 SOC 2 合规性审计的约束，(2) 并非设计、意图或作为医疗器械或专业医疗建议、诊断、治疗或判断的替代品而提供。微软在此演示文稿、演示及演示模型中不作任何明示或暗示的保证。本演示文稿、演示或演示模型中的任何内容均不会修改微软书面签署协议中的任何条款和条件。这并非要约，适用条款及所提供的信息可能会随时由微软修订或更改。

本演示文稿、演示及演示模型并未授予您或贵组织与本演示文稿、演示及演示模型主题相关的任何专利、商标、版权或其他知识产权的许可。

本演示文稿、演示及演示模型中包含的信息代表微软在演示和/或展示日期对所讨论问题的当前观点，仅在您访问演示模型期间有效。由于微软必须应对不断变化的市场条件，因此不应将其视为微软的承诺，且微软无法保证在演示和/或展示日期之后以及您访问演示模型期间所呈现信息的准确性。

任何微软技术及其组件技术，包括本演示模型，均无意也未被提供作为 (1) 经认证金融服务专业人士，或 (2) 经认证医疗专业人士的专业建议、意见或判断的替代品。合作伙伴或客户有责任确保其使用微软技术构建的任何解决方案符合相关法规要求。

Azure OpenAI Embeddings QnA 快速上手指南

本项目是一个基于 Azure OpenAI 服务的文档搜索与问答（QnA）Web 应用。它利用检索增强生成（RAG）模式，将文档转换为向量嵌入，并通过 GPT 模型提取答案。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

1. 云资源要求

你需要拥有以下 Azure 资源（需提前在 Azure 门户创建）：

• Azure OpenAI Service：已部署以下模型：
  • 指令模型（如 text-davinci-003）或聊天模型（如 gpt-35-turbo, gpt-4）。
  • 嵌入模型（如 text-embedding-ada-002）。
• 可选资源（用于文档解析和翻译）：
  • Azure Form Recognizer (Document Intelligence)
  • Azure Translator
• 存储后端（任选其一，取决于部署方案）：
  • Azure Cognitive Search (需申请 Vector Search Private Preview)
  • Azure Cache for Redis Enterprise (含 RediSearch 模块)
  • Redis Stack (自建或容器化)
  • Azure PostgreSQL

2. 本地开发环境

• 操作系统：Windows, macOS, 或 Linux
• 运行时：
  • Docker & Docker Compose (推荐用于全栈本地运行)
  • Python 3.9+ (用于仅运行 Web 前端)
  • Conda 或 venv (Python 虚拟环境管理工具)
• 其他：Git

---

安装步骤

你可以选择通过 Azure 一键部署，或在本地使用 Docker/Python 运行。

方案 A：一键部署到 Azure (推荐生产试用)

根据你选择的存储后端，点击对应的部署按钮并在 Azure 门户中填写配置参数（参考下方的“环境变量”部分）：

• Azure Cognitive Search: Deploy to Azure
• Redis Enterprise: Deploy to Azure
• Redis Stack: Deploy to Azure
• PostgreSQL: Deploy to Azure

注意：若使用 Azure Cognitive Search 的向量搜索功能，需先在此处注册预览版：Vector Search SignUp。

方案 B：本地 Docker 运行 (全栈：Web + Redis + 批处理)

这是最简单的本地测试方式，会自动启动 Web 应用、Redis 数据库和批处理函数。

1. 克隆仓库：

   git clone https://github.com/ruoccofabrizio/azure-open-ai-embeddings-qna
   cd azure-open-ai-embeddings-qna
   

2. 配置环境变量： 复制模板文件并填入你的 Azure 资源密钥。

   cp .env.template .env
   vi .env 
   # 请使用编辑器打开 .env 文件，填入 OPENAI_API_KEY, REDIS_ADDRESS 等必要信息
   

3. 准备存储队列： 确保你在 .env 中配置的 AzureWebJobsStorage 存储账户中，创建一个名为 doc-processing 的队列。

4. 启动服务：

   docker compose up
   

方案 C：本地 Python 运行 (仅 Web 前端)

如果你已有后端的 Redis 实例和批处理服务，只想运行前端界面：

1. 启动依赖服务 (使用 Docker 快速启动 Redis 和批处理函数)：

   docker run -p 6379:6379 redis/redis-stack-server:latest
   docker run -p 7071:80 fruocco/oai-batch:latest
   

2. 配置 Python 环境 (以 venv 为例)：

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # Mac/Linux:
   source .venv/bin/activate
   
   pip install -r code\requirements.txt
   

3. 配置环境变量： 编辑 .env 文件，将 REDIS_ADDRESS 指向你的 Redis 实例地址。

4. 运行 Web 应用：

   cd code
   streamlit run OpenAI_Queries.py
   

---

基本使用

1. 访问应用

启动成功后，在浏览器中打开：

• Docker 部署：http://localhost:8080
• Python 本地运行：通常默认为 http://localhost:8501 (具体端口请参考 Streamlit 控制台输出)

2. 上传文档并生成向量

1. 在界面中找到 "Add Document" 区域。
2. 选择 "Add documents in Batch"。
3. 上传你的 PDF、Word 或文本文件。
4. 点击 "Convert all files and add embeddings"。
   • 系统将调用 Azure Form Recognizer (如果配置了) 提取文本。
   • 调用 Azure OpenAI 生成向量嵌入。
   • 将结果存入 Redis 或 Azure Search。

3. 进行问答

1. 在聊天框中输入关于文档内容的问题。
2. 系统会检索最相关的文档片段，并利用 GPT 模型生成精准答案。

关键配置说明 (环境变量)

在 .env 文件中，你需要重点关注以下配置：

• 模型切换：
  • 默认使用指令模型 (如 text-davinci-003)。
  • 若要使用聊天模型 (如 gpt-35-turbo, gpt-4)，请修改环境变量中的模型名称配置。
• 数据格式兼容性：
  • 如果你需要兼容旧版本的数据格式，请将 Web 应用标签设置为 fruocco/oai-embeddings:2023-03-27_25。
  • 建议使用最新格式，如需迁移旧数据，请在界面执行一次 "Convert all files and add embeddings"。

提示：对于中国开发者，如果遇到 Docker 拉取镜像缓慢的问题，建议配置国内 Docker 镜像加速器。