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

Aviso

A funcionalidade do Azure AI Search Vetor Store está em pré-visualização e as melhorias que requerem alterações significativas ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Aviso

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

Aviso

A funcionalidade Semantic Kernel Vetor Store está em fase de pré-visualização, e melhorias que exijam alterações significativas 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
Mapeamento da coleção para	Azure AI Índice de Pesquisa
Tipos de propriedade de chave suportados	corda
Tipos de propriedade de dados suportados	corda Int longo duplo flutuante booleano Desvio de Data e Hora e enumeráveis de cada um destes tipos
Tipos de propriedade vetorial suportados	ReadOnlyMemory Flutuador de incorporação<> flutuar[]
Tipos de índice suportados	Hnsw Apartamento
Funções de distância suportadas	Similaridade do Cosseno DotProductSimilarity Distância Euclidiana
Cláusulas de filtro suportadas	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
IsIndexed é suportado?	Sim
"É suportado IsFullTextIndexed?"	Sim
O StorageName é suportado?	Não, use JsonSerializerOptions e JsonPropertyNameAttribute em vez disso. Veja aqui mais informações.
O HybridSearch é suportado?	Sim

Área de funcionalidades	Suporte
Mapeamento da coleção para	Azure AI Índice de Pesquisa
Tipos de propriedade de chave suportados	corda
Tipos de propriedade de dados suportados	corda Int longo duplo flutuante booleano Desvio de Data e Hora e iteráveis de cada um desses tipos
Tipos de propriedade vetorial suportados	lista[float] lista[int] array numpy
Tipos de índice suportados	Hnsw Apartamento
Funções de distância suportadas	Similaridade do Cosseno DotProductSimilarity Distância Euclidiana Hamming
Cláusulas de filtro suportadas	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
É o IsFilterable suportado?	Sim
Está IsFullTextSearchable suportado?	Sim

Área de funcionalidades	Suporte
Mapeamento da coleção para	Azure AI Índice de Pesquisa
Tipos de propriedade de chave suportados	corda
Tipos de propriedade de dados suportados	corda Int longo duplo flutuante booleano Desvio de Data e Hora e enumeráveis de cada um destes tipos
Tipos de propriedade vetorial suportados	ReadOnlyMemory
Tipos de índice suportados	Hnsw Apartamento
Funções de distância suportadas	Similaridade do Cosseno DotProductSimilarity Distância Euclidiana
Cláusulas de filtro suportadas	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
É o IsFilterable suportado?	Sim
Está IsFullTextSearchable suportado?	Sim
Está StorageName 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

Iniciar

Adicione o pacote NuGet do conector Azure AI Search Vector 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.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

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

using Azure;
using Microsoft.Extensions.DependencyInjection;
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.Services.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 AzureAISearchCollection<string, Hotel>(
    new SearchIndexClient(new Uri(azureAISearchUri), new AzureKeyCredential(secret)),
    "skhotels");

Iniciar

Instale o kernel semântico com os extras do Azure, que incluem 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.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.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.azure_ai_search import AzureAISearchCollection

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

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 do índice. A etapa integrada 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.

Iniciar

Inclua a versão mais recente do conector de dados do Azure AI Search do Kernel Semântico no 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 uso do JsonPropertyNameAttribute é suportado se for necessário um nome de armazenamento diferente para o nome da propriedade do modelo de dados.

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 o AzureAISearchCollection na construção.

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