このページでは、Cloud SQL for PostgreSQL を使用して次の操作を行う方法について説明します。
モデルに基づいてベクトル エンベディングを生成し、保存する。
pgvector拡張機能を使用して、エンベディングをインデックスに登録し、クエリする。
詳細については、Cloud SQL を使用して生成 AI アプリケーションを作成するをご覧ください。
Cloud SQL では、Vertex AI でホストされているエンベディング モデルを使用して、テキスト文字列をエンベディングに変換できます。エンベディングは、特定のテキストの意味を数値ベクトルとして表したモデル表現です。
Cloud SQL は、real 値の配列としてエンベディングを実装します。生成されたエンベディングは pgvector 拡張関数の入力として使用できます。
始める前に
一部の要件は、Cloud SQL を使用してエンベディングを生成するのか、別のソースからデータベースに保存されているエンベディングのみを処理する必要があるかによって異なります。
リージョンの制約事項
Cloud SQL で Vertex AI エンベディングを生成するには、インスタンスが generative AI foundational models are supported のリージョンに存在する必要があります。このリージョンに、Cloud SQL がエンベディングに使用できる Vertex AI モデル（text-embedding と textembedding-gecko）が存在します。
必要なデータベース拡張機能
エンベディングを操作するには、Cloud SQL インスタンスに google_ml_integration 拡張機能をインストールします。Vertex AI モデルの場合は、バージョン 1.2 以降をインストールします。サードパーティ モデルまたはカスタムモデルの場合は、バージョン 1.4.2 以降をインストールします。
必要に応じて、これらのエンベディングを保存し、エンベディングでベクトル関数と演算子を使用する場合は、pgvector 拡張機能も必要です。
Cloud SQL は、この両方の拡張機能を備えています。これらは、インスタンス内の任意のデータベースにインストールできます。詳細については、PostgreSQL 拡張機能を構成するをご覧ください。
モデルへのアクセスを設定する
Cloud SQL インスタンスからエンベディングを生成するには、テキスト エンベディング モデルを使用するように Cloud SQL を構成する必要があります。
クラウドベースの text-embedding モデルまたは textembedding-gecko モデルを使用するには、Cloud SQL を Vertex AI と統合する必要があります。
データベース ユーザーにエンベディングの生成権限を付与する
データベース ユーザーに、embedding 関数を使用して予測を実行する権限を付与します。
psql クライアントを使用して接続するの説明に従って、
psqlクライアントをプライマリ インスタンスに接続します。psqlコマンド プロンプトで、データベースに接続して権限を付与します。\c DB_NAME GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;次のように置き換えます。
DB_NAME: 権限を付与するデータベースの名前
USER_NAME: 権限を付与するユーザーの名前
エンベディングを生成する
Cloud SQL には、テキストをベクトル エンベディングに変換する関数があります。このエンベディングをベクトルデータとしてデータベースに保存し、必要に応じて pgvector 関数を使用してクエリを実行します。
エンベディングを生成する
Cloud SQL を使用してエンベディングを生成するには、google_ml_integration 拡張機能が提供する embedding() 関数を使用します。
SELECT embedding( 'MODEL_IDVERSION_TAG', 'TEXT');
次の項目を置き換えます。
MODEL_ID: クエリするモデルの ID。
Vertex AI Model Garden を使用している場合は、
text-embedding-004またはtext-multilingual-embedding-002を指定します。これらは、Cloud SQL がテキスト エンベディングに使用できるクラウドベースのモデルです。詳細については、テキスト エンベディングをご覧ください。VERSION_TAG（省略可）: クエリするモデルのバージョンタグ。
text-embedding-004またはtext-multilingual-embedding-002より前のtextembedding-geckoバージョンの場合は、Prepend the tag with@` です。Vertex AI で
textembedding-geckoモデルのいずれかを使用している場合は、モデル バージョンに記載されているバージョンタグのいずれかを指定します。TEXT: ベクトル エンベディングに変換するテキスト。
次の例では、text-embedding-004 モデルを使用して、指定されたリテラル文字列に基づいてエンベディングを生成します。
SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');
生成されたエンベディングを保存する
embedding() 関数の戻り値は、real 値の配列です。この値をテーブルに保存するには、real[] 列を追加します。
ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];
次の項目を置き換えます。
TABLE: テーブル名
EMBEDDING_COLUMN: 新しいエンベディング列の名前
DIMENSIONS: モデルがサポートするディメンションの数。
Vertex AI で
text-embeddingモデルまたはtextembedding-geckoモデルのいずれかを使用している場合は、768を指定します。
省略可: pgvector 拡張機能をインストールしている場合は、エンベディングを vector 値として保存できます。
ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);
エンベディングを格納する列を作成したら、同じテーブルの別の列にすでに格納されている値に基づいてデータを入力できます。
UPDATE TABLE SET EMBEDDING_COLUMN = embedding('MODEL_IDVERSION_TAG', SOURCE_TEXT_COLUMN);
次の項目を置き換えます。
TABLE: テーブル名。
EMBEDDING_COLUMN: エンベディング列の名前。
MODEL_ID: クエリするモデルの ID。
Vertex AI Model Garden を使用している場合は、
text-embedding-004またはtext-multilingual-embedding-002を指定します。これらは、Cloud SQL がテキスト エンベディングに使用できるクラウドベースのモデルです。詳細については、テキスト エンベディングをご覧ください。VERSION_TAG（省略可）: クエリするモデルのバージョンタグ。
text-embedding-004またはtext-multilingual-embedding-002より前のtextembedding-geckoバージョンの場合は、Prepend the tag with@` です。Vertex AI で
textembedding-geckoモデルのいずれかを使用している場合は、モデル バージョンに記載されているバージョンタグのいずれかを指定します。SOURCE_TEXT_COLUMN: テキストを格納している列の名前。このテキストをエンベディングに変換します。
上記のコマンドは、real[] と vector の両方のエンベディング列で機能します。エンベディング列が vector 型の場合、Cloud SQL は embedding() の戻り値を real 配列から vector 値に暗黙的にキャストします。
次の例では、text-embedding-004 モデルを使用して、messages.message 列の内容に基づいてエンベディングを messages.message_vector 列に入力します。
UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);
pgvector を使用してエンベディングをクエリしてインデックスに登録する
pgvector PostgreSQL 拡張機能を使用すると、データベースに対してテキスト エンベディングの保存、インデックス登録、クエリを行う際に、ベクトル固有の演算子と関数を使用できます。Cloud SQL には、pgvector を処理するための独自の最適化が用意されており、エンベディングを含むクエリを高速化できるインデックスを作成できます。
最近傍インデックスを作成する
pgvector は、インデックス登録による近似最近傍検索をサポートしています。
インデックス メソッドとして hnsw を指定して pgvector ベースのインデックスを作成するには、次の例を使用します。
CREATE INDEX ON TABLE
USING hnsw (EMBEDDING_COLUMN DISTANCE_FUNCTION)
WITH (m = M, ef_construction = EF_CONSTRUCTION);
次のように置き換えます。
TABLE: インデックスを追加するテーブル。
EMBEDDING_COLUMN:
vectorデータを格納する列。DISTANCE_FUNCTION: このインデックスで使用する距離関数。次のいずれかを選択します。
L2 距離:
vector_l2_ops内積:
vector_ip_opsコサイン距離:
vector_cosine_ops
M（省略可）: グラフ内の近隣データポイントとの最大接続数。
pgvectorのデフォルト値は 16 であるため、5 ～ 48 の範囲で設定することをおすすめします。EF_CONSTRUCTION（省略可）: インデックスの構築時にグラフ走査中に最も近い候補を保持するリストのサイズ。値が大きいほど、アルゴリズムはより多くの候補を検討するようになり、より良いインデックスを作成できます。デフォルトのサイズは 64 です。
このインデックスを、vector ではなく real[] データ型を使用するエンベディング列に作成するには、列を vector データ型にキャストします。
CREATE INDEX ON TABLE
USING hnsw ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS))) DISTANCE_FUNCTION)
WITH (m = M, ef_construction = EF_CONSTRUCTION);
DIMENSIONS は、エンベディング列のディメンション幅に置き換えます。
次のセクションでは、このようなインデックスの例を示します。
指定されたテキストで類似クエリを作成する
エンベディングをデータベースに保存してインデックスを作成すると、pgvector クエリ機能の全範囲が使用可能になります。
テキストに最も近いセマンティック ネイバーを見つけるには、embedding() 関数を使用して、テキストをベクトルに変換します。同じクエリで、このベクトルを pgvector 最近傍演算子 <-> に適用し、意味的に最も類似したエンベディングを含むデータベース行を見つけます。
embedding() は real 配列を返すため、これらの値を pgvector 演算子で使用するには、embedding() 呼び出しを vector にキャストする必要があります。
SELECT RESULT_COLUMNS FROM TABLE
ORDER BY EMBEDDING_COLUMN
<-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
LIMIT ROW_COUNT
次の項目を置き換えます。
RESULT_COLUMNS: 意味的に類似した行から表示する列。
TABLE: テキストを比較するエンベディングを含むテーブル。
EMBEDDING_COLUMN: 保存されたエンベディングを含む列。
MODEL_ID: クエリするモデルの ID。
Vertex AI Model Garden を使用している場合は、
text-embedding-004またはtext-embedding-multilingual-002を指定します。これらは、Cloud SQL がテキスト エンベディングに使用できるクラウドベースのモデルです。詳細については、テキスト エンベディングをご覧ください。VERSION_TAG（省略可）: クエリするモデルのバージョンタグ。タグの前に
@を付けます。Vertex AI で
textembedding-geckoモデルのいずれかを使用している場合は、モデル バージョンに記載されているバージョンタグのいずれかを指定します。TEXT: 最も近い保存済みセマンティック ネイバーを見つけるために必要なテキスト。
ROW_COUNT: 返される行数。最良の一致が 1 つだけ必要な場合は、このパラメータの値として
1を指定します。
このクエリを vector ではなく、real[] データ型を使用する保存済みエンベディング列で実行するには、列を vector データ型にキャストします。
SELECT RESULT_COLUMNS FROM TABLE
ORDER BY EMBEDDING_COLUMN::vector
<-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
LIMIT ROW_COUNT
モデル バージョン タグを使用してエラーを回避する
選択したエンベディング モデルの安定版を常に使用することを強くおすすめします。ほとんどのモデルでは、バージョンタグは明示的に設定されています。
モデルのバージョンタグを指定せずに embedding() 関数を呼び出すことは、構文的には可能ですが、エラーが発生しやすくなります。
Vertex AI Model Garden でモデルを使用するときにバージョンタグを省略すると、Vertex AI はモデルの最新バージョンを使用します。これは最新の安定版ではない可能性があります。使用可能な Vertex AI モデル バージョンの詳細については、モデル バージョンをご覧ください。
特定の Vertex AI モデル バージョンは、特定のテキスト入力に対して常に同じ embedding() レスポンスを返します。embedding() の呼び出しでモデル バージョンを指定しないと、新しい公開モデル バージョンによって、特定の入力に対する返されるベクトルが突然変更される可能性があります。これにより、アプリでエラーや予期しない動作が発生する可能性があります。
このような問題を回避するため、常にモデル バージョンを指定してください。