CREATE EXTERNAL MODEL (Transact-SQL)

2025-06-16

Si applica a: Anteprima di SQL Server 2025 (17.x)

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

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

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 da aggiungere al messaggio di richiesta dell'endpoint di inferenza del modello di intelligenza artificiale. Per esempio:

'{"Dimensions" : 1536}'

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. Il NUMBER_OF_RETRIES deve 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:

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 tramite 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 vengono visualizzati eseguendo una 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

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 l'identità gestita per l'autenticazione.

Importante

Se si usa l'identità gestita con Azure OpenAI e SQL Server 2025, il Cognitive Services OpenAI Contributor ruolo deve essere concesso all'identità gestita assegnata dal sistema di SQL Server da 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 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.

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

Condividi tramite