← Cloudflare Vectorize / vectorize / reference

Vectorize API

На этой странице описан API Vectorize, доступный в Cloudflare Workers, включая примеры использования.

let vectorsToInsert = [
	{ id: "123", values: [32.4, 6.5, 11.2, 10.3, 87.9] },
	{ id: "456", values: [2.5, 7.8, 9.1, 76.9, 8.5] },
];
let inserted = await env.YOUR_INDEX.insert(vectorsToInsert);

Вставляет векторы в индекс. Вставка в Vectorize выполняется асинхронно, и операция вставки возвращает уникальный идентификатор мутации для этой операции. Обычно вставленные векторы становятся доступны для запросов в индексе Vectorize через несколько секунд.

Если в индексе уже есть векторы с таким же идентификатором вектора, будут вставлены только векторы с новыми идентификаторами.

Если вам нужно обновить существующие векторы, используйте upsert операцию.

let vectorsToUpsert = [
	{ id: "123", values: [32.4, 6.5, 11.2, 10.3, 87.9] },
	{ id: "456", values: [2.5, 7.8, 9.1, 76.9, 8.5] },
	{ id: "768", values: [29.1, 5.7, 12.9, 15.4, 1.1] },
];
let upserted = await env.YOUR_INDEX.upsert(vectorsToUpsert);

Выполняет upsert векторов в индекс. Операции upsert в Vectorize являются асинхронными, и операция upsert возвращает уникальный идентификатор мутации для этой операции. Обычно векторам, добавленным через upsert, требуется несколько секунд, чтобы стать доступными для запросов в индексе Vectorize.

Операция upsert добавляет векторы в индекс, если векторов с таким же ID ещё не существует, и перезаписывает векторы с совпадающим ID.

Операция upsert не объединяет и не комбинирует значения либо метаданные существующего вектора с новым вектором: новый вектор полностью заменяет существующий.

let queryVector = [32.4, 6.55, 11.2, 10.3, 87.9];
let matches = await env.YOUR_INDEX.query(queryVector);

Запрос к индексу с указанным вектором, который возвращает оценки ближайших векторов на основе настроенной метрики расстояния.

• Настройте количество возвращаемых совпадений, задав topK (по умолчанию: 5)
• Чтобы вернуть значения вектора, установите returnValues: true (по умолчанию: false)
• Чтобы вернуть метаданные вектора, установите returnMetadata: 'indexed' или returnMetadata: 'all' (по умолчанию: 'none')

let matches = await env.YOUR_INDEX.query(queryVector, {
	topK: 5,
	returnValues: true,
	returnMetadata: "all",
});

topK можно настроить для указания количества совпадений, возвращаемых операцией запроса. Теперь Vectorize поддерживает верхний предел в 100 для topK значение. Однако для операции запроса с returnValues имеет значение true или returnMetadata имеет значение all, topK ограничено максимальным значением 50.

returnMetadata поле предоставляет три способа получения метаданных вектора при выполнении запроса:

1. none: не получать метаданные.
2. indexed: получить метаданные только для индексируемых полей метаданных. Эта опция не добавляет задержки, но длинные текстовые поля могут быть усечены.
3. all: получить все метаданные, связанные с вектором. С этой опцией запросы могут выполняться медленнее, и topK ограничено 50.

let matches = await env.YOUR_INDEX.queryById("some-vector-id");

Запрос к индексу с использованием вектора, который уже есть в самом индексе.

Параметры запроса остаются такими же, как в описанной выше операции запроса.

let matches = await env.YOUR_INDEX.queryById("some-vector-id", {
	topK: 5,
	returnValues: true,
	returnMetadata: "all",
});

let ids = ["11", "22", "33", "44"];
const vectors = await env.YOUR_INDEX.getByIds(ids);

Возвращает указанные векторы по их ID, включая значения и метаданные.

let idsToDelete = ["11", "22", "33", "44"];
const deleted = await env.YOUR_INDEX.deleteByIds(idsToDelete);

Удаляет указанные ID векторов из текущего индекса. Удаление в Vectorize выполняется асинхронно: операция удаления возвращает уникальный идентификатор мутации для этой операции. Обычно векторы удаляются из индекса Vectorize за несколько секунд.

const details = await env.YOUR_INDEX.describe();

Возвращает конфигурацию указанного индекса напрямую, включая настроенные для него dimensions и расстояние metric.

Возвращает все идентификаторы векторов в индексе с помощью постраничных запросов, до 1000 идентификаторов векторов на страницу.

wrangler vectorize list-vectors <index-name> [--count=<number>] [--cursor=<cursor-string>]

Параметры:

• <index-name> - имя вашего индекса Vectorize
• --count (необязательно) - количество идентификаторов векторов, возвращаемых на странице. Должно быть от 1 до 1000 (по умолчанию: 100)
• --cursor (необязательно) - курсор пагинации из предыдущего ответа для продолжения получения списка с этой позиции

Подробные сведения о работе пагинации и рекомендации по её использованию приведены в Рекомендации по получению списка векторов.

Включает фильтрацию по метаданным для указанного свойства. Не более 10 свойств.

Выполните следующую wrangler vectorize команда:

wrangler vectorize create-metadata-index <index-name> --property-name='some-prop' --type='string'

Разрешить Vectorize удалить указанный индекс метаданных.

Выполните следующую wrangler vectorize команда:

wrangler vectorize delete-metadata-index <index-name> --property-name='some-prop'

Список свойств метаданных, для которых включена фильтрация по метаданным.

Выполните следующую wrangler vectorize команда:

wrangler vectorize list-metadata-index <index-name>

Получение дополнительных сведений об индексе.

Выполните следующую wrangler vectorize команда:

wrangler vectorize info <index-name>

Вектор представляет собой векторный эмбеддинг, полученный на выходе модели машинного обучения.

• id - уникальный string идентифицирующий вектор в индексе. Это значение должно соответствовать идентификатору документа, объекта или записи базы данных, из которых были получены значения вектора.
• namespace - необязательный ключ раздела внутри индекса. Операции выполняются в рамках пространства имён, поэтому это можно использовать для создания изолированных сегментов внутри большего индекса.
• values - массив number, Float32Array, или Float64Array в качестве самого векторного эмбеддинга. Это должен быть плотный массив, и длина этого массива должна соответствовать dimensions настроенных на индексе.
• metadata - необязательный набор пар ключ-значение, которые можно использовать для хранения дополнительных метаданных вместе с вектором.

let vectorExample = {
	id: "12345",
	values: [32.4, 6.55, 11.2, 10.3, 87.9],
	metadata: {
		key: "value",
		hello: "world",
		url: "r2://bucket/some/object.json",
	},
};

Bindings позволяют подключать к вашему Worker такие ресурсы, как индексы Vectorize или бакеты R2.

Привязки определяются либо в конфигурационный файл Wrangler связанный с вашим проектом Workers, либо через панель управления Cloudflare для этого проекта.

Индексы Vectorize привязываются по имени. Привязка для индекса с именем production-doc-search будет выглядеть примерно так:

{
	"vectorize": [
		{
			"binding": "PROD_SEARCH", // the index will be available as env.PROD_SEARCH in your Worker
			"index_name": "production-doc-search",
		},
	],
}

[[vectorize]]
binding = "PROD_SEARCH"
index_name = "production-doc-search"

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

Если вы используете TypeScript, выполните wrangler types каждый раз, когда вы изменяете файл конфигурации Wrangler. Это генерирует типы для env объект на основе ваших привязок, а также типы среды выполнения.