INTEGRITY Dokumentace

← Cloudflare Vectorize / vectorize / get-started

Vectorize a Workers AI

Vectorize umožňuje generovat vektorové embeddingy pomocí modelu strojového učení, včetně modelů dostupných v Workers AI.

Tento návod vás provede:

Předpoklady

Chcete-li pokračovat:

  1. Zaregistrujte si účet Cloudflare ↗ pokud jste to ještě neudělali.
  2. Nainstalujte npm ↗.
  3. Nainstalujte Node.js ↗. Použijte správce verzí Node, například Volta ↗ nebo nvm ↗ abyste se vyhnuli problémům s oprávněními a mohli měnit verze Node.js. Wrangler vyžaduje verzi Node 16.17.0 nebo novější.

1. Vytvořte Worker

Vytvoříte nový projekt, který bude obsahovat skript Workeru sloužící jako klientská aplikace pro váš index Vectorize.

Otevřete terminál a vytvořte nový projekt s názvem embeddings-tutorial spuštěním následujícího příkazu:

npm create cloudflare@latest -- embeddings-tutorial

Při nastavení vyberte následující možnosti:

Tímto vytvoříte nový embeddings-tutorial adresáři. Váš nový embeddings-tutorial adresář bude obsahovat:

2. Vytvořte index

Vektorová databáze se liší od tradiční SQL nebo NoSQL databáze. Je navržena tak, aby ukládala vektorové embeddingy, tedy reprezentace dat, nikoli data samotná.

Chcete-li vytvořit svůj první index Vectorize, přejděte do adresáře, který jste právě vytvořili pro svůj projekt Workers:

cd embeddings-tutorial

Chcete-li vytvořit index, použijte wrangler vectorize create příkaz a zadejte název indexu. Vhodný název indexu:

Kromě toho definujte dimensions vektorů, které budete ukládat v indexu, a také vzdálenost metric použitá k určení podobných vektorů při vytváření indexu. Tuto konfiguraci nelze později změnit, protože vektorová databáze je nakonfigurována pro pevně danou konfiguraci vektorů.

Spusťte následující wrangler vectorize příkaz a ujistěte se, že dimensions jsou nastaveny na 768: to je důležité, protože model Workers AI použitý v tomto tutoriálu vrací vektory se 768 dimenzemi.

npx wrangler vectorize create embeddings-index --dimensions=768 --metric=cosine
✅ Successfully created index 'embeddings-index'

[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "embeddings-index"

Tímto se vytvoří nová vektorová databáze a vypíše se binding konfiguraci potřebnou v dalším kroku.

3. Připojte svůj Worker ke svému indexu

Aby se váš Worker mohl připojit k indexu Vectorize, musíte vytvořit binding. Bindings umožňují vašim Workerům přistupovat k prostředkům, jako je Vectorize nebo R2, z Cloudflare Workers. Bindingy vytvoříte úpravou svého souboru Wrangler.

Chcete-li index svázat s Workerem, přidejte na konec souboru Wrangler následující:

{
	"vectorize": [
		{
			"binding": "VECTORIZE", // available in your Worker on env.VECTORIZE
			"index_name": "embeddings-index"
		}
	]
}
[[vectorize]]
binding = "VECTORIZE"
index_name = "embeddings-index"

Konkrétně:

4. Nastavte Workers AI

Než nasadíte svůj příklad s embeddingy, ujistěte se, že váš Worker používá váš katalog modelů, včetně model textových embeddingů vestavěné.

V rámci embeddings-tutorial adresáři otevřete soubor Wrangler ve svém editoru a přidejte nový [[ai]] binding, aby byly modely Workers AI dostupné ve vašem Workeru:

{
	"vectorize": [
		{
			"binding": "VECTORIZE",
			"index_name": "embeddings-index"
		}
	],
	"ai": {
		"binding": "AI" // available in your Worker on env.AI
	}
}
[[vectorize]]
binding = "VECTORIZE"
index_name = "embeddings-index"

[ai]
binding = "AI"

Jakmile máte Workers AI připravené, můžete napsat kód ve svém Workeru.

5. Napište kód ve svém Workeru

Chcete-li psát kód ve svém Workeru, přejděte do embeddings-tutorial Worker a otevřete src/index.ts soubor. index.ts je soubor, ve kterém konfigurujete interakce vašeho Workeru s indexem Vectorize.

Vymažte obsah index.ts. Vložte následující úryvek kódu do svého index.ts soubor. Na env parametru nahraďte <BINDING_NAME> hodnotou VECTORIZE:

export interface Env {
	VECTORIZE: Vectorize;
	AI: Ai;
}
interface EmbeddingResponse {
	shape: number[];
	data: number[][];
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let path = new URL(request.url).pathname;
		if (path.startsWith("/favicon")) {
			return new Response("", { status: 404 });
		}

		// You only need to generate vector embeddings once (or as
		// data changes), not on every request
		if (path === "/insert") {
			// In a real-world application, you could read content from R2 or
			// a SQL database (like D1) and pass it to Workers AI
			const stories = [
				"This is a story about an orange cloud",
				"This is a story about a llama",
				"This is a story about a hugging emoji",
			];
			const modelResp: EmbeddingResponse = await env.AI.run(
				"@cf/baai/bge-base-en-v1.5",
				{
					text: stories,
				},
			);

			// Convert the vector embeddings into a format Vectorize can accept.
			// Each vector needs an ID, a value (the vector) and optional metadata.
			// In a real application, your ID would be bound to the ID of the source
			// document.
			let vectors: VectorizeVector[] = [];
			let id = 1;
			modelResp.data.forEach((vector) => {
				vectors.push({ id: `${id}`, values: vector });
				id++;
			});

			let inserted = await env.VECTORIZE.upsert(vectors);
			return Response.json(inserted);
		}

		// Your query: expect this to match vector ID. 1 in this example
		let userQuery = "orange cloud";
		const queryVector: EmbeddingResponse = await env.AI.run(
			"@cf/baai/bge-base-en-v1.5",
			{
				text: [userQuery],
			},
		);

		let matches = await env.VECTORIZE.query(queryVector.data[0], {
			topK: 1,
		});
		return Response.json({
			// Expect a vector ID. 1 to be your top match with a score of
			// ~0.89693683
			// This tutorial uses a cosine distance metric, where the closer to one,
			// the more similar.
			matches: matches,
		});
	},
} satisfies ExportedHandler<Env>;

6. Nasaďte svůj Worker

Než Worker nasadíte globálně, přihlaste se ke svému účtu Cloudflare spuštěním:

npx wrangler login

Budete přesměrováni na webovou stránku s výzvou k přihlášení do dashboardu Cloudflare. Po přihlášení se zobrazí dotaz, zda Wrangler smí provádět změny ve vašem účtu Cloudflare. Přejděte dolů a vyberte Allow pokračovat.

Odtud nasaďte svůj Worker, aby byl projekt dostupný na internetu. Worker nasadíte příkazem:

npx wrangler deploy

Zobrazte náhled svého Workeru na adrese https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev.

7. Proveďte dotaz na svůj index

Nyní můžete přejít na adresu URL nově vytvořeného projektu, kde vložíte vektory a následně je vyhledáte.

S adresou URL vašeho nasazeného Workeru (například,https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev/), otevřete prohlížeč a:

  1. Vektory nejprve vložte tak, že navštívíte /insert.
  2. Dotaz na váš index proveďte pomocí trasy indexu: /.

Toto by mělo vrátit následující JSON:

{
	"matches": {
		"count": 1,
		"matches": [
			{
				"id": "1",
				"score": 0.89693683
			}
		]
	}
}

Tento příklad rozšiřte takto:

Dokončením tohoto tutoriálu jste úspěšně vytvořili index Vectorize, pomocí Workers AI vygenerovali vektorové embeddingy a globálně nasadili svůj projekt.

Další kroky