LlamaIndex metadata filters怎样按元数据筛选检索节点

LlamaIndex 的 metadata filters 不是对检索结果做一次事后筛选，而是把条件放进向量检索请求。做法是先把稳定的业务字段写入 Document 或 TextNode 的 metadata，再用 MetadataFilter 描述一个条件，用 MetadataFilters 组合多个条件，最后传给 index.as_retriever(filters=filters)。这样“只查某个租户、某个产品线或某个年份”的边界会跟着检索器走。

官方文档：https://developers.llamaindex.ai/python/framework/

先把可过滤字段写进节点

筛选的起点不是查询文本，而是入库时的元数据。下面用三个文档节点模拟一个知识库：tenant 用于租户隔离，category 用于业务分类，year 用于范围过滤。字段值尽量使用字符串、整数或浮点数等扁平类型，避免把嵌套字典直接塞进向量库。

from llama_index.core import VectorStoreIndex
from llama_index.core.schema import TextNode

# 用稳定字段描述租户、分类和年份，方便后续建立过滤条件
nodes = [
    TextNode(
        text="退款申请需要保留订单号和支付凭证。",
        metadata={"tenant": "shop-a", "category": "售后", "year": 2024},
    ),
    TextNode(
        text="库存盘点按仓库和批次生成差异报告。",
        metadata={"tenant": "shop-a", "category": "库存", "year": 2025},
    ),
    TextNode(
        text="供应商准入需要完成资质审核。",
        metadata={"tenant": "shop-b", "category": "采购", "year": 2025},
    ),
]

# 实际项目中可在这里传入已配置的向量库存储上下文
index = VectorStoreIndex(nodes)

这里的 metadata 同时会出现在节点和检索结果中。需要注意：字段存在于 Python 对象，不等于每个向量库都能用同样的运算符查询，入库后的字段类型仍要由目标后端确认。

用 MetadataFilter 绑定检索器

最常见的是等值筛选。例如只在 tenant=shop-a 的节点里做语义检索，可以直接把过滤器传给检索器。查询词仍然负责相似度排序，元数据条件负责缩小候选范围，两者不是互相替代关系。

from llama_index.core.vector_stores import MetadataFilter, MetadataFilters

# 只允许租户 shop-a 的节点进入本次语义检索
filters = MetadataFilters(
    filters=[MetadataFilter(key="tenant", value="shop-a")]
)

# 先按元数据收窄候选集合，再按查询文本排序
retriever = index.as_retriever(filters=filters, similarity_top_k=5)
results = retriever.retrieve("如何处理订单售后？")

# 输出节点和元数据，检查过滤边界是否符合预期
for item in results:
    print(item.node.text)
    print(item.node.metadata)

不要把 filters 写成查询字符串的一部分，也不要只在 LLM 生成答案后过滤。后一种做法既浪费检索预算，也可能把不属于当前租户的上下文送入生成链路。

用 AND、OR 表达实际业务条件

多个条件由 MetadataFilters 组合。下面的 AND 表示“属于 shop-a 且年份大于等于 2025”；如果要查多个分类，则可把两个等值条件改为 OR。官方核心类型还定义了 LT、LTE、GT、GTE、NE、IN、NIN、ANY、ALL 等运算符，但具体后端是否实现，要以对应集成文档为准。

from llama_index.core.vector_stores import (
    FilterCondition,
    FilterOperator,
    MetadataFilter,
    MetadataFilters,
)

# AND 适合租户隔离叠加时间范围，两个条件必须同时满足
filters = MetadataFilters(
    filters=[
        MetadataFilter(key="tenant", value="shop-a"),
        MetadataFilter(
            key="year", value=2025, operator=FilterOperator.GTE
        ),
    ],
    condition=FilterCondition.AND,
)

# OR 适合在同一字段上放宽到多个可接受值
category_filters = MetadataFilters(
    filters=[
        MetadataFilter(key="category", value="售后"),
        MetadataFilter(key="category", value="库存"),
    ],
    condition=FilterCondition.OR,
)

# 将其中一组条件绑定到检索器；top_k 只控制返回数量
retriever = index.as_retriever(filters=filters, similarity_top_k=5)

生产环境里建议先固定字段字典，再让写入端和查询端共用同一套类型约定。例如 year 全部写整数，不能一部分写 2025、另一部分写 "2025"；否则即使肉眼看起来相同，比较运算也可能无法命中。

空结果按四个边界排查

LlamaIndex 官方向量库列表把 Simple、Chroma、Qdrant、Milvus、Pinecone 等标为支持元数据过滤，但 FAISS、Hnswlib 等条目并不具备同样能力。即便同一向量库支持过滤，字段类型、数组运算符和原生参数也可能不同。因此排查时先确认“后端收到的条件”，再确认“返回的节点集合”，不要只盯着最终回答。

相关问题

MetadataFilter 和 MetadataFilters 有什么区别？

MetadataFilter 描述一个字段条件，MetadataFilters 负责装入多个条件并指定 AND、OR 或 NOT。

为什么过滤后结果数量变少？

过滤发生在相似度排序前，similarity_top_k 只从符合条件的候选节点中取结果，条件越窄，返回数量越少是正常现象。

可以把嵌套 JSON 直接作为 metadata 吗？

不建议。优先拆成扁平字段，并按目标向量库支持的标量或数组类型写入；复杂结构需要使用后端专用过滤能力。