INTEGRITY Документация

← Обзор / ai-search / configuration / retrieval

Фильтрация

Фильтрация метаданных сужает результаты поиска на основе метаданных, поэтому извлекается только релевантный контент. Фильтр применяется до поиска, поэтому запрос выполняется только к нужным документам.

Фильтрация использует атрибуты метаданных, извлечённые во время индексирования. Об определении пользовательских атрибутов и использовании встроенных атрибутов метаданных см. в Атрибуты метаданных.

AI Search может хранить строковые значения длиннее фильтруемого префикса. Фильтры учитывают только первые 64 байта UTF-8 каждой проиндексированной строки. Vectorize может хранить массивы строк, но пока не индексирует и не фильтрует их.

Вот пример фильтрации по метаданным с использованием привязка Workers:

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 Equals
$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 оператор

Сопоставляет сохранённое скалярное поле с любым значением в массиве кандидатов. $in не выполняет поиск внутри сохранённых массивов:

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

Фильтр «Starts with» для папок

Используйте запросы по диапазону, чтобы отфильтровать все файлы в папке и её подпапках.

Например, рассмотрим такую структуру файлов:

Использование { "folder": "docs/" } соответствует только файлам непосредственно в этой папке (например, guide.pdf), а не файлы в подпапках.

Чтобы найти все файлы, начинающиеся с docs/, используйте запрос по диапазону:

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

Это работает по следующей причине: