AI_GENERATE_EMBEDDINGS (Transact-SQL)

Si applica a: SQL Server 2025 (17.x) Azure SQL DatabaseSQL database in Microsoft Fabric

AI_GENERATE_EMBEDDINGS è una funzione predefinita che crea incorporamenti (matrici vettoriali) usando una definizione del modello di intelligenza artificiale precreata archiviata nel database.

Sintassi

Convenzioni relative alla sintassi Transact-SQL

AI_GENERATE_EMBEDDINGS ( source USE MODEL model_identifier [ PARAMETERS optional_json_request_body_parameters ] )

Argomenti

origine

Espressione di qualsiasi tipo di carattere, ad esempio nvarchar, varchar, nchar o char.

model_identifier

Il nome di un modello esterno definito come un EMBEDDINGS tipo utilizzato per creare l'array vettoriale di embedding.

Per altre informazioni, vedere CREATE EXTERNAL MODEL.

optional_json_request_body_parameters

Elenco di parametri aggiuntivi in formato JSON valido. Questi parametri vengono aggiunti al corpo del messaggio della richiesta REST prima di essere inviati alla posizione finale del modello esterno. Questi parametri dipendono da ciò che l'endpoint del modello esterno supporta e accetta.

Tipi restituiti

AI_GENERATE_EMBEDDINGS restituisce una tabella a colonna singola le cui righe sono le matrici di vettori di incorporamento generate restituite come JSON.

Formato restituito

Il formato del codice JSON restituito è il seguente:

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

Osservazioni:

Prerequisiti

Devi soddisfare i seguenti prerequisiti per utilizzare AI_GENERATE_EMBEDDINGS:

• Abilita sp_invoke_external_endpoint il database, con il seguente comando:

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

• Crea un modello esterno del EMBEDDINGS tipo, accessibile tramite i giusti finanziamenti, ruoli e/o permessi.

Parametri facoltativi

Il parametro optional_json_request_body_parameters in AI_GENERATE_EMBEDDINGS viene usato quando è necessario aggiungere un parametro endpoint al corpo del messaggio di richiesta di incorporamento. L'aggiunta di un parametro facoltativo sostituisce il valore in fase di esecuzione se tale parametro è definito nella definizione del modello.

Ad esempio, se il modello esterno contiene il parametro per dimensions impostato a 1536, passando quel parametro nel optional_json_request_body_parameters runtime con un nuovo valore come si vede qui: json_object("dimensions":755), il dimensions parametro sul modello viene sovrascritto.

Il valore passato in optional_json_request_body_parameters deve essere JSON valido.

Creare endpoint di incorporamento

Per maggiori informazioni sulla creazione di embedding endpoint, consulta il processo di Azure OpenAI in Azure AI Foundry Models, OpenAI o Ollama.

Eventi estesi (XEvent)

AI_GENERATE_EMBEDDINGS ha un evento esteso (ai_generate_embeddings_summary) che può essere abilitato per la risoluzione dei problemi. Contiene informazioni sulla richiesta e la risposta REST, come il codice di stato, eventuali errori riscontrati e il nome del modello utilizzato. L'evento external_rest_endpoint_summary esteso contiene informazioni aggiuntive che possono essere per la risoluzione dei problemi e il debug delle richieste REST.

Esempi

Un. Creare incorporamenti con un'istruzione SELECT

L'esempio seguente mostra come utilizzare la AI_GENERATE_EMBEDDINGS funzione con un'istruzione select che restituisce i risultati in un array JSON.

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

B. Creare incorporamenti con un'istruzione SELECT usando AI_GENERATE_CHUNKS

L'esempio seguente mostra come usare la AI_GENERATE_EMBEDDINGS funzione con la funzione AI_GENERATE_CHUNKS per passare testo suddiviso in dimensioni di chunk specificate con un'istruzione select che restituisce i risultati dell'array vettoriale.

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. Creare incorporamenti con un aggiornamento della tabella

Nell'esempio seguente viene illustrato come usare la AI_GENERATE_EMBEDDINGS funzione con un'istruzione di aggiornamento della tabella per restituire i risultati della matrice vettoriale in una colonna di tipo di dati vettoriale.

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

D. Creare incorporamenti con un'istruzione SELECT e PARAMETERS

Nell'esempio seguente viene illustrato come usare la AI_GENERATE_EMBEDDINGS funzione con un'istruzione select e passare parametri facoltativi all'endpoint, che restituisce i risultati della matrice vettoriale.

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

E. Generazione di ritenti degli embedding con retry_count opzione PARAMETERS

Se la chiamata incorporamenti rileva codici di stato HTTP che indicano problemi temporanei, è possibile configurare la richiesta per riprovare automaticamente.

Per specificare il numero di tentativi, aggiungi il seguente JSON all'opzione PARAMETERS . Questo valore dovrebbe essere un intero positivo compreso zero (0) e dieci (10) inclusi, e non può essere NULL.

Annotazioni

Se un retry_count valore viene specificato nella AI_GENERATE_EMBEDDINGS query, esso sovrascrive ( retry_count se definito) nella configurazione del modello esterno.

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

F. Esempio completo con suddivisione in blocchi, AI_GENERATE_EMBEDDINGS e creazione di modelli

Il seguente esempio dimostra un processo end-to-end per rendere i tuoi dati pronti per l'IA:

1. Usa CREA UN MODELLO ESTERNO per registrare e rendere accessibile il tuo modello di incorporamento.

2. Dividi il dataset in blocchi più piccoli con AI_GENERATE_CHUNKS, così i dati si adattano alla finestra contestuale del modello e migliora la precisione del recupero.

3. Generare embedding usando AI_GENERATE_EMBEDDINGS.

4. Inserire i risultati in una tabella con un tipo di dato vettoriale.

Annotazioni

Sostituire <password> con una password valida.

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

Contenuti correlati

• CREA UN MODELLO ESTERNO (Transact-SQL)
• ALTERARE IL MODELLO ESTERNO (Transact-SQL)
• DROP MODELLO ESTERNO (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL)
• sp_invoke_external_rest_endpoint
• Creare e distribuire una risorsa Azure OpenAI in Azure AI Foundry Models