Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

Vectorize と Workers AI

最終更新 Markdown で表示Agent セットアップ

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

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

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

前提条件

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

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

1. Worker を作成する

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

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

npm 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/)をブラウザーで開き、次を行います。

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

次の JSON が返るはずです。

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

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

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

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

次のステップ

役に立ちましたか?