CREA UN MODELLO ESTERNO (Transact-SQL)

Si applica a: SQL Server 2025 (17.x) Azure SQL DatabaseSQL 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 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 sull'istanza locale di SQL Server dove si trovano gli eseguibili 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>];

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.

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 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 utilizzare l'identità gestita dell'host Arc/VM come credenziale a livello di database in SQL Server 2025 (17.x), devi abilitare l'opzione utilizzando sp_configure con un utente che abbia ottenuto il permesso a livello server ALTER SETTINGS.

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

SCHEMABINDING

Le viste create con SCHEMABINDING questo riferimento fanno riferimento a un modello esterno (come un'istruzione SELECT che usa AI_GENERATE_EMBEDDINGS) non possono essere eliminate, e il Database Engine 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 di questo EMBEDDINGS tipo utilizzando Azure OpenAI e utilizza Managed Identity per l'autenticazione.

In SQL Server 2025 (17.x) e versioni successive, devi collegare il tuo SQL Server ad Azure Arc e abilitare l'identità gestita primaria.

Importante

Se utilizzi Managed Identity con Azure OpenAI e SQL Server 2025 (17.x), il ruolo di Contributor OpenAI dei Servizi Cognitivi deve essere assegnato all'identità gestita assegnata al sistema di SQL Server abilitata da Azure Arc. Per ulteriori informazioni, consulta Controllo di accesso basato sui ruoli per Azure OpenAI in Azure AI Foundry Models.

Crea credenziali di accesso ad 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/]
);

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

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

Crea credenziali di accesso ad 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, rendendolo ideale per l'integrazione delle funzionalità di intelligenza artificiale negli ambienti SQL Server.

Questo esempio ti guida nella configurazione di SQL Server 2025 (17.x) con ONNX Runtime per abilitare la generazione locale di embedded di testo basata su AI locale. Si applica solo in Windows.

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

Esegui il seguente comando Transact-SQL (T-SQL) per abilitare le funzionalità di anteprima di SQL Server 2025 (17.x) nel database che desideri utilizzare 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

Crea una directory sull'istanza SQL Server per contenere i file della libreria ONNX Runtime. 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 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

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' 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

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

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