使用 SQL Server Vector Store 连接器 (预览版)

警告

Sql Server Vector Store 功能处于预览状态,需要重大更改的改进可能仍发生在发布前的有限情况下。

警告

语义内核矢量存储功能为预览版功能,在发布之前仍可能会发生需要重大更改的改进,但这种情况有限。

警告

语义内核矢量存储功能为预览版功能,在发布之前仍可能会发生需要重大更改的改进,但这种情况有限。

概述

SQL Server Vector Store 连接器可用于访问和管理 SQL Server 中的数据。 连接器具有以下特征。

功能区域 支持
集合映射至 SQL Server 表
支持的键属性类型
  • 整数 (int)
  • 长整型
  • 字符串
  • Guid
  • DateTime
  • byte[]
支持的数据属性类型
  • 整数 (int)
  • short
  • 字节 (byte)
  • 长整型
  • Guid
  • 字符串
  • 布尔
  • 漂浮
  • double
  • decimal
  • byte[]
  • DateTime
  • TimeOnly
支持的向量属性类型
  • ReadOnlyMemory<float>
  • Embedding<float>
  • float[]
支持的索引类型
  • 平坦
支持的距离函数
  • CosineDistance
  • NegativeDotProductSimilarity
  • EuclideanDistance
支持记录中的多个向量 是的
是否支持 IsIndexed? 是的
是否支持FullTextIndexed?
是否支持 StorageName? 是的
支持 HybridSearch?

入门指南

将 SQL Sever Vector Store 连接器 NuGet 包添加到项目。

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

可以使用语义内核提供的扩展方法将矢量存储添加到 IServiceCollection 依赖项注入容器。

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

可以直接构造 Sql Server 矢量存储实例。

using Microsoft.SemanticKernel.Connectors.SqlServer;

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

可以构造对命名集合的直接引用。

using Microsoft.SemanticKernel.Connectors.SqlServer;

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

数据映射

从数据模型映射到存储时,SQL Server Vector Store 连接器提供默认映射器。 此映射器将数据模型上的属性列表直接转换为 SQL Server 中的列。

属性名称覆盖

可以提供不同于数据模型上的属性名称的覆盖属性名称,以便用于存储。 通过在数据模型属性特性或记录定义中设置 StorageName 选项,可完成属性名称覆盖。

下面是一个在其属性中设置了StorageName的数据模型示例,以及该数据模型如何在 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])
);

概述

SQL Server Vector Store 连接器是由语义内核提供的矢量存储实现,它使用 Azure SQL 作为矢量存储。 当 SQL Server 本地版支持向量时,也可以使用它。

连接器具有以下特征。

功能区域 支持
集合映射至 表字典
支持的键属性类型
  • str
  • 整数 (int)
支持的数据属性类型 任意类型
支持的向量属性类型
  • list[float]
  • numpy 数组
支持的索引类型
  • 平坦
支持的距离函数
  • 余弦距离
  • 点积相似性
  • Euclidean Distance
支持记录中的多个向量 是的
是否支持 is_filterable? 是的
是否支持 is_full_text_searchable?

入门指南

将语义内核包添加到项目。

pip install semantic-kernel[sql]

SQL Server 连接器使用 pyodbc 包连接到 SQL Server。 额外安装包,但需要单独安装适用于 SQL Server 的 ODBC 驱动程序,这因平台而异,有关详细信息,请参阅 azure SQL 文档

为了使存储和集合正常工作,它需要连接字符串,这可以传递给构造函数或在环境变量 SQL_SERVER_CONNECTION_STRING中设置。 为了正确处理向量,如果未找到,将添加 LongAsMax=yes 选项。 它还可以使用用户名/密码,也可以使用集成安全性。对于后者,使用DefaultAzureCredential

在下面的代码片段中,假定你有一个名为“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)

可以构造对命名集合的直接引用。

from semantic_kernel.connectors.sql_server import SqlServerCollection

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

注意:集合名称可以指定为简单字符串(例如 table_name)或完全限定的名称(例如 dbo.table_name)。 如果未指定任何架构,则建议使用后者以避免歧义,将使用默认架构(dbo)。

如果对连接有特定要求,还可以将 pyodbc.Connection 对象传递给 SqlServerStore 构造函数。 这样,可以使用自定义连接字符串或其他连接选项:

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)

必须确保自行关闭连接,因为存储或集合不会执行此操作。

自定义创建查询

SQL Server 连接器仅限于平面索引类型。

ensure_collection_exists 上的 SqlServerCollection 方法允许传入单个或多个自定义查询来创建集合。 查询按传入的顺序执行,不返回任何结果。

如果这样做,则不能保证其他方法仍按预期工作。 连接器不知道自定义查询,并且不会对其进行验证。

如果 DataModel 具有 idcontentvector 作为字段,则可以创建如下所示的表,以便在内容字段上创建索引:

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

即将推出

更多信息即将推出。