筛选 · Cloudflare AI Search docs

元数据筛选会根据元数据缩小搜索结果范围，从而仅检索相关内容。筛选在检索之前应用，因此你只查询真正相关的文档。

筛选使用在索引期间提取的元数据属性。要定义自定义属性或使用内置元数据属性，请参阅元数据属性。

以下是使用 Workers 绑定（binding）进行元数据筛选的示例：

const instance = env.AI_SEARCH.get("my-instance");

const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			filters: {
				folder: "docs/getting-started/",
				timestamp: { $gte: 1735689600 },
			},
		},
	},
});

筛选器语法

筛选器是 JSON 对象，其中键为元数据属性名称，值为筛选条件。

支持的运算符

运算符	说明
`$eq`	等于
`$ne`	不等于
`$in`	在（匹配数组中的任意值）
`$nin`	不在（排除数组中的值）
`$lt`	小于
`$lte`	小于或等于
`$gt`	大于
`$gte`	大于或等于

隐式 `$eq`

当你提供不带运算符的直接值时，会将其视为相等检查：

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": "docs/getting-started/" }
		}
	}
}

这等价于：

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": { "$eq": "docs/getting-started/" } }
		}
	}
}

范围查询

组合上下界运算符以按范围筛选：

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "timestamp": { "$gte": 1735689600, "$lt": 1735900000 } }
		}
	}
}

多个条件（隐式 AND）

当你指定多个键时，必须全部匹配：

{
	"ai_search_options": {
		"retrieval": {
			"filters": {
				"folder": "docs/getting-started/",
				"timestamp": { "$gte": 1735689600 }
			}
		}
	}
}

`$in` 运算符

匹配数组中的任意值：

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": { "$in": ["docs/guides/", "docs/tutorials/"] } }
		}
	}
}

针对文件夹的“以……开头”筛选器

使用范围查询筛选文件夹及其子文件夹中的所有文件。

例如，考虑以下文件结构：

docs
- guide.pdf
- tutorials
  - getting-started
    - intro.pdf

使用 { "folder": "docs/" } 仅匹配该文件夹中的直接文件（如 guide.pdf），而不匹配子文件夹中的文件。

要匹配所有以 docs/ 开头的文件，请使用范围查询：

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": { "$gte": "docs/", "$lt": "docs0" } }
		}
	}
}

原理如下：

$gte 包含所有以 docs/ 开头的路径
对 docs0 使用 $lt 会排除不以 docs/ 开头的路径（因为在 ASCII 中 0 位于 / 之后）