使用 Azure AI 搜索矢量存储连接器 （预览版）

警告

语义内核向量存储功能处于预览状态，需要中断性变更的改进可能仍发生在发布前的有限情况下。

概述

Azure AI 搜索矢量存储连接器可用于访问和管理 Azure AI 搜索中的数据。 连接器具有以下特征。

功能区域	支持
集合映射到	Azure AI 搜索索引
支持的键属性类型	string
支持的数据属性类型	string int long double float 布尔 DateTimeOffset 和枚举每种类型
支持的向量属性类型	ReadOnlyMemory<float>
支持的索引类型	Hnsw 平面
支持的距离函数	CosineSimilarity DotProductSimilarity EuclideanDistance
支持的筛选器子句	AnyTagEqualTo EqualTo
支持记录中的多个向量	是
是否支持Filterable？	是
是否支持FullTextSearchable？	是
支持 StoragePropertyName？	否，请改用 JsonSerializerOptions 和 JsonPropertyNameAttribute 改用。 有关详细信息，请参阅此处。

限制

值得注意的 Azure AI 搜索连接器功能限制。

功能区域	解决方法
不支持在创建集合期间配置全文搜索分析器。	直接使用 Azure AI 搜索客户端 SDK 创建集合

入门

将 Azure AI 搜索矢量存储连接器 NuGet 包添加到项目。

dotnet add package Microsoft.SemanticKernel.Connectors.AzureAISearch --prerelease

可以使用语义内核提供的扩展方法将向量存储添加到可用的 KernelBuilder 依赖项注入容器或 IServiceCollection 依赖项注入容器。

using Azure;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder()
    .AddAzureAISearchVectorStore(new Uri(azureAISearchUri), new AzureKeyCredential(secret));

using Azure;
using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAzureAISearchVectorStore(new Uri(azureAISearchUri), new AzureKeyCredential(secret));

还提供不带参数的扩展方法。 这些要求将 Azure AI 搜索 SearchIndexClient 的实例单独注册到依赖项注入容器。

using Azure;
using Azure.Search.Documents.Indexes;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<SearchIndexClient>(
    sp => new SearchIndexClient(
        new Uri(azureAISearchUri),
        new AzureKeyCredential(secret)));
kernelBuilder.AddAzureAISearchVectorStore();

using Azure;
using Azure.Search.Documents.Indexes;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<SearchIndexClient>(
    sp => new SearchIndexClient(
        new Uri(azureAISearchUri),
        new AzureKeyCredential(secret)));
builder.Services.AddAzureAISearchVectorStore();

可以直接构造 Azure AI 搜索矢量存储实例。

using Azure;
using Azure.Search.Documents.Indexes;
using Microsoft.SemanticKernel.Connectors.AzureAISearch;

var vectorStore = new AzureAISearchVectorStore(
    new SearchIndexClient(
        new Uri(azureAISearchUri),
        new AzureKeyCredential(secret)));

可以构造对命名集合的直接引用。

using Azure;
using Azure.Search.Documents.Indexes;
using Microsoft.SemanticKernel.Connectors.AzureAISearch;

var collection = new AzureAISearchVectorStoreRecordCollection<Hotel>(
    new SearchIndexClient(new Uri(azureAISearchUri), new AzureKeyCredential(secret)),
    "skhotels");

入门

使用 Azure Extras 安装语义内核，其中包括 Azure AI 搜索 SDK。

pip install semantic-kernel[azure]

然后，可以使用类创建矢量存储实例 AzureAISearchStore ，这将使用环境变量 AZURE_AI_SEARCH_ENDPOINT 并 AZURE_AI_SEARCH_API_KEY 连接到 Azure AI 搜索实例，也可以直接提供这些值。 还可以提供 Azure 凭据或令牌凭据，而不是 API 密钥。

from semantic_kernel.connectors.memory.azure_ai_search import AzureAISearchStore

vector_store = AzureAISearchStore()

还可以使用自己的 Azure 搜索客户端实例创建矢量存储。

from azure.search.documents.indexes import SearchIndexClient
from semantic_kernel.connectors.memory.azure_ai_search import AzureAISearchStore

search_client = SearchIndexClient(endpoint="https://<your-search-service-name>.search.windows.net", credential="<your-search-service-key>")
vector_store = AzureAISearchStore(search_index_client=search_client)

也可以直接创建集合。

from semantic_kernel.connectors.memory.azure_ai_search import AzureAISearchCollection

collection = AzureAISearchCollection(collection_name="skhotels", data_model_type=hotel)

序列化

由于 Azure AI 搜索连接器需要使用与索引对应的字段作为输入的简单听写，因此序列化非常简单，只需使用与索引字段对应的键返回包含值的听写，从听写到存储模型的内置步骤是创建的听写的直接传递。

有关此概念的更多详细信息，请参阅 序列化文档。

入门

通过在 Maven 项目中添加以下依赖项 pom.xml，在 Maven 项目中包括最新版本的语义内核 Azure AI 搜索数据连接器：

<dependency>
    <groupId>com.microsoft.semantic-kernel</groupId>
    <artifactId>semantickernel-data-azureaisearch</artifactId>
    <version>[LATEST]</version>
</dependency>

然后，可以使用类创建矢量存储实例 AzureAISearchVectorStore ，将 AzureAISearch 客户端作为参数。

import com.azure.core.credential.AzureKeyCredential;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;
import com.microsoft.semantickernel.data.azureaisearch.AzureAISearchVectorStore;
import com.microsoft.semantickernel.data.azureaisearch.AzureAISearchVectorStoreOptions;
import com.microsoft.semantickernel.data.azureaisearch.AzureAISearchVectorStoreRecordCollection;
import com.microsoft.semantickernel.data.azureaisearch.AzureAISearchVectorStoreRecordCollectionOptions;

public class Main {
    public static void main(String[] args) {
        // Build the Azure AI Search client
        var searchClient = new SearchIndexClientBuilder()
                .endpoint("https://<your-search-service-name>.search.windows.net")
                .credential(new AzureKeyCredential("<your-search-service-key>"))
                .buildAsyncClient();

        // Build an Azure AI Search Vector Store
        var vectorStore = AzureAISearchVectorStore.builder()
                .withSearchIndexAsyncClient(searchClient)
                .withOptions(new AzureAISearchVectorStoreOptions())
                .build();
    }
}

也可以直接创建集合。

var collection = new AzureAISearchVectorStoreRecordCollection<>(searchClient, "skhotels",
        AzureAISearchVectorStoreRecordCollectionOptions.<Hotel>builder()
                .withRecordClass(Hotel.class)
                .build());

数据映射

将数据从数据模型映射到存储时，Azure AI 搜索连接器使用的默认映射器是 Azure AI 搜索 SDK 提供的映射器。

此映射器将数据模型上的属性列表直接转换为 Azure AI 搜索中的字段，并用于 System.Text.Json.JsonSerializer 转换为存储架构。 这意味着，如果需要与数据模型属性名称不同的存储名称，则支持使用该 JsonPropertyNameAttribute 名称。

还可以使用具有自定义属性命名策略的自定义 JsonSerializerOptions 实例。 若要启用此功能， JsonSerializerOptions 必须同时传递给 SearchIndexClient 构造和 AzureAISearchVectorStoreRecordCollection 施工时。

var jsonSerializerOptions = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper };
var collection = new AzureAISearchVectorStoreRecordCollection<Hotel>(
    new SearchIndexClient(
        new Uri(azureAISearchUri),
        new AzureKeyCredential(secret),
        new() { Serializer = new JsonObjectSerializer(jsonSerializerOptions) }),
    "skhotels",
    new() { JsonSerializerOptions = jsonSerializerOptions });