Uso del connettore SQL Server Vector Store (anteprima)

Informazioni generali

Il connettore sql Server Vector Store può essere usato per accedere e gestire i dati in SQL Server. Il connettore presenta le caratteristiche seguenti.

Come iniziare

Aggiungi al progetto il pacchetto NuGet del connettore SQL Server Vector Store.

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

È possibile aggiungere l'archivio vettoriale al IServiceCollection contenitore di inserimento delle dipendenze usando i metodi di estensione forniti dal kernel semantico.

using Microsoft.Extensions.DependencyInjection;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSqlServerVectorStore(_ => "<connectionstring>");

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSqlServerVectorStore(_ => "<connectionstring>")

È possibile costruire direttamente un'istanza dell'archivio vettoriale di Sql Server.

using Microsoft.SemanticKernel.Connectors.SqlServer;

var vectorStore = new SqlServerVectorStore("<connectionstring>");

È possibile costruire un riferimento diretto a una raccolta denominata.

using Microsoft.SemanticKernel.Connectors.SqlServer;

var collection = new SqlServerCollection<string, Hotel>("<connectionstring>", "skhotels");

Mappatura dei dati

Il connettore SQL Server Vector Store fornisce un mapper predefinito quando si esegue il mapping dal modello di dati all'archiviazione. Questo mapper esegue una conversione diretta dell'elenco di proprietà nel modello di dati nelle colonne in SQL Server.

Sostituzione del nome della proprietà

È possibile fornire nomi di proprietà di override da usare nell'archiviazione, diversi dai nomi delle proprietà nel modello di dati. La sostituzione del nome della proprietà viene eseguita impostando l'opzione StorageName tramite gli attributi della proprietà del modello di dati o la definizione di record.

Di seguito è riportato un esempio di modello di dati con StorageName impostato sui relativi attributi e come verrà rappresentato in un comando di SQL Server.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreKey]
    public ulong HotelId { get; set; }

    [VectorStoreData(StorageName = "hotel_name")]
    public string? HotelName { get; set; }

    [VectorStoreData(StorageName = "hotel_description")]
    public string? Description { get; set; }

    [VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineDistance)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

CREATE TABLE Hotel (
[HotelId] BIGINT NOT NULL,
[hotel_name] NVARCHAR(MAX),
[hotel_description] NVARCHAR(MAX),
[DescriptionEmbedding] VECTOR(4),
PRIMARY KEY ([HotelId])
);

Informazioni generali

Il connettore sql Server Vector Store è un'implementazione dell'archivio vettoriale fornita dal kernel semantico che usa Azure SQL come archivio vettoriale. Una volta che SQL Server locale supporta i vettori, può essere usato anche con questo.

Il connettore presenta le caratteristiche seguenti.

Come iniziare

Aggiungere il pacchetto Semantic Kernel al progetto.

pip install semantic-kernel[sql]

Il connettore SQL Server usa il pacchetto pyodbc per connettersi a SQL Server. Il pacchetto aggiuntivo installerà il pacchetto, ma sarà necessario installare separatamente il driver ODBC per SQL Server, che differisce dalla piattaforma, vedere la documentazione di Azure SQL per informazioni dettagliate.

Per consentire il funzionamento dell'archivio e della raccolta, è necessaria una stringa di connessione, che può essere passata al costruttore o essere impostata nella variabile SQL_SERVER_CONNECTION_STRINGdi ambiente . Per gestire correttamente i vettori, l'opzione LongAsMax=yes verrà aggiunta se non trovata. Può anche usare nome utente/password o sicurezza integrata, per quest'ultimo viene DefaultAzureCredential usato .

Nei frammenti di codice seguenti si presuppone che sia stata definita una classe del modello di dati denominata "DataModel".

from semantic_kernel.connectors.sql_server import SqlServerStore

vector_store = SqlServerStore()

# OR

vector_store = SqlServerStore(connection_string="Driver={ODBC Driver 18 for SQL Server};Server=server_name;Database=database_name;UID=user;PWD=password;LongAsMax=yes;")

vector_collection = vector_store.get_collection("dbo.table_name", DataModel)

È possibile costruire un riferimento diretto a una raccolta denominata.

from semantic_kernel.connectors.sql_server import SqlServerCollection

vector_collection = SqlServerCollection("dbo.table_name", DataModel)

Nota: il nome della raccolta può essere specificato come stringa semplice (ad esempio table_name) o come nome completo (ad esempio dbo.table_name). Quest'ultimo è consigliato per evitare ambiguità, se non viene specificato alcuno schema, verrà usato lo schema predefinito (dbo).

Quando si hanno requisiti specifici per la connessione, è anche possibile passare un pyodbc.Connection oggetto al SqlServerStore costruttore. In questo modo è possibile usare una stringa di connessione personalizzata o altre opzioni di connessione:

from semantic_kernel.connectors.sql_server import SqlServerStore
import pyodbc

# Create a connection to the SQL Server database
connection = pyodbc.connect("Driver={ODBC Driver 18 for SQL Server};Server=server_name;Database=database_name;UID=user;PWD=password;LongAsMax=yes;")
# Create a SqlServerStore with the connection
vector_store = SqlServerStore(connection=connection)

Sarà necessario assicurarsi di chiudere la connessione manualmente, perché l'archivio o la raccolta non lo farà per te.

Crea query personalizzate

Il connettore SQL Server è limitato al tipo di indice Flat.

Il ensure_collection_exists metodo in SqlServerCollection consente di passare una o più query personalizzate per creare la raccolta. Le query vengono eseguite nell'ordine in cui vengono passate, non vengono restituiti risultati.

Se questa operazione viene eseguita, non c'è garanzia che gli altri metodi funzionino ancora come previsto. Il connettore non riconosce le query personalizzate e non le convalida.

Se ha DataModelid, contente vector come campi, ad esempio è possibile creare la tabella come questa per creare anche un indice nel campo contenuto:

from semantic_kernel.connectors.sql_server import SqlServerCollection

# Create a collection with a custom query
async with SqlServerCollection("dbo.table_name", DataModel) as collection:    
    collection.ensure_collection_exists(
        queries=["CREATE TABLE dbo.table_name (id INT PRIMARY KEY, content NVARCHAR(3000) NULL, vector VECTOR(1536) NULL ) PRIMARY KEY (id);",
        "CREATE INDEX idx_content ON dbo.table_name (content);"]
    )

Presto disponibile

Altre informazioni saranno presto disponibili.