Usando o conector do Repositório de Vetores do Azure AI Search (versão prévia)

Aviso

A funcionalidade do Repositório de Vetores do Kernel Semântico está em versão prévia e as melhorias que exigem alterações significativas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Visão geral

O conector do Repositório de Vetores do Azure AI Search pode ser usado para acessar e gerenciar dados no Azure AI Search. O conector tem as seguintes características.

Área de recurso	Suporte
A coleção é mapeada para	Índice de Pesquisa de IA do Azure
Tipos de propriedade de chave com suporte	string
Tipos de propriedade de dados com suporte	string INT longo duplo float bool DateTimeOffset e enumeráveis de cada um desses tipos
Tipos de propriedade de vetor com suporte	Float ReadOnlyMemory<>
Tipos de índice com suporte	Hnsw Plano
Funções de distância suportadas	Semelhança de cosseno DotProductSimilarity Distância Euclidiana
Cláusulas de filtro com suporte	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
IsFilterable suportado?	Sim
IsFullTextSearchable suportado?	Sim
StoragePropertyName com suporte?	Não, use JsonSerializerOptions e JsonPropertyNameAttribute em vez disso. Veja aqui para mais informações.

Limitações

Limitações notáveis da funcionalidade do conector do Azure AI Search.

Área de recurso	Solução alternativa
Não há suporte para a configuração de analisadores de pesquisa de texto completo durante a criação da coleção.	Usar o SDK do cliente do Azure AI Search diretamente para a criação da coleção

Introdução

Adicione o pacote NuGet do conector do Repositório de Vetores do Azure AI Search ao seu projeto.

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

Você pode adicionar o repositório de vetores ao contêiner de injeção de dependência disponível no KernelBuilder ou ao IServiceCollection contêiner de injeção de dependência usando métodos de extensão fornecidos pelo Semantic Kernel.

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));

Métodos de extensão que não usam parâmetros também são fornecidos. Eles exigem que uma instância do Azure AI Search SearchIndexClient seja registrada separadamente com o contêiner de injeção de dependência.

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();

Você pode construir uma instância do Repositório de Vetores do Azure AI Search diretamente.

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

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

É possível construir uma referência direta a uma coleção nomeada.

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");

Introdução

Instale o kernel semântico com os extras do Azure, que inclui o SDK do Azure AI Search.

pip install semantic-kernel[azure]

Em seguida, você pode criar uma instância de repositório de vetores usando a AzureAISearchStore classe, isso usará as variáveis AZURE_AI_SEARCH_ENDPOINT de ambiente e AZURE_AI_SEARCH_API_KEY , para se conectar à instância do Azure AI Search, esses valores também podem ser fornecidos diretamente. Você também pode fornecer credenciais do Azure ou credenciais de token em vez de uma chave de API.

from semantic_kernel.connectors.memory.azure_ai_search import AzureAISearchStore

vector_store = AzureAISearchStore()

Você também pode criar o repositório de vetores com sua própria instância do cliente azure search.

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)

Você também pode criar uma coleção diretamente.

from semantic_kernel.connectors.memory.azure_ai_search import AzureAISearchCollection

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

Serialização

Como o conector do Azure AI Search precisa de um dicionário simples com os campos correspondentes ao índice como entrada, a serialização é bastante fácil, basta retornar um dicionário com os valores com as chaves correspondentes aos campos de índice, a etapa interna do dicionário para o modelo de armazenamento é uma passagem direta do dicionário criado.

Para obter mais detalhes sobre esse conceito, consulte a documentação de serialização.

Introdução

Inclua a versão mais recente do conector de dados do Azure AI Search do Kernel Semântico em seu projeto Maven adicionando a seguinte dependência ao seu pom.xml:

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

Em seguida, você pode criar uma instância de repositório de vetores usando a AzureAISearchVectorStore classe, tendo o cliente AzureAISearch como parâmetro.

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();
    }
}

Você também pode criar uma coleção diretamente.

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

Mapeamento de dados

O mapeador padrão usado pelo conector do Azure AI Search ao mapear dados do modelo de dados para o armazenamento é aquele fornecido pelo SDK do Azure AI Search.

Esse mapeador faz uma conversão direta da lista de propriedades no modelo de dados para os campos no Azure AI Search e usa System.Text.Json.JsonSerializer para converter no esquema de armazenamento. Isso significa que o uso do JsonPropertyNameAttribute será suportado se um nome de armazenamento diferente do nome da propriedade do modelo de dados for necessário.

Também é possível usar uma instância personalizada JsonSerializerOptions com uma política de nomenclatura de propriedade personalizada. Para permitir isso, o JsonSerializerOptions deve ser passado para a SearchIndexClient construção e o AzureAISearchVectorStoreRecordCollection on.

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 });