チュートリアル: Azure Database for PostgreSQL と Azure OpenAI を使用してセマンティック検索を作成する

2025-06-27

適用対象: Azure Database for PostgreSQL - フレキシブルサーバー

このハンズオンチュートリアルでは、Azure Database for PostgreSQL と Azure OpenAI を使用してセマンティック検索アプリケーションを構築する方法について説明します。

セマンティック検索では、セマンティクスに基づいて検索されます。標準の字句検索では、クエリで指定されたキーワードに基づいて検索されます。たとえば、レシピデータセットに、グルテンフリー、ビーガン、乳製品フリー、フルーツフリー、デザートなどのラベルが含まれていない場合がありますが、これらの特性は成分から推測できます。基本となるのは、このようなセマンティッククエリを発行し、関連する検索結果を取得するという考え方です。

このチュートリアルでは、次の操作を行います。

検索シナリオと、検索に関連するデータフィールドを特定します。
検索に関係するすべてのデータフィールドについて、対応するベクターフィールドを作成して、データフィールドに格納されている値の埋め込みを格納します。
選択したデータフィールド内のデータの埋め込みを生成し、その埋め込みを対応するベクターフィールドに保存します。
入力検索クエリの埋め込みを生成します。
ベクトルデータフィールドを検索し、ニアレストネイバーを一覧表示します。
適切な関連性、ランク付け、パーソナル化モデルを使用して結果を実行し、最終的なランク付けを生成します。このようなモデルがない場合は、結果をドット積の降順でランク付けします。
モデル、結果の品質、およびクリックスルー率やドウェル時間などのビジネスメトリックを監視します。データの品質、データの鮮度、パーソナル化からユーザーエクスペリエンスまで、検索スタックをデバッグおよび改善するためのフィードバックメカニズムを組み込みます。

前提条件

OpenAI アカウントを作成し、 Azure OpenAI へのアクセスを要求します。
目的のサブスクリプションでの権利を Azure OpenAI に与えます。
Azure OpenAI リソースを作成し、モデルをデプロイするためのアクセス許可を付与します。
Azure OpenAI リソースとモデルを作成してデプロイします。埋め込みモデル text-embedding-ada-002 をデプロイします。埋め込みを作成する必要があるため、デプロイ名をコピーします。

azure_ai と pgvector の拡張機能を有効にする

Azure Database for PostgreSQL フレキシブルサーバーで azure_ai と pgvector を有効にするには、それらを許可リストに追加する必要があります。 SHOW azure.extensions;を実行して、それらが正しく追加されていることを確認します。

その後、ターゲットデータベースに接続し、 CREATE EXTENSION コマンドを実行して拡張機能をインストールできます。拡張機能を使用できるようにするデータベースごとに、コマンドを個別に繰り返す必要があります。

CREATE EXTENSION azure_ai;
CREATE EXTENSION vector;

OpenAI エンドポイントとキーを構成する

Azure AI サービスの [ リソース管理>キーとエンドポイント] で、Azure AI リソースのエンドポイントとキーを見つけることができます。エンドポイントといずれかのキーを使用して、 azure_ai 拡張機能でモデルデプロイを呼び出せるようにします。

select azure_ai.set_setting('azure_openai.endpoint','https://<endpoint>.openai.azure.com');
select azure_ai.set_setting('azure_openai.subscription_key', '<API Key>');

データをダウンロードする

Kaggle からデータをダウンロードします。

テーブルの作成

サーバーに接続し、 test データベースを作成します。そのデータベースで、次のコマンドを使用して、データをインポートするテーブルを作成します。

CREATE TABLE public.recipes(
    rid integer NOT NULL,
    recipe_name text,
    prep_time text,
    cook_time text,
    total_time text,
    servings integer,
    yield text,
    ingredients text,
    directions text,
    rating real,
    url text,
    cuisine_path text,
    nutrition text,
    timing text,
    img_src text,
    PRIMARY KEY (rid)
);

データをインポートする

エンコードを UTF-8 に設定するには、クライアントウィンドウで次の環境変数を設定します。この特定のデータセットは Windows-1252 エンコードを使用するため、この手順が必要です。

Rem on Windows
Set PGCLIENTENCODING=utf-8;

# on Unix based operating systems
export PGCLIENTENCODING=utf-8

作成したテーブルにデータをインポートします。このデータセットにはヘッダー行が含まれていることに注意してください。

psql -d <database> -h <host> -U <user> -c "\copy recipes FROM <local recipe data file> DELIMITER ',' CSV HEADER"

埋め込みを格納する列を追加する

埋め込み列をテーブルに追加します。

ALTER TABLE recipes ADD COLUMN embedding vector(1536);

埋め込みの生成

azure_ai拡張機能を使用して、データの埋め込みを生成します。次の例では、いくつかのフィールドをベクター化し、連結します。

WITH ro AS (
    SELECT ro.rid
    FROM
        recipes ro
    WHERE
        ro.embedding is null
        LIMIT 500
)
UPDATE
    recipes r
SET
    embedding = azure_openai.create_embeddings('text-embedding-ada-002', r.recipe_name||' '||r.cuisine_path||' '||r.ingredients||' '||r.nutrition||' '||r.directions)
FROM
    ro
WHERE
    r.rid = ro.rid;

処理する行がなくなったら、コマンドを繰り返します。

ヒント

LIMIT値で遊びます。値が大きいと、Azure OpenAI によって課される調整により、ステートメントが途中で失敗する可能性があります。ステートメントが失敗した場合は、少なくとも 1 分間待ってから、コマンドをもう一度実行します。

検索する

利便性のため、データベースに検索機能を作成します。

create function
    recipe_search(searchQuery text, numResults int)
returns table(
            recipeId int,
            recipe_name text,
            nutrition text,
            score real)
as $$
declare
    query_embedding vector(1536);
begin
    query_embedding := (azure_openai.create_embeddings('text-embedding-ada-002', searchQuery));
    return query
    select
        r.rid,
        r.recipe_name,
        r.nutrition,
        (r.embedding <=> query_embedding)::real as score
    from
        recipes r
    order by score asc limit numResults; -- cosine distance
end $$
language plpgsql;

次に、その関数を呼び出して検索します。

select recipeid, recipe_name, score from recipe_search('vegan recipes', 10);

結果を調べます。

 recipeid |                         recipe_name                          |   score
----------+--------------------------------------------------------------+------------
      829 | Avocado Toast (Vegan)                                        | 0.15672222
      836 | Vegetarian Tortilla Soup                                     | 0.17583494
      922 | Vegan Overnight Oats with Chia Seeds and Fruit               | 0.17668104
      600 | Spinach and Banana Power Smoothie                            |  0.1773768
      519 | Smokey Butternut Squash Soup                                 | 0.18031077
      604 | Vegan Banana Muffins                                         | 0.18287598
      832 | Kale, Quinoa, and Avocado Salad with Lemon Dijon Vinaigrette | 0.18368931
      617 | Hearty Breakfast Muffins                                     | 0.18737361
      946 | Chia Coconut Pudding with Coconut Milk                       |  0.1884186
      468 | Spicy Oven-Roasted Plums                                     | 0.18994217
(10 rows)