Microsoft.Extensions.VectorData.Abstractions 入门

Microsoft.Extensions.VectorData.Abstractions 入门

我们很高兴地介绍 Microsoft.Extensions.VectorData.Abstractions 库，现在可以预览了。

正如 Microsoft.Extensions.AI 库为使用 AI 服务提供统一层一样，这个软件包为 .NET 生态系统提供了帮助将向量存储集成到 .NET 应用程序和库中的抽象。

为什么要使用向量存储？

向量数据库在搜索和扎根于生成 AI 响应等任务中至关重要。与关系数据库和文档数据库针对结构化和半结构化数据进行优化类似，向量数据库旨在高效存储、索引和管理以嵌入向量表示的数据。因此，向量数据库使用的索引算法优化了高效检索可以在应用程序下游使用的数据。

Microsoft.Extensions.VectorData是什么？

Microsoft.Extensions.VectorData是一组核心的.NET库，由 Semantic Kernel 和更广泛的 .NET 生态系统共同开发。这些库提供了一个统一的 C# 抽象层，用于与向量存储进行交互。Microsoft.Extensions.VectorData中的抽象为库作者和开发人员提供了以下功能：

• 在向量存储上执行创建-读取-更新-删除（CRUD）操作。
• 在向量存储上使用向量和文本搜索。

如何开始？

开始使用 Microsoft.Extensions.VectorData 抽象的最简单方法是使用任何 Semantic Kernel 向量存储连接器。在这个例子中，我将使用内存中的向量存储实现。为了补充这个示例并使其感觉更加真实，我们还将使用 Microsoft.Extensions.AI 中的 Ollama 参考实现。然而，任何支持嵌入生成的其他实现也可以使用。

常见的连接器：

• 内存中，本示例中使用它进行演示
• SQLite
• Qdrant
• Redis
• SQL Server
• Milvus 计划中

创建应用并添加必要的 NuGet 包

1. 创建控制听应用Create a C# console application.
2. 安装如下 NuGet packages
   • Microsoft.Extensions.VectorData.Abstractions
   • Microsoft.SemanticKernel.Connectors.InMemory
   • OllamaSharp
3. 安装之后，项目文件中的 NuGet 包

   <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.6.0" />
    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.58.0-preview" />
    <PackageReference Include="OllamaSharp" Version="5.2.3" />
   </ItemGroup>
   

在应用中添加如下命名空间引用：

using Microsoft.Extensions.AI;
using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.InMemory;
using OllamaSharp;

存储数据

在本示例中，我们将在一个电影介绍的集合上，执行语义搜索。

定义模型

首先定义表示电影信息的数据模型。

public class Movie
{
    [VectorStoreKey]
    public int Key {get;set;}

    [VectorStoreData] 
    public string Title {get;set;}

    [VectorStoreData]
    public string Description {get;set;}

    // all-minilm
    [VectorStoreVector(384)]
    public ReadOnlyMemory<float> Vector {get;set;}
}

通过使用属性如 VectoStoreKey、VectorStoreVector 和 VectorStoreData，您可以注释您的数据模型，以便向量存储实现可以更轻松地将 POCO 对象映射到其底层数据模型。有关每个属性支持的选项的更多信息，请参阅 语义内核向量存储数据模型 学习页面。

• [VectorStoreKey], Use this attribute to indicate that your property is the key of the record.
• [VectorStoreData(IsIndexed = true)], Use this attribute to indicate that your property contains general data that is not a key or a vector.
• [VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)], Use this attribute to indicate that your property contains a vector.

创建向量存储和电影集合

定义好数据模型后，创建一个向量存储和一个集合来存储电影数据。

var movieData = new List<Movie>()
{
    new Movie
        {
            Key=0, 
            Title="Lion King", 
            Description="《狮子王》是一部经典的迪士尼动画电影，讲述了一只年轻狮子辛巴的故事，他在父亲悲惨去世后踏上了夺回荣耀之地王位的旅程。"
        },
    new Movie
        {
            Key=1,
            Title="Inception", 
            Description="《盗梦空间》是一部由克里斯托弗·诺兰执导的科幻电影，讲述了一群小偷进入目标的梦境，以窃取信息的故事。"
        },
    new Movie
        {
            Key=2,
            Title="The Matrix", 
            Description="《黑客帝国》是一部由沃卓斯基姐妹执导的科幻电影，讲述了一位名叫尼奥的计算机黑客，发现他所生活的世界是由机器创造的模拟现实。"
        },
    new Movie
        {
            Key=3,
            Title="Shrek", 
            Description="《怪物史瑞克》是一部动画电影，讲述了一个名叫史瑞克的 Ogre 的故事，他踏上了一段使命，去拯救被龙囚禁的芬娜公主，并把她带回杜洛克王国。"
        }
};

var vectorStore = new InMemoryVectorStore();

var movies = vectorStore.GetCollection<int, Movie>("movies");

await movies.EnsureCollectionExistsAsync();

创建嵌入生成器

本示例使用 Ollama 提供的模型来生成嵌入生成器。

要生成嵌入，请使用 Ollama 提供的模型。在这个示例中，使用的模型是 all-minilm，但任何模型都可以。

1. 安装 Ollama。
2. 在 Ollama 中下载all-minilm模型。
3. 在您的应用程序中配置OllamaEmbeddingGenerator：

var uri = "http://localhost:11434";
string model = "all-minilm";        // diminsion: 384

var client = new OllamaApiClient(uri, model);
// Create the embedding generator.
IEmbeddingGenerator<string, Embedding<float>> generator =
            client as IEmbeddingGenerator<string, Embedding<float>>;

生成向量

现在您有了一个嵌入生成器，可以使用它为您的电影数据生成嵌入，并将其存储在您的向量存储中。

foreach (var movie in movieData)
{
    movie.Vector = await generator.GenerateVectorAsync(movie.Description);
    await movies.UpsertAsync(movie);
}

自动生成向量

需要预先准备 2 个条件：

1. 可以在定义模型的时候，指定矢量字段对应的内容字段
2. 指定集合所使用的矢量生成器

定义模型的时候，指定矢量字段对应的字段, 注意 Vector 字段的变化。

public class Movie
{
    [VectorStoreKey]
    public int Key {get;set;}

    [VectorStoreData] 
    public string Title {get;set;}

    [VectorStoreData]
    public string Description {get;set;}

    // all-minilm
    [VectorStoreVector(384)]
    public string Vector => Description;
}

指定集合所使用的矢量生成器

在数据源级别。

var options = new InMemoryVectorStoreOptions
{
    EmbeddingGenerator = generator
};            
var vectorStore = new InMemoryVectorStore(options);

在集合级别

var definition = new VectorStoreCollectionDefinition
{
    EmbeddingGenerator = generator
};

var movies = vectorStore.GetCollection<int, Movie>("movies", definition);
await movies.EnsureCollectionExistsAsync();

这样，可以直接更新记录而不再需要专门为 Vector 字段手动赋予生成的矢量。

foreach (var movie in movieData)
{
    // movie.Vector = await generator.GenerateVectorAsync(movie.Description);
    await movies.UpsertAsync(movie);
}

查询数据

现在您在数据存储中拥有数据，可以对其进行查询。

生成查询嵌入

为查询 "适合家庭观看的电影" 生成嵌入。

var query = "A family friendly movie";
var queryEmbedding = await generator.GenerateVectorAsync(query);
Console.WriteLine($"Query: {query}, length: {queryEmbedding.Length}");

查询你的数据存储

现在你已经拥有了查询的嵌入，你可以利用它在你的数据存储中搜索相关结果。

var nearest = movies.SearchAsync(queryEmbedding, 1, null);
await foreach(var result in nearest)
{
    Console.WriteLine($"Title: {result.Record.Title}");
    Console.WriteLine($"Description: {result.Record.Description}");
    Console.WriteLine($"Score: {result.Score}");
    Console.WriteLine();
}

结果应如下所示：

Query: A family friendly movie, length: 384
Title: Lion King
Description: 《狮子王》是一部经典的迪士尼动画电影，讲述了一只年轻狮子辛巴的故事，他在父亲悲惨去世后踏上了夺回荣耀之地王位的旅程。
Score: 0.0012379942927509546

换一下提问：

Query: 描述未来的科幻电影, length: 384
Title: The Matrix
Description: 《黑客帝国》是一部由沃卓斯基姐妹执导的科幻电影，讲述了一位名叫尼奥的计算机黑客，发现他所生活的世界是由机器创造的模拟现实。
Score: 0.4787377417087555

原来的英文：

继续学习

有关使用抽象的详细文档，请参见语义内核向量存储学习网站。从以下示例中了解更多：

• RAG 示例
• Microsoft.Extensions.VectorData 核心概念。

Microsoft.Extensions.VectorData 的下一步是什么？

类似于 Microsoft.Extensions.AI，

• 我们计划：继续与 Semantic Kernel 合作，基于其抽象进行开发，以及与 Microsoft.Extensions.VectorData 合作，以在 RAG 场景中提供更流畅的体验。请查看 Semantic Kernel 博客以了解更多信息。
• 与生态系统中的向量存储合作伙伴合作，提供客户端 SDK、库作者以及 .NET 生态系统中的开发人员，以推广 Microsoft.Extensions.VectorData。

我们期待您开始使用 Microsoft.Extensions.VectorData 进行构建。尝试一下并给我们反馈！

参考资料

• Introducing Microsoft.Extensions.VectorData Preview
• What are Semantic Kernel Vector Store connectors? (Preview)
• 开箱即用的连接器
• Microsoft.Extensions.VectorData.Abstractions
• OpenAI embedding 词嵌：text-embedding-ada-002