Usando o conector do Azure AI Search Vetor Store (Visualização)

Aviso

A funcionalidade Semantic Kernel Vetor Store está em pré-visualização, e melhorias que exigem alterações de quebra ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Descrição geral

O conector do Azure AI Search Vetor Store pode ser usado para acessar e gerenciar dados no Azure AI Search. O conector tem as seguintes características.

Área de funcionalidades	Suporte
Mapas da coleção para	Azure AI Search Index
Tipos de propriedade de chave suportados	string
Tipos de propriedade de dados suportados	string número inteiro long duplo flutuante booleano DateTimeOffset e enumeráveis de cada um destes tipos
Tipos de propriedade vetorial suportados	Float ReadOnlyMemory<>
Tipos de índice suportados	Hnsw Apartamento
Funções de distância suportadas	CossenoSimilaridade DotProductSimilarity Distância Euclidiana
Cláusulas de filtro suportadas	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
IsFilterable suportado?	Sim
IsFullTextSearchable suportado?	Sim
StoragePropertyName suportado?	Não, use JsonSerializerOptions e JsonPropertyNameAttribute em vez disso. Veja aqui mais informações.

Limitações

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

Área de funcionalidades	Solução
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 de Pesquisa do Azure AI diretamente para a criação de coleções

Introdução

Adicione o pacote NuGet do conector do Azure AI Search Vetor Store ao seu projeto.

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

Você pode adicionar o armazenamento vetorial ao contêiner de injeção de dependência disponível no KernelBuilder ou ao contêiner de IServiceCollection 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. Isso exige 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 Azure AI Search Vetor Store 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 azure, que inclui o SDK do Azure AI Search.

pip install semantic-kernel[azure]

Em seguida, você pode criar uma instância de armazenamento 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 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 de pesquisa 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)

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 ditado simples com os campos correspondentes ao índice como entrada, a serialização é bastante fácil, basta retornar um ditado com os valores com as chaves correspondentes aos campos de índice, a etapa interna do ditado para o modelo de loja é uma passagem direta do ditado 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 armazenamento 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 Azure AI Search ao mapear dados do modelo de dados para o armazenamento é o 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 para o esquema de armazenamento. Isso significa que o JsonPropertyNameAttribute uso do é suportado se um nome de armazenamento diferente para o 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 o SearchIndexClient e para a AzureAISearchVectorStoreRecordCollection construção.

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