← Cloudflare Vectorize / vectorize / best-practices

Запрос векторов

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

При необходимости можно применить фильтры метаданных или пространство имён чтобы сузить пространство поиска векторов.

Чтобы передать вектор в качестве запроса к индексу, используйте query() метод самого индекса.

Вектор запроса представляет собой массив чисел JavaScript: 32-битных чисел с плавающей точкой или 64-битных чисел с плавающей точкой: number[], Float32Array, или Float64Array. В отличие от случая, когда вставка векторов, вектору запроса не нужен идентификатор или метаданные.

// query vector dimensions must match the Vectorize index dimension being queried
let queryVector = [54.8, 5.5, 3.1, ...];
let matches = await env.YOUR_INDEX.query(queryVector);

Это вернёт набор совпадений, похожий на приведённый ниже, в зависимости от метрики расстояния, настроенной для индекса Vectorize. Пример ответа с cosine метрика расстояния:

{
	"count": 5,
	"matches": [
		{ "score": 0.999909486, "id": "5" },
		{ "score": 0.789848214, "id": "4" },
		{ "score": 0.720476967, "id": "4444" },
		{ "score": 0.463884663, "id": "6" },
		{ "score": 0.378282232, "id": "1" }
	]
}

При необходимости можно изменить количество возвращаемых результатов и/или указать, должны ли результаты включать метаданные и значения:

// query vector dimensions must match the Vectorize index dimension being queried
let queryVector = [54.8, 5.5, 3.1, ...];
// topK defaults to 5; returnValues defaults to false; returnMetadata defaults to "none"
let matches = await env.YOUR_INDEX.query(queryVector, {
	topK: 1,
	returnValues: true,
	returnMetadata: "all",
});

Это вернёт набор совпадений, похожий на приведённый ниже, в зависимости от метрики расстояния, настроенной для индекса Vectorize. Пример ответа с cosine метрика расстояния:

{
	"count": 1,
	"matches": [
		{
			"score": 0.999909486,
			"id": "5",
			"values": [58.79999923706055, 6.699999809265137, 3.4000000953674316, ...],
			"metadata": { "url": "/products/sku/55519183" }
		}
	]
}

См. Vectorize API для дополнительных примеров.

Теперь Vectorize позволяет искать векторы, похожие на вектор, уже присутствующий в индексе, с помощью queryById() операция. Её можно рассматривать как одну операцию, объединяющую getById() и query() операцию.

// the query operation would yield results if a vector with id `some-vector-id` is already present in the index.
let matches = await env.YOUR_INDEX.queryById("some-vector-id");

При выполнении запросов к векторам можно указать использование высокоточной оценки, что повышает точность оценок совпадений и результатов запроса, либо использование приближённой оценки для более быстрого отклика. При использовании приближённой оценки возвращаемые значения являются приблизительной оценкой реального расстояния или сходства между вашим запросом и найденными векторами. Этот режим используется по умолчанию, так как обеспечивает удачный баланс между точностью и задержкой.

Высокоточная оценка включается путём установки returnValues: true для вашего запроса. Этот параметр указывает Vectorize использовать исходные значения векторов для ваших совпадений, что позволяет вычислять точные оценки совпадения и повышает точность результатов. Однако, поскольку обрабатывается больше данных, высокоточная оценка увеличивает задержку запросов.

Если вы генерируете эмбеддинги из Workers AI модели текстовых эмбеддингов тип ответа от env.AI.run() представляет собой объект, который включает как shape вектора ответа, например [1,768] - и вектор data в виде массива векторов:

interface EmbeddingResponse {
	shape: number[];
	data: number[][];
}

let userQuery = "a query from a user or service";
const queryVector: EmbeddingResponse = await env.AI.run(
	"@cf/baai/bge-base-en-v1.5",
	{
		text: [userQuery],
	},
);

При передаче вектора в query() метод индекса Vectorize: передавайте только сам векторный эмбеддинг в .data вложенного объекта, а не в ответе верхнего уровня.

Например:

let matches = await env.TEXT_EMBEDDINGS.query(queryVector.data[0], { topK: 1 });

Передача queryVector или queryVector.data приведёт к query() чтобы вернуть ошибку.

При использовании модели OpenAI JavaScript client API ↗ и API эмбеддингов ↗, тип ответа от embeddings.create представляет собой объект, включающий модель, информацию об использовании и запрошенный векторный эмбеддинг.

const openai = new OpenAI({ apiKey: env.YOUR_OPENAPI_KEY });

let userQuery = "a query from a user or service";

let embeddingResponse = await openai.embeddings.create({
	input: userQuery,
	model: "text-embedding-ada-002",
});

Как и в случае с Workers AI, вам нужно будет передать сам векторный эмбеддинг (.embedding[0]) а не EmbeddingResponse обёртку при выполнении запроса к индексу Vectorize:

let matches = await env.TEXT_EMBEDDINGS.query(embeddingResponse.embedding[0], {
	topK: 1,
});