AI_GENERATE_EMBEDDINGS (Transact-SQL)

Si applica a: SQL Server 2025 (17.x) Database SQL di AzureIstanza gestita di SQL di Azuredatabase SQL in Microsoft Fabric

La AI_GENERATE_EMBEDDINGS funzione crea embedding (array vettoriali) utilizzando una definizione predefinita del modello AI memorizzata 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

Un'espressione di qualsiasi tipo di carattere, come nvarchar, varchar, nchar o char.

model_identifier

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

Per altre informazioni, vedere CREATE EXTERNAL MODEL.

optional_json_request_body_parameters

Un elenco valido in formato JSON di parametri aggiuntivi. La funzione aggiunge questi parametri al corpo del messaggio della richiesta REST prima di inviarlo alla posizione endpoint 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:

AI_GENERATE_EMBEDDINGSè disponibile in Istanza gestita di SQL di Azure con i criteri di aggiornamentoalways-up-to-date.

Prerequisiti

Per utilizzare AI_GENERATE_EMBEDDINGS, assicurati di soddisfare i seguenti requisiti:

  • Abilita sp_invoke_external_endpoint il database, con il seguente comando:

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

    Annotazioni

    Su database SQL di Azure e SQL database in Fabric, l'opzione external rest endpoint enabled di configurazione di sistema è abilitata di default.

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

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

Parametri facoltativi

Usa il optional_json_request_body_parameters parametro in AI_GENERATE_EMBEDDINGS quando devi aggiungere un parametro endpoint al corpo del messaggio di richiesta di embedding. L'aggiunta di un parametro opzionale sovrascrive il valore a runtime se la definizione del modello include quel parametro.

Ad esempio, se il modello esterno contiene il parametro per dimensions impostato a 1.536, puoi passare quel parametro optional_json_request_body_parameters a runtime con un nuovo valore.

Nell'esempio seguente viene eseguito l'override dimensions del parametro nel modello:

json_object("dimensions":755)

Il valore in optional_json_request_body_parameters cui passi deve essere un JSON valido.

Eventi estesi (XEvent)

AI_GENERATE_EMBEDDINGS ha un evento esteso (ai_generate_embeddings_summary) che puoi abilitare per la risoluzione del problema. 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 aiutare nella risoluzione dei problemi e nel 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.

DECLARE @params JSON = N'{"dimensions":768}'
SELECT id,
       AI_GENERATE_EMBEDDINGS(large_text USE MODEL MyAzureOpenAIModel PARAMETERS @params)
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.

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. Un esempio completo con creazione di modelli, chunking e generazione di embedding

Il seguente esempio dimostra un processo end-to-end per rendere i tuoi dati pronti per l'IA utilizzando Azure OpenAI API Key:

  1. Usa CREA UN MODELLO ESTERNO per registrare il tuo modello di embedding e renderlo accessibile.

  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. Genera embeddings usando AI_GENERATE_EMBEDDINGS.

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

Annotazioni

Sostituire <password> con una password valida.

Abilita l'invocazione esterna dell'endpoint REST sul server database:

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

Crea una chiave maestra del database:

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

Crea credenziali di accesso ad Azure OpenAI usando una chiave:

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

Crea un modello esterno per chiamare l'endpoint REST degli embeddings di 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/]
);

Crea una tabella con testo da bloccare e inserire dati:

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

Crea una nuova tabella per contenere il testo a blocchi e gli embedding vettoriali:

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

Inserire il testo a blocchi e gli embedding vettoriali nella tabella 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;

Visualizzare i risultati

SELECT *
FROM text_embeddings;

Contenuti correlati

  • Last updated on