← Cloudflare Vectorize / vectorize / reference

Vectorize API

Tato stránka popisuje API Vectorize dostupné v Cloudflare Workers, včetně příkladů použití.

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

Vloží vektory do indexu. Vkládání ve službě Vectorize probíhá asynchronně a operace vložení vrátí identifikátor mutace jedinečný pro danou operaci. Obvykle trvá několik sekund, než jsou vložené vektory k dispozici pro dotazování v indexu Vectorize.

Pokud v indexu již existují vektory se stejným ID vektoru, vloží se pouze vektory s novými ID.

Pokud potřebujete aktualizovat existující vektory, použijte upsert operace.

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

Provede upsert vektorů do indexu. Upserty ve Vectorize jsou asynchronní a operace upsert vrací identifikátor mutace jedinečný pro danou operaci. Upsertované vektory jsou obvykle k dispozici pro dotazování v indexu Vectorize během několika sekund.

Operace upsert vloží do indexu nové vektory, pokud vektory se stejným ID ještě neexistují, a existující vektory se stejným ID přepíše.

Upsert nesloučí ani nezkombinuje hodnoty nebo metadata existujícího vektoru s upsertovaným vektorem: upsertovaný vektor zcela nahradí existující vektor.

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

Dotaz na index se zadaným vektorem, který vrátí skóre nejbližších vektorů podle nastavené metriky vzdálenosti.

• Počet vrácených shod nastavíte pomocí topK (výchozí: 5)
• Hodnoty vektoru vrátíte nastavením returnValues: true (výchozí: false)
• Metadata vektoru vrátíte nastavením returnMetadata: 'indexed' nebo returnMetadata: 'all' (výchozí: 'none')

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

topK lze nakonfigurovat tak, aby určoval počet shod vrácených operací dotazu. Vectorize nyní podporuje horní limit 100 pro topK hodnotu. Pro operaci dotazu s returnValues nastaveno na true nebo returnMetadata nastaveno na all, topK je omezen na maximální hodnotu 50.

returnMetadata pole poskytuje tři způsoby, jak při dotazování načíst metadata vektoru:

1. none: Metadata nenačítat.
2. indexed: Načtena metadata pouze pro indexovaná pole metadat. Tato možnost nezvyšuje latenci, ale dlouhá textová pole mohou být oříznuta.
3. all: Načíst veškerá metadata přiřazená k vektoru. S touto možností mohou dotazy probíhat pomaleji a topK je omezen na 50.

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

Dotaz na index pomocí vektoru, který je v indexu již obsažen.

Možnosti dotazu zůstávají stejné jako u výše popsané operace dotazu.

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

Načte zadané vektory podle jejich ID, včetně hodnot a metadat.

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

Odstraní zadaná ID vektorů z aktuálního indexu. Mazání ve Vectorize probíhá asynchronně a operace odstranění vrátí jedinečný identifikátor mutace pro danou operaci. Odstranění vektorů z indexu Vectorize obvykle trvá několik sekund.

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

Přímo načte konfiguraci daného indexu, včetně nastaveného dimensions a vzdálenost metric.

Vypíše všechny identifikátory vektorů v indexu pomocí stránkovaných požadavků a vrátí až 1000 identifikátorů vektorů na stránku.

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

Parametry:

• <index-name> - název vašeho indexu Vectorize
• --count (volitelné) - počet ID vektorů, které se mají vrátit na jednu stránku. Musí být mezi 1 a 1000 (výchozí: 100)
• --cursor (volitelné) - kurzor stránkování z předchozí odpovědi, kterým lze pokračovat ve výpisu od dané pozice

Podrobné pokyny ke stránkování a doporučeným postupům najdete v Osvědčené postupy pro výpis vektorů.

Povolí filtrování metadat u zadané vlastnosti. Omezeno na 10 vlastností.

Spusťte následující wrangler vectorize příkaz:

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

Umožní Vectorize odstranit zadaný index metadat.

Spusťte následující wrangler vectorize příkaz:

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

Vypíše vlastnosti metadat, pro které je povoleno filtrování metadat.

Spusťte následující wrangler vectorize příkaz:

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

Získejte další podrobnosti o indexu.

Spusťte následující wrangler vectorize příkaz:

wrangler vectorize info <index-name>

Vektor představuje výstupní vektorový embedding modelu strojového učení.

• id - jedinečný string identifikující vektor v indexu. Mělo by odpovídat ID dokumentu, objektu nebo databázovému identifikátoru, ze kterého byly hodnoty vektoru vygenerovány.
• namespace - volitelný oddílový klíč (partition key) v rámci indexu. Operace se provádějí podle jmenného prostoru, takže jej lze použít k vytvoření izolovaných segmentů v rámci většího indexu.
• values - pole number, Float32Array, nebo Float64Array jako samotné vektorové vložení (embedding). Musí se jednat o husté pole a délka tohoto pole se musí shodovat s dimensions nakonfigurovaný na indexu.
• metadata - volitelná sada dvojic klíč-hodnota, kterou lze použít k uložení dalších metadat spolu s vektorem.

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 umožňují k vašemu Workeru připojit prostředky, včetně indexů Vectorize nebo bucketů R2.

Bindingy se definují buď v Konfigurační soubor Wrangler přiřazené k vašemu projektu Workers, nebo přes Cloudflare dashboard vašeho projektu.

Indexy Vectorize se propojují pomocí bindingu podle názvu. Binding pro index nazvaný production-doc-search by vypadalo takto:

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

Viz dokumentace k bindingům pro další podrobnosti.

Pokud používáte TypeScript, spusťte wrangler types pokaždé, když upravíte konfigurační soubor Wrangler. Tím se vygenerují typy pro env objekt na základě vašich vazeb, stejně jako typy runtime.