Uso del conector del almacén de vectores de Azure AI Search (versión preliminar)

Advertencia

La funcionalidad Almacén de vectores de kernel semántico está en versión preliminar y las mejoras que requieren cambios importantes pueden producirse en circunstancias limitadas antes de la versión.

Información general

El conector del almacén de vectores de Azure AI Search se puede usar para acceder a los datos y administrarlos en Azure AI Search. El conector tiene las siguientes características.

Área de características	Soporte técnico
La colección se asigna a	Índice de Azure AI Search
Tipos de propiedades de clave admitidos	string
Tipos de propiedad de datos admitidos	string int long double FLOAT bool DateTimeOffset y enumerables de cada uno de estos tipos
Tipos de propiedades vectoriales admitidos	ReadOnlyMemory<float>
Tipos de índice admitidos	Hnsw Plano
Funciones de distancia admitidas	CosineSimilarity DotProductSimilarity EuclideanDistance
Admite varios vectores en un registro	Sí
¿Se admite IsFilterable?	Sí
¿Se admite IsFullTextSearchable?	Sí
¿Se admite StoragePropertyName?	No, use JsonSerializerOptions y JsonPropertyNameAttribute en su lugar. Consulta aquí para obtener más información.

Limitaciones

Limitaciones notables de la funcionalidad del conector de Azure AI Search.

Área de características	Solución alternativa
No se admite la configuración de analizadores de búsqueda de texto completo durante la creación de colecciones.	Uso del SDK de cliente de Azure AI Search directamente para la creación de colecciones

Introducción

Agregue el paquete NuGet del conector del almacén de vectores de Azure AI Search al proyecto.

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

Puede agregar el almacén de vectores al contenedor de inserción de dependencias disponible en KernelBuilder o al IServiceCollection contenedor de inserción de dependencias mediante métodos de extensión proporcionados por kernel semántico.

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

También se proporcionan métodos de extensión que no toman parámetros. Estos requieren que una instancia de Azure AI Search SearchIndexClient se registre por separado con el contenedor de inserción de dependencias.

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

Puede construir directamente una instancia de Azure AI Search Vector Store.

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

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

Es posible construir una referencia directa a una colección con nombre.

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

Introducción

Instale el kernel semántico con los extras de Azure, que incluye el SDK de Azure AI Search.

pip install semantic-kernel[azure]

A continuación, puede crear una instancia de almacén de vectores mediante la AzureAISearchStore clase , que usará las variables AZURE_AI_SEARCH_ENDPOINT de entorno y AZURE_AI_SEARCH_API_KEY para conectarse a la instancia de Azure AI Search, esos valores también se pueden proporcionar directamente. También puede proporcionar credenciales de Azure o credenciales de token en lugar de una clave de API.

from semantic_kernel.connectors.memory.azure_ai_search import AzureAISearchStore

vector_store = AzureAISearchStore()

También puede crear el almacén de vectores con su propia instancia del cliente de 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)

También puede crear una colección directamente.

from semantic_kernel.connectors.memory.azure_ai_search import AzureAISearchCollection

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

Serialización

Dado que el conector de Azure AI Search necesita un dict simple con los campos correspondientes al índice como entrada, la serialización es bastante fácil, simplemente devuelve un dict con los valores con las claves correspondientes a los campos de índice, el paso integrado de dict al modelo de almacén es un paso directo del dict creado.

Para obtener más información sobre este concepto, consulte la documentación de serialización.

Introducción

Incluya la versión más reciente del conector de datos semántico de Azure AI Search en el proyecto de Maven agregando la siguiente dependencia a pom.xml:

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

A continuación, puede crear una instancia de almacén de vectores mediante la AzureAISearchVectorStore clase , teniendo el 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();
    }
}

También puede crear una colección directamente.

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

Asignación de datos

El asignador predeterminado que usa el conector de Azure AI Search al asignar datos del modelo de datos al almacenamiento es el proporcionado por el SDK de Azure AI Search.

Este asignador realiza una conversión directa de la lista de propiedades en el modelo de datos a los campos de Azure AI Search y usa System.Text.Json.JsonSerializer para convertir en el esquema de almacenamiento. Esto significa que se admite el uso de si se requiere un nombre de almacenamiento diferente al nombre de JsonPropertyNameAttribute la propiedad del modelo de datos.

También es posible usar una instancia personalizada JsonSerializerOptions con una directiva de nomenclatura de propiedades personalizada. Para habilitar esto, JsonSerializerOptions debe pasarse tanto a como SearchIndexClient a en la AzureAISearchVectorStoreRecordCollection construcción.

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