仕組み

VectorizeはDBなので、Workersとセットで使う
テキストをVector = 数字の配列として扱い、テキストの部分一致ではなく意味の近さで検索できるようにするのが目的
流れとしては、Workersでテキストを受取りVectorに変換、Vectorにidやmetadataを付与してインデックスに保管

用語：

Vetorizeに保存しているデータは「Vector」
DBのテーブル/コレクション相当のものは「Index」

注意点や詰まった部分：

テーブルの中身を見ることが出来ないので、ちゃんと作成・更新されたのかがわかりづらい。
- npx wrangler vectorize list で created と modified に差が生じていればとりあえず、操作自体は成功している事に気付ける
テキストを分割してVectorにするが、Prismaのように「渡したidと同じものを全て削除・更新して」ということが出来ないので、削除・更新ロジックが複雑になる

始める

テンプレートから始めると良い

npm create cloudflare@latest -- vectorize-tutorial

https://developers.cloudflare.com/vectorize/get-started/intro/

CLIからの場合

npx wrangler vectorize create インデックス名 \
  --dimensions 1024 \
  --metric "cosine" \
  --description "インデックスの説明" \
  --update-config

*重要：日本語に対応したVector生成モデルを使う場合は、dimensionsを 1024 にする。
- ここを 1536 などにすると一切機能しなくなる

他のCLIコマンド：

// 削除
npx wrangler vectorize delete インデックス名

// 確認
npx wrangler vectorize list

wrangler.jsonc ：

	"ai": {
		"binding": "AI"
	},
	"vectorize": [
		{
			"binding": "VECTORIZE",
			"index_name": "インデックス名",
			"remote": true
		}
	]

必要なbindingはaiとvectorize

Vectorの生成

まず、受け入れたtextをVectorに変換

const embedding = await env.AI.run('@cf/baai/bge-m3', { text: texts });

日本語を使う場合は多言語対応のモデルを使う

次にVectorをインデックスに保管

await env.VECTORIZE.upsert([{ id: 'example-id', values: [0.1, 0.2, 0.3], metadata: { info: 'example-metadata' } }]);

insert ではなくupsert を使う方が良い
values にテキストから生成されたVectorを入れる
id は自分で付与する必要がある
metadataもあったほうが良い

chunkに分ける

受け取ったテキストが長い場合は数分割したほうが良い

const chunks = chunkText(content);

const embedding = await env.AI.run('@cf/baai/bge-m3', { text: chunks });

上記の場合、受け取った content を chunkText関数で800文字毎に分割してVectorを生成

chunkText.ts：

export function chunkText(text: string, chunkSize = 800): string[] {
	const chunks: string[] = [];
	let start = 0;

	while (start < text.length) {
		chunks.push(text.slice(start, start + chunkSize));
		start += chunkSize;
	}

	return chunks;
}

インデックスには分けて保管する

await env.VECTORIZE.upsert(
	embedding.data.map((vec: number[], i: number) => ({
		id: `${memoId}-chunk-${i}`,
		values: vec,
		metadata: { index: i, memoId },
	}))
);

*重要：Chunkに分けたVectorは、同一のテキストから発生したことを id・metadataに記しておく。
- 取得・削除・更新の為に必要

Vectorの検索

受け取ったqueryのテキストから合致するVectorを取得する例

まず query をVectorにする

const embedding = await env.AI.run('@cf/baai/bge-m3', { text: [query] });

インデックスから意味的に近いものを取得

const results = await env.VECTORIZE.query(embedding.data[0], { topK: 8, returnMetadata: true });

returnMetadata: true はchunkとして分けた元は同じテキストのVectorを絞るために必要
topKは意味的に近いものを上位から何個取得するか

filter

アプリ側からqueryなどでVector検索をするが、Vectorの数字配列データが欲しいわけではない。欲しいのは SearhInputなどに入力されたqueryとアプリ側のどのデータが近いのかという情報。

なので、返すべきはインデックス保管時にmetadata に設定した memoId や postId

const memoIds = [
  ...new Set(
    results.matches
      .filter(
        (m) => m.score !== undefined && m.score >= 0.6 && m.metadata?.memoId
      )
      .map((m) => m.metadata?.memoId)
  ),
];

上記は意味的に近かった8件の中から、さらに score が 0.6 以上だったものをインデックスから選ぶ
...new Set で被り無しの配列にしているのはアプリ側に返すmemoIdは重複が必要無いため

*Vectorの削除

重要：

Vectorの削除には自分で作成した id を正確に指定しないといけない
- metadata の識別子を使ってPrismaのように一括で削除は出来ない

const { memoId, chunkCount }: any = await req.json();

const idsToDelete = Array.from(
  { length: chunkCount },
  (_, i) => `${memoId}-chunk-${i}`
);
await env.VECTORIZE.deleteByIds(idsToDelete);

問題になるのは、VectorをChunkに分けて保存しているということ。

Prismaのように「渡したmemoIdやpostId がmetadata に存在するものを一括で削除」することが出来ないため、id に付与した${i}の数を削除時にも把握している必要がある。

${memoId}-chunkのような id にすればIndexの把握は必要無くなるが、id は一意である必要があるのでそれは出来ない。

対策：

アプリ側から削除したいデータのChunkCountを計算して渡すことにより、一意のmemoId が持つ Vector（${memoId}-chunk-${i} ）を全て削除できる
*注意：Chunkの長さが10を超えることは無いだろうという前提でArray.form({ length:10 }) のようにして削除を試行することは出来ない。存在する id にアクセスすることもあるので機能しない

*Vectorの更新

アプリから受け取った識別子（ memoId 、postId）を持つVectorを全て削除したのち、新しいVectorを作成する

const idsToDelete = Array.from(
  { length: currentChunks },
  (_, i) => `${memoId}-chunk-${i}`
);
await env.VECTORIZE.deleteByIds(idsToDelete);

const chunks = chunkText(content);
const embedding: any = await env.AI.run("@cf/baai/bge-m3", { text: chunks });

await env.VECTORIZE.upsert(
  embedding.data.map((vec: number[], i: number) => ({
    id: `${memoId}-chunk-${i}`,
    values: vec,
    metadata: { memoId, index: i },
  }))
);

エラーに詰まった場合

npx wrangler tail

上記コマンドを実行すると、 index.tsに来たリクエストの成功や失敗、エラー原因等がリアルタイムでターミナルに表示される。

✘ [ERROR] Error: VECTOR_UPSERT_ERROR (code = 40012): invalid vector for id="155-chunk-0", expected 1536 dimensions, and got 1024 dimensions;

Cloudflare：Vectorize

Cloudflare：Vectorize