Tair (Redis® OSS-Compatible):Implement hybrid search by using TairVector

Why combine search methods

Large language models (LLMs) encode unstructured data—text, images, audio, and video—as vectors, enabling semantic similarity search. Each search method has distinct strengths and limitations:

TairVector combines all three methods in a single statement. Results from each method are scored, weighted, and merged into a final candidate set. Use the hybrid_ratio parameter to control how much weight each method receives.

How hybrid_ratio works

hybrid_ratio sets the weight for vector search. The weight for full-text search is 1 - hybrid_ratio.

When both vector search and full-text search retrieve the same item, that item ranks higher in the merged results.

Example dataset

The examples in this guide use the open-source fashion-product-images-small dataset, which contains 44,000 product entries.

When using open-source datasets, comply with the associated licenses and applicable laws.

Map dataset fields to TairVector

TairVector uses a Tair vector index Key-Key-(Key-Value) storage structure. Before importing data, create a vector index (for example, hybrid_index) and map each dataset field to the appropriate TairVector role:

Dataset field	TairVector role	Purpose
id	Primary key	Point queries; scans a small amount of data
image	Vector	LLM-encoded image embeddings for vector search
productDisplayName	Full-text description	Text used for full-text search
All other fields	Key-value pairs	Attributes for conditional filtering (no limit on count)

The following figure shows the resulting data structure in TairVector.

Prerequisites

Before you begin, ensure that you have:

• Loaded the fashion-product-images-small dataset

• Set up a Tair instance

• Imported the dataset to Tair using the field mapping above

For the complete setup and import code, download hybrid_search_demo.ipynb. Run pip install jupyter to install the required dependencies before opening the file.

Run hybrid search queries

All examples use tvs_knnsearch to query the hybrid_index with topk=20. The query text is "Green Kidswear". The hybrid_ratio value is the only variable between scenarios.

Vector search

Set hybrid_ratio to 0.9999 to use near-pure vector search.

topk = 20
text = "Green Kidswear"
vector = model.encode([text])[0]
filter_str = None
kwargs = {"TEXT": text, "hybrid_ratio": 0.9999}
result = client.tvs_knnsearch(index_name, topk, vector, False, filter_str, **kwargs)
top_img = [images[id_pos[int(item[0])]] for item in result]
display_result(top_img)

Result:

Full-text search

Set hybrid_ratio to 0.0001 to use near-pure full-text search.

topk = 20
text = "Green Kidswear"
vector = model.encode([text])[0]
filter_str = None
kwargs = {"TEXT": text, "hybrid_ratio": 0.0001}
result = client.tvs_knnsearch(index_name, topk, vector, False, filter_str, **kwargs)
top_img = [images[id_pos[int(item[0])]] for item in result]
display_result(top_img)

Result:

Hybrid search (vector + full-text)

Set hybrid_ratio to 0.5 to balance vector and full-text search equally.

topk = 20
text = "Green Kidswear"
vector = model.encode([text])[0]
filter_str = None
kwargs = {"TEXT": text, "hybrid_ratio": 0.5}
result = client.tvs_knnsearch(index_name, topk, vector, False, filter_str, **kwargs)
top_img = [images[id_pos[int(item[0])]] for item in result]
display_result(top_img)

Result:

Hybrid search with conditional filtering

Add a filter_str to restrict results to a specific attribute. This example filters to subCategory == "Topwear" while keeping hybrid_ratio at 0.5.

topk = 20
text = "Green Kidswear"
vector = model.encode([text])[0]
filter_str = "subCategory == \"Topwear\""
kwargs = {"TEXT": text, "hybrid_ratio": 0.5}
result = client.tvs_knnsearch(index_name, topk, vector, False, filter_str, **kwargs)
print(result)
top_img = [images[id_pos[int(item[0])]] for item in result]
display_result(top_img)

Result:

Choose a search strategy

Use the following table to pick the right combination for your scenario.

Key observations from the example results:

• Both vector search and full-text search return relevant results for "Green Kidswear". Full-text search shows slightly higher precision in the top-ranked candidate set.

• In hybrid mode, items retrieved by both methods rank higher than items retrieved by only one. This re-ranking effect improves result quality without requiring manual score tuning.

• Conditional filtering narrows the candidate set to improve the hit rate of vector search when the target attribute is known.

What's next

• For the full tvs_knnsearch API reference and supported parameters, see TairVector.