LlamaIndex 怎样把元数据加入向量检索过滤

LlamaIndex 中，先把业务属性写入节点的 metadata，再用 MetadataFilters 描述条件，并传给 index.as_retriever(filters=...)。过滤条件最终要由具体向量存储适配器支持；只把标签写进文本，或只在提示词里要求“不要检索其他类别”，都不等于元数据过滤。

官方地址：https://developers.llamaindex.ai/python/framework/integrations/vector_stores/chroma_metadata_filter/

先固定字段和向量存储

本文以 ChromaVectorStore 为例，只实现一个简单约束：返回 department="support" 且 status="published" 的节点。LlamaIndex 提供统一过滤对象，适配器负责翻译到存储查询；这不表示任意后端都支持所有运算符、嵌套组合和字段类型。

完整链路包括字段约定、节点入库、检索参数和结果判读。先用小型演示集合把字段连通，再替换真实嵌入模型和文档处理流程。不要直接在生产集合里反复插入测试节点。

元数据要跟着实际入库的节点

元数据是独立字段，不是文本里出现同一个词。比如正文提及 support，并不会自动创建 department 字段。手工构造 TextNode 时直接设置 metadata；如果从 Document 分块，则需要确认最终节点保留了所需属性，并通过相同适配器写进集合。

字段名的大小写、字符串取值和类型应由入库与查询共同约定。不要在入库时使用整数类别码、查询时却传字符串名称。字段迁移后，旧节点也需要更新或重建；修改内存里的对象并不意味着存储中的旧记录同步变化。

用本地演示集合接通过滤检索

准备隔离的 Python 虚拟环境，安装核心库与 Chroma 集成。以下命令供读者自行执行，本文没有运行这些示例。

# 在独立虚拟环境安装本例依赖；确认可用后记录实际版本
python -m pip install llama-index-core llama-index-vector-stores-chroma chromadb

下面用 MockEmbedding 排除模型下载和外部嵌入 API 的干扰。它只是接口演示用的模拟嵌入，不具备真实语义排序能力。本例只能帮助观察元数据条件是否传到了后端，不能用于评价检索相关性。

from uuid import uuid4
import chromadb
from llama_index.core import StorageContext, VectorStoreIndex
from llama_index.core.embeddings import MockEmbedding
from llama_index.core.schema import TextNode
from llama_index.core.vector_stores import (
    MetadataFilter, MetadataFilters, FilterOperator, FilterCondition
)
from llama_index.vector_stores.chroma import ChromaVectorStore

# 使用独立临时集合，避免触碰现有业务数据
client = chromadb.EphemeralClient()
collection_name = "filter-demo-" + uuid4().hex
collection = client.create_collection(collection_name)
try:
    nodes = [
        TextNode(
            id_="support-public",
            text="Published instructions for a service ticket.",
            metadata={"department": "support", "status": "published"},
        ),
        TextNode(
            id_="support-draft",
            text="Draft notes for a service ticket.",
            metadata={"department": "support", "status": "draft"},
        ),
        TextNode(
            id_="sales-public",
            text="Published instructions for a sales request.",
            metadata={"department": "sales", "status": "published"},
        ),
    ]
    store = ChromaVectorStore(chroma_collection=collection)
    context = StorageContext.from_defaults(vector_store=store)
    # 模拟嵌入仅演示过滤链路，不代表真实语义相似度
    index = VectorStoreIndex(
        nodes,
        storage_context=context,
        embed_model=MockEmbedding(embed_dim=8),
    )
    filters = MetadataFilters(
        filters=[
            MetadataFilter(
                key="department", value="support",
                operator=FilterOperator.EQ,
            ),
            MetadataFilter(
                key="status", value="published",
                operator=FilterOperator.EQ,
            ),
        ],
        condition=FilterCondition.AND,
    )
    retriever = index.as_retriever(
        filters=filters, similarity_top_k=1
    )
    hits = retriever.retrieve("How should a service ticket be handled?")
    # 仅输出演示节点标识和字段，不打印业务原文
    for hit in hits:
        print(hit.node.node_id, hit.node.metadata)
    if not hits:
        print("没有满足条件的返回节点")
finally:
    # 即使索引或检索报错，也清理本次独立集合
    client.delete_collection(collection_name)

这组构造数据中，只有 support-public 同时满足两项等值条件。符合该条件的命中应携带 support 与 published 属性；具体执行结果以读者环境为准。异常会正常抛出，不把适配器错误伪装成“未找到”。示例没有创建查询引擎，也没有调用大模型生成回答。

理解 AND、top-k 和空结果

AND 要求两项同时成立；OR 则允许满足其中任意一项。把 AND 改成 OR，会让 support 草稿或 sales 已发布内容也进入允许范围，因此不能将它们当作可互换的写法。top-k 决定本次检索希望取回的数量，不是字段条件，也不保证一定返回这么多。

在本文 Chroma 适配器中，MetadataFilters 会被翻译为后端 where 条件并用于集合查询。它不同于先做不带条件的 top-k，再在 Python 中删除不匹配条目：后一种做法可能丢失原本应在限定范围内入选的内容。不要同时给标准 filters 与 Chroma 专用 where 参数传两份条件。

空结果时先看字段是否真正入库、取值是否一致、是否连接了预期集合，以及条件是否过窄。换后端遇到不支持运算符的错误，应回到该集成的能力说明调整，不能简单删掉过滤后继续返回数据。如果部门字段还承担权限作用，条件必须由可信服务端身份与授权规则构建，不能直接信任客户端传来的 department；本例的业务分类并不是完整授权系统。

接入真实文档前的取舍与常见问题

真实使用时，将 MockEmbedding 换成适合文本语言的嵌入模型。建库和查询需使用兼容的向量维度与模型；变更后应安排相应的重建策略。保留字段字典、集成版本、集合名称与入库规则，之后排查空结果才有明确依据。

metadata 会自动变成过滤条件吗？不会。字段可用于存储和检索处理，但查询时仍要显式配置 filters，或由应用的可信逻辑统一注入。

只增加 top-k 能修复错误条件吗？不能。字段名或类型不一致时，应修正数据与条件；扩大数量不能改变不匹配的事实。

所有向量后端都支持相同嵌套条件吗？不能这样假设。应以所用适配器与数据库的能力为准，本文只给出 Chroma 上的简单等值 AND 示例。

把字段约定放在入库之前，把过滤条件放在检索参数中，再把命中节点与来源属性一起判读，元数据才真正成为向量检索的可控约束。

参考：LlamaIndex Chroma 元数据过滤、Chroma 适配器源码。