Weaviate Hybrid 查询语法详解

1、主路径检索 (Primary Query)

primary_resp = collection.query.hybrid(
    query=query,                          # ① 查询文本
    filters=primary_filters,              # ② 预过滤条件
    limit=max_results * 3,                # ③ 返回数量上限
    alpha=0.75,                           # ④ 混合检索权重
    query_properties=["question^3", "keywords^1.5"],  # ⑤ 字段权重
    return_metadata=wvc_query.MetadataQuery(score=True)  # ⑥ 返回元数据
)

2、兜底检索 (Fallback Query)

fallback_resp = collection.query.hybrid(
    query=query,
    filters=fallback_filters,
    limit=max_results * 2,
    alpha=0.6,                            # 向量权重降低
    query_properties=["answer^2.5", "answer_keywords^2.0"],  # 匹配答案字段
    return_metadata=wvc_query.MetadataQuery(score=True)
)

参数逐一解释

1、query (查询文本)

query=query  # 用户的原始问题，例如："如何退货？"

• Weaviate 会自动将文本转为向量（通过配置的 embedding 模型）
• 同时进行语义检索（向量相似度）和关键词检索（BM25）

2、filters (预过滤条件)

# 主路径：基于 keywords 字段过滤
primary_filters = wvc_query.Filter.by_property("keywords").contains_any(query_keywords)

# 兜底路径：基于 answer_keywords 字段过滤
fallback_filters = wvc_query.Filter.by_property("answer_keywords").contains_any(fallback_keywords)

语法解析：

• Filter.by_property("字段名") – 指定要过滤的字段
• .contains_any([...]) – 字段值包含列表中任意一个关键词

作用：先缩小搜索范围，提高检索效率和精准度

示例：

# 假设 query_keywords = ["退货", "退款"]
# 相当于 SQL: WHERE keywords in ('退货', '退款')

3、limit (返回数量)

limit=max_results * 3  # 主路径多取一些候选
limit=max_results * 2  # 兜底路径少取一些

• 为什么主路径取 3 倍？因为后面要用 Rerank 精排，多给一些候选
• 兜底路径取 2 倍，作为补充

4、alpha (混合检索权重)

alpha=0.75  # 主路径：向量检索权重 75%
alpha=0.6   # 兜底路径：向量检索权重 60%

含义：

• alpha = 1.0 → 纯向量语义检索（理解意思，忽略关键词）
• alpha = 0.0 → 纯关键词 BM25 检索（精确匹配关键词）
• alpha = 0.75 → 75% 语义 + 25% 关键词

为什么主路径 alpha 更高？

• 问题匹配时，语义理解更重要（用户可能换一种问法）
• 兜底时降低向量权重，增加关键词权重，提高精准度

5、query_properties (字段权重)

# 主路径：重点匹配 question 和 keywords
query_properties=["question^3", "keywords^1.5"]

# 兜底路径：重点匹配 answer 和 answer_keywords
query_properties=["answer^2.5", "answer_keywords^2.0"]

语法解析：

• "字段名^权重" – 使用 ^ 符号设置字段权重
• question^3 表示 question 字段的匹配分数 × 3

实际效果（假设用户问”如何退货”）：

为什么这样设计？

• 主路径优先找”相似问题”（question 权重最高）
• 兜底路径转向找”相关答案”（answer 权重最高）

6、return_metadata (返回元数据)

return_metadata=wvc_query.MetadataQuery(score=True)

作用：让 Weaviate 返回每条结果的相似度分数

使用方式：

for obj in response.objects:
    score = obj.metadata.score  # 获取相似度分数 (0~1)
    print(f"分数: {score}, 问题: {obj.properties['question']}")

两个查询的对比

完整流程示意

用户提问: "如何退货？"
    ↓
【主路径检索】
├─ 过滤: keywords 包含 ["退货", "退款"]
├─ 混合检索: 75% 语义 + 25% 关键词
├─ 重点匹配: question (×3) > keywords (×1.5)
└─ 返回: 高分问题匹配结果
    ↓
【质量评估】结果不足且无高分？
    ↓ 是
【兜底检索】
├─ 过滤: answer_keywords 包含 ["退货", "退款"]
├─ 混合检索: 60% 语义 + 40% 关键词
├─ 重点匹配: answer (×2.5) > answer_keywords (×2.0)
└─ 返回: 相关答案补充
    ↓
【合并 + Rerank 精排】→ 返回 Top-K

官方文档参考

关于其他细节，可查看 Weaviate 官方文档：

• Hybrid Search
• Filters
• Query Properties