如何使用语义内核将数据引入矢量存储（预览版）

项目
11/03/2024

警告

语义内核向量存储功能处于预览状态，需要中断性变更的改进可能仍发生在发布前的有限情况下。

本文将演示如何创建应用程序

从 Microsoft Word 文档中的每一段获取文本
为每个段落生成嵌入内容
将文本、嵌入和对原始位置的引用插入 Redis 实例。

先决条件

对于此示例，需要

托管在 Azure 或其他所选提供程序中的嵌入生成模型。
Redis 或 Docker Desktop 的实例，以便在本地运行 Redis。
要分析和加载的 Word 文档。下面是一个 zip，其中包含一个可以下载和使用的示例 Word 文档： vector-store-data-ingestion-input.zip。

设置 Redis

如果已有 Redis 实例，则可以使用该实例。如果想要在本地测试项目，可以使用 docker 轻松启动 Redis 容器。

docker run -d --name redis-stack -p 6379:6379 -p 8001:8001 redis/redis-stack:latest

若要验证它是否成功运行，请在浏览器中访问 http://localhost:8001/redis-stack/browser 。

这些说明的其余部分将假定你使用此容器使用上述设置。

创建项目

创建一个新项目，并从语义内核添加 Redis 连接器的 nuget 包引用、用于读取 Word 文档的 open xml 包以及用于生成嵌入内容的语义内核的 OpenAI 连接器。

dotnet new console --framework net8.0 --name SKVectorIngest
cd SKVectorIngest
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI
dotnet add package Microsoft.SemanticKernel.Connectors.Redis --prerelease
dotnet add package DocumentFormat.OpenXml

添加数据模型

若要上传数据，首先需要描述数据在数据库中应具有的格式。我们可以通过创建一个包含描述每个属性函数的属性的数据模型来执行此操作。

将一个新文件添加到调用 TextParagraph.cs 的项目，并将以下模型添加到其中。

using Microsoft.Extensions.VectorData;

namespace SKVectorIngest;

internal class TextParagraph
{
    /// <summary>A unique key for the text paragraph.</summary>
    [VectorStoreRecordKey]
    public required string Key { get; init; }

    /// <summary>A uri that points at the original location of the document containing the text.</summary>
    [VectorStoreRecordData]
    public required string DocumentUri { get; init; }

    /// <summary>The id of the paragraph from the document containing the text.</summary>
    [VectorStoreRecordData]
    public required string ParagraphId { get; init; }

    /// <summary>The text of the paragraph.</summary>
    [VectorStoreRecordData]
    public required string Text { get; init; }

    /// <summary>The embedding generated from the Text.</summary>
    [VectorStoreRecordVector(1536)]
    public ReadOnlyMemory<float> TextEmbedding { get; set; }
}

请注意，我们将该值1536传递给 .VectorStoreRecordVectorAttribute 这是矢量的维度大小，必须匹配所选嵌入生成器生成的向量的大小。

提示

有关如何批注数据模型以及每个属性可用的其他选项的详细信息，请参阅定义数据模型。

阅读文档中的段落

我们需要一些代码来读取单词文档，并在其中查找每个段落的文本。

将一个新文件添加到调用 DocumentReader.cs 的项目，并添加以下类以从文档读取段落。

using System.Text;
using System.Xml;
using DocumentFormat.OpenXml.Packaging;

namespace SKVectorIngest;

internal class DocumentReader
{
    public static IEnumerable<TextParagraph> ReadParagraphs(Stream documentContents, string documentUri)
    {
        // Open the document.
        using WordprocessingDocument wordDoc = WordprocessingDocument.Open(documentContents, false);
        if (wordDoc.MainDocumentPart == null)
        {
            yield break;
        }

        // Create an XmlDocument to hold the document contents and load the document contents into the XmlDocument.
        XmlDocument xmlDoc = new XmlDocument();
        XmlNamespaceManager nsManager = new XmlNamespaceManager(xmlDoc.NameTable);
        nsManager.AddNamespace("w", "http://schemas.openxmlformats.org/wordprocessingml/2006/main");
        nsManager.AddNamespace("w14", "http://schemas.microsoft.com/office/word/2010/wordml");

        xmlDoc.Load(wordDoc.MainDocumentPart.GetStream());

        // Select all paragraphs in the document and break if none found.
        XmlNodeList? paragraphs = xmlDoc.SelectNodes("//w:p", nsManager);
        if (paragraphs == null)
        {
            yield break;
        }

        // Iterate over each paragraph.
        foreach (XmlNode paragraph in paragraphs)
        {
            // Select all text nodes in the paragraph and continue if none found.
            XmlNodeList? texts = paragraph.SelectNodes(".//w:t", nsManager);
            if (texts == null)
            {
                continue;
            }

            // Combine all non-empty text nodes into a single string.
            var textBuilder = new StringBuilder();
            foreach (XmlNode text in texts)
            {
                if (!string.IsNullOrWhiteSpace(text.InnerText))
                {
                    textBuilder.Append(text.InnerText);
                }
            }

            // Yield a new TextParagraph if the combined text is not empty.
            var combinedText = textBuilder.ToString();
            if (!string.IsNullOrWhiteSpace(combinedText))
            {
                Console.WriteLine("Found paragraph:");
                Console.WriteLine(combinedText);
                Console.WriteLine();

                yield return new TextParagraph
                {
                    Key = Guid.NewGuid().ToString(),
                    DocumentUri = documentUri,
                    ParagraphId = paragraph.Attributes?["w14:paraId"]?.Value ?? string.Empty,
                    Text = combinedText
                };
            }
        }
    }
}

生成嵌入并上传数据

我们需要一些代码来生成嵌入内容并将段落上传到 Redis。让我们在单独的类中执行此操作。

添加一 DataUploader.cs 个名为的新文件，并将以下类添加到其中。

#pragma warning disable SKEXP0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Embeddings;

namespace SKVectorIngest;

internal class DataUploader(IVectorStore vectorStore, ITextEmbeddingGenerationService textEmbeddingGenerationService)
{
    /// <summary>
    /// Generate an embedding for each text paragraph and upload it to the specified collection.
    /// </summary>
    /// <param name="collectionName">The name of the collection to upload the text paragraphs to.</param>
    /// <param name="textParagraphs">The text paragraphs to upload.</param>
    /// <returns>An async task.</returns>
    public async Task GenerateEmbeddingsAndUpload(string collectionName, IEnumerable<TextParagraph> textParagraphs)
    {
        var collection = vectorStore.GetCollection<string, TextParagraph>(collectionName);
        await collection.CreateCollectionIfNotExistsAsync();

        foreach (var paragraph in textParagraphs)
        {
            // Generate the text embedding.
            Console.WriteLine($"Generating embedding for paragraph: {paragraph.ParagraphId}");
            paragraph.TextEmbedding = await textEmbeddingGenerationService.GenerateEmbeddingAsync(paragraph.Text);

            // Upload the text paragraph.
            Console.WriteLine($"Upserting paragraph: {paragraph.ParagraphId}");
            await collection.UpsertAsync(paragraph);

            Console.WriteLine();
        }
    }
}

将其放在一起

最后，我们需要组合不同的部分。在此示例中，我们将使用语义内核依赖项注入容器，但也可以使用任何基于容器 IServiceCollection 的容器。

将以下代码添加到 Program.cs 文件以创建容器、注册 Redis 矢量存储并注册嵌入服务。请确保将文本嵌入生成设置替换为自己的值。

#pragma warning disable SKEXP0010 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
#pragma warning disable SKEXP0020 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

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

// Replace with your values.
var deploymentName = "text-embedding-ada-002";
var endpoint = "https://sksample.openai.azure.com/";
var apiKey = "your-api-key";

// Register Azure Open AI text embedding generation service and Redis vector store.
var builder = Kernel.CreateBuilder()
    .AddAzureOpenAITextEmbeddingGeneration(deploymentName, endpoint, apiKey)
    .AddRedisVectorStore("localhost:6379");

// Register the data uploader.
builder.Services.AddSingleton<DataUploader>();

// Build the kernel and get the data uploader.
var kernel = builder.Build();
var dataUploader = kernel.Services.GetRequiredService<DataUploader>();

最后一步，我们希望从单词文档中读取段落，并调用数据上传程序来生成嵌入内容并上传段落。

// Load the data.
var textParagraphs = DocumentReader.ReadParagraphs(
    new FileStream(
        "vector-store-data-ingestion-input.docx",
        FileMode.Open),
    "file:///c:/vector-store-data-ingestion-input.docx");

await dataUploader.GenerateEmbeddingsAndUpload(
    "sk-documentation",
    textParagraphs);

在 Redis 中查看数据

导航到 Redis 堆栈浏览器，例如 http://localhost:8001/redis-stack/browser 现在应能够查看已上传的段落的位置。下面是应看到其中一个已上传段落的示例。

{
    "DocumentUri" : "file:///c:/vector-store-data-ingestion-input.docx",
    "ParagraphId" : "14CA7304",
    "Text" : "Version 1.0+ support across C#, Python, and Java means it’s reliable, committed to non breaking changes. Any existing chat-based APIs are easily expanded to support additional modalities like voice and video.",
    "TextEmbedding" : [...]
}

即将推出

即将出台的进一步说明

即将推出

即将出台的进一步说明

通过

如何使用语义内核将数据引入矢量存储（预览版）

先决条件

设置 Redis

创建项目

添加数据模型

阅读文档中的段落

生成嵌入并上传数据

将其放在一起

在 Redis 中查看数据

即将推出

即将推出

其他资源