向量样本 - Azure AI 搜索

此仓库提供了 Python、C#、REST 和 JavaScript 代码示例，用于演示 Azure AI 搜索中的 向量支持。

从 REST API 版本 2023-07-01-Preview 到较新版本的 API，存在一些重大变更。这些重大变更同样适用于针对该 REST API 版本的 Azure SDK 测试版包。有关迁移指南，请参阅 升级 REST API。

预览功能在 补充使用条款 下提供。

demo-python 示例

示例	描述
demo-python 自述文件	不断增长的笔记本集合，展示了向量搜索支持的各个方面，包括数据分块、文本和图像内容及查询的嵌入，并使用多种框架和技术。

demo-dotnet 示例

示例	描述
DotNetVectorDemo	一个 .NET 控制台应用程序，调用 Azure OpenAI 将数据向量化。然后调用 Azure AI 搜索来创建、加载和查询向量数据。
DotNetIntegratedVectorizationDemo	一个 .NET 控制台应用程序，调用 Azure AI 搜索来创建索引、索引器、数据源和技能集。数据由 Azure 存储账户提供。技能集在索引过程中以及查询执行时都会调用 Azure OpenAI 来对文本查询进行向量化。
QuantizationAndStorageOptions	一个 .NET 控制台应用程序，演示了 窄数据类型 和内置标量量化，从而减少内存和磁盘上的向量索引大小。它还禁用了在查询响应中返回向量的存储，如果您在查询中不返回向量，则无需启用此功能。

demo-java 示例

示例	描述
demo-vectors	一个 Java 控制台应用程序，调用 Azure OpenAI 将数据向量化。然后调用 Azure AI 搜索来创建、加载和查询向量数据。
demo-integrated-vectorization	一个 Java 控制台应用程序，调用 Azure AI 搜索来创建索引、索引器、数据源和技能集。数据由 Azure 存储账户提供。技能集在索引过程中以及查询执行时都会调用 Azure OpenAI 来对文本查询进行向量化。

demo-javascript 示例

示例	描述
JavaScriptVectorDemo	单个文件夹包含三个代码示例。azure-search-vector-sample.js 脚本仅调用 Azure OpenAI，用于为索引中的字段生成嵌入。docs-text-openai-embeddings.js 程序是一个端到端代码示例，调用 Azure OpenAI 生成嵌入，并调用 Azure AI 搜索来创建、加载和查询包含向量的索引。query-text-openai-embeddings.js 脚本则为向量查询生成嵌入。

其他向量样本和工具

• azure-ai-search-lab 一个用于尝试 Azure 中各种 AI 驱动搜索场景的学习与实验实验室。它包括一个 Web 应用程序前端，该前端使用 Azure AI 搜索和 Azure OpenAI 执行具有多种选项的搜索——从简单的关键词搜索，到语义排名、向量和混合搜索，以及使用生成式 AI 以多种方式回答搜索查询。这使您能够快速了解每种选项的作用、它们如何影响搜索结果，以及不同方法之间的比较。
• chat-with-your-data-solution-accelerator 一个用于部署多个 Azure 资源以构建自定义“与您的数据对话”解决方案的模板。使用此加速器可以创建符合编码最佳实践的生产就绪解决方案。
• Azure Search OpenAI 演示 一个在 Azure 上运行的检索增强生成模式示例应用，使用 Azure AI 搜索进行检索，并使用 Azure OpenAI 大型语言模型来驱动 ChatGPT 式和问答体验。使用“vectors”分支可以利用向量检索功能。
• Azure Search OpenAI 演示 - C# 一个在 Azure 上运行的检索增强生成模式示例应用，使用 Azure AI 搜索进行检索，并使用 Azure OpenAI 大型语言模型通过 C# 实现 ChatGPT 式和问答体验。
• Azure OpenAI 嵌入问答与作为向量存储的 Azure 搜索（GitHub）一个简单的 Web 应用程序，用于支持 OpenAI 的文档搜索。该仓库使用 Azure OpenAI 服务从文档中创建嵌入向量，以便通过 Azure AI 搜索进行检索，并借助 Azure OpenAI 大型语言模型来实现 ChatGPT 式和问答体验，从而回答用户的问题。
• ChatGPT 检索插件 Azure 搜索向量数据库 ChatGPT 检索插件允许您通过自然语言提问轻松找到个人或工作文档。Azure AI 搜索现在作为官方向量数据库受到支持。
• Azure 搜索向量搜索演示 Web 应用模板 一个基于 React 的向量搜索演示 Web 应用模板，使用 Azure OpenAI 进行文本搜索，使用 Cognitive Services Florence Vision API 进行图像搜索。
• Azure 搜索比较工具

文档

• Azure AI 搜索文档

  • Azure AI 搜索中的检索增强生成 (RAG)
  • 向量搜索概述
  • 混合搜索概述
  • 创建向量索引
  • 查询向量索引
  • 向量搜索算法
  • REST API 参考

• Azure OpenAI 服务文档

• Azure AI 计算机视觉文档

Azure AI Search 向量搜索示例快速上手指南

本指南基于 azure-search-vector-samples 仓库，帮助开发者快速在 Azure 环境中构建和测试向量搜索（Vector Search）功能。该仓库提供了 Python、.NET、Java 和 JavaScript 的完整代码示例，涵盖数据分块、嵌入生成、索引创建及混合查询等核心场景。

环境准备

在开始之前，请确保您具备以下环境和资源：

系统要求

• 操作系统：Windows, macOS, 或 Linux
• 运行时环境（根据所选语言示例任选其一）：
  • Python 3.8+ (推荐用于 demo-python)
  • .NET 6.0+ (用于 demo-dotnet)
  • Java JDK 11+ (用于 demo-java)
  • Node.js 14+ (用于 demo-javascript)

前置依赖与 Azure 资源

您需要拥有以下 Azure 资源并获取相应的连接字符串和密钥：

1. Azure AI Search 服务：需启用向量搜索功能（建议创建时选择支持向量的层级）。
2. Azure OpenAI 服务：用于生成文本或图像的嵌入向量（Embeddings）。
   • 注：若无法使用 Azure OpenAI，部分示例支持替换为其他兼容 OpenAI API 的模型服务。
3. Azure Storage 账户（可选）：部分集成向量化示例（Integrated Vectorization）需要此资源作为数据源。

依赖安装

克隆仓库后，进入对应语言的示例目录安装依赖。

Python 示例：

git clone https://github.com/Azure-Samples/azure-search-vector-samples.git
cd azure-search-vector-samples/demo-python
pip install -r requirements.txt

.NET 示例：

cd azure-search-vector-samples/demo-dotnet/DotNetVectorDemo
dotnet restore

JavaScript 示例：

cd azure-search-vector-samples/demo-javascript
npm install

提示：国内开发者若遇到 pip 或 npm 下载缓慢，可临时切换至国内镜像源：

• Pip: pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
• Npm: npm config set registry https://registry.npmmirror.com

安装步骤与配置

大多数示例通过环境变量或配置文件来管理凭证。以 Python 笔记本示例为例，配置步骤如下：

1. 复制配置模板： 在 demo-python 目录下，将 .env.sample 复制为 .env。

   cp .env.sample .env
   

2. 填写凭证信息： 编辑 .env 文件，填入您的 Azure 资源信息：

   AZURE_SEARCH_SERVICE_ENDPOINT=https://<your-search-service>.search.windows.net
   AZURE_SEARCH_ADMIN_KEY=<your-admin-key>
   AZURE_OPENAI_ENDPOINT=https://<your-openai-resource>.openai.azure.com/
   AZURE_OPENAI_API_KEY=<your-openai-key>
   AZURE_OPENAI_DEPLOYMENT_NAME=text-embedding-ada-002
   

3. 验证连接： 确保防火墙允许本地机器访问 Azure 服务端点，或使用 Azure Cloud Shell 进行运行。

基本使用

以下以 Python (demo-python) 为例，展示最基础的向量搜索流程。其他语言（.NET/Java/JS）逻辑类似，均包含“生成嵌入 -> 创建索引 -> 写入数据 -> 执行查询”四个步骤。

场景：构建一个简单的文本向量索引并查询

1. 启动 Jupyter Notebook： 进入 demo-python 目录并启动服务：

   jupyter notebook
   

2. 运行核心示例： 打开名为 basic-vector-search.ipynb (或类似名称的基础示例笔记本) 。

3. 执行代码单元： 按顺序执行以下逻辑的代码块（无需修改代码，仅需确保 .env 配置正确）：

   步骤 A: 生成嵌入 (Embedding Generation) 调用 Azure OpenAI 将文本转换为向量。

   from openai import AzureOpenAI
   
   client = AzureOpenAI(
       azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
       api_key=os.getenv("AZURE_OPENAI_API_KEY"),
       api_version="2023-05-15"
   )
   
   text = "Azure AI Search supports vector search capabilities."
   response = client.embeddings.create(input=text, model=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"))
   vector = response.data[0].embedding
   

   步骤 B: 创建向量索引 (Create Index) 定义包含 vector 字段的索引架构。

   from azure.search.documents.indexes import SearchIndexClient
   from azure.search.documents.indexes.models import SearchField, SearchFieldDataType, SimpleField, SearchableField, VectorSearch, HnswAlgorithmConfiguration
   
   index_client = SearchIndexClient(endpoint=os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT"), credential=AzureKeyCredential(os.getenv("AZURE_SEARCH_ADMIN_KEY")))
   
   fields = [
       SimpleField(name="id", type=SearchFieldDataType.String, key=True),
       SearchableField(name="content", type=SearchFieldDataType.String),
       SearchField(name="vector", type=SearchFieldDataType.Collection(SearchFieldDataType.Single), searchable=True, vector_search_dimensions=1536, vector_search_profile_name="myHnswProfile")
   ]
   
   # 创建索引逻辑...
   

   步骤 C: 上传数据 (Upload Data) 将文档及其对应的向量上传至索引。

   步骤 D: 执行向量查询 (Vector Query) 将用户查询语句转化为向量，并在索引中检索相似内容。

   # 生成查询向量
   query_vector = client.embeddings.create(input="How does vector search work?", model=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME")).data[0].embedding
   
   # 执行搜索
   results = search_client.search(
       search_text=None, 
       vector_queries=[VectorizedQuery(vector=query_vector, k_nearest_neighbors=3, fields="vector")]
   )
   
   for result in results:
       print(f"Score: {result['@search.score']}, Content: {result['content']}")
   

进阶示例说明

• 集成向量化 (Integrated Vectorization)：参考 demo-dotnet/DotNetIntegratedVectorizationDemo 或 Java 对应示例。此模式利用 Azure AI Search 内置的技能集（Skillset）自动调用 Azure OpenAI 进行索引时的向量化，无需客户端预先计算向量。
• 图像搜索：demo-python 中包含处理图像内容分块和嵌入的 Notebook，需配合 Azure AI Vision 服务使用。
• 量化存储优化：.NET 示例中的 QuantizationAndStorageOptions 展示了如何通过窄数据类型和标量量化减少内存和磁盘占用。

更多详细文档请参考 Azure AI Search 官方文档。