AI_GENERATE_EMBEDDINGS(Transact-SQL)

適用対象: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceMicrosoft Fabric 内の SQL データベース

AI_GENERATE_EMBEDDINGS関数は、データベースに保存されたあらかじめ作成されたAIモデル定義を使って埋め込み(ベクトル配列)を作成します。

構文

Transact-SQL 構文表記規則

AI_GENERATE_EMBEDDINGS ( source USE MODEL model_identifier [ PARAMETERS optional_json_request_body_parameters ] )

論争

ソース

nvarchar、varchar、nchar、char など、任意の文字タイプの表現です。

model_identifier

埋め込みベクトル配列を作成するために使われるEMBEDDINGS型として定義された外部モデルの名前です。

詳細については、「 CREATE EXTERNAL MODEL」を参照してください。

optional_json_request_body_parameters

有効なJSON形式の追加パラメータリスト。 関数はこれらのパラメータをRESTリクエストメッセージボディに付加し、外部モデルのエンドポイント位置に送信します。 これらのパラメータは、外部モデルのエンドポイントが何を支持し受け入れるかに依存します。

戻り値の型

AI_GENERATE_EMBEDDINGS は、JSON として返される生成された埋め込みベクター配列である行を持つ単一列テーブルを返します。

戻り値の形式

返される JSON の形式は次のとおりです。

[
    0.0023929428,
    0.00034713413,
    -0.0023142276,
    -0.025654867,
    -0.011492423,
    0.0010358924,
    -0.014836246,
    0.0035484824,
    0.000045630233,
    -0.027581815,
    0.023816079,
    0.005012586,
    -0.027732948,
    -0.010088143,
    ...
    -0.014571763
]

注釈

AI_GENERATE_EMBEDDINGS は、 Always-up-to-date更新ポリシーを使用して Azure SQL Managed Instance で使用できます。

[前提条件]

AI_GENERATE_EMBEDDINGSを利用するには、以下の前提条件を満たすことを確認してください。

  • データベースで sp_invoke_external_endpoint を有効にしてください。以下のコマンドで:

    EXECUTE sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;

    注

    FabricのAzure SQL DatabaseおよびSQLデータベースでは、external rest endpoint enabledシステム設定オプションがデフォルトで有効になっています。

埋め込みエンドポイントの作成について詳しくは、 Azure AI Foundry Models、 OpenAI、または OllamaのAzure OpenAIのプロセスをご覧ください。

  • 適切な付与、役割、権限を通じてアクセス可能なEMBEDDINGSタイプの外部モデルを作成します。

省略可能なパラメーター

埋め込みリクエストメッセージの本文にエンドポイントパラメータを追加する必要があるときは、AI_GENERATE_EMBEDDINGSのoptional_json_request_body_parametersパラメータを使いましょう。 モデル定義にオプションパラメータが含まれている場合、実行時にその値を上書きします。

例えば、 外部モデル に dimensions のパラメータが1,536に設定されている場合、そのパラメータを実行時に新しい値で optional_json_request_body_parameters に渡すことができます。

次の例では、モデルの dimensions パラメーターがオーバーライドされています。

json_object("dimensions":755)

optional_json_request_body_parametersに渡す値は有効なJSONでなければなりません。

拡張イベント (XEvent)

AI_GENERATE_EMBEDDINGS トラブルシューティングのために有効にできる拡張イベント(ai_generate_embeddings_summary)があります。 このデータベースには、ステータスコード、発生したエラー、使用されたモデル名など、RESTリクエストおよびレスポンスに関する情報が含まれています。 拡張イベント external_rest_endpoint_summary には、トラブルシューティングやRESTリクエストのデバッグに役立つ追加情報が含まれています。

例示

Ａ。 SELECT ステートメントを使用して埋め込みを作成する

以下の例は、select文で結果をJSON配列に返すための AI_GENERATE_EMBEDDINGS 関数の使い方を示しています。

SELECT id,
       AI_GENERATE_EMBEDDINGS(large_text USE MODEL MyAzureOpenAIModel)
FROM myTable;

B. AI_GENERATE_CHUNKSを使用して SELECT ステートメントで埋め込みを作成する

以下の例は、AI_GENERATE_EMBEDDINGS関数で関数を使って、指定されたチャンクサイズで分割されたテキストをselect文で渡し、ベクトル配列の結果を返す方法を示しています。

SELECT id,
       title,
       large_text,
       AI_GENERATE_EMBEDDINGS(c.chunk_text USE MODEL MyAzureOpenAIModel)
FROM myTable
CROSS APPLY AI_GENERATE_CHUNKS (
    SOURCE = large_text,
    CHUNK_TYPE = FIXED,
    CHUNK_SIZE = 10
) AS c;

C. テーブルの更新を使用して埋め込みを作成する

次の例は、テーブル更新ステートメントで AI_GENERATE_EMBEDDINGS 関数を使用して、ベクター配列の結果をベクター データ型の列に返す方法を示しています。

UPDATE t
    SET myEmbeddings = AI_GENERATE_EMBEDDINGS(t.text USE MODEL MyAzureOpenAIModel)
FROM myTable AS t;

D. SELECT ステートメントと PARAMETERS を使用して埋め込みを作成する

次の例は、select ステートメントで AI_GENERATE_EMBEDDINGS 関数を使用し、オプションのパラメーターをエンドポイントに渡す方法を示しています。これは、ベクター配列の結果を返します。

DECLARE @params JSON = N'{"dimensions":768}'
SELECT id,
       AI_GENERATE_EMBEDDINGS(large_text USE MODEL MyAzureOpenAIModel PARAMETERS @params)
FROM myTable;

E. PARAMETERSオプションで埋め込み生成 retry_count 再試す

埋め込み呼び出しで一時的な問題を示す HTTP 状態コードが検出された場合は、要求を自動的に再試行するように構成できます。

再試行回数を指定するには、 PARAMETERS オプションに以下のJSONを追加してください。 この値は0(0)から10(10)までの正の整数であるべきで、 NULLにはなりません。

注

retry_countクエリでAI_GENERATE_EMBEDDINGS値が指定されている場合、外部モデルの設定で定義されている場合のretry_countが上書きされます。

DECLARE @params JSON = N'{"sql_rest_options":{"retry_count":10}} '
SELECT id,
       AI_GENERATE_EMBEDDINGS(large_text USE MODEL MyAzureOpenAIModel PARAMETERS @params)
FROM myTable;

F. モデル作成、チャンク生成、埋め込み生成を含む完全な例

以下の例は、Azure OpenAI API Keyを用いてデータをAI対応にするためのエンドツーエンドのプロセスを示しています。

  1. CREATE EXTERNAL MODELを使って埋め込みモデルを登録し、アクセス可能にしてください。

  2. データセットを AI_GENERATE_CHUNKSでより小さなチャンクに分割し、データがモデルのコンテキストウィンドウ内に収まり、検索精度を向上させます。

  3. AI_GENERATE_EMBEDDINGSを使って埋め込みを生成します。

  4. 結果を ベクターデータ型のテーブルに挿入します。

注

<password> を有効なパスワードに置き換えます。

データベースサーバー上で外部RESTエンドポイント呼び出しを有効にします:

EXECUTE sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;
GO

データベースマスターキーの作成:

IF NOT EXISTS (SELECT *
               FROM sys.symmetric_keys
               WHERE [name] = '##MS_DatabaseMasterKey##')
    BEGIN
        CREATE MASTER KEY ENCRYPTION BY PASSWORD = N'<password>';
    END
GO

Azure OpenAIへのアクセス資格は以下のキーを使って作成します:

CREATE DATABASE SCOPED CREDENTIAL [https://my-azure-openai-endpoint.cognitiveservices.azure.com/]
    WITH IDENTITY = 'HTTPEndpointHeaders', secret = '{"api-key":"YOUR_AZURE_OPENAI_KEY"}';
GO

Azure OpenAIの埋め込み用REST エンドポイントを呼び出す外部モデルを作成します:

CREATE EXTERNAL MODEL MyAzureOpenAIModel
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.cognitiveservices.azure.com/openai/deployments/text-embedding-ada-002/embeddings?api-version=2023-05-15',
      API_FORMAT = 'Azure OpenAI',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'text-embedding-ada-002',
      CREDENTIAL = [https://my-azure-openai-endpoint.cognitiveservices.azure.com/]
);

テキストからチャンク、データを挿入するテーブルを作成する:

CREATE TABLE textchunk
(
    text_id INT IDENTITY (1, 1) PRIMARY KEY,
    text_to_chunk NVARCHAR (MAX)
);
GO

INSERT INTO textchunk (text_to_chunk)
VALUES ('All day long we seemed to dawdle through a land which was full of beauty of every kind. Sometimes we saw little towns or castles on the top of steep hills such as we see in old missals; sometimes we ran by rivers and streams which seemed from the wide stony margin on each side of them to be subject to great floods.'),
       ('My Friend, Welcome to the Carpathians. I am anxiously expecting you. Sleep well to-night. At three to-morrow the diligence will start for Bukovina; a place on it is kept for you. At the Borgo Pass my carriage will await you and will bring you to me. I trust that your journey from London has been a happy one, and that you will enjoy your stay in my beautiful land. Your friend, DRACULA')
GO

チャンク化されたテキストとベクター埋め込みを保持するための新しいテーブルを作成します:

CREATE TABLE text_embeddings
(
    embeddings_id INT IDENTITY (1, 1) PRIMARY KEY,
    chunked_text NVARCHAR (MAX),
    vector_embeddings VECTOR(1536)
);

チャンクされたテキストとベクター埋め込みをtext_embeddingsテーブルに AI_GENERATE_CHUNKS と AI_GENERATE_EMBEDDINGSで挿入します:

INSERT INTO text_embeddings (chunked_text, vector_embeddings)
SELECT c.chunk,
       AI_GENERATE_EMBEDDINGS(c.chunk USE MODEL MyAzureOpenAIModel)
FROM textchunk AS t
CROSS APPLY AI_GENERATE_CHUNKS (
    SOURCE = t.text_to_chunk,
    CHUNK_TYPE = FIXED,
    CHUNK_SIZE = 100
) AS c;

結果の表示

SELECT *
FROM text_embeddings;

関連コンテンツ

  • Last updated on