AI_GENERATE_EMBEDDINGS(Transact-SQL)

対象者: SQL Server 2025 (17.x) Azure SQL Database SQL database in Microsoft Fabric

AI_GENERATE_EMBEDDINGS は、データベースに格納されている事前に作成された AI モデル定義を使用して埋め込み (ベクター配列) を作成する組み込み関数です。

構文

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:

データベースで sp_invoke_external_endpoint を有効にしてください。以下のコマンドで:
```
EXECUTE sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;
```
適切な付与、役割、権限を通じてアクセス可能なEMBEDDINGSタイプの外部モデルを作成します。

省略可能なパラメーター

optional_json_request_body_parameters内のパラメーター AI_GENERATE_EMBEDDINGSは、埋め込み要求メッセージの本文にエンドポイントパラメーターを追加する必要がある場合に使用されます。省略可能なパラメーターを追加すると、そのパラメーターがモデル定義で定義されている場合、実行時に値がオーバーライドされます。

例えば、外部モデルにdimensionsのパラメータが1536に設定されている場合、実行時にそのパラメータをoptional_json_request_body_parametersで新しい値で渡すことで、モデル上のdimensionsパラメータは上書きされます。(json_object("dimensions":755))

optional_json_request_body_parametersに渡される値は有効な JSON である必要があります。

埋め込みエンドポイントを作成する

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

拡張イベント (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_CHUNKS関数で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 関数を使用し、オプションのパラメーターをエンドポイントに渡す方法を示しています。これは、ベクター配列の結果を返します。

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

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

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

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

注

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

SELECT id,
       AI_GENERATE_EMBEDDINGS(large_text USE MODEL MyAzureOpenAIModel PARAMETERS TRY_CONVERT (JSON, N'{"retry_count":10}'))
FROM myTable;

F. チャンク、AI_GENERATE_EMBEDDINGS、モデルの作成を含む完全な例

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

CREATE EXTERNAL MODELを使って登録し、埋め込みモデルをアクセス可能にしてください。
データセットを AI_GENERATE_CHUNKSでより小さなチャンクに分割し、データがモデルのコンテキストウィンドウ内に収まり、検索精度を向上させます。
AI_GENERATE_EMBEDDINGSを使って埋め込みを生成します。
結果をベクターデータ型のテーブルに挿入します。

注

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

-- Enable the external REST endpoint invocation on the database server
EXECUTE sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;
GO

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

-- Create access credentials to Azure OpenAI using a key:
CREATE DATABASE SCOPED CREDENTIAL [https://my-azure-openai-endpoint.openai.azure.com/]
    WITH IDENTITY = 'HTTPEndpointHeaders', secret = '{"api-key":"YOUR_AZURE_OPENAI_KEY"}';
GO

-- Create an external model to call the Azure OpenAI embeddings REST endpoint
CREATE EXTERNAL MODEL MyAzureOpenAIModel
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.openai.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.openai.azure.com/]
);

-- Create a table with text to chunk and insert data
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 country 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 a new table to hold the chunked text and vector embeddings
CREATE TABLE text_embeddings
(
    embeddings_id INT IDENTITY (1, 1) PRIMARY KEY,
    chunked_text NVARCHAR (MAX),
    vector_embeddings VECTOR(1536)
);

-- Insert the chunked text and vector embeddings into the text_embeddings table using AI_GENERATE_CHUNKS and AI_GENERATE_EMBEDDINGS
INSERT INTO text_embeddings (chunked_text, vector_embeddings)
SELECT c.chunk, AI_GENERATE_EMBEDDINGS(c.chunk USE MODEL MyAzureOpenAIModel)
FROM textchunk t
CROSS APPLY
    AI_GENERATE_CHUNKS(source = t.text_to_chunk, chunk_type = FIXED, chunk_size = 100) c;

-- View the results
SELECT * FROM text_embeddings;

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-19