本 notebook 说明 Milvus 向量存储在 LlamaIndex 中的使用，重点介绍元数据过滤能力。你将学习如何为带元数据的文档建立索引、使用 LlamaIndex 内置的元数据过滤器执行向量搜索，以及将 Milvus 的原生过滤表达式应用于向量存储。

到本 notebook 结束时，你将了解如何利用 Milvus 的过滤功能，根据文档元数据缩小搜索结果范围。

前置条件

安装依赖项

开始之前，请确保已安装以下依赖项：

! pip install llama-index-vector-stores-milvus llama-index

如果你使用 Google Colab，可能需要重启运行时（转到界面顶部的 “Runtime” 菜单，然后从下拉菜单中选择 “Restart session”。）

设置账户

本教程使用 OpenAI 进行文本嵌入和答案生成。你需要准备 OpenAI API 密钥。

import openai

openai.api_key = "sk-"

要使用 Milvus 向量存储，请指定你的 Milvus 服务器 URI（并可选择提供 TOKEN）。要启动 Milvus 服务器，你可以按照 Milvus 安装指南进行设置，或者直接免费试用 Zilliz Cloud。

URI = "./milvus_filter_demo.db"  # Use Milvus-Lite for demo purpose
# TOKEN = ""

准备数据

在本示例中，我们将使用几本标题相似或相同但元数据（作者、类型和出版年份）不同的书籍作为示例数据。这将有助于演示 Milvus 如何基于向量相似度和元数据属性来过滤和检索文档。

from llama_index.core.schema import TextNode

nodes = [
    TextNode(
        text="Life: A User's Manual",
        metadata={
            "author": "Georges Perec",
            "genre": "Postmodern Fiction",
            "year": 1978,
        },
    ),
    TextNode(
        text="Life and Fate",
        metadata={
            "author": "Vasily Grossman",
            "genre": "Historical Fiction",
            "year": 1980,
        },
    ),
    TextNode(
        text="Life",
        metadata={
            "author": "Keith Richards",
            "genre": "Memoir",
            "year": 2010,
        },
    ),
    TextNode(
        text="The Life",
        metadata={
            "author": "Malcolm Knox",
            "genre": "Literary Fiction",
            "year": 2011,
        },
    ),
]

构建索引

在本节中，我们将使用默认嵌入模型（OpenAI 的 text-embedding-ada-002）将示例数据存储到 Milvus 中。标题将被转换为文本嵌入并存储在稠密嵌入字段中，而所有元数据将存储在标量字段中。

from llama_index.vector_stores.milvus import MilvusVectorStore
from llama_index.core import StorageContext, VectorStoreIndex

vector_store = MilvusVectorStore(
    uri=URI,
    # token=TOKEN,
    collection_name="test_filter_collection",  # Change collection name here
    dim=1536,  # Vector dimension depends on the embedding model
    overwrite=True,  # Drop collection if exists
)
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex(nodes, storage_context=storage_context)

2025-04-22 08:31:09,871 [DEBUG][_create_connection]: Created new connection using: 19675caa8f894772b3db175b65d0063a (async_milvus_client.py:547)

元数据过滤器

在本节中，我们将把 LlamaIndex 内置的元数据过滤器和条件应用于 Milvus 搜索。

定义元数据过滤器

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

filters = MetadataFilters(
    filters=[
        MetadataFilter(
            key="year", value=2000, operator=FilterOperator.GT
        )  # year > 2000
    ]
)

使用过滤器从向量存储中检索

retriever = index.as_retriever(filters=filters, similarity_top_k=5)
result_nodes = retriever.retrieve("Books about life")
for node in result_nodes:
    print(node.text)
    print(node.metadata)
    print("\n")

The Life
{'author': 'Malcolm Knox', 'genre': 'Literary Fiction', 'year': 2011}

Life
{'author': 'Keith Richards', 'genre': 'Memoir', 'year': 2010}

多个元数据过滤器

你还可以组合多个元数据过滤器来创建更复杂的查询。LlamaIndex 支持 AND 和 OR 条件来组合过滤器。这允许根据文档的元数据属性进行更精确、更灵活的检索。

AND 条件

尝试一个筛选 1979 年至 2010 年出版书籍的示例（具体来说，1979 < year ≤ 2010）：

from llama_index.core.vector_stores import FilterCondition

filters = MetadataFilters(
    filters=[
        MetadataFilter(
            key="year", value=1979, operator=FilterOperator.GT
        ),  # year > 1979
        MetadataFilter(
            key="year", value=2010, operator=FilterOperator.LTE
        ),  # year <= 2010
    ],
    condition=FilterCondition.AND,
)

retriever = index.as_retriever(filters=filters, similarity_top_k=5)
result_nodes = retriever.retrieve("Books about life")
for node in result_nodes:
    print(node.text)
    print(node.metadata)
    print("\n")

Life and Fate
{'author': 'Vasily Grossman', 'genre': 'Historical Fiction', 'year': 1980}

Life
{'author': 'Keith Richards', 'genre': 'Memoir', 'year': 2010}

OR 条件

再尝试一个筛选由 Georges Perec 或 Keith Richards 撰写的书籍的示例：

filters = MetadataFilters(
    filters=[
        MetadataFilter(
            key="author", value="Georges Perec", operator=FilterOperator.EQ
        ),  # author is Georges Perec
        MetadataFilter(
            key="author", value="Keith Richards", operator=FilterOperator.EQ
        ),  # author is Keith Richards
    ],
    condition=FilterCondition.OR,
)

retriever = index.as_retriever(filters=filters, similarity_top_k=5)
result_nodes = retriever.retrieve("Books about life")
for node in result_nodes:
    print(node.text)
    print(node.metadata)
    print("\n")

Life
{'author': 'Keith Richards', 'genre': 'Memoir', 'year': 2010}

Life: A User's Manual
{'author': 'Georges Perec', 'genre': 'Postmodern Fiction', 'year': 1978}

使用 Milvus 的关键字参数

除了内置的过滤功能外，你还可以通过 string_expr 关键字参数使用 Milvus 的原生过滤表达式。这允许你在搜索操作期间将特定过滤表达式直接传给 Milvus，从而超越标准元数据过滤，访问 Milvus 的高级过滤能力。

Milvus 提供强大而灵活的过滤选项，可对你的向量数据进行精确查询：

• 基本运算符：比较运算符、范围过滤器、算术运算符和逻辑运算符
• 过滤表达式模板：常见过滤场景的预定义模式
• 专用运算符：针对 JSON 或数组字段的数据类型特定运算符

有关 Milvus 过滤表达式的完整文档和示例，请参阅 Milvus Filtering 的官方文档。

retriever = index.as_retriever(
    vector_store_kwargs={
        "string_expr": "genre like '%Fiction'",
    },
    similarity_top_k=5,
)
result_nodes = retriever.retrieve("Books about life")
for node in result_nodes:
    print(node.text)
    print(node.metadata)
    print("\n")

The Life
{'author': 'Malcolm Knox', 'genre': 'Literary Fiction', 'year': 2011}

Life and Fate
{'author': 'Vasily Grossman', 'genre': 'Historical Fiction', 'year': 1980}

Life: A User's Manual
{'author': 'Georges Perec', 'genre': 'Postmodern Fiction', 'year': 1978}