Compartir a través de

CREATE EXTERNAL MODEL (Transact-SQL)

Se aplica a: VERSIÓN PRELIMINAR de SQL Server 2025 (17.x)

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-ada-002'
    [ , CREDENTIAL = <credential_name> ]
    [ , PARAMETERS = '{"valid":"JSON"}' ]
  );

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 se especifica, la propiedad se asigna al usuario actual. En función de los permisos y roles, es necesario 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

TIPO_DE_MODELO

Tipo de modelo al que se accede desde la ubicación del punto de conexión 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

Indique qué DATABASE SCOPED CREDENTIAL objeto se usa con el punto de conexión de inferencia del modelo de IA. Puede encontrar más información sobre los tipos de credenciales aceptados y las reglas de nomenclatura en sp_invoke_external_rest_endpoint o en la sección Comentarios de este artículo.

PARÁMETROS

Cadena JSON válida que contiene parámetros en tiempo de ejecución que se van a anexar al mensaje de solicitud del punto de conexión de inferencia del modelo de IA. Por ejemplo:

'{ "Dimensions": 1536 }'

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 en retry_count 3, escribiría la siguiente cadena JSON:

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

Recuento de reintentos con otros parámetros

El recuento de reintentos también se puede combinar con otros parámetros siempre que sea una cadena JSON válida.

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

Observaciones

HTTPS y TLS

Solo se admiten los puntos de conexión de inferencia del modelo de IA configurados para usar HTTPS con el protocolo de cifrado TLS para el LOCATION parámetro .

Formatos de API aceptados y tipos de modelo

En las secciones siguientes se describen los formatos de API aceptados para cada MODEL_TYPE.

API_FORMAT para EMBEDDINGS

En esta tabla se describen las estructuras de puntos de conexión de DIRECCIÓN URL y formatos de API para el tipo de EMBEDDINGS 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:

Reglas de nombre de credencial para EXTERNAL MODEL

El objeto creado usado DATABASE SCOPED CREDENTIAL por debe EXTERNAL MODEL cumplir las reglas siguientes específicas:

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

  • El dominio de dirección URL debe ser uno de esos dominios incluidos en la lista de permitidos.

  • 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 de acceso url llamada debe coincidir completamente con la parte correspondiente de la ruta de acceso de dirección URL en el nombre de credencial.

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

Reglas de intercalación y nombre de credencial

RFC 3986 Sección 6.2.2.1 indica que "Cuando un URI usa componentes de la sintaxis genérica, las reglas de equivalencia de sintaxis de componentes siempre se aplican; es decir, que el esquema y el host no distinguen mayúsculas de minúsculas", y el RFC 7230 sección 2.7.3 menciona que "todos los demás se comparan de manera que distingue mayúsculas de minúsculas".

Como hay un conjunto de reglas de intercalación en el nivel de base de datos, se aplica la siguiente lógica, para ser coherente con la regla de intercalación de la base de datos y la RFC mencionada anteriormente. (La regla descrita podría ser más restrictiva que las reglas RFC, por ejemplo, si la base de datos está establecida para usar una intercalación que distingue mayúsculas de 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 administrada para la autenticación en SQL Server 2025, debe habilitar la opción con sp_configure un usuario al que se concede el permiso de nivel de servidor ALTER SETTINGS.

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

SCHEMABINDING

Quitar vistas creadas con SCHEMABINDING y hacer referencia a una EXTERNAL MODEL instrucción (como una SELECT instrucción mediante AI_GENERATE_EMBEDDINGS) se impide con el motor de base de datos que genera un error. La propia definición de vista debe modificarse o quitarse primero para quitar dependencias que hacen referencia a .EXTERNAL MODEL

Vista de catálogo

Los metadatos del modelo externo se ven consultando la vista de sys.external_models catálogo. Tenga en cuenta que debe tener acceso a un modelo para poder ver los metadatos.

SELECT * FROM sys.external_models;

Ejemplos

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

En este ejemplo se crea un EXTERNAL MODEL de tipo EMBEDDINGS mediante Azure OpenAI y se usa la identidad administrada para la autenticación.

Importante

Si usa identidad administrada con Azure OpenAI y SQL Server 2025, el rol Colaborador de OpenAI de Cognitive Services debe concederse a la identidad administrada asignada por el sistema de SQL Server habilitada por Azure Arc. Para más información, consulte Control de acceso basado en rol para Azure OpenAI en modelos de Azure AI Foundry.

-- Create access credentials to Azure OpenAI using a managed identity:
CREATE DATABASE SCOPED CREDENTIAL [https://my-azure-openai-endpoint.openai.azure.com/]
    WITH IDENTITY = 'Managed Identity', secret = '{"resourceid":"https://cognitiveservices.azure.com"}';
GO

-- Create the EXTERNAL MODEL
CREATE EXTERNAL MODEL MyAzureOpenAiModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.openai.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.openai.azure.com/]
);

Creación de un MODELO EXTERNO con Azure OpenAI mediante claves de API y parámetros

En este ejemplo se crea un EXTERNAL MODEL de tipo EMBEDDINGS mediante Azure OpenAI y se usan claves de API para la autenticación. En el ejemplo también se usa PARAMETERS para establecer el parámetro Dimensions en el punto de conexión en 725.

-- 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 the EXTERNAL MODEL
CREATE EXTERNAL MODEL MyAzureOpenAiModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.openai.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.openai.azure.com/],
      PARAMETERS = '{"Dimensions":725}'
);

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

En este ejemplo se crea un EXTERNAL MODEL de tipo EMBEDDINGS mediante Ollama hospedado 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

En este ejemplo se crea un EXTERNAL MODEL de tipo EMBEDDINGS mediante las credenciales basadas en encabezados 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]
);

Contenido relacionado