CRÉER UN MODÈLE EXTERNE (Transact-SQL)

S’applique à : SQL Server 2025 (17.x) Azure SQL Database SQL database in Microsoft Fabric

Crée un objet de modèle externe qui contient l’emplacement, la méthode d’authentification et l’objectif d’un point de terminaison d’inférence de modèle IA.

Syntaxe

Conventions de la syntaxe 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' ]
  );

Les arguments

external_model_object_name

Spécifie le nom défini par l’utilisateur pour le modèle externe. Le nom doit être unique au sein de la base de données.

owner_name

Spécifie le nom de l’utilisateur ou du rôle propriétaire du modèle externe. Si vous ne précisez pas cet argument, l’utilisateur actuel devient le propriétaire. Selon les permissions et les rôles, il se peut que vous deviez accorder des autorisations explicites aux utilisateurs pour utiliser des modèles externes spécifiques.

EMPLACEMENT

Fournit le protocole de connectivité et le chemin d’accès au point de terminaison d’inférence du modèle IA.

API_FORMAT

Format de message d’API pour le fournisseur de point de terminaison d’inférence du modèle IA.

Les valeurs acceptées sont les suivantes :

Azure OpenAI
OpenAI
Ollama
ONNX Runtime

TYPE_DE_MODÈLE

Le type de modèle accédé depuis l’emplacement du point d’arrivée du modèle d’inférence IA.

Les valeurs acceptées sont les suivantes :

EMBEDDINGS

MODÈLE

Modèle spécifique hébergé par le fournisseur d’IA. Par exemple, text-embedding-ada-002, text-embedding-3-large ou o3-mini.

INFORMATIONS D'IDENTIFICATION

Spécifie l’objet DATABASE SCOPED CREDENTIAL utilisé avec le point d’inférence du modèle IA. Pour plus d’informations sur les types de diplômes acceptés et les règles de dénomination, consultez sp_invoke_external_rest_endpoint ou la section Remarques de cet article.

PARAMÈTRES

Une chaîne JSON valide contenant des paramètres d’exécution à ajouter au message de demande d’inférence d’inférence du modèle IA. Par exemple:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH spécifie le répertoire sur l’instance SQL Server locale où se trouvent les exécutables à l’exécution ONNX.

Autorisations

Création et modification de modèles externes

Nécessite ou ALTER ANY EXTERNAL MODEL l’autorisation CREATE EXTERNAL MODEL de base de données.

Par exemple:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Ou:

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

Subventions de modèle externe

Pour utiliser un modèle externe dans une fonction IA, un principal doit lui accorder la possibilité EXECUTE .

Par exemple:

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

Nombre de nouvelles tentatives

Si l’appel d’incorporation rencontre des codes d’état HTTP indiquant des problèmes temporaires, vous pouvez configurer la demande pour réessayer automatiquement. Pour spécifier le nombre de nouvelles tentatives, ajoutez le code JSON suivant au PARAMETERSEXTERNAL MODELfichier . Il <number_of_retries> doit s’agir d’un nombre entier compris entre zéro (0) et dix (10), inclus et ne peut pas être NULL ou négatif.

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

Par exemple, pour fixer le retry_count à 3, utilisez la chaîne JSON suivante :

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

Nombre de nouvelles tentatives avec d’autres paramètres

Vous pouvez combiner le nombre de tentatives avec d’autres paramètres tant que la chaîne JSON est valide.

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

Remarques

HTTPS et TLS

Pour ce LOCATION paramètre, seuls les terminaux d’inférence du modèle IA configurés pour utiliser HTTPS avec le protocole de chiffrement TLS sont pris en charge.

Formats d’API acceptés et types de modèles

Les sections suivantes décrivent les formats d’API acceptés pour chaque MODEL_TYPEfichier .

API_FORMAT pour EMBEDDINGS

Ce tableau présente les formats API et les structures de points d’accès URL pour le EMBEDDINGS type de modèle. Pour afficher des structures de charge utile spécifiques, utilisez le lien dans la colonne Format de l’API.

Format d’API	Format du chemin d’accès d’emplacement
Azure OpenAI	https://{endpoint}/openai/deployments/{deployment-id}/embeddings ?api-version={date}
OpenAI	https ://{server_name}/v1/embeddings
Ollama	https ://localhost :{port}/api/embed

Créer des points de terminaison d’incorporation

Pour plus d’informations sur la création de points de terminaison d’incorporation, utilisez ces liens pour le fournisseur de points de terminaison d’inférence de modèle IA approprié :

Azure OpenAI dans les modèles Azure AI Foundry
OpenAI
Ollama

Règles de nom de crédential pour un modèle externe

Le modèle créé DATABASE SCOPED CREDENTIAL par un modèle externe doit suivre ces règles :

Doit être une URL valide
Le domaine URL doit être l’un de ceux inclus dans la liste des autorisations.
L’URL ne doit pas contenir de chaîne de requête
Le protocole + nom de domaine complet (FQDN) de l’URL appelée doit correspondre au protocole + nom de domaine complet du nom d’identification
Chaque partie du chemin d’URL appelée doit correspondre entièrement à la partie respective du chemin d’URL dans le nom de l’identifiant.
L’identifiant doit pointer vers un chemin plus générique que l’URL de la requête. Par exemple, une identifiante créée pour path https://northwind.azurewebsite.net/customers ne peut pas être utilisée pour l’URL https://northwind.azurewebsite.net.

Règles de nom de classement et d’informations d’identification

La section 6.2.2.1 de la RFC 3986 stipule que « Lorsqu’un URI utilise des composants de la syntaxe générique, les règles d’équivalence de la syntaxe des composants s’appliquent toujours ; à savoir, que le schéma et l’hôte sont insensibles à la casse. » La section 2.7.3 de la RFC 7230 mentionne que « tous les autres sont comparés de manière sensible à la casse ».

Parce qu’une règle de compilation est définie au niveau de la base de données, la logique suivante s’applique pour maintenir la cohérence de la règle de compilation de la base de données et les règles RFC. (La règle décrite pourrait potentiellement être plus restrictive que les règles RFC, par exemple si la base de données est configurée pour utiliser une collation sensible à la casse.)

Vérifiez si l’URL et les informations d’identification correspondent à l’aide du RFC, ce qui signifie :
- Vérifiez le schéma et l’hôte à l’aide d’un classement non sensible à la casse (Latin1_General_100_CI_AS_KS_WS_SC)
- Vérifiez que tous les autres segments de l’URL sont comparés dans un classement respectant la casse (Latin1_General_100_BIN2)
Vérifiez que l’URL et les informations d’identification correspondent à l’aide des règles de classement de base de données (et sans effectuer d’encodage d’URL).

Identité managée

Pour utiliser l’identité gérée de l’hôte Arc/VM comme identifiant au niveau de la base de données dans SQL Server 2025 (17.x), vous devez activer cette option en utilisant sp_configure avec un utilisateur ayant obtenu la permission ALTER SETTINGS au niveau serveur.

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

SCHEMABINDING

Les vues créées avec SCHEMABINDING cette référence font référence à un modèle externe (comme une SELECT instruction utilisant AI_GENERATE_EMBEDDINGS) ne peuvent pas être supprimées, et le moteur de base de données génère une erreur. Pour supprimer les dépendances référenciant un modèle externe, il faut d’abord modifier ou supprimer la définition de la vue.

Vue du catalogue

Vous pouvez consulter les métadonnées des modèles externes en interrogeant la vue catalogue sys.external_models . Vous devez avoir accès à un modèle pour en voir les métadonnées.

SELECT *
FROM sys.external_models;

Exemples avec des points de terminaison distants

Créer un MODÈLE EXTERNE avec Azure OpenAI à l’aide d’Une identité managée

Cet exemple crée un modèle externe de ce EMBEDDINGS type utilisant Azure OpenAI et utilise l’identité gérée pour l’authentification.

Dans SQL Server 2025 (17.x) et versions ultérieures, vous devez connecter votre SQL Server à Azure Arc et activer l’identité principale gérée.

Important

Si vous utilisez Managed Identity avec Azure OpenAI et SQL Server 2025 (17.x), le rôle de contributeur Cognitive Services OpenAI doit être attribué à l’identité managée assignée au système de SQL Server activée par Azure Arc. Pour plus d’informations, voir Contrôle d’accès basé sur les rôles pour Azure OpenAI dans Azure AI Foundry Models.

Créez des identifiants d’accès à Azure OpenAI en utilisant une identité gérée :

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

Créez le modèle externe :

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

Créer un modèle externe avec Azure OpenAI en utilisant des clés et paramètres API

Cet exemple crée un modèle externe de ce EMBEDDINGS type utilisant Azure OpenAI et utilise des clés API pour l’authentification. L’exemple utilise PARAMETERS également pour définir le paramètre de dimensions au niveau du point de terminaison sur 725.

Créez des identifiants d’accès à Azure OpenAI à l’aide d’une clé :

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

Créez le modèle externe :

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}'
);

Créer un MODÈLE EXTERNE avec Ollama et un propriétaire explicite

Cet exemple crée un modèle externe du EMBEDDINGS type utilisant Ollama hébergé localement à des fins de développement.

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

Créer un MODÈLE EXTERNE avec OpenAI

Cet exemple crée un modèle externe du EMBEDDINGS type utilisant les identifiants OpenAI API_FORMAT et HTTP basés sur les en-têtes pour l’authentification.

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

Exemple avec l’exécution ONNX fonctionnant localement

ONNX Runtime est un moteur d’inférence open source qui vous permet d’exécuter des modèles Machine Learning localement, ce qui vous permet d’intégrer des fonctionnalités d’IA dans des environnements SQL Server.

Cet exemple vous guide dans la configuration de SQL Server 2025 (17.x) avec ONNX Runtime pour permettre la génération locale d’intégration de texte alimentée par l’IA. Elle s’applique uniquement sur Windows.

Important

Cette fonctionnalité nécessite l’installation de SQL Server Machine Learning Services .

Étape 1 : Activer les fonctionnalités en préversion du développeur sur SQL Server 2025

Exécutez la commande Transact-SQL suivante (T-SQL) pour activer les fonctionnalités d’aperçu de SQL Server 2025 (17.x) dans la base de données que vous souhaitez utiliser pour cet exemple :

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Étape 2 : Activer le runtime IA local sur SQL Server 2025

Activez les temps d’exécution d’IA externes en exécutant la requête T-SQL suivante :

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

Étape 3 : Configurez la bibliothèque d’exécution ONNX

Créez un répertoire sur l’instance SQL Server pour contenir les fichiers de la bibliothèque d’exécution ONNX. Dans cet exemple, C:\onnx_runtime est utilisé.

Vous pouvez utiliser les commandes suivantes pour créer le répertoire :

cd C:\
mkdir onnx_runtime

Ensuite, téléchargez une version d’ONNX Runtime (1.19 ou plus) adaptée à votre système d’exploitation. Après avoir décompressé le téléchargement, copiez le onnxruntime.dll (situé dans le répertoire lib) dans le C:\onnx_runtime répertoire créé.

Étape 4 : Configurer la bibliothèque de jetons

Téléchargez et générez la tokenizers-cpp bibliothèque à partir de GitHub. Une fois la dll créée, placez le tokenizer dans le C:\onnx_runtime répertoire.

Note

Vérifiez que la dll créée est nommée tokenizers_cpp.dll

Étape 5 : Télécharger le modèle ONNX

Commencez par créer le model répertoire dans C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

Cet exemple utilise le all-MiniLM-L6-v2-onnx modèle, qui peut être téléchargé à partir de Hugging Face.

Clonez le référentiel dans le C:\onnx_runtime\model répertoire avec la commande git suivante :

Si ce n’est pas le cas, vous pouvez télécharger git à partir du lien de téléchargement suivant ou via winget (winget install Microsoft.Git)

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

Étape 6 : Définir les autorisations d’annuaire

Utilisez le script PowerShell suivant pour donner à l’utilisateur MSSQLLaunchpad un accès au répertoire ONNX Runtime :

$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

Étape 7 : Créer le modèle externe

Effectuez la requête suivante pour enregistrer votre modèle ONNX comme objet modèle externe :

La valeur « PARAMÈTRES » utilisée ici est un espace réservé nécessaire pour 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 devrait pointer vers le répertoire contenant model.onnx et tokenizer.json fichiers.
LOCAL_RUNTIME_PATH devrait pointer vers le répertoire contenant onnxruntime.dll et tokenizer_cpp.dll fichiers.

Étape 8 : Générer des incorporations

Utilisez la ai_generate_embeddings fonction pour tester le modèle en lançant la requête suivante :

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

Cette commande lance, AIRuntimeHostcharge les DLL requises et traite le texte d’entrée.

Le résultat de la requête précédente est un tableau d’embeddings :

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

Activer la journalisation système XEvent

Effectuez la requête suivante pour activer la journalisation système afin de dépanner.

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

Ensuite, utilisez cette requête : consultez les journaux système capturés :

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

Nettoyage

Pour supprimer l’objet modèle externe, exécutez l’instruction T-SQL suivante :

DROP EXTERNAL MODEL myLocalOnnxModel;

Pour supprimer les autorisations d’annuaire, exécutez les commandes PowerShell suivantes :

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

Enfin, supprimez le C:/onnx_runtime répertoire.

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-12-08