ベクトル化とワーカーAI

Vectorizeを使用すると、Workers AIで利用可能なモデルを含む機械学習モデルを使用して、ベクトル埋め込みを生成できます。

このガイドでは、次のことを説明します：

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

前提条件

続行するには：

まだであれば、Cloudflareアカウント ↗にサインアップしてください。
npm ↗をインストールします。
Node.js ↗をインストールします。権限の問題を避け、Node.jsのバージョンを変更するために、Volta ↗やnvm ↗のようなNodeバージョンマネージャーを使用してください。Wranglerは、16.17.0以上のNodeバージョンを必要とします。

1. ワーカーを作成する

新しいプロジェクトを作成し、そこにワーカーのスクリプトを含めます。これは、あなたのVectorizeインデックスのクライアントアプリケーションとして機能します。

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

npm create cloudflare@latest -- embeddings-tutorial

yarn create cloudflare@latest embeddings-tutorial

pnpm create cloudflare@latest embeddings-tutorial

For setup, select the following options:

For What would you like to start with?, choose Hello Worldの例.
For Which template would you like to use?, choose Hello Worldワーカー.
For Which language do you want to use?, choose TypeScript.
For Do you want to use git for version control?, choose Yes.
For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

これにより、新しいembeddings-tutorialディレクトリが作成されます。新しいembeddings-tutorialディレクトリには以下が含まれます：

src/index.tsにある「Hello World」ワーカー。
wrangler.toml設定ファイル。wrangler.tomlは、あなたのembeddings-tutorialワーカーがインデックスにアクセスする方法です。

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

✅ インデックス 'embeddings-index' を正常に作成しました

[[vectorize]]
binding = "VECTORIZE" # env.VECTORIZEでワーカーで利用可能
index_name = "embeddings-index"

これにより、新しいベクトルデータベースが作成され、次のステップで必要なバインディング設定が出力されます。

3. ワーカーをインデックスにバインドする

ワーカーがVectorizeインデックスに接続するためのバインディングを作成する必要があります。バインディングを使用すると、Cloudflare WorkersからVectorizeやR2などのリソースにアクセスできます。wrangler.tomlファイルを更新することでバインディングを作成します。

インデックスをワーカーにバインドするには、wrangler.tomlファイルの末尾に以下を追加します：

[[vectorize]]
binding = "VECTORIZE" # env.VECTORIZEでワーカーで利用可能
index_name = "embeddings-index"

具体的には：

<BINDING_NAME>に設定する値（文字列）は、ワーカー内でこのデータベースを参照するために使用されます。このチュートリアルでは、バインディングの名前をVECTORIZEとします。
バインディングは有効なJavaScript変数名 ↗でなければなりません。例えば、binding = "MY_INDEX"やbinding = "PROD_SEARCH_INDEX"は、バインディングの有効な名前になります。
バインディングは、env.<BINDING_NAME>でワーカー内で利用可能で、VectorizeのクライアントAPIがこのバインディングで使用できるように公開されます。

4. Workers AIをセットアップする

埋め込みの例をデプロイする前に、ワーカーがテキスト埋め込みモデルを含むモデルカタログを使用していることを確認してください。

embeddings-tutorialディレクトリ内から、エディタでwrangler.tomlファイルを開き、Workers AIのモデルをワーカーで利用できるようにするために新しい[[ai]]バインディングを追加します：

[[vectorize]]
binding = "VECTORIZE" # env.VECTORIZEでワーカーで利用可能
index_name = "embeddings-index"

[ai]
binding = "AI" # env.AIでワーカーで利用可能

Workers AIの準備が整ったので、ワーカー内でコードを書くことができます。

5. ワーカー内でコードを書く

ワーカー内でコードを書くには、embeddings-tutorialワーカーに移動し、src/index.tsファイルを開きます。index.tsファイルは、ワーカーが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 });
    }

    // ベクトル埋め込みは一度だけ生成する必要があります（または
    // データが変更されるとき）、すべてのリクエストで生成する必要はありません
    if (path === "/insert") {
      // 実際のアプリケーションでは、R2や
      // SQLデータベース（D1など）からコンテンツを読み取り、Workers AIに渡すことができます
      const stories = [
        "これはオレンジの雲についての物語です",
        "これはラマについての物語です",
        "これはハグする絵文字についての物語です",
      ];
      const modelResp: EmbeddingResponse = await env.AI.run(
        "@cf/baai/bge-base-en-v1.5",
        {
          text: stories,
        },
      );

      // ベクトル埋め込みをVectorizeが受け入れられる形式に変換します。
      // 各ベクトルにはID、値（ベクトル）、およびオプションのメタデータが必要です。
      // 実際のアプリケーションでは、IDはソース
      // ドキュメントのIDにバインドされます。
      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);
    }

    // あなたのクエリ：この例ではベクトルID 1に一致することを期待します
    let userQuery = "オレンジの雲";
    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({
      // ベクトルID 1がスコア
      // ~0.89693683で最も一致することを期待します
      // このチュートリアルではコサイン距離メトリックを使用しており、1に近いほど
      // より類似しています。
      matches: matches,
    });
  },
} satisfies ExportedHandler<Env>;

6. ワーカーをデプロイする

ワーカーをグローバルにデプロイする前に、次のコマンドを実行してCloudflareアカウントにログインします：

npx wrangler login

Cloudflareダッシュボードにログインするように求められるウェブページにリダイレクトされます。ログインした後、WranglerがCloudflareアカウントに変更を加えることができるかどうかを尋ねられます。下にスクロールして許可を選択して続行します。

ここから、プロジェクトをインターネット上でアクセス可能にするためにワーカーをデプロイします。ワーカーをデプロイするには、次のコマンドを実行します：

npx wrangler deploy

デプロイしたワーカーのプレビューはhttps://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.devで確認できます。

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

これで、新しく作成したプロジェクトのURLにアクセスしてベクトルを挿入し、それらをクエリすることができます。

デプロイしたワーカーのURL（例えば、https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev/）を開き、次の手順を実行します：

最初に/insertにアクセスしてベクトルを挿入します。
インデックスルート/にアクセスしてインデックスをクエリします。

これにより、次のJSONが返されるはずです：

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

この例を拡張するには：

より多くの入力を追加し、より大きなベクトルセットを生成します。
URLで渡されたカスタムクエリパラメータを受け入れます（例えば、URL.searchParamsを介して）。
異なる距離メトリックで新しいインデックスを作成し、入力に応じてスコアがどのように変化するかを観察します。

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

次のステップ

Workers AIとVectorizeを使用して生成AIチャットボットを構築します。
ベクトルデータベースの仕組みについてさらに学びます。
Cloudflare WorkersからVectorize APIを使用する方法に関する例を読みます。

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings