AI_GENERATE_EMBEDDINGS (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Azure SQL Database SQLdatabase in Microsoft Fabric

AI_GENERATE_EMBEDDINGS é uma função interna que cria inserções (matrizes de vetor) usando uma definição de modelo de IA pré-criada armazenada no banco de dados.

Sintaxe

Convenções de sintaxe de Transact-SQL

AI_GENERATE_EMBEDDINGS ( source USE MODEL model_identifier [ PARAMETERS optional_json_request_body_parameters ] )

Argumentos

origem

Uma expressão de qualquer tipo de caractere (por exemplo, nvarchar, varchar, nchar ou char).

model_identifier

O nome de um modelo externo definido como um EMBEDDINGS tipo usado para criar o array vetorial de embeddings.

Para obter mais informações, consulte CREATE EXTERNAL MODEL.

optional_json_request_body_parameters

Uma lista formatada em JSON válida de parâmetros adicionais. Esses parâmetros são adicionados ao corpo da mensagem da solicitação REST antes de serem enviados para a localização de endpoint do modelo externo. Esses parâmetros dependem do que o endpoint do modelo externo suporta e aceita.

Tipos de retorno

AI_GENERATE_EMBEDDINGS retorna uma tabela de coluna única cujas linhas são as matrizes de vetor de inserção geradas retornadas como JSON.

Formato de retorno

O formato do JSON retornado é o seguinte:

[
    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
]

Observações

Pré-requisitos

Você deve atender aos seguintes pré-requisitos para utilizar AI_GENERATE_EMBEDDINGS:

Ative sp_invoke_external_endpoint no banco de dados, com o seguinte comando:

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

Crie um modelo externo do EMBEDDINGS tipo, acessível por meio das bolsas, funções e/ou permissões corretas.

Parâmetros opcionais

O parâmetro optional_json_request_body_parameters é AI_GENERATE_EMBEDDINGS usado quando um parâmetro de ponto de extremidade precisa ser adicionado ao corpo da mensagem de solicitação de inserções. Adicionar um parâmetro opcional substituirá o valor em runtime se esse parâmetro for definido na definição do modelo.

Por exemplo, se o modelo externo contém o parâmetro para dimensions definido como 1536, ao passar esse parâmetro em optional_json_request_body_parameters tempo de execução com um novo valor como visto aqui: json_object("dimensions":755), o dimensions parâmetro no modelo é sobreposto.

O valor passado optional_json_request_body_parameters deve ser JSON válido.

Criar pontos de extremidade de inserção

Para mais informações sobre como criar endpoints de embedding, revise o processo para Azure OpenAI em Azure AI Foundry Models, OpenAI ou Ollama.

Eventos Estendidos (XEvent)

AI_GENERATE_EMBEDDINGS tem um evento estendido (ai_generate_embeddings_summary) que pode ser habilitado para solução de problemas. Ele contém informações sobre a solicitação e resposta REST, como código de status, quaisquer erros encontrados e o nome do modelo utilizado. O evento external_rest_endpoint_summary estendido contém informações adicionais que podem ser para solução de problemas e depuração de solicitações REST.

Exemplos

Um. Criar inserções com uma instrução SELECT

O exemplo a seguir mostra como usar a AI_GENERATE_EMBEDDINGS função com uma instrução select que retorna resultados em um array JSON.

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

B. Criar inserções com uma instrução SELECT usando AI_GENERATE_CHUNKS

O exemplo a seguir mostra como usar a AI_GENERATE_EMBEDDINGS função com a função AI_GENERATE_CHUNKS para passar texto dividido em tamanhos de blocos especificados com uma instrução select que retorna resultados do array vetorial.

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. Criar inserções com uma atualização de tabela

O exemplo a seguir mostra como usar a AI_GENERATE_EMBEDDINGS função com uma instrução de atualização de tabela para retornar os resultados da matriz de vetor em uma coluna de tipo de dados de vetor.

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

D. Criar inserções com uma instrução SELECT e PARÂMETROS

O exemplo a seguir mostra como usar a AI_GENERATE_EMBEDDINGS função com uma instrução select e passar parâmetros opcionais para o ponto de extremidade, que retorna os resultados da matriz de vetor.

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

E. Geração de embeddings de retentativa com `retry_count` opção PARAMETERS

Se a chamada de inserções encontrar códigos de status HTTP indicando problemas temporários, você poderá configurar a solicitação para tentar novamente automaticamente.

Para especificar o número de tentativas, adicione o JSON a seguir à PARAMETERS opção. Esse valor deve ser um inteiro positivo entre zero (0) e dez (10) inclusive, e não pode ser NULL.

Observação

Se um retry_count valor for especificado na AI_GENERATE_EMBEDDINGS consulta, ele substitui ( retry_count se definido) na configuração do modelo externo.

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

F. Um exemplo completo com criação de modelos, fragmentação e geração de embedding

Azure OpenAI API Key
Identidade Gerenciada

O exemplo a seguir demonstra um processo de ponta a ponta para deixar seus dados prontos para IA usando a Chave API do Azure OpenAI:

Use CRIAR MODELO EXTERNO para registrar e tornar seu modelo de incorporação acessível.
Divida o conjunto de dados em partes menores com AI_GENERATE_CHUNKS, para que os dados se encaixem na janela de contexto do modelo e melhorem a precisão da recuperação.
Gerar embeddings usando AI_GENERATE_EMBEDDINGS.
Insira os resultados em uma tabela com um tipo de dado vetorial.

Observação

Substitua <password> por uma senha válida.

Ative a invocação externa do endpoint REST no servidor de banco de dados:

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

Crie uma chave mestra de banco de dados:

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

Crie credenciais de acesso ao Azure OpenAI usando uma chave:

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

Crie um modelo externo para chamar o endpoint REST de embeddings do Azure OpenAI:

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/]
);

Crie uma tabela com texto para fragmentar e insira dados:

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

Crie uma nova tabela para armazenar o texto em blocos e as incorporações vetoriais:

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

Insira o texto em blocos e as incorporações vetoriais na tabela text_embeddings usando AI_GENERATE_CHUNKS e 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;

Exibir os resultados

SELECT *
FROM text_embeddings;

O exemplo a seguir demonstra um processo completo para deixar seus dados prontos para IA usando Identidade Gerenciada:

Ative a Identidade Gerenciada. Essa opção se aplica a implantações baseadas em SQL Server Azure Arc / Azure Virtual Machine (VM).
Use CRIAR MODELO EXTERNO com Azure OpenAI usando Identidade Gerenciada para registrar e tornar seu modelo de incorporação acessível usando Identidade Gerenciada.
Divida o conjunto de dados em partes menores com AI_GENERATE_CHUNKS, para que os dados se encaixem na janela de contexto do modelo e melhorem a precisão da recuperação.
Gerar embeddings usando AI_GENERATE_EMBEDDINGS.
Insira os resultados em uma tabela com um tipo de dado vetorial.

Observação

Substitua <password> por uma senha válida.

Ative a identidade gerenciada para autenticação:

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

Ative a invocação externa do endpoint REST no servidor de banco de dados:

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

Crie uma chave mestra de banco de dados:

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

Crie credenciais de acesso ao Azure OpenAI usando uma chave:

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

Crie um modelo externo para chamar o endpoint REST de embeddings do Azure OpenAI:

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/]
);

Crie uma tabela com texto para fragmentar e insira dados:

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

Crie uma nova tabela para armazenar o texto em blocos e as incorporações vetoriais:

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

Insira o texto em blocos e as incorporações vetoriais na tabela text_embeddings usando AI_GENERATE_CHUNKS e 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;

Veja os resultados:

SELECT *
FROM text_embeddings;

Comentários

Esta página foi útil?

Last updated on 2025-12-08

Compartilhar via

AI_GENERATE_EMBEDDINGS (Transact-SQL)

Sintaxe

Argumentos

origem

model_identifier

optional_json_request_body_parameters

Tipos de retorno

Formato de retorno

Observações

Pré-requisitos

Parâmetros opcionais

Criar pontos de extremidade de inserção

Eventos Estendidos (XEvent)

Exemplos

Um. Criar inserções com uma instrução SELECT

B. Criar inserções com uma instrução SELECT usando AI_GENERATE_CHUNKS

C. Criar inserções com uma atualização de tabela

D. Criar inserções com uma instrução SELECT e PARÂMETROS

E. Geração de embeddings de retentativa com retry_count opção PARAMETERS

F. Um exemplo completo com criação de modelos, fragmentação e geração de embedding

Conteúdo relacionado

Comentários

Recursos adicionais

E. Geração de embeddings de retentativa com `retry_count` opção PARAMETERS