add hybrid search

Author: eavanvalkenburg

Diff for: python/samples/concepts/memory/complex_memory.py

@@ -44,7 +44,7 @@
     vectorstoremodel,
 )
 from semantic_kernel.data.const import DISTANCE_FUNCTION_DIRECTION_HELPER, DistanceFunction, IndexKind
-from semantic_kernel.data.vector_search import add_vector_to_records
+from semantic_kernel.data.vector_search import KeywordHybridSearchMixin, add_vector_to_records
 
 # This is a rather complex sample, showing how to use the vector store
 # with a number of different collections.
@@ -279,6 +279,29 @@ async def main(collection: str, use_azure_openai: bool):
         print_with_color("Now we can start searching.", Colors.CBLUE)
         print_with_color("  For each type of search, enter a search term, for instance `python`.", Colors.CBLUE)
         print_with_color("  Enter exit to exit, and skip or nothing to skip this search.", Colors.CBLUE)
+        if isinstance(record_collection, KeywordHybridSearchMixin):
+            search_text = input("Enter search text for hybrid text search: ")
+            if search_text.lower() == "exit":
+                await cleanup(record_collection)
+                return
+            if not search_text or search_text.lower() != "skip":
+                print("-" * 30)
+                print_with_color(
+                    f"Using hybrid text search, for {distance_function.value}, "
+                    f"the {'higher' if DISTANCE_FUNCTION_DIRECTION_HELPER[distance_function](1, 0) else 'lower'} the score the better",  # noqa: E501
+                    Colors.CBLUE,
+                )
+                try:
+                    vector = (await embedder.generate_raw_embeddings([search_text]))[0]
+                    search_results = await record_collection.hybrid_search(
+                        keywords=search_text, vector=vector, options=options
+                    )
+                    if search_results.total_count == 0:
+                        print("\nNothing found...\n")
+                    else:
+                        [print_record(result) async for result in search_results.results]
+                except Exception as e:
+                    print(f"Error: {e}")
         if isinstance(record_collection, VectorTextSearchMixin):
             search_text = input("Enter search text for text search: ")
             if search_text.lower() == "exit":

Diff for: python/semantic_kernel/connectors/memory/azure_ai_search/azure_ai_search_collection.py

@@ -17,9 +17,14 @@
     get_search_client,
     get_search_index_client,
 )
-from semantic_kernel.data.record_definition import VectorStoreRecordDefinition, VectorStoreRecordVectorField
+from semantic_kernel.data.record_definition import (
+    VectorStoreRecordDataField,
+    VectorStoreRecordDefinition,
+    VectorStoreRecordVectorField,
+)
 from semantic_kernel.data.text_search import AnyTagsEqualTo, EqualTo, KernelSearchResults
 from semantic_kernel.data.vector_search import (
+    KeywordHybridSearchMixin,
     VectorizableTextSearchMixin,
     VectorizedSearchMixin,
     VectorSearchFilter,
@@ -33,6 +38,7 @@
     VectorStoreInitializationException,
     VectorStoreOperationException,
 )
+from semantic_kernel.kernel_types import OptionalOneOrMany
 from semantic_kernel.utils.feature_stage_decorator import experimental
 
 if sys.version_info >= (3, 12):
@@ -49,6 +55,7 @@ class AzureAISearchCollection(
     VectorizableTextSearchMixin[TKey, TModel],
     VectorizedSearchMixin[TKey, TModel],
     VectorTextSearchMixin[TKey, TModel],
+    KeywordHybridSearchMixin[TKey, TModel],
     Generic[TKey, TModel],
 ):
     """Azure AI Search collection implementation."""
@@ -241,13 +248,15 @@ async def _inner_search(
         search_text: str | None = None,
         vectorizable_text: str | None = None,
         vector: list[float | int] | None = None,
+        keywords: OptionalOneOrMany[str] = None,
         **kwargs: Any,
     ) -> KernelSearchResults[VectorSearchResult[TModel]]:
         search_args: dict[str, Any] = {
             "top": options.top,
             "skip": options.skip,
             "include_total_count": options.include_total_count,
         }
+        vector_field = self.data_model_definition.try_get_vector_field(options.vector_field_name)
         if options.filter.filters:
             search_args["filter"] = self._build_filter_string(options.filter)
         if search_text is not None:
@@ -257,15 +266,29 @@ async def _inner_search(
                 VectorizableTextQuery(
                     text=vectorizable_text,
                     k_nearest_neighbors=options.top,
-                    fields=options.vector_field_name,
+                    fields=vector_field.name if vector_field else None,
                 )
             ]
         if vector is not None:
+            if keywords is not None:
+                # hybrid search
+                search_args["search_fields"] = (
+                    [options.keyword_field_name]
+                    if options.keyword_field_name
+                    else [
+                        field.name
+                        for field in self.data_model_definition.fields
+                        if isinstance(field, VectorStoreRecordDataField) and field.is_full_text_searchable
+                    ]
+                )
+                if not search_args["search_fields"]:
+                    raise VectorStoreOperationException("No searchable fields found for hybrid search.")
+                search_args["search_text"] = keywords if isinstance(keywords, str) else ", ".join(keywords)
             search_args["vector_queries"] = [
                 VectorizedQuery(
                     vector=vector,
                     k_nearest_neighbors=options.top,
-                    fields=options.vector_field_name,
+                    fields=vector_field.name if vector_field else None,
                 )
             ]
         if "vector_queries" not in search_args and "search_text" not in search_args:

Diff for: python/semantic_kernel/data/vector_search.py

@@ -32,7 +32,7 @@
 )
 from semantic_kernel.kernel import Kernel
 from semantic_kernel.kernel_pydantic import KernelBaseModel
-from semantic_kernel.kernel_types import OneOrMany
+from semantic_kernel.kernel_types import OneOrMany, OptionalOneOrMany
 from semantic_kernel.utils.feature_stage_decorator import experimental
 from semantic_kernel.utils.list_handler import desync_list
 
@@ -82,6 +82,7 @@ class VectorSearchOptions(SearchOptions):
 
     filter: VectorSearchFilter = Field(default_factory=VectorSearchFilter)
     vector_field_name: str | None = None
+    keyword_field_name: str | None = None
     top: Annotated[int, Field(gt=0)] = 3
     skip: Annotated[int, Field(ge=0)] = 0
     include_vectors: bool = False
@@ -116,6 +117,7 @@ def options_class(self) -> type[SearchOptions]:
     async def _inner_search(
         self,
         options: VectorSearchOptions,
+        keywords: OptionalOneOrMany[str] = None,
         search_text: str | None = None,
         vectorizable_text: str | None = None,
         vector: list[float | int] | None = None,
@@ -144,6 +146,7 @@ async def _inner_search(
 
         Args:
             options: The search options, can be None.
+            keywords: The text to search for, optional.
             search_text: The text to search for, optional.
             vectorizable_text: The text to search for, will be vectorized downstream, optional.
             vector: The vector to search for, optional.
@@ -216,7 +219,7 @@ async def _get_vector_search_results_from_results(
 
 @experimental
 class VectorizedSearchMixin(VectorSearchBase[TKey, TModel], Generic[TKey, TModel]):
-    """The mixin for searching with vectors."""
+    """The mixin for searching with vectors. To be used in combination with VectorStoreRecordCollection."""
 
     async def vectorized_search(
         self,
@@ -280,7 +283,7 @@ def create_text_search_from_vectorized_search(
 class VectorizableTextSearchMixin(VectorSearchBase[TKey, TModel], Generic[TKey, TModel]):
     """The mixin for searching with text that get's vectorized downstream.
 
-    To be used in combination with VectorSearchBase.
+    To be used in combination with VectorStoreRecordCollection.
     """
 
     async def vectorizable_text_search(
@@ -341,7 +344,7 @@ def create_text_search_from_vectorizable_text_search(
 
 @experimental
 class VectorTextSearchMixin(VectorSearchBase[TKey, TModel], Generic[TKey, TModel]):
-    """The mixin for text search, to be used in combination with VectorSearchBase."""
+    """The mixin for text search, to be used in combination with VectorStoreRecordCollection."""
 
     async def text_search(
         self,
@@ -394,6 +397,66 @@ def create_text_search_from_vector_text_search(
         return VectorStoreTextSearch.from_vector_text_search(self, string_mapper, text_search_results_mapper)
 
 
+# region: Keyword Hybrid Search
+
+
+@experimental
+class KeywordHybridSearchMixin(VectorSearchBase[TKey, TModel], Generic[TKey, TModel]):
+    """The mixin for hybrid vector and text search, to be used in combination with VectorStoreRecordCollection."""
+
+    async def hybrid_search(
+        self,
+        vector: list[float | int],
+        keywords: OneOrMany[str],
+        options: SearchOptions | None = None,
+        **kwargs: Any,
+    ) -> "KernelSearchResults[VectorSearchResult[TModel]]":
+        """Search the vector store for records that match the given text and filters.
+
+        Args:
+            vector: The vector to search for.
+            keywords: The keywords to search for.
+            options: options, should include query_text
+            **kwargs: if options are not set, this is used to create them.
+
+        Raises:
+            VectorSearchExecutionException: If an error occurs during the search.
+            VectorStoreModelDeserializationException: If an error occurs during deserialization.
+            VectorSearchOptionsException: If the search options are invalid.
+            VectorStoreMixinException: raised when the method is not used in combination with the VectorSearchBase.
+
+        """
+        options = create_options(self.options_class, options, **kwargs)  # type: ignore
+        try:
+            return await self._inner_search(vector=vector, keywords=keywords, options=options)  # type: ignore
+        except (VectorStoreModelDeserializationException, VectorSearchOptionsException, VectorSearchExecutionException):
+            raise  # pragma: no cover
+        except Exception as exc:
+            raise VectorSearchExecutionException(f"An error occurred during the search: {exc}") from exc
+
+    def create_text_search_from_vector_text_search(
+        self,
+        string_mapper: Callable[[TModel], str] | None = None,
+        text_search_results_mapper: Callable[[TModel], TextSearchResult] | None = None,
+    ) -> "VectorStoreTextSearch[TModel]":
+        """Create a VectorStoreTextSearch object.
+
+        This method is used to create a VectorStoreTextSearch object that can be used to search the vector store
+        for records that match the given text and filter.
+        The text string will be vectorized downstream and used for the vector search.
+
+        Args:
+            string_mapper: A function that maps the record to a string.
+            text_search_results_mapper: A function that maps the record to a TextSearchResult.
+
+        Returns:
+            VectorStoreTextSearch: The created VectorStoreTextSearch object.
+        """
+        from semantic_kernel.data.vector_store_text_search import VectorStoreTextSearch
+
+        return VectorStoreTextSearch.from_vector_text_search(self, string_mapper, text_search_results_mapper)
+
+
 # region: add_vector_to_records
 
 

Diff for: python/tests/conftest.py

@@ -365,9 +365,7 @@ def data_model_definition(
         fields={
             "id": VectorStoreRecordKeyField(property_type="str"),
             "content": VectorStoreRecordDataField(
-                has_embedding=True,
-                embedding_property_name="vector",
-                property_type="str",
+                has_embedding=True, embedding_property_name="vector", property_type="str", is_full_text_searchable=True
             ),
             "vector": VectorStoreRecordVectorField(
                 dimensions=dimensions,

Diff for: python/tests/unit/connectors/memory/azure_ai_search/test_azure_ai_search.py

@@ -1,6 +1,7 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 
+import asyncio
 from unittest.mock import MagicMock, Mock, patch
 
 from pytest import fixture, mark, raises
@@ -14,6 +15,7 @@
     data_model_definition_to_azure_ai_search_index,
     get_search_index_client,
 )
+from semantic_kernel.data.vector_search import VectorSearchOptions
 from semantic_kernel.exceptions import (
     ServiceInitializationError,
     VectorStoreInitializationException,
@@ -72,6 +74,17 @@ def mock_get():
         yield mock_get_document
 
 
+@fixture
+def mock_search():
+    async def iter_search_results(*args, **kwargs):
+        yield {"id": "id1", "content": "content", "vector": [1.0, 2.0, 3.0]}
+        await asyncio.sleep(0.0)
+
+    with patch(f"{BASE_PATH_SEARCH_CLIENT}.search") as mock_search:
+        mock_search.side_effect = iter_search_results
+        yield mock_search
+
+
 @fixture
 def mock_delete():
     with patch(f"{BASE_PATH_SEARCH_CLIENT}.delete_documents") as mock_delete_documents:
@@ -293,3 +306,93 @@ def test_get_search_index_client(azure_ai_search_unit_test_env):
 
     with raises(ServiceInitializationError):
         get_search_index_client(settings)
+
+
+@mark.parametrize("include_vectors", [True, False])
+async def test_search_text_search(collection, mock_search, include_vectors):
+    options = VectorSearchOptions(include_vectors=include_vectors)
+    results = await collection.text_search("test", options=options)
+    assert results is not None
+    async for result in results.results:
+        assert result is not None
+        assert result.record is not None
+        assert result.record["id"] == "id1"
+        assert result.record["content"] == "content"
+        if include_vectors:
+            assert result.record["vector"] == [1.0, 2.0, 3.0]
+    mock_search.assert_awaited_once_with(
+        top=3,
+        skip=0,
+        include_total_count=False,
+        search_text="test",
+        select=["*"] if include_vectors else ["id", "content"],
+    )
+
+
+@mark.parametrize("include_vectors", [True, False])
+async def test_search_vectorized_search(collection, mock_search, include_vectors):
+    options = VectorSearchOptions(include_vectors=include_vectors)
+    results = await collection.vectorized_search([0.1, 0.2, 0.3], options=options)
+    assert results is not None
+    async for result in results.results:
+        assert result is not None
+        assert result.record is not None
+        assert result.record["id"] == "id1"
+        assert result.record["content"] == "content"
+        if include_vectors:
+            assert result.record["vector"] == [1.0, 2.0, 3.0]
+    for call in mock_search.call_args_list:
+        assert call[1]["top"] == 3
+        assert call[1]["skip"] == 0
+        assert call[1]["include_total_count"] is False
+        assert call[1]["select"] == ["*"] if include_vectors else ["id", "content"]
+        assert call[1]["vector_queries"][0].vector == [0.1, 0.2, 0.3]
+        assert call[1]["vector_queries"][0].fields == "vector"
+        assert call[1]["vector_queries"][0].k_nearest_neighbors == 3
+
+
+@mark.parametrize("include_vectors", [True, False])
+async def test_search_vectorizable_search(collection, mock_search, include_vectors):
+    options = VectorSearchOptions(include_vectors=include_vectors)
+    results = await collection.vectorizable_text_search("test", options=options)
+    assert results is not None
+    async for result in results.results:
+        assert result is not None
+        assert result.record is not None
+        assert result.record["id"] == "id1"
+        assert result.record["content"] == "content"
+        if include_vectors:
+            assert result.record["vector"] == [1.0, 2.0, 3.0]
+    for call in mock_search.call_args_list:
+        assert call[1]["top"] == 3
+        assert call[1]["skip"] == 0
+        assert call[1]["include_total_count"] is False
+        assert call[1]["select"] == ["*"] if include_vectors else ["id", "content"]
+        assert call[1]["vector_queries"][0].text == "test"
+        assert call[1]["vector_queries"][0].fields == "vector"
+        assert call[1]["vector_queries"][0].k_nearest_neighbors == 3
+
+
+@mark.parametrize("include_vectors", [True, False])
+@mark.parametrize("keywords", ["test", ["test1", "test2"]], ids=["single", "multiple"])
+async def test_search_keyword_hybrid_search(collection, mock_search, include_vectors, keywords):
+    options = VectorSearchOptions(include_vectors=include_vectors, keyword_field_name="content")
+    results = await collection.hybrid_search(keywords=keywords, vector=[0.1, 0.2, 0.3], options=options)
+    assert results is not None
+    async for result in results.results:
+        assert result is not None
+        assert result.record is not None
+        assert result.record["id"] == "id1"
+        assert result.record["content"] == "content"
+        if include_vectors:
+            assert result.record["vector"] == [1.0, 2.0, 3.0]
+    for call in mock_search.call_args_list:
+        assert call[1]["top"] == 3
+        assert call[1]["skip"] == 0
+        assert call[1]["include_total_count"] is False
+        assert call[1]["select"] == ["*"] if include_vectors else ["id", "content"]
+        assert call[1]["search_fields"] == ["content"]
+        assert call[1]["search_text"] == "test" if keywords == "test" else "test1, test2"
+        assert call[1]["vector_queries"][0].vector == [0.1, 0.2, 0.3]
+        assert call[1]["vector_queries"][0].fields == "vector"
+        assert call[1]["vector_queries"][0].k_nearest_neighbors == 3

Diff for: python/tests/unit/data/test_vector_search_base.py

@@ -12,9 +12,7 @@
 async def test_search(vector_store_record_collection: VectorSearchBase):
     record = {"id": "test_id", "content": "test_content", "vector": [1.0, 2.0, 3.0]}
     await vector_store_record_collection.upsert(record)
-    results = await vector_store_record_collection._inner_search(
-        options=VectorSearchOptions(), search_text="test_content"
-    )
+    results = await vector_store_record_collection._inner_search(options=VectorSearchOptions(), keywords="test_content")
     records = [rec async for rec in results.results]
     assert records[0].record == record