INTEGRITY Документация

← Cloudflare Vectorize / vectorize / get-started

Vectorize и Workers AI

Vectorize позволяет генерировать векторные эмбеддинги с помощью модели машинного обучения, включая модели, доступные в Workers AI.

Это руководство проведёт вас через следующие шаги:

Предварительные требования

Чтобы продолжить:

  1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗ если вы ещё этого не сделали.
  2. Установка npm ↗.
  3. Установка Node.js ↗. Используйте менеджер версий Node, например Volta ↗ или nvm ↗ чтобы избежать проблем с правами доступа и переключать версии Node.js. Wrangler требует версии Node 16.17.0 или более поздней версии.

1. Создайте Worker

Вы создадите новый проект со скриптом Worker, который будет выступать клиентским приложением для вашего индекса Vectorize.

Откройте терминал и создайте новый проект с именем embeddings-tutorial выполнив следующую команду:

npm create cloudflare@latest -- embeddings-tutorial

Для настройки выберите следующие параметры:

Это создаст новый embeddings-tutorial каталог. Ваш новый embeddings-tutorial каталог будет включать:

2. Создайте индекс

Векторная база данных отличается от традиционной SQL или NoSQL базы данных. Она предназначена для хранения векторных эмбеддингов, которые являются представлениями данных, а не самими исходными данными.

Чтобы создать свой первый индекс Vectorize, перейдите в каталог, который вы только что создали для проекта Workers:

cd embeddings-tutorial

Чтобы создать индекс, используйте wrangler vectorize create команду и укажите имя индекса. Хорошее имя индекса:

Кроме того, определите как dimensions векторов, которые будут храниться в индексе, а также расстояние metric используемая для определения похожих векторов при создании индекса. Эту конфигурацию нельзя изменить позже, поскольку векторная база данных настраивается с фиксированной конфигурацией векторов.

Выполните следующую wrangler vectorize команду, убедившись, что dimensions установлены в 768: это важно, поскольку модель Workers AI, используемая в этом руководстве, выводит векторы с 768 измерениями.

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"

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

3. Привяжите свой Worker к индексу

Чтобы Worker мог подключаться к индексу Vectorize, необходимо создать привязку. Bindings позволяют вашим Workers обращаться к таким ресурсам, как Vectorize или R2, из Cloudflare Workers. Вы создаёте привязки, обновляя свой файл Wrangler.

Чтобы привязать индекс к своему Worker, добавьте следующее в конец файла Wrangler:

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

А именно:

4. Настройте Workers AI

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

Внутри embeddings-tutorial каталоге откройте файл Wrangler в редакторе и добавьте новую [[ai]] привязку, чтобы сделать модели Workers AI доступными в вашем Worker:

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

После настройки Workers AI можно писать код в своём Worker.

5. Напишите код в своём Worker

Чтобы написать код в своём Worker, перейдите в embeddings-tutorial Worker и откройте src/index.ts файл. index.ts файл предназначен для настройки взаимодействия вашего Worker с индексом Vectorize.

Очистите содержимое index.ts. Вставьте следующий фрагмент кода в свой index.ts файл. На env параметр, замените <BINDING_NAME> с 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. Разверните Worker

Перед глобальным развёртыванием Worker войдите в свой аккаунт Cloudflare, выполнив команду:

npx wrangler login

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

Теперь разверните Worker, чтобы сделать проект доступным в интернете. Для развёртывания Worker выполните команду:

npx wrangler deploy

Откройте предпросмотр Worker по адресу https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev.

7. Запросите свой индекс

Теперь можно перейти по URL-адресу созданного проекта, чтобы вставить векторы и выполнить к ним запросы.

Используя URL-адрес развёрнутого Worker (например,https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev/), откройте браузер и выполните следующее:

  1. Сначала вставьте векторы, перейдя в /insert.
  2. Выполните запрос к индексу, перейдя по маршруту индекса: /.

В результате должен вернуться следующий JSON:

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

Расширьте этот пример, выполнив следующее:

Завершив это руководство, вы успешно создали индекс Vectorize, использовали Workers AI для создания векторных эмбеддингов и развернули проект по всему миру.

Следующие шаги