redis-vector-search

Redis 向量搜索

关于在 Redis 中存储和搜索嵌入向量的指南。涵盖索引配置、算法选择、混合过滤，以及使用 RedisVL 实现 RAG 检索模式。

适用场景

• 在 FT.CREATE（原始 RQE）或 RedisVL IndexSchema 中定义 VECTOR 字段。
• 选择 HNSW 或 FLAT，并调整 HNSW 参数。
• 为向量查询添加类别、日期或租户过滤条件。
• 基于 Redis 构建检索增强生成（RAG）流水线。

此技能以 redis-query-engine 技能为基础——向量字段位于 RQE 索引中，并使用相同的 FT.CREATE / FT.SEARCH 机制。

1. 正确配置向量索引

以下三项设置必须与嵌入模型匹配：

• DIM — 模型的输出维度（例如，OpenAI text-embedding-3-small 为 1536）。不匹配会导致结果悄无声息地变得毫无意义。
• DISTANCE_METRIC — 对归一化文本嵌入使用 COSINE（常见情况），对未归一化的内积使用 IP，对原始欧几里得距离使用 L2。
• TYPE / datatype — 通常使用 FLOAT32。只有在内存成本受到严格限制时，才使用 FLOAT16 或量化变体。

原始 RQE：

FT.CREATE idx:docs ON HASH PREFIX 1 doc:
    SCHEMA
        content TEXT
        embedding VECTOR HNSW 6
            TYPE FLOAT32
            DIM 1536
            DISTANCE_METRIC COSINE

RedisVL：

schema = IndexSchema.from_dict({
    "index": {"name": "idx:docs", "prefix": "doc:"},
    "fields": [
        {"name": "content", "type": "text"},
        {"name": "embedding", "type": "vector", "attrs": {
            "dims": 1536, "algorithm": "HNSW",
            "datatype": "FLOAT32", "distance_metric": "COSINE",
        }},
    ]
})

请参阅 references/index-creation.md，了解 redis-py 和 RedisVL 的不同写法。

2. HNSW 与 FLAT

算法	速度	准确度	内存	最适用场景
HNSW	快（近似）	~95% 以上召回率（可调）	较高	大型数据集（>10k 个向量）、对延迟敏感的场景
FLAT	慢（精确）	100%	较低	小型数据集（<10k 个向量）、对准确度要求严格的场景

对于任何生产规模的工作负载，默认使用 HNSW。可调整的参数：

• M — 每个节点的连接数（16–64）。值越高 = 召回率越高，内存占用越大。
• EF_CONSTRUCTION — 构建时的图质量（100–500）。值越高 = 索引质量越好，构建越慢。
• EF_RUNTIME — 查询时的候选列表大小。值越高 = 召回率越高，查询越慢。

当语料较小且需要精确结果时（例如，对几千个条目进行语义去重），使用 FLAT。

请参阅 references/algorithm-choice.md。

3. 混合搜索——向量搜索前先过滤

应用属性过滤条件（TAG / NUMERIC），让引擎在向量比较之前缩小搜索范围。不要先获取大量结果，再在客户端过滤——这样速度更慢、准确度也更低。

from redisvl.query import VectorQuery
from redisvl.query.filter import Num, Tag

filters = (Tag("category") == "technology") & (Num("date") >= 2024)

query = VectorQuery(
    vector=query_embedding,
    vector_field_name="embedding",
    return_fields=["content", "category", "date"],
    num_results=10,
    filter_expression=filters,
)
results = index.query(query)

对于文本 + 向量融合（结合 BM25 加权文本评分与向量相似度），Redis ≥ 8.4 且 redis-py ≥ 7.1 时使用 HybridQuery，较早版本的 Redis 则使用 AggregateHybridQuery。这与上述经过过滤的向量搜索是两种不同的“混合”搜索。

请参阅 references/hybrid-search.md。

4. RAG 模式

标准流水线：嵌入用户查询 → 在 Redis 中进行向量搜索 → 将排名前 K 的上下文传递给大模型。

# Index documents with embeddings
records = [{"content": doc.content,
            "embedding": embed_model.encode(doc.content).tolist(),
            "source": doc.source}
           for doc in documents]
index.load(records)

# Retrieve relevant context for a user question
q_emb = embed_model.encode(user_question)
results = index.query(VectorQuery(
    vector=q_emb,
    vector_field_name="embedding",
    return_fields=["content", "source"],
    num_results=5,
))

# Generate with retrieved context
context = "\n".join(r["content"] for r in results)
response = llm.generate(f"Context: {context}\n\nQuestion: {user_question}")

实用技巧：

• 使度量指标与模型匹配。 大多数现代文本嵌入模型与 COSINE 的搭配效果最好。
• 为长文档分块后再建立索引——使用 200–500 个 token 的分块进行检索，通常优于对整页内容建立索引。
• 使用 index.load([...]) 批量插入，而不是每条记录单独调用一次。
• 在向量搜索前，先按属性过滤（租户、时间新近度、文档类型）。

请参阅 references/rag-pattern.md。

参考资料

• Redis：向量
• Redis：RAG 快速入门
• RedisVL 文档