.Net: Add hybrid search abstraction and azure ai search implementation (#10441)

### Motivation and Context

#9399

Adding the ADR, Keyword Hybrid Search abstractions and an implementation
with integration tests for Azure AI Search.

### Description

Adding the ADR, Keyword Hybrid Search abstractions and an implementation
with integration tests for Azure AI Search.
More implementations to follow.

### 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 😄

Author: westey-m

docs/decisions/00NN-hybrid-search.md

@@ -23,7 +23,10 @@ namespace Microsoft.SemanticKernel.Connectors.AzureAISearch;
 /// </summary>
 /// <typeparam name="TRecord">The data model to use for adding, updating and retrieving data from storage.</typeparam>
 #pragma warning disable CA1711 // Identifiers should not have incorrect suffix
-public sealed class AzureAISearchVectorStoreRecordCollection<TRecord> : IVectorStoreRecordCollection<string, TRecord>, IVectorizableTextSearch<TRecord>
+public sealed class AzureAISearchVectorStoreRecordCollection<TRecord> :
+    IVectorStoreRecordCollection<string, TRecord>,
+    IVectorizableTextSearch<TRecord>,
+    IKeywordVectorizedHybridSearch<TRecord>
 #pragma warning restore CA1711 // Identifiers should not have incorrect suffix
 {
     /// <summary>The name of this database for telemetry purposes.</summary>
@@ -68,6 +71,9 @@ public sealed class AzureAISearchVectorStoreRecordCollection<TRecord> : IVectorS
     /// <summary>The default options for vector search.</summary>
     private static readonly VectorData.VectorSearchOptions s_defaultVectorSearchOptions = new();
 
+    /// <summary>The default options for hybrid vector search.</summary>
+    private static readonly KeywordVectorizedHybridSearchOptions s_defaultKeywordVectorizedHybridSearchOptions = new();
+
     /// <summary>Azure AI Search client that can be used to manage the list of indices in an Azure AI Search Service.</summary>
     private readonly SearchIndexClient _searchIndexClient;
 
@@ -316,25 +322,16 @@ public async IAsyncEnumerable<string> UpsertBatchAsync(IEnumerable<TRecord> reco
     /// <inheritdoc />
     public Task<VectorSearchResults<TRecord>> VectorizedSearchAsync<TVector>(TVector vector, VectorData.VectorSearchOptions? options = null, CancellationToken cancellationToken = default)
     {
-        Verify.NotNull(vector);
-
-        if (this._propertyReader.FirstVectorPropertyName is null)
-        {
-            throw new InvalidOperationException("The collection does not have any vector fields, so vector search is not possible.");
-        }
-
-        if (vector is not ReadOnlyMemory<float> floatVector)
-        {
-            throw new NotSupportedException($"The provided vector type {vector.GetType().FullName} is not supported by the Azure AI Search connector.");
-        }
+        var floatVector = VerifyVectorParam(vector);
 
         // Resolve options.
         var internalOptions = options ?? s_defaultVectorSearchOptions;
-        string? vectorFieldName = this.ResolveVectorFieldName(internalOptions.VectorPropertyName);
+        var vectorProperty = this._propertyReader.GetVectorPropertyOrFirst(internalOptions.VectorPropertyName);
+        var vectorPropertyName = this._propertyReader.GetJsonPropertyName(vectorProperty!.DataModelPropertyName);
 
         // Configure search settings.
         var vectorQueries = new List<VectorQuery>();
-        vectorQueries.Add(new VectorizedQuery(floatVector) { KNearestNeighborsCount = internalOptions.Top, Fields = { vectorFieldName } });
+        vectorQueries.Add(new VectorizedQuery(floatVector) { KNearestNeighborsCount = internalOptions.Top, Fields = { vectorPropertyName } });
         var filterString = AzureAISearchVectorStoreCollectionSearchMapping.BuildFilterString(internalOptions.Filter, this._propertyReader.JsonPropertyNamesMap);
 
         // Build search options.
@@ -370,11 +367,12 @@ public Task<VectorSearchResults<TRecord>> VectorizableTextSearchAsync(string sea
 
         // Resolve options.
         var internalOptions = options ?? s_defaultVectorSearchOptions;
-        string? vectorFieldName = this.ResolveVectorFieldName(internalOptions.VectorPropertyName);
+        var vectorProperty = this._propertyReader.GetVectorPropertyOrFirst(internalOptions.VectorPropertyName);
+        var vectorPropertyName = this._propertyReader.GetJsonPropertyName(vectorProperty!.DataModelPropertyName);
 
         // Configure search settings.
         var vectorQueries = new List<VectorQuery>();
-        vectorQueries.Add(new VectorizableTextQuery(searchText) { KNearestNeighborsCount = internalOptions.Top, Fields = { vectorFieldName } });
+        vectorQueries.Add(new VectorizableTextQuery(searchText) { KNearestNeighborsCount = internalOptions.Top, Fields = { vectorPropertyName } });
         var filterString = AzureAISearchVectorStoreCollectionSearchMapping.BuildFilterString(internalOptions.Filter, this._propertyReader.JsonPropertyNamesMap);
 
         // Build search options.
@@ -398,6 +396,48 @@ public Task<VectorSearchResults<TRecord>> VectorizableTextSearchAsync(string sea
         return this.SearchAndMapToDataModelAsync(null, searchOptions, internalOptions.IncludeVectors, cancellationToken);
     }
 
+    /// <inheritdoc />
+    public Task<VectorSearchResults<TRecord>> KeywordVectorizedHybridSearch<TVector>(TVector vector, ICollection<string> keywords, KeywordVectorizedHybridSearchOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        Verify.NotNull(keywords);
+        var floatVector = VerifyVectorParam(vector);
+
+        // Resolve options.
+        var internalOptions = options ?? s_defaultKeywordVectorizedHybridSearchOptions;
+        var vectorProperty = this._propertyReader.GetVectorPropertyOrFirst(internalOptions.VectorPropertyName);
+        var vectorPropertyName = this._propertyReader.GetJsonPropertyName(vectorProperty.DataModelPropertyName);
+        var textDataProperty = this._propertyReader.GetFullTextDataPropertyOrSingle(internalOptions.FullTextPropertyName);
+        var textDataPropertyName = this._propertyReader.GetJsonPropertyName(textDataProperty.DataModelPropertyName);
+
+        // Configure search settings.
+        var vectorQueries = new List<VectorQuery>();
+        vectorQueries.Add(new VectorizedQuery(floatVector) { KNearestNeighborsCount = internalOptions.Top, Fields = { vectorPropertyName } });
+        var filterString = AzureAISearchVectorStoreCollectionSearchMapping.BuildFilterString(internalOptions.Filter, this._propertyReader.JsonPropertyNamesMap);
+
+        // Build search options.
+        var searchOptions = new SearchOptions
+        {
+            VectorSearch = new(),
+            Size = internalOptions.Top,
+            Skip = internalOptions.Skip,
+            Filter = filterString,
+            IncludeTotalCount = internalOptions.IncludeTotalCount,
+        };
+        searchOptions.VectorSearch.Queries.AddRange(vectorQueries);
+        searchOptions.SearchFields.Add(textDataPropertyName);
+
+        // Filter out vector fields if requested.
+        if (!internalOptions.IncludeVectors)
+        {
+            searchOptions.Select.Add(this._propertyReader.KeyPropertyJsonName);
+            searchOptions.Select.AddRange(this._propertyReader.DataPropertyJsonNames);
+        }
+
+        var keywordsCombined = string.Join(" ", keywords);
+
+        return this.SearchAndMapToDataModelAsync(keywordsCombined, searchOptions, internalOptions.IncludeVectors, cancellationToken);
+    }
+
     /// <summary>
     /// Get the document with the given key and map it to the data model using the configured mapper type.
     /// </summary>
@@ -556,31 +596,6 @@ private GetDocumentOptions ConvertGetDocumentOptions(GetRecordOptions? options)
         return innerOptions;
     }
 
-    /// <summary>
-    /// Resolve the vector field name to use for a search by using the storage name for the field name from options
-    /// if available, and falling back to the first vector field name if not.
-    /// </summary>
-    /// <param name="optionsVectorFieldName">The vector field name provided via options.</param>
-    /// <returns>The resolved vector field name.</returns>
-    /// <exception cref="InvalidOperationException">Thrown if the provided field name is not a valid field name.</exception>
-    private string ResolveVectorFieldName(string? optionsVectorFieldName)
-    {
-        string? vectorFieldName;
-        if (!string.IsNullOrWhiteSpace(optionsVectorFieldName))
-        {
-            if (!this._propertyReader.JsonPropertyNamesMap.TryGetValue(optionsVectorFieldName!, out vectorFieldName))
-            {
-                throw new InvalidOperationException($"The collection does not have a vector field named '{optionsVectorFieldName}'.");
-            }
-        }
-        else
-        {
-            vectorFieldName = this._propertyReader.FirstVectorPropertyJsonName;
-        }
-
-        return vectorFieldName!;
-    }
-
     /// <summary>
     /// Get a document with the given key, and return null if it is not found.
     /// </summary>
@@ -638,4 +653,16 @@ private async Task<T> RunOperationAsync<T>(string operationName, Func<Task<T>> o
             };
         }
     }
+
+    private static ReadOnlyMemory<float> VerifyVectorParam<TVector>(TVector vector)
+    {
+        Verify.NotNull(vector);
+
+        if (vector is not ReadOnlyMemory<float> floatVector)
+        {
+            throw new NotSupportedException($"The provided vector type {vector.GetType().FullName} is not supported by the Azure AI Search connector.");
+        }
+
+        return floatVector;
+    }
 }

dotnet/src/Connectors/Connectors.Memory.AzureAISearch/AzureAISearchVectorStoreRecordCollection.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Extensions.VectorData;
+
+/// <summary>
+/// Contains a method for doing a hybrid search using a vector and keywords.
+/// </summary>
+/// <typeparam name="TRecord">The record data model to use for retrieving data from the store.</typeparam>
+public interface IKeywordVectorizedHybridSearch<TRecord>
+{
+    /// <summary>
+    /// Performs a hybrid search for records that match the given embedding and keywords, after applying the provided filters.
+    /// </summary>
+    /// <typeparam name="TVector">The type of the vector.</typeparam>
+    /// <param name="vector">The vector to search the store with.</param>
+    /// <param name="keywords">A collection of keywords to search the store with.</param>
+    /// <param name="options">The options that control the behavior of the search.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The records found by the hybrid search, including their result scores.</returns>
+    Task<VectorSearchResults<TRecord>> KeywordVectorizedHybridSearch<TVector>(
+        TVector vector,
+        ICollection<string> keywords,
+        KeywordVectorizedHybridSearchOptions? options = default,
+        CancellationToken cancellationToken = default);
+}

dotnet/src/Connectors/VectorData.Abstractions/VectorSearch/IKeywordVectorizedHybridSearch.cs

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Extensions.VectorData;
+
+/// <summary>
+/// Options for hybrid search when using a dense vector and string keywords to do the search.
+/// </summary>
+public class KeywordVectorizedHybridSearchOptions
+{
+    /// <summary>
+    /// Gets or sets a search filter to use before doing the hybrid search.
+    /// </summary>
+    public VectorSearchFilter? Filter { get; init; }
+
+    /// <summary>
+    /// Gets or sets the name of the target dense vector property to search on.
+    /// Use the name of the vector property from your data model or as provided in the record definition.
+    /// If not provided will default to the first vector property in the schema.
+    /// </summary>
+    public string? VectorPropertyName { get; init; }
+
+    /// <summary>
+    /// Gets or sets the name of the target text property to do the text/keyword search on.
+    /// The property must have full text search enabled.
+    /// Use the name of the data property from your data model or as provided in the record definition.
+    /// If not provided will look if there is a text property with full text search enabled, and
+    /// will throw if either none or multiple exist.
+    /// </summary>
+    public string? FullTextPropertyName { get; init; }
+
+    /// <summary>
+    /// Gets or sets the maximum number of results to return.
+    /// </summary>
+    public int Top { get; init; } = 3;
+
+    /// <summary>
+    /// Gets or sets the number of results to skip before returning results, i.e. the index of the first result to return.
+    /// </summary>
+    public int Skip { get; init; } = 0;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to include vectors in the retrieval result.
+    /// </summary>
+    public bool IncludeVectors { get; init; } = false;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the total count should be included in the results.
+    /// </summary>
+    /// <remarks>
+    /// Default value is false.
+    /// Not all vector search implementations will support this option in which case the total
+    /// count will be null even if requested via this option.
+    /// </remarks>
+    public bool IncludeTotalCount { get; init; } = false;
+}

dotnet/src/Connectors/VectorData.Abstractions/VectorSearch/KeywordVectorizedHybridSearchOptions.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Threading.Tasks;
+using SemanticKernel.IntegrationTests.Connectors.Memory.Xunit;
+
+namespace SemanticKernel.IntegrationTests.Connectors.Memory.AzureAISearch;
+
+/// <summary>
+/// Attribute to use to skip tests if the settings for Azure AI Search is not set.
+/// </summary>
+[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
+public sealed class AzureAISearchConfigConditionAttribute : Attribute, ITestCondition
+{
+    public ValueTask<bool> IsMetAsync()
+    {
+        var config = AzureAISearchVectorStoreFixture.GetAzureAISearchConfiguration();
+        var isMet = config is not null && !string.IsNullOrWhiteSpace(config.ServiceUrl) && !string.IsNullOrWhiteSpace(config.ApiKey);
+
+        return ValueTask.FromResult(isMet);
+    }
+
+    public string SkipReason
+        => "Azure AI Search ServiceUrl or ApiKey was not specified in user secrets. Use the following command to set them: dotnet user-secrets set \"AzureAISearch:ServiceUrl\" \"your_service_url\" and dotnet user-secrets set \"AzureAISearch:ApiKey\" \"your_api_key\"";
+}

dotnet/src/IntegrationTests/Connectors/Memory/AzureAISearch/AzureAISearchConfigConditionAttribute.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Connectors.AzureAISearch;
+using Xunit;
+
+namespace SemanticKernel.IntegrationTests.Connectors.Memory.AzureAISearch;
+
+/// <summary>
+/// Inherits common integration tests that should pass for any <see cref="IKeywordVectorizedHybridSearch{TRecord}"/>.
+/// </summary>
+/// <param name="fixture">Azure AI Search setup and teardown.</param>
+[Collection("AzureAISearchVectorStoreCollection")]
+[AzureAISearchConfigCondition]
+public class AzureAISearchKeywordVectorizedHybridSearchTests(AzureAISearchVectorStoreFixture fixture) : BaseKeywordVectorizedHybridSearchTests<string>
+{
+    protected override string Key1 => "1";
+    protected override string Key2 => "2";
+    protected override string Key3 => "3";
+    protected override string Key4 => "4";
+    protected override int DelayAfterUploadInMilliseconds => 2000;
+
+    protected override IVectorStoreRecordCollection<string, TRecord> GetTargetRecordCollection<TRecord>(string recordCollectionName, VectorStoreRecordDefinition? vectorStoreRecordDefinition)
+    {
+        return new AzureAISearchVectorStoreRecordCollection<TRecord>(fixture.SearchIndexClient, recordCollectionName + AzureAISearchVectorStoreFixture.TestIndexPostfix, new()
+        {
+            VectorStoreRecordDefinition = vectorStoreRecordDefinition
+        });
+    }
+}

dotnet/src/IntegrationTests/Connectors/Memory/AzureAISearch/AzureAISearchKeywordVectorizedHybridSearchTests.cs

@@ -29,8 +29,13 @@ public class AzureAISearchVectorStoreFixture : IAsyncLifetime
     /// <summary>
     /// Test index name which consists out of "hotels-" and the machine name with any non-alphanumeric characters removed.
     /// </summary>
+    private readonly string _testIndexName = "hotels-" + TestIndexPostfix;
+
+    /// <summary>
+    /// Gets the test index name postfix that is derived from the local machine name used to avoid clashes between test runs from different callers.
+    /// </summary>
 #pragma warning disable CA1308 // Normalize strings to uppercase
-    private readonly string _testIndexName = "hotels-" + new Regex("[^a-zA-Z0-9]").Replace(Environment.MachineName.ToLowerInvariant(), "");
+    public static string TestIndexPostfix { get; private set; } = new Regex("[^a-zA-Z0-9]").Replace(Environment.MachineName.ToLowerInvariant(), "");
 #pragma warning restore CA1308 // Normalize strings to uppercase
 
     /// <summary>
@@ -43,12 +48,20 @@ public class AzureAISearchVectorStoreFixture : IAsyncLifetime
         .AddUserSecrets<AzureAISearchVectorStoreFixture>()
         .Build();
 
+    /// <summary>
+    /// Get the test configuration for Azure AI Search.
+    /// </summary>
+    public static AzureAISearchConfiguration? GetAzureAISearchConfiguration()
+    {
+        return s_configuration.GetRequiredSection("AzureAISearch").Get<AzureAISearchConfiguration>();
+    }
+
     /// <summary>
     /// Initializes a new instance of the <see cref="AzureAISearchVectorStoreFixture"/> class.
     /// </summary>
     public AzureAISearchVectorStoreFixture()
     {
-        var config = s_configuration.GetRequiredSection("AzureAISearch").Get<AzureAISearchConfiguration>();
+        var config = GetAzureAISearchConfiguration();
         Assert.NotNull(config);
         this.Config = config;
         this.SearchIndexClient = new SearchIndexClient(new Uri(config.ServiceUrl), new AzureKeyCredential(config.ApiKey));