CREA UN MODELLO ESTERNO (Transact-SQL)

Si applica a: SQL Server 2025 (17.x) Azure SQL Database SQL database 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 relative alla 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 specificato, la proprietà viene assegnata all'utente corrente. A seconda delle autorizzazioni e dei ruoli, è necessario concedere autorizzazioni esplicite agli utenti per usare 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

Tipo di modello a cui si accede dalla posizione dell'endpoint di inferenza del modello di intelligenza artificiale.

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

Indicare quale DATABASE SCOPED CREDENTIAL oggetto viene usato con l'endpoint di inferenza del modello di intelligenza artificiale. Altre informazioni sui tipi di credenziali accettate e sulle regole di denominazione sono disponibili in sp_invoke_external_rest_endpoint o nella sezione Osservazioni di questo articolo.

PARAMETRI

Stringa JSON valida che contiene parametri di runtime da aggiungere al messaggio di richiesta dell'endpoint di inferenza del modello di intelligenza artificiale. Per esempio:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH specifica la directory in SQL Server locale in cui si trovano i file eseguibili di runtime ONNX.

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

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 su retry_count 3, scrivere la stringa JSON seguente:

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

Numero di tentativi con altri parametri

Il numero di tentativi può anche essere combinato con altri parametri, purché sia una stringa JSON valida.

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

Osservazioni:

HTTPS e TLS

Per il parametro sono supportati solo gli endpoint di inferenza del modello di intelligenza artificiale configurati per l'uso di HTTPS con il LOCATION protocollo di crittografia TLS.

Formati di API accettati e tipi di modello

Le sezioni seguenti descrivono i formati API accettati per ogni MODEL_TYPE.

API_FORMAT per EMBEDDINGS

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

Formato API	Formato percorso percorso
Azure OpenAI	https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI	https://{server_name}/v1/embeddings
Ollama	https://localhost:{port}/api/embed

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 nei modelli di Azure AI Foundry
OpenAI
Ollama

Regole del nome delle credenziali per EXTERNAL MODEL

L'oggetto creato DATABASE SCOPED CREDENTIAL da un EXTERNAL MODEL oggetto deve rispettare specifiche regole seguenti:

Deve essere un URL valido
Il dominio URL deve essere uno di questi domini inclusi nell'elenco consenti
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
Le credenziali devono puntare a un percorso più generico rispetto all'URL della richiesta. Ad esempio, non è possibile usare credenziali create per il percorso https://northwind.azurewebsite.net/customers per l'URL https://northwind.azurewebsite.net

Regole di confronto e nome credenziali

RFC 3986 Sezione 6.2.2.1 indica che "Quando un URI usa componenti della sintassi generica, le regole di equivalenza della sintassi dei componenti si applicano sempre; vale a dire che lo schema e l'host non fanno distinzione tra maiuscole e minuscole" e RFC 7230 Sezione 2.7.3 indica che "tutti gli altri vengono confrontati in modo con distinzione tra maiuscole e minuscole".

Poiché è presente un set di regole di confronto a livello di database, viene applicata la logica seguente, per essere coerente con la regola delle regole di confronto del database e la RFC menzionata in precedenza. La regola descritta potrebbe potenzialmente essere più restrittiva rispetto alle regole RFC, ad esempio se il database è impostato per usare regole di confronto con distinzione tra maiuscole e minuscole:

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)
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à gestita per l'autenticazione in SQL Server 2025, è necessario abilitare l'opzione usando sp_configure con un utente a cui viene concessa l'autorizzazione a livello di server ALTER SETTINGS.

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

SCHEMABINDING

L'eliminazione di viste create con SCHEMABINDING e il riferimento a un EXTERNAL MODEL oggetto ( ad esempio un'istruzione SELECT che usa AI_GENERATE_EMBEDDINGS) viene impedita con il motore di database che genera un errore. La definizione di vista stessa deve prima essere modificata o eliminata per rimuovere le dipendenze che fanno riferimento a un oggetto EXTERNAL MODEL.

Vista catalogo

I metadati del modello esterno possono essere visualizzati con l'esecuzione di query sulla vista del sys.external_models catalogo. Si noti che è necessario avere accesso a un modello per poter visualizzare i 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 EXTERNAL MODEL oggetto del EMBEDDINGS tipo usando Azure OpenAI e usa l'identità gestita per l'autenticazione.

Importante

Se si usa l'identità gestita con Azure OpenAI e SQL Server 2025, il ruolo Collaboratore OpenAI di Servizi cognitivi deve essere concesso all'identità gestita assegnata dal sistema di SQL Server abilitata da Azure Arc. Per altre informazioni, vedere Controllo degli accessi in base al ruolo per Azure OpenAI nei modelli di 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/]
);

Creare un MODELLO ESTERNO con Azure OpenAI usando chiavi API e parametri

Questo esempio crea un EXTERNAL MODEL oggetto del EMBEDDINGS tipo 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.

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

Creare un MODELLO ESTERNO con Ollama e un proprietario esplicito

In questo esempio viene creato un EXTERNAL MODEL oggetto del EMBEDDINGS tipo usando Ollama ospitato localmente a scopo 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

In questo esempio viene creato un EXTERNAL MODEL oggetto del EMBEDDINGS tipo usando le credenziali basate sull'intestazione HTTP e OpenAI API_FORMAT 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 un runtime ONNX locale

Questo esempio illustra come configurare SQL Server 2025 con un runtime ONNX per abilitare la generazione di incorporamento di testo basata su intelligenza artificiale locale. Si applica solo in Windows.

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

Importante

Questa funzionalità richiede l'installazione di Machine Learning Services per SQL Server .

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

Eseguire il comando SQL seguente per abilitare le funzionalità di anteprima di SQL Server 2025 nel database che si vuole 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

Abilitare i runtime di intelligenza artificiale esterni eseguendo il codice SQL seguente:

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

Passaggio 3: Configurare la libreria di runtime ONNX

Creare una directory in 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

Scaricare quindi il runtime ONNX (versione ≥ 1.19) appropriato per il 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 tokenizers-cpp libreria da GitHub. Dopo aver creato la dll, posizionare il tokenizer nella C:\onnx_runtime directory .

Annotazioni

Verificare che la DLL creata sia denominata tokenizers_cpp.dll

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 collegamento di download seguente o tramite winget (winget install 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

Usare lo script di PowerShell seguente per fornire all'utente MSSQLLaunchpad l'accesso alla directory di runtime 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

Passaggio 7: Creare il modello esterno

Eseguire il codice SQL seguente per registrare il modello ONNX come oggetto modello esterno:

Il valore 'PARAMETERS' utilizzato 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

Usare la ai_generate_embeddings funzione per testare il modello eseguendo il codice SQL seguente:

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 dell'istruzione SQL è una matrice di incorporamenti:

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

Abilitare i dati di telemetria XEvent

Eseguire il codice SQL seguente per abilitare i dati di telemetria 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

Usare quindi questa query SQL per visualizzare i dati di telemetria acquisiti:

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, eseguire il codice SQL seguente:

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.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-19