CREATE EXTERNAL MODEL (Transact-SQL)

Applica a: SQL Server 2025 (17.x) < >database SQL di AzureIstanza gestita di SQL di AzureSQL in Microsoft Fabric

Crea un oggetto modello esterno che contiene la posizione, il metodo di autenticazione e lo scopo di un endpoint di inferenza del modello di intelligenza artificiale.

Sintassi

convenzioni di sintassi 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' ]
  );

Argomenti

external_model_object_name

Specifica il nome definito dall'utente per il modello esterno. Il nome deve essere univoco all'interno del database.

owner_name

Specifica il nome dell'utente o del ruolo proprietario del modello esterno. Se non specifichi questo argomento, l'utente attuale diventa il proprietario. A seconda dei permessi e dei ruoli, potresti dover concedere permessi espliciti agli utenti per utilizzare modelli esterni specifici.

UBICAZIONE

Fornisce il protocollo di connettività e il percorso dell'endpoint di inferenza del modello di intelligenza artificiale.

API_FORMAT

Formato del messaggio API per il provider di endpoint di inferenza del modello di intelligenza artificiale.

I valori accettati sono:

• Azure OpenAI
• OpenAI
• Ollama
• ONNX Runtime

TIPO_DI_MODULO

Il tipo di modello accessibile dalla posizione finale di inferenza del modello AI.

I valori accettati sono:

• EMBEDDINGS

MODELLO

Modello specifico ospitato dal provider di intelligenza artificiale. Ad esempio, text-embedding-ada-002, text-embedding-3-large o o3-mini.

CREDENZIALE

Specifica l'oggetto DATABASE SCOPED CREDENTIAL utilizzato con l'endpoint di inferenza del modello AI. Per ulteriori informazioni sui tipi di credenziali accettati e sulle regole di denominazione, consulta sp_invoke_external_rest_endpoint o la sezione Osservazioni di questo articolo.

PARAMETRI

Una stringa JSON valida che contiene parametri di runtime da aggiungere al messaggio di richiesta endpoint di inferenza del modello AI. Per esempio:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH specifica la directory nell'istanza di SQL Server locale in cui si trovano i file eseguibili onNX Runtime.

Autorizzazioni

Creazione e modifica di modelli esterni

Richiede ALTER ANY EXTERNAL MODEL o CREATE EXTERNAL MODEL l'autorizzazione del database.

Per esempio:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

O:

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

Concessioni di modelli esterni

Per usare un modello esterno in una funzione di intelligenza artificiale, è necessario concedere a EXECUTE un'entità di sicurezza la possibilità.

Per esempio:

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

Conteggio tentativi

Se la chiamata incorporamenti rileva codici di stato HTTP che indicano problemi temporanei, è possibile configurare la richiesta per riprovare automaticamente. Per specificare il numero di tentativi, aggiungere il codice JSON seguente a in PARAMETERS in EXTERNAL MODEL. Deve <number_of_retries> essere un numero intero compreso tra zero (0) e dieci (10), inclusi e non può essere NULL o negativo.

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

Ad esempio, per impostare il retry_count a 3, usa la seguente stringa JSON:

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

Numero di tentativi con altri parametri

Puoi combinare il conteggio dei tentativi con altri parametri purché la stringa JSON sia valida.

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

Osservazioni:

HTTPS e TLS

Per il LOCATION parametro, sono supportati solo gli endpoint di inferenza del modello AI configurati per usare HTTPS con il protocollo di crittografia TLS.

Formati di API accettati e tipi di modello

Le sezioni seguenti illustrano i formati API accettati per ciascun MODEL_TYPE.

API_FORMAT per EMBEDDINGS

Questa tabella delinea i formati API e le strutture endpoint URL per il EMBEDDINGS tipo di modello. Per visualizzare strutture di payload specifiche, usare il collegamento nella colonna Formato API.

Creare endpoint di incorporamento

Per altre informazioni sulla creazione di endpoint di incorporamento, usare questi collegamenti per il provider di endpoint di inferenza del modello di intelligenza artificiale appropriato:

• Azure OpenAI in Azure AI Foundry Models
• OpenAI
• Ollama

Regole del nome delle credenziali per un modello esterno

Il modello creato DATABASE SCOPED CREDENTIAL utilizzato da un modello esterno deve seguire queste regole:

• Deve essere un URL valido

• Il dominio URL deve essere uno di quei domini inclusi nella lista di permessi.

• L'URL non deve contenere una stringa di query

• Protocollo + nome di dominio completo (FQDN) dell'URL chiamato deve corrispondere al protocollo e al nome FQDN del nome della credenziale

• Ogni parte del percorso URL chiamato deve corrispondere completamente alla rispettiva parte del percorso URL nel nome delle credenziali.

• La credenziale deve indicare un percorso più generico dell'URL della richiesta. Ad esempio, una credenziale creata per path https://northwind.azurewebsite.net/customers non può essere usata per l'URL https://northwind.azurewebsite.net.

Regole di confronto e nome credenziali

La sezione 6.2.2.1 dell'RFC 3986 afferma che "Quando un URI utilizza componenti della sintassi generica, si applicano sempre le regole di equivalenza della sintassi dei componenti; ovvero, che lo schema e l'ospite non distinguono la maiuscole." La sezione 2.7.3 della RFC 7230 menziona che "tutte le altre vengono confrontate in modo sensibile alla maiuscolare."

Poiché una regola di collation è impostata a livello di database, la seguente logica si applica per mantenere la regola di collation del database e le regole RFC coerenti. (La regola descritta potrebbe essere potenzialmente più restrittiva rispetto alle regole RFC, ad esempio se il database è impostato per utilizzare una collazione a seconda delle mazze e minuscole e minuscoli.)

1. Controllare se l'URL e la corrispondenza delle credenziali usano la RFC, ovvero:

   • Controllare lo schema e l'host usando regole di confronto senza distinzione tra maiuscole e minuscole (Latin1_General_100_CI_AS_KS_WS_SC)
   • Verificare che tutti gli altri segmenti dell'URL vengano confrontati in regole di confronto con distinzione tra maiuscole e minuscole (Latin1_General_100_BIN2)

2. Verificare che l'URL e le credenziali corrispondano usando le regole di confronto del database (e senza eseguire alcuna codifica URL).

Identità gestita

Per usare l'identità managed identity dell'host Arc/VM come credenziale a livello di database in SQL Server 2025 (17.x) ), è necessario abilitare l'opzione usando sp_configure con un utente granted l'autorizzazione ALTER SETTINGS a livello di server.

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

SCHEMABINDING

Le viste create con che fanno riferimento a un modello esterno (ad esempio un'istruzione /> ) non possono essere eliminate e il motore di database genera un errore. Per rimuovere le dipendenze che fanno riferimento a un modello esterno, devi prima modificare o eliminare la definizione di vista.

Vista del catalogo

Puoi visualizzare i metadati dei modelli esterni interrogando la vista del catalogo sys.external_models . Devi avere accesso a un modello per visualizzare i suoi metadati.

SELECT *
FROM sys.external_models;

Esempi con endpoint remoti

Creare un MODELLO ESTERNO con Azure OpenAI usando l'identità gestita

Questo esempio crea un modello esterno del tipo EMBEDDINGS usando Azure OpenAI e usa Managed Identity per l'autenticazione.

In SQL Server 2025 (17.x) e versioni successive è necessario connettere il SQL Server a Azure Arc e abilitare l'identità gestita primaria.

Creare le credenziali di accesso per Azure OpenAI usando un'identità gestita:

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

Crea il modello esterno:

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

Creare un modello esterno con Azure OpenAI usando chiavi API e parametri

Questo esempio crea un modello esterno del tipo EMBEDDINGS usando Azure OpenAI e usa le chiavi API per l'autenticazione. L'esempio usa PARAMETERS anche per impostare il parametro dimensions nell'endpoint su 725.

Creare le credenziali di accesso per Azure OpenAI usando una chiave:

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

Crea il modello esterno:

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

Creare un MODELLO ESTERNO con Ollama e un proprietario esplicito

Questo esempio crea un modello esterno del EMBEDDINGS tipo utilizzando Ollama ospitato localmente per scopi di sviluppo.

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

Creare un MODELLO ESTERNO con OpenAI

Questo esempio crea un modello esterno del EMBEDDINGS tipo utilizzando le credenziali basate su OpenAI API_FORMAT e header HTTP per l'autenticazione.

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

Esempio con ONNX Runtime che funziona localmente

ONNX Runtime è un motore di inferenza open source che consente di eseguire modelli di Machine Learning in locale, rendendola ideale per l'integrazione di funzionalità di intelligenza artificiale in ambienti SQL Server.

Questo esempio illustra come configurare SQL Server 2025 (17.x) con ONNX Runtime per abilitare la generazione di incorporamento di testo basata su intelligenza artificiale locale. Si applica solo alle Windows.

Considerazioni relative alla sicurezza

È possibile usare la funzionalità host di runtime di intelligenza artificiale per configurare e usare librerie LLMs e ONNX personalizzate con SQL Server. Poiché Microsoft non convalida o monitora modelli e librerie di terze parti, l'utente è responsabile della selezione di modelli e librerie appropriati, del filtraggio del contenuto, della protezione del runtime e della conformità ai criteri e alle normative applicabili.

Per attenuare questi rischi, prendere in considerazione le procedure consigliate per la sicurezza seguenti:

• Implementare controlli di accesso sicuri: assicurarsi che solo gli utenti autorizzati abbiano accesso ai dati sensibili e ai modelli di runtime ONNX. Convalidare tutti i modelli prima di caricarli in SQL Server. Usare il principio dei privilegi minimi, nonché i ruoli e i privilegi del database.
• Monitorare e controllare l'accesso: monitorare e controllare regolarmente l'accesso al database e AI_GENERATE_EMBEDDINGS alle chiamate di funzione per rilevare attività sospette.
• Eseguire valutazioni regolari della sicurezza: eseguire analisi delle vulnerabilità e revisioni della sicurezza per identificare e attenuare i potenziali rischi.

Passaggio 1: Abilitare le funzionalità di anteprima per gli sviluppatori in SQL Server 2025

Eseguire il comando di Transact-SQL (T-SQL) seguente per abilitare le funzionalità di anteprima di SQL Server 2025 (17.x) nel database da usare per questo esempio:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Passaggio 2: Abilitare il runtime di intelligenza artificiale locale in SQL Server 2025

Abilita runtime di IA esterne eseguendo la seguente query T-SQL:

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

Passo 3: Configura la libreria di runtime ONNX

Creare una directory nell'istanza di SQL Server per contenere i file della libreria di runtime ONNX. In questo esempio viene C:\onnx_runtime usato .

Per creare la directory, è possibile usare i comandi seguenti:

cd C:\
mkdir onnx_runtime

Successivamente, scarica una versione di ONNX Runtime (1.19 o superiore) adatta al tuo sistema operativo. Dopo aver decompresso il download, copiare ( onnxruntime.dll che si trova nella directory lib) nella C:\onnx_runtime directory creata.

Passaggio 4: Configurare la libreria di tokenizzazione

Scaricare e compilare la libreria tokenizers-cpp da GitHub. Dopo aver creato la dll, posizionare il tokenizer nella C:\onnx_runtime directory .

Passaggio 5: Scaricare il modello ONNX

Per iniziare, creare la model directory in C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

Questo esempio usa il all-MiniLM-L6-v2-onnx modello, che può essere scaricato da Hugging Face.

Clonare il repository nella C:\onnx_runtime\model directory con il comando git seguente:

Se non è installato, è possibile scaricare git dal seguente collegamento download o tramite winget (installazione winget Microsoft. Git)

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

Passaggio 6: Impostare le autorizzazioni della directory

Usa il seguente script PowerShell per fornire all'utente MSSQLLaunchpad l'accesso alla directory 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

Passaggio 7: Creare il modello esterno

Esegui la seguente query per registrare il tuo modello ONNX come oggetto modello esterno:

Il valore 'PARAMETERS' usato qui è un segnaposto necessario per 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 dovrebbe puntare alla directory che contiene model.onnx e tokenizer.json file.
• LOCAL_RUNTIME_PATH dovrebbe indicare la cartella che contiene onnxruntime.dll e tokenizer_cpp.dll file.

Passaggio 8: Generare incorporamenti

Usa la ai_generate_embeddings funzione per testare il modello eseguendo la seguente query:

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

Questo comando avvia , AIRuntimeHostcarica le DLL necessarie ed elabora il testo di input.

Il risultato della query precedente è un array di embedding:

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

Abilita il logging del sistema XEvent

Esegui la seguente query per abilitare il logging di sistema per la risoluzione dei problemi.

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

Successivamente, usa questa query e consulta i log di sistema catturati:

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

Pulizia

Per rimuovere l'oggetto modello esterno, esegui la seguente istruzione T-SQL:

DROP EXTERNAL MODEL myLocalOnnxModel;

Per rimuovere le autorizzazioni della directory, eseguire i comandi di PowerShell seguenti:

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

Eliminare infine la C:/onnx_runtime directory.

Contenuti correlati

• ALTER EXTERNAL MODEL (Transact-SQL)
• DROP EXTERNAL MODEL (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL)
• sys.external_models
• Creare e distribuire una Azure OpenAI nella risorsa modelli Azure AI Foundry
• Opzioni di configurazione del server
• Controllo degli accessi in base al ruolo per Azure OpenAI nei modelli Azure AI Foundry