ベクトル化API

このページでは、Cloudflare Workers内で利用可能なベクトル化APIについて、使用例を含めて説明します。

操作

ベクトルの挿入

let vectorsToInsert = [
  { id: "123", values: [32.4, 6.5, 11.2, 10.3, 87.9] },
  { id: "456", values: [2.5, 7.8, 9.1, 76.9, 8.5] },
];
let inserted = await env.YOUR_INDEX.insert(vectorsToInsert);

インデックスにベクトルを挿入します。ベクトル化の挿入は非同期で、挿入操作はその操作に固有の変更識別子を返します。挿入されたベクトルがベクトル化インデックスでクエリ可能になるまでには通常数秒かかります。

同じベクトルIDを持つベクトルがすでにインデックスに存在する場合、新しいIDを持つベクトルのみが挿入されます。

既存のベクトルを更新する必要がある場合は、upsert操作を使用してください。

ベクトルのアップサート

let vectorsToUpsert = [
  { id: "123", values: [32.4, 6.5, 11.2, 10.3, 87.9] },
  { id: "456", values: [2.5, 7.8, 9.1, 76.9, 8.5] },
  { id: "768", values: [29.1, 5.7, 12.9, 15.4, 1.1] },
];
let upserted = await env.YOUR_INDEX.upsert(vectorsToUpsert);

インデックスにベクトルをアップサートします。ベクトル化のアップサートは非同期で、アップサート操作はその操作に固有の変更識別子を返します。アップサートされたベクトルがベクトル化インデックスでクエリ可能になるまでには通常数秒かかります。

アップサート操作は、同じIDを持つベクトルが存在しない場合はベクトルをインデックスに挿入し、同じIDを持つベクトルを上書きします。

アップサートは、既存のベクトルの値やメタデータをアップサートされたベクトルとマージまたは結合することはありません：アップサートされたベクトルは既存のベクトルを完全に置き換えます。

ベクトルのクエリ

let queryVector = [32.4, 6.55, 11.2, 10.3, 87.9];
let matches = await env.YOUR_INDEX.query(queryVector);

提供されたベクトルでインデックスをクエリし、設定された距離メトリックに基づいて最も近いベクトルのスコアを返します。

topKを設定して返される一致の数を構成します（デフォルト：5）
returnValues: trueを設定してベクトルの値を返します（デフォルト：false）
returnMetadata: 'indexed'またはreturnMetadata: 'all'を設定してベクトルのメタデータを返します（デフォルト：‘none’）

let matches = await env.YOUR_INDEX.query(queryVector, {
  topK: 5,
  returnValues: true,
  returnMetadata: "all",
});

topK

topKは、クエリ操作によって返される一致の数を指定するために構成できます。ベクトル化は現在、topK値の上限を100にサポートしています。ただし、returnValuesがtrueに設定されているか、returnMetadataがallに設定されているクエリ操作の場合、topKは最大値20に制限されます。

returnMetadata

returnMetadataフィールドは、クエリ中にベクトルメタデータを取得するための3つの方法を提供します：

none: メタデータを取得しません。
indexed: インデックスされたメタデータフィールドのメタデータのみを取得します。このオプションには遅延オーバーヘッドはありませんが、長いテキストフィールドは切り捨てられる可能性があります。
all: ベクトルに関連付けられたすべてのメタデータを取得します。このオプションではクエリが遅くなる可能性があり、topKは20に制限されます。

IDによるベクトルの取得

let ids = ["11", "22", "33", "44"];
const vectors = await env.YOUR_INDEX.getByIds(ids);

指定されたIDによるベクトルを取得し、値とメタデータを含みます。

IDによるベクトルの削除

let idsToDelete = ["11", "22", "33", "44"];
const deleted = await env.YOUR_INDEX.deleteByIds(idsToDelete);

現在のインデックスから提供されたベクトルIDを削除します。ベクトル化の削除は非同期で、削除操作はその操作に固有の変更識別子を返します。ベクトルがベクトル化インデックスから削除されるまでには通常数秒かかります。

インデックスの詳細を取得

const details = await env.YOUR_INDEX.describe();

指定されたインデックスの構成を直接取得し、その設定されたdimensionsと距離metricを含みます。

メタデータインデックスの作成

指定されたプロパティでメタデータフィルタリングを有効にします。最大10のプロパティに制限されています。

次のwrangler vectorizeコマンドを実行します：

wrangler vectorize create-metadata-index <index-name> --property-name='some-prop' --type='string'

メタデータインデックスの削除

ベクトル化が指定されたメタデータインデックスを削除できるようにします。

次のwrangler vectorizeコマンドを実行します：

wrangler vectorize delete-metadata-index <index-name> --property-name='some-prop'

メタデータインデックスの一覧表示

メタデータフィルタリングが有効になっているメタデータプロパティの一覧を表示します。

次のwrangler vectorizeコマンドを実行します：

wrangler vectorize list-metadata-index <index-name>

インデックス情報の取得

インデックスに関する追加の詳細を取得します。

次のwrangler vectorizeコマンドを実行します：

wrangler vectorize info <name>

ベクトル

ベクトルは、機械学習モデルからのベクトル埋め込み出力を表します。

id - インデックス内のベクトルを識別する一意のstring。これは、ベクトル値が生成されたドキュメント、オブジェクト、またはデータベース識別子のIDにマッピングされるべきです。
namespace - インデックス内のオプションのパーティションキー。操作は名前空間ごとに実行されるため、これを使用して大きなインデックス内に孤立したセグメントを作成できます。
values - ベクトル埋め込み自体としてのnumber、Float32Array、またはFloat64Arrayの配列。この配列は密な配列でなければならず、この配列の長さはインデックスに設定されたdimensionsと一致する必要があります。
metadata - ベクトルに追加のメタデータを保存するために使用できるオプションのキーと値のペアのセット。

let vectorExample = {
  id: "12345",
  values: [32.4, 6.55, 11.2, 10.3, 87.9],
  metadata: {
    key: "value",
    hello: "world",
    url: "r2://bucket/some/object.json",
  },
};

ワーカーへのバインディング

Bindingsを使用すると、ベクトル化インデックスやR2バケットなどのリソースをワーカーに接続できます。

バインディングは、ワーカープロジェクトに関連付けられたwrangler.toml構成内、またはプロジェクトのCloudflareダッシュボードを介して定義されます。

ベクトル化インデックスは名前でバインドされます。production-doc-searchという名前のインデックスのバインディングは、以下のようになります：

[[vectorize]]
binding = "PROD_SEARCH" # インデックスはワーカー内でenv.PROD_SEARCHとして利用可能になります
index_name = "production-doc-search"

詳細については、バインディングのドキュメントを参照してください。

TypeScriptタイプ

npm create cloudflare@latestを介して作成された新しいワーカープロジェクトには、ベクトル化に関連するTypeScriptタイプが自動的に含まれます。

古いプロジェクトや、TypeScriptプロジェクトでベクトル化のREST API ↗を使用しようとしている非ワーカーのプロジェクトは、@cloudflare/workers-typesバージョン4.20230922.0以降がインストールされていることを確認してください。

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings