AI_GENERATE_EMBEDDINGS (Transact-SQL)

Van toepassing op: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL-database in Microsoft Fabric

De AI_GENERATE_EMBEDDINGS functie creëert embeddings (vectorarrays) door gebruik te maken van een vooraf gemaakte AI-modeldefinitie die in de database is opgeslagen.

Syntaxis

Transact-SQL syntaxis-conventies

AI_GENERATE_EMBEDDINGS ( source USE MODEL model_identifier [ PARAMETERS optional_json_request_body_parameters ] )

Argumenten

bron

Een uitdrukking van elk karaktertype, zoals nvarchar, varchar, nchar of char.

model_identifier

De naam van een extern model is gedefinieerd als een EMBEDDINGS type dat wordt gebruikt om de embeddingsvectorarray te maken.

Zie CREATE EXTERNAL MODEL voor meer informatie.

optional_json_request_body_parameters

Een geldige JSON-geformatteerde lijst met extra parameters. De functie voegt deze parameters toe aan het REST-verzoekbericht voordat het naar de eindpunt van het externe model wordt gestuurd. Deze parameters zijn afhankelijk van wat het externe model ondersteunt en accepteert.

Retourtypen

AI_GENERATE_EMBEDDINGS retourneert een tabel met één kolom waarvan de rijen de gegenereerde insluitingsvectormatrices zijn die als JSON worden geretourneerd.

Retourindeling

De indeling van de geretourneerde JSON is als volgt:

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

Opmerkingen

AI_GENERATE_EMBEDDINGSis beschikbaar in Azure SQL Managed Instance met het always-up-to-datumupdatebeleid.

Vereiste voorwaarden

Om te gebruiken AI_GENERATE_EMBEDDINGS, zorg ervoor dat je aan de volgende vereisten voldoet:

  • Schakel sp_invoke_external_endpoint in op de database, met het volgende commando:

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

    Opmerking

    Op Azure SQL Database en SQL Database in Fabric is de external rest endpoint enabled systeemconfiguratieoptie standaard ingeschakeld.

Voor meer informatie over het creëren van embedding-endpoints, bekijk het proces voor Azure OpenAI in Azure AI Foundry Models, OpenAI of Ollama.

  • Maak een extern model van dit EMBEDDINGS type, toegankelijk via de juiste subsidies, rollen en permissies.

Optionele parameters

Gebruik de optional_json_request_body_parameters parameter in AI_GENERATE_EMBEDDINGS wanneer je een eindpuntparameter moet toevoegen aan het hoofdgedeelte van het embeddings-verzoekbericht. Het toevoegen van een optionele parameter overschrijft de waarde tijdens runtime als de modeldefinitie die parameter bevat.

Als het externe model bijvoorbeeld de parameter voor dimensions op 1.536 zet, kun je die parameter optional_json_request_body_parameters tijdens runtime doorgeven met een nieuwe waarde.

In het volgende voorbeeld wordt de dimensions parameter voor het model overschreven:

json_object("dimensions":755)

De waarde waarin je doorgeeft optional_json_request_body_parameters moet geldige JSON zijn.

Uitgebreide gebeurtenissen (XEvent)

AI_GENERATE_EMBEDDINGS Heeft een uitgebreide gebeurtenis (ai_generate_embeddings_summary) die je kunt inschakelen voor probleemoplossing. Het bevat informatie over het REST-verzoek en de reactie, zoals statuscode, eventuele fouten die het tegenkwam en de gebruikte modelnaam. Het uitgebreide evenement external_rest_endpoint_summary bevat aanvullende informatie die kan helpen bij het oplossen van problemen en het debuggen van REST-verzoeken.

Voorbeelden

Eén. Insluitingen maken met een SELECT-instructie

Het volgende voorbeeld laat zien hoe je de AI_GENERATE_EMBEDDINGS functie gebruikt met een select-instructie die resultaten teruggeeft in een JSON-array.

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

B. Insluitingen maken met een SELECT-instructie met behulp van AI_GENERATE_CHUNKS

Het volgende voorbeeld laat zien hoe je de AI_GENERATE_EMBEDDINGS functie met de AI_GENERATE_CHUNKS-functie gebruikt om tekst te sturen die is opgesplitst in gespecificeerde chunk-groottes met een select-instructie die vectorarrayresultaten teruggeeft.

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. Insluitingen maken met een tabelupdate

In het volgende voorbeeld ziet u hoe u de AI_GENERATE_EMBEDDINGS functie gebruikt met een tabelupdate-instructie om de vectormatrixresultaten te retourneren in een kolom met vectorgegevenstypen.

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

D. Insluitingen maken met een SELECT-instructie en PARAMETERS

In het volgende voorbeeld ziet u hoe u de AI_GENERATE_EMBEDDINGS functie gebruikt met een select-instructie en optionele parameters doorgeeft aan het eindpunt, waarmee vectormatrixresultaten worden geretourneerd.

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

E. Generatie van embeddings opnieuw proberen met retry_count de optie PARAMETERS

Als de aanroep voor insluitingen HTTP-statuscodes aangeeft die tijdelijke problemen aangeven, kunt u de aanvraag configureren om het automatisch opnieuw te proberen.

Om het aantal herhalingen te specificeren, voeg je de volgende JSON toe aan de PARAMETERS optie. Deze waarde moet een positief geheel getal zijn tussen nul (0) en tien (10) inclusief, en kan niet .NULL

Opmerking

Als een retry_count waarde in de AI_GENERATE_EMBEDDINGS query wordt gespecificeerd, overschrijft deze de retry_count (indien gedefinieerd) waarde in de configuratie van het externe model.

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. Een volledig voorbeeld met modelcreatie, chunking en embedding-generatie

Het volgende voorbeeld demonstreert een end-to-end proces om je data AI-klaar te maken met behulp van Azure OpenAI API Key:

  1. Gebruik CREATE EXTERNAL MODEL om je embeddingmodel te registreren en toegankelijk te maken.

  2. Splits de dataset op in kleinere stukken met AI_GENERATE_CHUNKS, zodat de data binnen het contextvenster van het model past en de nauwkeurigheid van het ophalen verbetert.

  3. Genereer embeddings door gebruik te maken van AI_GENERATE_EMBEDDINGS.

  4. Voeg de resultaten in in een tabel met een vectordatatype.

Opmerking

Vervang <password> door een geldig wachtwoord.

Schakel de externe REST-endpoint-aanroep in op de databaseserver:

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

Maak een databasehoofdsleutel aan:

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

Maak toegangsgegevens aan voor Azure OpenAI met behulp van een sleutel:

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

Maak een extern model om het Azure OpenAI-embeddings REST-eindpunt aan te roepen:

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

Maak een tabel met tekst om data in te hakken en in te voegen:

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

Maak een nieuwe tabel aan om de gebrokene tekst en vector-embeddings op te slaan:

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

Voeg de gebrokene tekst en vector-embeddings in in de text_embeddings-tabel door gebruik te maken van AI_GENERATE_CHUNKS en 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;

De resultaten weergeven

SELECT *
FROM text_embeddings;

Verwante inhoud

  • Last updated on