Skip to content

Commit f88cf5f

Browse files
authored
.Net: Create a getting started project for vector stores. (#9489)
### Motivation and Context #7606 Only three steps so far, more to be added in a subsequent PR. ### Description - Add a getting started project for vector stores - Add three initial steps, more to follow - Update README files ### Contribution Checklist <!-- Before submitting this PR, please make sure: --> - [x] The code builds clean without any errors or warnings - [x] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [x] All unit tests pass, and I have added new tests where possible - [x] I didn't break anyone 😄
1 parent aec6577 commit f88cf5f

9 files changed

Lines changed: 457 additions & 11 deletions

File tree

‎dotnet/SK-dotnet.sln‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -317,11 +317,11 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TimePlugin", "samples\Demos
317317
EndProject
318318
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Connectors.Memory.AzureCosmosDBNoSQL", "src\Connectors\Connectors.Memory.AzureCosmosDBNoSQL\Connectors.Memory.AzureCosmosDBNoSQL.csproj", "{B0B3901E-AF56-432B-8FAA-858468E5D0DF}"
319319
EndProject
320-
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Connectors.Amazon", "src\Connectors\Connectors.Amazon\Connectors.Amazon.csproj", "{E059E9B0-1302-474D-B1B5-10A6E0F1A769}"
320+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Connectors.Amazon", "src\Connectors\Connectors.Amazon\Connectors.Amazon.csproj", "{E059E9B0-1302-474D-B1B5-10A6E0F1A769}"
321321
EndProject
322-
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AmazonBedrockAIModels", "samples\Demos\AmazonBedrockModels\AmazonBedrockAIModels.csproj", "{ABEAACCD-CF63-4850-8ED5-E01379DBFC46}"
322+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AmazonBedrockAIModels", "samples\Demos\AmazonBedrockModels\AmazonBedrockAIModels.csproj", "{ABEAACCD-CF63-4850-8ED5-E01379DBFC46}"
323323
EndProject
324-
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Connectors.Amazon.UnitTests", "src\Connectors\Connectors.Amazon.UnitTests\Connectors.Amazon.UnitTests.csproj", "{CCC6DC57-2AC1-4C8E-A448-2CC0537A288E}"
324+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Connectors.Amazon.UnitTests", "src\Connectors\Connectors.Amazon.UnitTests\Connectors.Amazon.UnitTests.csproj", "{CCC6DC57-2AC1-4C8E-A448-2CC0537A288E}"
325325
EndProject
326326
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Connectors.Redis.UnitTests", "src\Connectors\Connectors.Redis.UnitTests\Connectors.Redis.UnitTests.csproj", "{1D4667B9-9381-4E32-895F-123B94253EE8}"
327327
EndProject
@@ -409,6 +409,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SemanticKernel.AotTests", "
409409
EndProject
410410
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Process.Utilities.UnitTests", "src\Experimental\Process.Utilities.UnitTests\Process.Utilities.UnitTests.csproj", "{DAC54048-A39A-4739-8307-EA5A291F2EA0}"
411411
EndProject
412+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "GettingStartedWithVectorStores", "samples\GettingStartedWithVectorStores\GettingStartedWithVectorStores.csproj", "{8C3DE41C-E2C8-42B9-8638-574F8946EB0E}"
413+
EndProject
412414
Global
413415
GlobalSection(SolutionConfigurationPlatforms) = preSolution
414416
Debug|Any CPU = Debug|Any CPU
@@ -1070,6 +1072,12 @@ Global
10701072
{DAC54048-A39A-4739-8307-EA5A291F2EA0}.Publish|Any CPU.Build.0 = Debug|Any CPU
10711073
{DAC54048-A39A-4739-8307-EA5A291F2EA0}.Release|Any CPU.ActiveCfg = Release|Any CPU
10721074
{DAC54048-A39A-4739-8307-EA5A291F2EA0}.Release|Any CPU.Build.0 = Release|Any CPU
1075+
{8C3DE41C-E2C8-42B9-8638-574F8946EB0E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
1076+
{8C3DE41C-E2C8-42B9-8638-574F8946EB0E}.Debug|Any CPU.Build.0 = Debug|Any CPU
1077+
{8C3DE41C-E2C8-42B9-8638-574F8946EB0E}.Publish|Any CPU.ActiveCfg = Debug|Any CPU
1078+
{8C3DE41C-E2C8-42B9-8638-574F8946EB0E}.Publish|Any CPU.Build.0 = Debug|Any CPU
1079+
{8C3DE41C-E2C8-42B9-8638-574F8946EB0E}.Release|Any CPU.ActiveCfg = Release|Any CPU
1080+
{8C3DE41C-E2C8-42B9-8638-574F8946EB0E}.Release|Any CPU.Build.0 = Release|Any CPU
10731081
EndGlobalSection
10741082
GlobalSection(SolutionProperties) = preSolution
10751083
HideSolutionNode = FALSE
@@ -1217,6 +1225,7 @@ Global
12171225
{6ECFDF04-2237-4A85-B114-DAA34923E9E6} = {5D4C0700-BBB5-418F-A7B2-F392B9A18263}
12181226
{39EAB599-742F-417D-AF80-95F90376BB18} = {831DDCA2-7D2C-4C31-80DB-6BDB3E1F7AE0}
12191227
{DAC54048-A39A-4739-8307-EA5A291F2EA0} = {0D8C6358-5DAA-4EA6-A924-C268A9A21BC9}
1228+
{8C3DE41C-E2C8-42B9-8638-574F8946EB0E} = {FA3720F1-C99A-49B2-9577-A940257098BF}
12201229
EndGlobalSection
12211230
GlobalSection(ExtensibilityGlobals) = postSolution
12221231
SolutionGuid = {FBDC56A3-86AD-4323-AA0F-201E59123B83}
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<PropertyGroup>
3+
<AssemblyName>GettingStartedWithVectorStores</AssemblyName>
4+
<RootNamespace></RootNamespace>
5+
<ImplicitUsings>enable</ImplicitUsings>
6+
<TargetFramework>net8.0</TargetFramework>
7+
<IsTestProject>true</IsTestProject>
8+
<IsPackable>false</IsPackable>
9+
<!-- Suppress: "Declare types in namespaces", "Require ConfigureAwait", "Experimental" -->
10+
<NoWarn>$(NoWarn);CS8618,IDE0009,CA1051,CA1050,CA1707,CA1054,CA2007,VSTHRD111,CS1591,RCS1110,RCS1243,CA5394,SKEXP0001,SKEXP0010,SKEXP0020,SKEXP0040,SKEXP0050,SKEXP0060,SKEXP0070,SKEXP0101</NoWarn>
11+
<OutputType>Library</OutputType>
12+
<UserSecretsId>5ee045b0-aea3-4f08-8d31-32d1a6f8fed0</UserSecretsId>
13+
</PropertyGroup>
14+
<ItemGroup>
15+
<PackageReference Include="Microsoft.NET.Test.Sdk" />
16+
<PackageReference Include="xRetry" />
17+
<PackageReference Include="xunit" />
18+
<PackageReference Include="xunit.abstractions" />
19+
<PackageReference Include="xunit.runner.visualstudio">
20+
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
21+
<PrivateAssets>all</PrivateAssets>
22+
</PackageReference>
23+
<PackageReference Include="Azure.Identity" />
24+
<PackageReference Include="Microsoft.Extensions.Configuration" />
25+
<PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
26+
<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
27+
<PackageReference Include="Microsoft.Extensions.Configuration.Json" />
28+
<PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
29+
<PackageReference Include="Microsoft.Extensions.DependencyInjection" />
30+
<PackageReference Include="Microsoft.Extensions.Http" />
31+
<PackageReference Include="Microsoft.Extensions.Http.Resilience" />
32+
<PackageReference Include="Microsoft.Extensions.Logging" />
33+
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
34+
<PackageReference Include="Microsoft.Extensions.Logging.Console" />
35+
<PackageReference Include="System.Linq.Async" />
36+
<PackageReference Include="System.Text.Json" />
37+
</ItemGroup>
38+
39+
<Import Project="$(RepoRoot)/dotnet/src/InternalUtilities/samples/SamplesInternalUtilities.props" />
40+
41+
<ItemGroup>
42+
<ProjectReference Include="..\..\src\Connectors\Connectors.AzureOpenAI\Connectors.AzureOpenAI.csproj" />
43+
<ProjectReference Include="..\..\src\Connectors\Connectors.Memory.AzureAISearch\Connectors.Memory.AzureAISearch.csproj" />
44+
<ProjectReference Include="..\..\src\Connectors\Connectors.Memory.InMemory\Connectors.Memory.InMemory.csproj" />
45+
<ProjectReference Include="..\..\src\Connectors\Connectors.Memory.Redis\Connectors.Memory.Redis.csproj" />
46+
<ProjectReference Include="..\..\src\SemanticKernel.Abstractions\SemanticKernel.Abstractions.csproj" />
47+
<ProjectReference Include="..\..\src\SemanticKernel.Core\SemanticKernel.Core.csproj" />
48+
</ItemGroup>
49+
<ItemGroup>
50+
<Using Include="Xunit" />
51+
<Using Include="Xunit.Abstractions" />
52+
</ItemGroup>
53+
</Project>
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using Microsoft.Extensions.VectorData;
4+
5+
namespace GettingStartedWithVectorStores;
6+
7+
/// <summary>
8+
/// Sample model class that represents a glossary entry.
9+
/// </summary>
10+
/// <remarks>
11+
/// Note that each property is decorated with an attribute that specifies how the property should be treated by the vector store.
12+
/// This allows us to create a collection in the vector store and upsert and retrieve instances of this class without any further configuration.
13+
/// </remarks>
14+
internal sealed class Glossary
15+
{
16+
[VectorStoreRecordKey]
17+
public string Key { get; set; }
18+
19+
[VectorStoreRecordData(IsFilterable = true)]
20+
public string Category { get; set; }
21+
22+
[VectorStoreRecordData]
23+
public string Term { get; set; }
24+
25+
[VectorStoreRecordData]
26+
public string Definition { get; set; }
27+
28+
[VectorStoreRecordVector(Dimensions: 1536)]
29+
public ReadOnlyMemory<float> DefinitionEmbedding { get; set; }
30+
}
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Starting With Semantic Kernel Vector Stores
2+
3+
This project contains a step by step guide to get started using Vector Stores with the Semantic Kernel.
4+
5+
The examples can be run as integration tests but their code can also be copied to stand-alone programs.
6+
7+
## Configuring Secrets
8+
9+
Most of the examples will require secrets and credentials, to access OpenAI, Azure OpenAI,
10+
Vector Stores and other resources. We suggest using .NET
11+
[Secret Manager](https://learn.microsoft.com/aspnet/core/security/app-secrets)
12+
to avoid the risk of leaking secrets into the repository, branches and pull requests.
13+
You can also use environment variables if you prefer.
14+
15+
To set your secrets with Secret Manager:
16+
17+
```
18+
cd dotnet/samples/GettingStartedWithVectorStores
19+
20+
dotnet user-secrets init
21+
22+
dotnet user-secrets set "AzureOpenAIEmbeddings:DeploymentName" "..."
23+
dotnet user-secrets set "AzureOpenAIEmbeddings:Endpoint" "..."
24+
25+
dotnet user-secrets set "AzureAISearch:Endpoint" "..."
26+
dotnet user-secrets set "AzureAISearch:ApiKey" "..."
27+
```
28+
29+
To set your secrets with environment variables, use these names:
30+
31+
```
32+
AzureOpenAIEmbeddings__DeploymentName
33+
AzureOpenAIEmbeddings__Endpoint
34+
35+
AzureAISearch__Endpoint
36+
AzureAISearch__ApiKey
37+
```
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using Microsoft.Extensions.VectorData;
4+
using Microsoft.SemanticKernel.Connectors.InMemory;
5+
using Microsoft.SemanticKernel.Embeddings;
6+
7+
namespace GettingStartedWithVectorStores;
8+
9+
/// <summary>
10+
/// Example showing how to generate embeddings and ingest data into an in-memory vector store.
11+
/// </summary>
12+
public class Step1_Ingest_Data(ITestOutputHelper output, VectorStoresFixture fixture) : BaseTest(output), IClassFixture<VectorStoresFixture>
13+
{
14+
/// <summary>
15+
/// Example showing how to ingest data into an in-memory vector store.
16+
/// </summary>
17+
[Fact]
18+
public async Task IngestDataIntoInMemoryVectorStoreAsync()
19+
{
20+
// Construct the vector store and get the collection.
21+
var vectorStore = new InMemoryVectorStore();
22+
var collection = vectorStore.GetCollection<string, Glossary>("skglossary");
23+
24+
// Ingest data into the collection.
25+
await IngestDataIntoVectorStoreAsync(collection, fixture.TextEmbeddingGenerationService);
26+
27+
// Retrieve an item from the collection and write it to the console.
28+
var record = await collection.GetAsync("4");
29+
Console.WriteLine(record!.Definition);
30+
}
31+
32+
/// <summary>
33+
/// Ingest data into the given collection.
34+
/// </summary>
35+
/// <param name="collection">The collection to ingest data into.</param>
36+
/// <param name="textEmbeddingGenerationService">The service to use for generating embeddings.</param>
37+
/// <returns>The keys of the upserted records.</returns>
38+
internal static async Task<IEnumerable<string>> IngestDataIntoVectorStoreAsync(
39+
IVectorStoreRecordCollection<string, Glossary> collection,
40+
ITextEmbeddingGenerationService textEmbeddingGenerationService)
41+
{
42+
// Create the collection if it doesn't exist.
43+
await collection.CreateCollectionIfNotExistsAsync();
44+
45+
// Create glossary entries and generate embeddings for them.
46+
var glossaryEntries = CreateGlossaryEntries().ToList();
47+
var tasks = glossaryEntries.Select(entry => Task.Run(async () =>
48+
{
49+
entry.DefinitionEmbedding = await textEmbeddingGenerationService.GenerateEmbeddingAsync(entry.Definition);
50+
}));
51+
await Task.WhenAll(tasks);
52+
53+
// Upsert the glossary entries into the collection and return their keys.
54+
var upsertedKeysTasks = glossaryEntries.Select(x => collection.UpsertAsync(x));
55+
return await Task.WhenAll(upsertedKeysTasks);
56+
}
57+
58+
/// <summary>
59+
/// Create some sample glossary entries.
60+
/// </summary>
61+
/// <returns>A list of sample glossary entries.</returns>
62+
private static IEnumerable<Glossary> CreateGlossaryEntries()
63+
{
64+
yield return new Glossary
65+
{
66+
Key = "1",
67+
Category = "Software",
68+
Term = "API",
69+
Definition = "Application Programming Interface. A set of rules and specifications that allow software components to communicate and exchange data."
70+
};
71+
72+
yield return new Glossary
73+
{
74+
Key = "2",
75+
Category = "Software",
76+
Term = "SDK",
77+
Definition = "Software development kit. A set of libraries and tools that allow software developers to build software more easily."
78+
};
79+
80+
yield return new Glossary
81+
{
82+
Key = "3",
83+
Category = "SK",
84+
Term = "Connectors",
85+
Definition = "Semantic Kernel Connectors allow software developers to integrate with various services providing AI capabilities, including LLM, AudioToText, TextToAudio, Embedding generation, etc."
86+
};
87+
88+
yield return new Glossary
89+
{
90+
Key = "4",
91+
Category = "SK",
92+
Term = "Semantic Kernel",
93+
Definition = "Semantic Kernel is a set of libraries that allow software developers to more easily develop applications that make use of AI experiences."
94+
};
95+
96+
yield return new Glossary
97+
{
98+
Key = "5",
99+
Category = "AI",
100+
Term = "RAG",
101+
Definition = "Retrieval Augmented Generation - a term that refers to the process of retrieving additional data to provide as context to an LLM to use when generating a response (completion) to a user’s question (prompt)."
102+
};
103+
104+
yield return new Glossary
105+
{
106+
Key = "6",
107+
Category = "AI",
108+
Term = "LLM",
109+
Definition = "Large language model. A type of artificial ingelligence algorithm that is designed to understand and generate human language."
110+
};
111+
}
112+
}
Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using Microsoft.Extensions.VectorData;
4+
using Microsoft.SemanticKernel.Connectors.InMemory;
5+
using Microsoft.SemanticKernel.Embeddings;
6+
7+
namespace GettingStartedWithVectorStores;
8+
9+
/// <summary>
10+
/// Example showing how to do vector searches with an in-memory vector store.
11+
/// </summary>
12+
public class Step2_Vector_Search(ITestOutputHelper output, VectorStoresFixture fixture) : BaseTest(output), IClassFixture<VectorStoresFixture>
13+
{
14+
/// <summary>
15+
/// Do a basic vector search where we just want to retrieve the single most relevant result.
16+
/// </summary>
17+
[Fact]
18+
public async Task SearchAnInMemoryVectorStoreAsync()
19+
{
20+
var collection = await GetVectorStoreCollectionWithDataAsync();
21+
22+
// Search the vector store.
23+
var searchResultItem = await SearchVectorStoreAsync(
24+
collection,
25+
"What is an Application Programming Interface?",
26+
fixture.TextEmbeddingGenerationService);
27+
28+
// Write the search result with its score to the console.
29+
Console.WriteLine(searchResultItem.Record.Definition);
30+
Console.WriteLine(searchResultItem.Score);
31+
}
32+
33+
/// <summary>
34+
/// Search the given collection for the most relevant result to the given search string.
35+
/// </summary>
36+
/// <param name="collection">The collection to search.</param>
37+
/// <param name="searchString">The string to search matches for.</param>
38+
/// <param name="textEmbeddingGenerationService">The service to generate embeddings with.</param>
39+
/// <returns>The top search result.</returns>
40+
internal static async Task<VectorSearchResult<Glossary>> SearchVectorStoreAsync(IVectorStoreRecordCollection<string, Glossary> collection, string searchString, ITextEmbeddingGenerationService textEmbeddingGenerationService)
41+
{
42+
// Generate an embedding from the search string.
43+
var searchVector = await textEmbeddingGenerationService.GenerateEmbeddingAsync(searchString);
44+
45+
// Search the store and get the single most relevant result.
46+
var searchResult = await collection.VectorizedSearchAsync(
47+
searchVector,
48+
new()
49+
{
50+
Top = 1
51+
});
52+
var searchResultItems = await searchResult.Results.ToListAsync();
53+
return searchResultItems.First();
54+
}
55+
56+
/// <summary>
57+
/// Do a more complex vector search with pre-filtering.
58+
/// </summary>
59+
[Fact]
60+
public async Task SearchAnInMemoryVectorStoreWithFilteringAsync()
61+
{
62+
var collection = await GetVectorStoreCollectionWithDataAsync();
63+
64+
// Generate an embedding from the search string.
65+
var searchString = "How do I provide additional context to an LLM?";
66+
var searchVector = await fixture.TextEmbeddingGenerationService.GenerateEmbeddingAsync(searchString);
67+
68+
// Search the store with a filter and get the single most relevant result.
69+
var searchResult = await collection.VectorizedSearchAsync(
70+
searchVector,
71+
new()
72+
{
73+
Top = 1,
74+
Filter = new VectorSearchFilter().EqualTo(nameof(Glossary.Category), "AI")
75+
});
76+
var searchResultItems = await searchResult.Results.ToListAsync();
77+
78+
// Write the search result with its score to the console.
79+
Console.WriteLine(searchResultItems.First().Record.Definition);
80+
Console.WriteLine(searchResultItems.First().Score);
81+
}
82+
83+
private async Task<IVectorStoreRecordCollection<string, Glossary>> GetVectorStoreCollectionWithDataAsync()
84+
{
85+
// Construct the vector store and get the collection.
86+
var vectorStore = new InMemoryVectorStore();
87+
var collection = vectorStore.GetCollection<string, Glossary>("skglossary");
88+
89+
// Ingest data into the collection using the code from step 1.
90+
await Step1_Ingest_Data.IngestDataIntoVectorStoreAsync(collection, fixture.TextEmbeddingGenerationService);
91+
92+
return collection;
93+
}
94+
}

0 commit comments

Comments
 (0)