Vectorize と Workers AI

Vectorize では、機械学習モデル（Workers AI で使えるモデルを含む）を使ってベクトル埋め込みを生成できます。

このガイドでは、次のことを行います。

Vectorize インデックスを作成する。
Cloudflare Worker をインデックスに接続する。
Workers AI でベクトル埋め込みを生成する。
Vectorize でそれらのベクトル埋め込みをクエリする。

前提条件

続けるには、次を行います。

まだなら Cloudflare アカウント ↗ に登録します。
npm ↗ をインストールします。
Node.js ↗ をインストールします。権限の問題を避け、Node.js のバージョンを切り替えるには、Volta ↗ や nvm ↗ などの Node バージョンマネージャーを使います。Wrangler には Node バージョン 16.17.0 以降が必要です。

1. Worker を作成する

Worker スクリプトを含む新しいプロジェクトを作成します。このスクリプトが Vectorize インデックスのクライアントアプリケーションになります。

ターミナルを開き、次のコマンドで embeddings-tutorial という新しいプロジェクトを作成します。

npm create cloudflare@latest -- embeddings-tutorial

yarn create cloudflare embeddings-tutorial

pnpm create cloudflare@latest embeddings-tutorial

セットアップでは、次のオプションを選びます。

What would you like to start with? では、Hello World example を選びます。
Which template would you like to use? では、Worker only を選びます。
Which language do you want to use? では、TypeScript を選びます。
Do you want to use git for version control? では、Yes を選びます。
Do you want to deploy your application? では、No を選びます（デプロイ前にいくつか変更します）。

これで新しい embeddings-tutorial ディレクトリができます。新しい embeddings-tutorial ディレクトリには次が含まれます。

src/index.ts にある "Hello World" Worker。
wrangler.jsonc 設定ファイル。wrangler.jsonc で、embeddings-tutorial Worker がインデックスへアクセスします。

2. インデックスを作成する

ベクトルデータベースは、従来の SQL や NoSQL データベースとは異なります。ベクトルデータベースは、データの表現であるベクトル埋め込みを保存するためのもので、元データそのものは保存しません。

最初の Vectorize インデックスを作成するには、Workers プロジェクト用に今作ったディレクトリへ移動します。

cd embeddings-tutorial

インデックスを作成するには、wrangler vectorize create コマンドを使い、インデックス名を指定します。よいインデックス名は次のとおりです。

小文字または数字の ASCII 文字の組み合わせで、32 文字未満、先頭は文字、スペースの代わりにハイフン（-）を使います。
用途と環境がわかります。例: "production-doc-search" や "dev-recommendation-engine"。
インデックスの説明にだけ使い、コードから直接参照しません。

加えて、インデックスに保存するベクトルの 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 インデックスに接続するには、バインディングを作成する必要があります。バインディングを使うと、Workers から Vectorize や R2 などのリソースへアクセスできます。バインディングは Wrangler ファイルを更新して作成します。

インデックスを Worker にバインドするには、Wrangler ファイルの末尾に次を追加します。

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

[[vectorize]]
binding = "VECTORIZE"
index_name = "embeddings-index"

具体的には次のとおりです。

<BINDING_NAME> に設定した値（文字列）で、Worker 内からこのデータベースを参照します。このチュートリアルでは、バインディング名を VECTORIZE にします。
バインディングは有効な JavaScript の変数名 ↗ である必要があります。たとえば binding = "MY_INDEX" や binding = "PROD_SEARCH_INDEX" は、どちらも有効なバインディング名です。
バインディングは Worker 内の env.<BINDING_NAME> で使え、Vectorize のクライアント API はこのバインディング上に公開されます。Workers アプリケーション内から使えます。

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 ダッシュボードへのログインを求める Web ページが開きます。ログインしたあと、Wrangler が Cloudflare アカウントを変更してよいか確認されます。下へスクロールし、許可を選んで続けます。

ここから Worker をデプロイすると、プロジェクトをインターネット上で利用できます。Worker をデプロイするには、次を実行します。

npx wrangler deploy

https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev で Worker をプレビューできます。

7. インデックスをクエリする

新しく作成したプロジェクトの URL を開き、ベクトルを挿入してからクエリできます。

デプロイした Worker の URL（例: https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev/）をブラウザーで開き、次を行います。

先に /insert を開いてベクトルを挿入します。
インデックスルート / を開いてインデックスをクエリします。

次の JSON が返るはずです。

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

この例は、次のように拡張できます。

入力を増やし、より大きなベクトル集合を生成する。
たとえば URL.searchParams 経由で、URL に渡したカスタムクエリパラメーターを受け取る。
別の距離メトリックで新しいインデックスを作り、入力に対するスコアの変化を確認する。

このチュートリアルを終えると、Vectorize インデックスの作成、Workers AI によるベクトル埋め込みの生成、プロジェクトのグローバルデプロイまで完了しています。

次のステップ

Workers AI と Vectorize で生成 AI チャットボットを構築する。
ベクトルデータベースの仕組みを詳しく学ぶ。
Cloudflare Workers から Vectorize API を使う例を読む。