AI_GENERATE_EMBEDDINGS（Transact-SQL）

适用于： SQL Server 2025 (17.x) Azure SQL 数据库 Azure SQL 托管实例 Microsoft Fabric 中的 SQL 数据库

该 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 在具有 Always-up-to-date更新策略的 Azure SQL 托管实例中可用。

先决条件

使用 AI_GENERATE_EMBEDDINGS时，请确保你满足以下先决条件：

在数据库中启用 sp_invoke_external_endpoint ，使用以下命令：
```
EXECUTE sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;
```
注释

在 Azure SQL 数据库和 Fabric 中的 SQL 数据库中，external rest endpoint enabled系统配置选项默认启用。

如需了解更多关于创建嵌入端点的信息，请查看 Azure OpenAI在Azure AI Foundry Models、 OpenAI或 Ollama中的流程。

创建该类型的外部模型EMBEDDINGS，通过正确的授权、角色和权限访问。

可选参数

当你需要在嵌入请求消息的正文中添加端点参数时，可以使用 optional_json_request_body_parameters 该 AI_GENERATE_EMBEDDINGS 参数。如果模型定义中包含该参数，添加可选参数在运行时会覆盖该值。

例如，如果外部模型包含设置为1,536的参数 dimensions ，你可以在运行时用新值传递该 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 语句的 AI_GENERATE_EMBEDDINGS 函数，返回结果为 JSON 数组。

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

B. 使用 AI_GENERATE_CHUNKS 使用 SELECT 语句创建嵌入内容

以下示例展示了如何使用 AI_GENERATE_EMBEDDINGSAI_GENERATE_CHUNKS 函数通过 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 语句结合使用，以将向量数组结果返回到向量数据类型列。

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

D. 使用 SELECT 语句和 PARAMETERS 创建嵌入内容

以下示例演示如何将 AI_GENERATE_EMBEDDINGS 函数与 select 语句一起使用，并将可选参数传递给返回向量数组结果的终结点。

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

E. 重试嵌入生成时的参数 `retry_count` 选项

如果嵌入调用遇到指示临时问题的 HTTP 状态代码，则可以将请求配置为自动重试。

要指定重试次数，可以在选项中 PARAMETERS 添加以下 JSON。该值应为零0（）和十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;

以下示例展示了通过使用 Azure OpenAI API Key 使数据具备 AI 的端到端流程：

使用创建外部模型注册你的嵌入模型并使其可访问。
将数据集拆分成更小的块， AI_GENERATE_CHUNKS，使数据符合模型的上下文窗口，提高检索准确性。
通过使用 AI_GENERATE_EMBEDDINGS生成嵌入。
将结果插入带有向量数据类型的表中。

注释

将 <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)
);

通过使用 AI_GENERATE_CHUNKS 和 AI_GENERATE_EMBEDDINGS将分块文本和向量嵌入插入到text_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;

以下示例展示了通过管理身份实现数据AI准备的端到端流程：

启用托管身份。该选项适用于SQL Server Azure Arc和Azure虚拟机（VM）部署。
使用Azure OpenAI的管理身份创建外部模型来注册你的嵌入模型，并通过管理身份使其可访问。
将数据集拆分成更小的块， AI_GENERATE_CHUNKS，使数据符合模型的上下文窗口，提高检索准确性。
通过使用 AI_GENERATE_EMBEDDINGS生成嵌入。
将结果插入带有向量数据类型的表中。

注释

用<password>替换。

启用托管身份以进行认证：

EXECUTE sp_configure 'allow server scoped db credentials', 1;
RECONFIGURE WITH OVERRIDE;