CREAR MODELO EXTERNO (Transact-SQL)

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

Crea un objeto de modelo externo que contiene la ubicación, el método de autenticación y el propósito de un punto de conexión de inferencia del modelo de IA.

Sintaxis

Convenciones de sintaxis de Transact-SQL

CREATE EXTERNAL MODEL external_model_object_name
[ AUTHORIZATION owner_name ]
WITH
  (   LOCATION = '<prefix>://<path>[:<port>]'
    , API_FORMAT = '<OpenAI, Azure OpenAI, etc>'
    , MODEL_TYPE = EMBEDDINGS
    , MODEL = 'text-embedding-model-name'
    [ , CREDENTIAL = <credential_name> ]
    [ , PARAMETERS = '{"valid":"JSON"}' ]
    [ , LOCAL_RUNTIME_PATH = 'path to the ONNX Runtime files' ]
  );

Argumentos

external_model_object_name

Especifica el nombre definido por el usuario para el modelo externo. El nombre debe ser único en la base de datos.

owner_name

Especifica el nombre del usuario o rol que posee el modelo externo. Si no especificas este argumento, el usuario actual se convierte en el propietario. Dependiendo de los permisos y roles, puede que necesites conceder permisos explícitos a los usuarios para usar modelos externos específicos.

UBICACIÓN

Proporciona el protocolo de conectividad y la ruta de acceso al punto de conexión de inferencia del modelo de IA.

API_FORMAT

Formato de mensaje de API para el proveedor de puntos de conexión de inferencia del modelo de IA.

Los valores aceptados son:

• Azure OpenAI
• OpenAI
• Ollama
• ONNX Runtime

TIPO_DE_MODELO

El tipo de modelo accedido desde la ubicación del endpoint de inferencia del modelo de IA.

Los valores aceptados son:

• EMBEDDINGS

MODELO

Modelo específico hospedado por el proveedor de IA. Por ejemplo, text-embedding-ada-002, text-embedding-3-large o o3-mini.

CREDENCIAL

Especifica el DATABASE SCOPED CREDENTIAL objeto utilizado con el endpoint de inferencia del modelo de IA. Para más información sobre los tipos de credenciales aceptados y las normas de nombre, consulte sp_invoke_external_rest_endpoint o la sección de Comentarios de este artículo.

PARÁMETROS

Una cadena JSON válida que contiene parámetros de ejecución para añadir al mensaje de solicitud de endpoint de inferencia del modelo de IA. Por ejemplo:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH especifica el directorio en la instancia local de SQL Server donde se encuentran los ejecutables de tiempo de ejecución ONNX.

Permisos

Creación y modificación de modelos externos

Requiere ALTER ANY EXTERNAL MODEL o CREATE EXTERNAL MODEL permiso de base de datos.

Por ejemplo:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

O:

GRANT ALTER ANY EXTERNAL MODEL TO [<PRINCIPAL>];

Concesiones de modelos externos

Para usar un modelo externo en una función de IA, se le debe conceder a una entidad de seguridad la capacidad de EXECUTE hacerlo.

Por ejemplo:

GRANT EXECUTE ON EXTERNAL MODEL::MODEL_NAME TO [<PRINCIPAL>];
GO

Número de reintentos

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 reintentos, agregue el siguiente código JSON a PARAMETERS en en .EXTERNAL MODEL <number_of_retries> debe ser un número entero entre cero (0) y diez (10), ambos inclusive, y no puede ser NULL o negativo.

{ "sql_rest_options": { "retry_count": <number_of_retries> } }

Por ejemplo, para establecer el retry_count a 3, usa la siguiente cadena JSON:

{ "sql_rest_options": { "retry_count": 3 } }

Recuento de reintentos con otros parámetros

Puedes combinar el conteo de intentos con otros parámetros siempre que la cadena JSON sea válida.

{ "dimensions": 725, "sql_rest_options": { "retry_count": 5 } }

Observaciones

HTTPS y TLS

Para el LOCATION parámetro, solo se soportan endpoints de inferencia de modelos de IA configurados para usar HTTPS con el protocolo de cifrado TLS.

Formatos de API aceptados y tipos de modelo

Las siguientes secciones describen los formatos de API aceptados para cada MODEL_TYPEarchivo .

API_FORMAT para EMBEDDINGS

Esta tabla describe los formatos de API y las estructuras de endpoints URL para el EMBEDDINGS tipo de modelo. Para ver estructuras de carga específicas, use el vínculo en la columna Formato de API.

Formato de API	Formato de ruta de acceso de ubicación
Azure OpenAI	https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI	https://{server_name}/v1/embeddings
Ollama	https://localhost:{port}/api/embed

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

Para obtener más información sobre cómo crear puntos de conexión de inserción, use estos vínculos para el proveedor de puntos de conexión de inferencia del modelo de IA adecuado:

• Modelos de Azure OpenAI en Azure AI Foundry
• OpenAI
• Ollama

Reglas de nombre de credenciales para modelos externos

El modelo creado DATABASE SCOPED CREDENTIAL que utiliza un modelo externo debe seguir estas reglas:

• Debe ser una dirección URL válida.

• El dominio URL debe ser uno de los dominios incluidos en la lista de permisos.

• La dirección URL no debe contener una cadena de consulta.

• El protocolo + nombre de dominio completo (FQDN) de la dirección URL llamada debe coincidir con el protocolo + FQDN del nombre de credencial.

• Cada parte de la ruta URL llamada debe coincidir completamente con la parte correspondiente de la ruta URL en el nombre de la credencial.

• La credencial debe apuntar a una ruta más genérica que la URL de la solicitud. Por ejemplo, una credencial creada para path https://northwind.azurewebsite.net/customers no puede usarse para la URL https://northwind.azurewebsite.net.

Reglas de intercalación y nombre de credencial

La sección 6.2.2.1 del RFC 3986 establece que "Cuando un URI utiliza componentes de la sintaxis genérica, siempre se aplican las reglas de equivalencia de la sintaxis de componentes; es decir, que el esquema y el anfitrión no distinguen mayúsculas y minúsculas." La Sección 2.7.3 de la RFC 7230 menciona que "todas las demás se comparan de manera sensible a mayúsculas y mayúsculas."

Dado que una regla de clasificación se establece a nivel de base de datos, se aplica la siguiente lógica para mantener la coherencia de la regla de clasificación de la base de datos y las reglas RFC. (La regla descrita podría ser potencialmente más restrictiva que las reglas RFC, por ejemplo, si la base de datos está configurada para usar una clasificación sensible a mayúsculas y minúsculas.)

1. Compruebe si la dirección URL y la credencial coinciden con la RFC, lo que significa:

   • Compruebe el esquema y el host mediante una intercalación que no distingue mayúsculas de minúsculas (Latin1_General_100_CI_AS_KS_WS_SC)
   • Compruebe que todos los demás segmentos de la dirección URL se comparan en una intercalación que distingue mayúsculas de minúsculas (Latin1_General_100_BIN2)

2. Compruebe que la dirección URL y las credenciales coinciden con las reglas de intercalación de base de datos (y sin realizar ninguna codificación de direcciones URL).

Identidad administrada

Para usar la identidad gestionada del host Arc/VM como credencial a nivel de base de datos en SQL Server 2025 (17.x), debes habilitar la opción usando sp_configure con un usuario que tenga el permiso a nivel de servidor ALTER SETTINGS.

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

SCHEMABINDING

Las vistas creadas con SCHEMABINDING eso hacen referencia a un modelo externo (como una SELECT sentencia que usa AI_GENERATE_EMBEDDINGS) no pueden ser eliminadas, y el Motor de Base de Datos genera un error. Para eliminar dependencias que hacen referencia a un modelo externo, primero debes modificar o eliminar la definición de vista.

Vista de catálogo

Puedes ver los metadatos externos del modelo consultando la vista de catálogo sys.external_models . Debes tener acceso a un modelo para ver sus metadatos.

SELECT *
FROM sys.external_models;

Ejemplos con puntos de conexión remotos

Creación de un MODELO EXTERNO con Azure OpenAI mediante identidad administrada

Este ejemplo crea un modelo externo del EMBEDDINGS tipo usando Azure OpenAI y utiliza Identidad Gestionada para la autenticación.

En SQL Server 2025 (17.x) y versiones posteriores, debes conectar tu SQL Server a Azure Arc y habilitar la identidad gestionada principal.

Importante

Si utilizas Identidad Gestionada con Azure OpenAI y SQL Server 2025 (17.x), el rol de Contributor OpenAI de Servicios Cognitivos debe concederse a la identidad gestionada asignada por el sistema de SQL Server habilitada por Azure Arc. Para más información, consulte Control de acceso basado en roles para Azure OpenAI en Azure AI Foundry Models.

Crear credenciales de acceso a Azure OpenAI usando una identidad gestionada:

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

Crea el modelo externo:

CREATE EXTERNAL MODEL MyAzureOpenAIModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.cognitiveservices.azure.com/openai/deployments/text-embedding-ada-002/embeddings?api-version=2024-02-01',
      API_FORMAT = 'Azure OpenAI',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'text-embedding-ada-002',
      CREDENTIAL = [https://my-azure-openai-endpoint.cognitiveservices.azure.com/]
);

Crea un modelo externo con Azure OpenAI usando claves y parámetros de API

Este ejemplo crea un modelo externo del EMBEDDINGS tipo usando Azure OpenAI y utiliza claves API para la autenticación. En el ejemplo también se usa PARAMETERS para establecer el parámetro de dimensiones en el punto de conexión en 725.

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

Crea el modelo externo:

CREATE EXTERNAL MODEL MyAzureOpenAIModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.cognitiveservices.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-02-01',
      API_FORMAT = 'Azure OpenAI',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'text-embedding-3-small',
      CREDENTIAL = [https://my-azure-openai-endpoint.cognitiveservices.azure.com/],
      PARAMETERS = '{"dimensions":725}'
);

Crear un MODELO EXTERNO con Ollama y un propietario explícito

Este ejemplo crea un modelo externo del EMBEDDINGS tipo usando Ollama alojado localmente para fines de desarrollo.

CREATE EXTERNAL MODEL MyOllamaModel
AUTHORIZATION AI_User
WITH (
      LOCATION = 'https://localhost:11435/api/embed',
      API_FORMAT = 'Ollama',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'all-minilm'
);

Creación de un MODELO EXTERNO con OpenAI

Este ejemplo crea un modelo externo del EMBEDDINGS tipo utilizando las credenciales basadas en encabezados de OpenAI API_FORMAT y HTTP para la autenticación.

-- Create access credentials
CREATE DATABASE SCOPED CREDENTIAL [https://openai.com]
WITH IDENTITY = 'HTTPEndpointHeaders', secret = '{"Bearer":"YOUR_OPENAI_KEY"}';
GO

-- Create the external model
CREATE EXTERNAL MODEL MyAzureOpenAIModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://api.openai.com/v1/embeddings',
      API_FORMAT = 'OpenAI',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'text-embedding-ada-002',
      CREDENTIAL = [https://openai.com]
);

Ejemplo con ONNX Runtime ejecutándose localmente

ONNX Runtime es un motor de inferencia de código abierto que permite ejecutar modelos de aprendizaje automático localmente, lo que lo convierte en ideal para integrar funcionalidades de inteligencia artificial en entornos de SQL Server.

Este ejemplo te guía para configurar SQL Server 2025 (17.x) con ONNX Runtime para habilitar la generación local de incrustación de texto impulsada por IA. Solo se aplica en Windows.

Importante

Esta característica requiere que SQL Server Machine Learning Services esté instalado.

Paso 1: Habilitación de las características de la versión preliminar para desarrolladores en SQL Server 2025

Ejecuta el siguiente comando Transact-SQL (T-SQL) para habilitar funciones de vista previa de SQL Server 2025 (17.x) en la base de datos que quieras usar para este ejemplo:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Paso 2: Habilitación del entorno de ejecución de inteligencia artificial local en SQL Server 2025

Activa los entornos de ejecución de IA externos ejecutando la siguiente consulta T-SQL:

EXECUTE sp_configure 'external AI runtimes enabled', 1;
RECONFIGURE WITH OVERRIDE;

Paso 3: Configurar la biblioteca de tiempo de ejecución ONNX

Crea un directorio en la instancia de SQL Server para almacenar los archivos de la biblioteca en tiempo de ejecución ONNX. En este ejemplo, C:\onnx_runtime se usa .

Puede usar los siguientes comandos para crear el directorio:

cd C:\
mkdir onnx_runtime

Después, descarga una versión de ONNX Runtime (1.19 o superior) que sea adecuada para tu sistema operativo. Después de descomprimir la descarga, copie ( onnxruntime.dll ubicado en el directorio lib) en el C:\onnx_runtime directorio que se creó.

Paso 4: Configuración de la biblioteca de tokenización

Descargue y compile la tokenizers-cpp biblioteca desde GitHub. Una vez creado el archivo DLL, coloque el tokenizador en el C:\onnx_runtime directorio .

Nota:

Asegúrese de que el archivo DLL creado se denomina tokenizers_cpp.dll

Paso 5: Descargar el modelo ONNX

Empiece por crear el model directorio en C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

En este ejemplo se usa el all-MiniLM-L6-v2-onnx modelo, que se puede descargar de Hugging Face.

Clone el repositorio en el C:\onnx_runtime\model directorio con el siguiente comando de Git :

Si no está instalado, puede descargar Git desde el siguiente vínculo de descarga o a través de winget (winget install Microsoft.Git)

cd C:\onnx_runtime\model
git clone https://huggingface.co/nsense/all-MiniLM-L6-v2-onnx

Paso 6: Establecer permisos de directorio

Utiliza el siguiente script de PowerShell para proporcionar al usuario de MSSQLLaunchpad acceso al directorio de tiempo de ejecución ONNX:

$AIExtPath = "C:\onnx_runtime";
$Acl = Get-Acl -Path $AIExtPath
$AccessRule = New-Object System.Security.AccessControl.FileSystemAccessRule("MSSQLLaunchpad", "FullControl", "ContainerInherit,ObjectInherit", "None","Allow")
$Acl.AddAccessRule($AccessRule)
Set-Acl -Path $AIExtPath -AclObject $Acl

Paso 7: Crear el modelo externo

Ejecuta la siguiente consulta para registrar tu modelo ONNX como objeto de modelo externo:

El valor 'PARAMETERS' utilizado aquí es un marcador de posición necesario para SQL Server 2025 (17.x).

CREATE EXTERNAL MODEL myLocalOnnxModel
WITH (
    LOCATION = 'C:\onnx_runtime\model\all-MiniLM-L6-v2-onnx',
    API_FORMAT = 'ONNX Runtime',
    MODEL_TYPE = EMBEDDINGS,
    MODEL = 'allMiniLM',
    PARAMETERS = '{"valid":"JSON"}',
    LOCAL_RUNTIME_PATH = 'C:\onnx_runtime\'
);

• LOCATION debe apuntar al directorio que contiene model.onnx y tokenizer.json archivos.
• LOCAL_RUNTIME_PATH debe apuntar a directorio que contiene onnxruntime.dll y tokenizer_cpp.dll archivos.

Paso 8: Generar incrustaciones

Utiliza la ai_generate_embeddings función para probar el modelo ejecutando la siguiente consulta:

SELECT AI_GENERATE_EMBEDDINGS(N'Test Text' USE MODEL myLocalOnnxModel);

Este comando inicia AIRuntimeHost, carga los archivos DLL necesarios y procesa el texto de entrada.

El resultado de la consulta anterior es un array de incrustaciones:

[0.320098,0.568766,0.154386,0.205526,-0.027379,-0.149689,-0.022946,-0.385856,-0.039183...]

Activar el registro del sistema XEvent

Ejecuta la siguiente consulta para habilitar el registro del sistema y la resolución de problemas.

CREATE EVENT SESSION newevt
ON SERVER
ADD EVENT ai_generate_embeddings_airuntime_trace
(
    ACTION (sqlserver.sql_text, sqlserver.session_id)
)
ADD TARGET package0.ring_buffer
WITH (MAX_MEMORY = 4096 KB, EVENT_RETENTION_MODE = ALLOW_SINGLE_EVENT_LOSS, MAX_DISPATCH_LATENCY = 30 SECONDS, TRACK_CAUSALITY = ON, STARTUP_STATE = OFF);
GO

ALTER EVENT SESSION newevt ON SERVER STATE = START;
GO

A continuación, utiliza esta consulta y consulta los registros del sistema capturados:

SELECT event_data.value('(@name)[1]', 'varchar(100)') AS event_name,
       event_data.value('(@timestamp)[1]', 'datetime2') AS [timestamp],
       event_data.value('(data[@name = "model_name"]/value)[1]', 'nvarchar(200)') AS model_name,
       event_data.value('(data[@name = "phase_name"]/value)[1]', 'nvarchar(100)') AS phase,
       event_data.value('(data[@name = "message"]/value)[1]', 'nvarchar(max)') AS message,
       event_data.value('(data[@name = "request_id"]/value)[1]', 'nvarchar(max)') AS session_id,
       event_data.value('(data[@name = "error_code"]/value)[1]', 'bigint') AS error_code
FROM (SELECT CAST (target_data AS XML) AS target_data
      FROM sys.dm_xe_sessions AS s
           INNER JOIN sys.dm_xe_session_targets AS t
               ON s.address = t.event_session_address
      WHERE s.name = 'newevt'
            AND t.target_name = 'ring_buffer') AS data
CROSS APPLY target_data.nodes('//RingBufferTarget/event') AS XEvent(event_data);

Limpieza

Para eliminar el objeto modelo externo, ejecuta la siguiente sentencia T-SQL:

DROP EXTERNAL MODEL myLocalOnnxModel;

Para quitar los permisos de directorio, ejecute los siguientes comandos de PowerShell:

$Acl.RemoveAccessRule($AccessRule)
Set-Acl -Path $AIExtPath -AclObject $Acl

Por último, elimine el C:/onnx_runtime directorio.

Contenido relacionado

• ALTERAR MODELO EXTERNO (Transact-SQL)
• DESCARTAR MODELO EXTERNO (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL)
• sys.external_models
• Creación e implementación de un recurso de Azure OpenAI en Azure AI Foundry Models
• Opciones de configuración del servidor
• Control de acceso basado en rol para Azure OpenAI en modelos de Azure AI Foundry