← Cloudflare Vectorize / vectorize / best-practices

Dotazování vektorů

Dotazování indexu, neboli vektorové vyhledávání, umožňuje prohledat index zadáním vstupního vektoru a vrátit nejbližší vektory podle nakonfigurovaná metrika vzdálenosti.

Volitelně můžete použít filtry metadat nebo namespace k zúžení prostoru pro vyhledávání vektorů.

Chcete-li předat vektor jako dotaz indexu, použijte query() metodu přímo na samotném indexu.

Vektor dotazu je buď pole čísel JavaScriptu, nebo 32bitových či 64bitových čísel s plovoucí desetinnou čárkou: number[], Float32Array, nebo Float64Array. Na rozdíl od případu, kdy vkládání vektorů, dotazovací vektor nepotřebuje ID ani metadata.

// 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);

Tímto se vrátí sada shod podobná následující, v závislosti na metrice vzdálenosti nakonfigurované pro index Vectorize. Ukázková odpověď s cosine metrika vzdálenosti:

{
	"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" }
	]
}

Volitelně můžete změnit počet vracených výsledků a/nebo to, zda mají výsledky obsahovat metadata a hodnoty:

// 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",
});

Tímto se vrátí sada shod podobná následující, v závislosti na metrice vzdálenosti nakonfigurované pro index Vectorize. Ukázková odpověď s cosine metrika vzdálenosti:

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

Viz Vectorize API pro další příklady.

Vectorize nyní umožňuje vyhledávat vektory podobné vektoru, který se již v indexu nachází, pomocí queryById() operaci. Tu lze považovat za jedinou operaci, která kombinuje getById() a query() operace.

// 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");

Při dotazování vektorů můžete zvolit buď vysoce přesné skórování, které zvyšuje přesnost skóre shody i výsledků dotazu, nebo přibližné skórování pro rychlejší odezvu. Při přibližném skórování jsou vrácená skóre pouze odhadem skutečné vzdálenosti či podobnosti mezi vaším dotazem a vrácenými vektory; jde o výchozí nastavení dotazu, protože nabízí dobrý kompromis mezi přesností a latencí.

Vysoce přesné bodování se zapíná nastavením returnValues: true ve vašem dotazu. Toto nastavení říká Vectorize, aby pro shody použil původní hodnoty vektorů, což umožňuje výpočet přesných skóre shody a zvyšuje přesnost výsledků. Protože se zpracovává více dat, vysoce přesné skórování zvýší latenci dotazů.

Pokud generujete embeddingy z Workers AI model pro vkládání textu, typ odpovědi z env.AI.run() je objekt, který zahrnuje jak shape vektoru odpovědi, například [1,768] - a vektor data jako pole vektorů:

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],
	},
);

Při předávání vektoru do query() indexu Vectorize předávejte pouze samotné vektorové vložení do vlastnosti .data podobjektu, nikoli v odpovědi nejvyšší úrovně.

Například:

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

Předávání queryVector nebo queryVector.data způsobí query() a vrátí chybu.

Při použití OpenAI Klientské API pro JavaScript ↗ a Embeddings API ↗, typ odpovědi z embeddings.create je objekt, který zahrnuje model, informace o využití a požadované vektorové vložení.

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",
});

Podobně jako u Workers AI musíte zadat samotný vektorový embedding (.embedding[0]) a ne EmbeddingResponse wrapperu při dotazování na index Vectorize:

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