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 melhorias que exigem mudanças disruptivas ainda podem ocorrer em circunstâncias limitadas antes do lançamento final.

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 Funcionalidade	Suporte
A coleção está mapeada para	Índice de Pesquisa de IA do Azure
Tipos de propriedades de chave suportados	cadeia de caracteres
Tipos de propriedade de dados com suporte	string INT longo duplo flutuar bool DateTimeOffset (Deslocamento de Data e Hora) e enumeráveis de cada um desses tipos
Tipos de propriedades de vetores 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
"O IsFilterable é suportado?"	Sim
O IsFullTextSearchable é suportado?	Sim
StoragePropertyName é compatível?	Não, use JsonSerializerOptions e JsonPropertyNameAttribute em vez disso. Veja aqui para mais informações.
O HybridSearch é suportado?	Sim

Área de Funcionalidade	Suporte
A coleção corresponde a	Índice de Pesquisa de IA do Azure
Tipos de propriedades de chave suportados	string
Tipos de propriedade de dados com suporte	cadeia de caracteres INT longo duplo flutuar bool DateTimeOffset e iteráveis de cada um desses tipos
Tipos de propriedades de vetores com suporte	lista[float] lista[int] array numpy
Tipos de índice com suporte	Hnsw Plano
Funções de distância suportadas	Semelhança de cosseno DotProductSimilarity Distância Euclidiana Hamming
Cláusulas de filtro com suporte	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
"O IsFilterable é suportado?"	Sim
O IsFullTextSearchable é suportado?	Sim

Área de Funcionalidade	Suporte
A coleção é mapeada para	Índice de Pesquisa de IA do Azure
Tipos de propriedades de chave suportados	string
Tipos de propriedade de dados com suporte	string INT longo duplo flutuar bool DateTimeOffset e enumeráveis de cada um desses tipos
Tipos de propriedades de vetores com suporte	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
"O IsFilterable é suportado?"	Sim
O IsFullTextSearchable é suportado?	Sim
StoragePropertyName é compatível?	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 Funcionalidade	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

Iniciando

Adicione o pacote NuGet do conector de Armazenamento 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 no contêiner de injeção de dependências.

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

Iniciando

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 cujas chaves correspondem aos campos de índice. A etapa embutida 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.

Iniciando

Inclua a versão mais recente do conector de dados do Azure AI Search no 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 tanto para o SearchIndexClient quanto para o AzureAISearchVectorStoreRecordCollection durante a 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 });