Compartir a través de

AI_GENERATE_EMBEDDINGS (Transact-SQL)

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

AI_GENERATE_EMBEDDINGS es una función integrada que crea incrustaciones (matrices vectoriales) mediante una definición de modelo de IA creada previamente almacenada en la base de datos.

Sintaxis

Convenciones de sintaxis de Transact-SQL

AI_GENERATE_EMBEDDINGS ( source USE MODEL model_identifier [ PARAMETERS optional_json_request_body_parameters ] )

Argumentos

de origen

Expresión de cualquier tipo de carácter (por ejemplo, nvarchar, varchar, nchar o char).

model_identifier

El nombre de un modelo externo definido como un EMBEDDINGS tipo que se utiliza para crear el array vectorial de embeddings.

Para obtener más información, vea CREATE EXTERNAL MODEL.

optional_json_request_body_parameters

Una lista con formato JSON válida de parámetros adicionales. Estos parámetros se añaden al cuerpo del mensaje de solicitud REST antes de enviarse a la ubicación final del modelo externo. Estos parámetros dependen de lo que soporte y acepte el endpoint del modelo externo.

Tipos de retorno

AI_GENERATE_EMBEDDINGS devuelve una tabla de una sola columna cuyas filas son las matrices de vectores de inserción generadas que se devuelven como JSON.

Formato de devolución

El formato del JSON devuelto es el siguiente:

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

Observaciones

Prerrequisitos

Debes cumplir los siguientes requisitos para poder utilizar AI_GENERATE_EMBEDDINGS:

  • Activa sp_invoke_external_endpoint la base de datos con el siguiente comando:

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

  • Crea un modelo externo del EMBEDDINGS tipo, accesible mediante las subvenciones, roles y/o permisos adecuados.

Parámetros opcionales

El parámetro optional_json_request_body_parameters de AI_GENERATE_EMBEDDINGS se usa cuando es necesario agregar un parámetro de punto de conexión al cuerpo del mensaje de solicitud de inserción. Al agregar un parámetro opcional, se invalida el valor en tiempo de ejecución si ese parámetro se define en la definición del modelo.

Por ejemplo, si el modelo externo contiene el parámetro para dimensions fijado en 1536, al pasar ese parámetro en optional_json_request_body_parameters el tiempo de ejecución con un nuevo valor como se ve aquí: json_object("dimensions":755), el dimensions parámetro en el modelo se sobrescribe.

El valor pasado a optional_json_request_body_parameters debe ser JSON válido.

Creación de puntos de conexión de inserción

Para más información sobre cómo crear endpoints de embebida, revisa el proceso para Azure OpenAI en Azure AI Foundry Models, OpenAI u Ollama.

Eventos extendidos (XEvent)

AI_GENERATE_EMBEDDINGS tiene un evento extendido (ai_generate_embeddings_summary) que se puede habilitar para solucionar problemas. Contiene información sobre la solicitud y respuesta REST, como el código de estado, cualquier error que haya encontrado y el nombre del modelo utilizado. El evento external_rest_endpoint_summary extendido contiene información adicional que puede ser para solucionar problemas y depurar solicitudes REST.

Ejemplos

Un. Creación de incrustaciones con una instrucción SELECT

El siguiente ejemplo muestra cómo usar la AI_GENERATE_EMBEDDINGS función con una sentencia select que devuelve resultados en un array JSON.

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

B. Creación de incrustaciones con una instrucción SELECT mediante AI_GENERATE_CHUNKS

El siguiente ejemplo muestra cómo usar la AI_GENERATE_EMBEDDINGS función con la función AI_GENERATE_CHUNKS para pasar texto dividido en tamaños de fragmento especificados con una sentencia select que devuelve los resultados de un array vectorial.

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. Creación de incrustaciones con una actualización de tabla

En el ejemplo siguiente se muestra cómo usar la AI_GENERATE_EMBEDDINGS función con una instrucción de actualización de tabla para devolver los resultados de la matriz vectorial en una columna de tipo de datos vectorial.

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

D. Crear incrustaciones con una instrucción SELECT y PARAMETERS

En el ejemplo siguiente se muestra cómo usar la AI_GENERATE_EMBEDDINGS función con una instrucción select y pasar parámetros opcionales al punto de conexión, que devuelve los resultados de la matriz vectorial.

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

E. Generación de embedos de reintentos con retry_count opción PARÁMETROS

Si la llamada de inserción encuentra códigos de estado HTTP que indican problemas temporales, puede configurar la solicitud para volver a intentarlo automáticamente.

Para especificar el número de intentos, añade el siguiente JSON a la PARAMETERS opción. Este valor debe ser un entero positivo entre cero (0) y diez (10) inclusive, y no puede ser NULL.

Nota:

Si se especifica un retry_count valor en la AI_GENERATE_EMBEDDINGS consulta, anula el retry_count (si está definido) en la configuración del modelo externo.

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

F. Un ejemplo completo con creación de modelos, fragmentación y generación de incrustaciones

El siguiente ejemplo demuestra un proceso de extremo a extremo para hacer que tus datos estén listos para IA usando Azure OpenAI API Key:

  1. Utiliza CREAR MODELO EXTERNO para registrar y hacer accesible tu modelo de incrustación.

  2. Divide el conjunto de datos en partes más pequeñas con AI_GENERATE_CHUNKS, para que los datos encajen dentro de la ventana contextual del modelo y mejore la precisión de la recuperación.

  3. Genera incrustaciones usando AI_GENERATE_EMBEDDINGS.

  4. Inserta los resultados en una tabla con un tipo de dato vectorial.

Nota:

Reemplace <password> por una contraseña válida.

Activa la invocación externa del endpoint REST en el servidor de base de datos:

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

Crea una clave maestra de base de datos:

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

Crear credenciales de acceso a Azure OpenAI usando una clave:

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

Crear un modelo externo para llamar al endpoint REST de embeddings de 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 tabla con texto para fragmentar e insertar datos:

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 nueva tabla para contener el texto fragmentado y las incrustaciones vectoriales:

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

Inserta el texto fragmentado y las incrustaciones vectoriales en la tabla de text_embeddings usando AI_GENERATE_CHUNKS y 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;

Visualización de los resultados

SELECT *
FROM text_embeddings;

Contenido relacionado

  • Last updated on