CREATE EXTERNAL MODEL (Transact-SQL)

Van toepassing op: SQL Server 2025 (17.x) Preview

Hiermee maakt u een extern modelobject dat de locatie, verificatiemethode en het doel van een eindpunt voor deductie van een AI-model bevat.

Syntaxis

Transact-SQL syntaxis-conventies

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

Argumenten

external_model_object_name

Hiermee geeft u de door de gebruiker gedefinieerde naam voor het externe model. De naam moet uniek zijn binnen de database.

owner_name

Hiermee geeft u de naam op van de gebruiker of rol die eigenaar is van het externe model. Als dit niet is opgegeven, wordt het eigendom aan de huidige gebruiker gegeven. Afhankelijk van machtigingen en rollen moet aan gebruikers expliciete machtigingen worden verleend om specifieke externe modellen te kunnen gebruiken.

LOCATIE

Biedt het connectiviteitsprotocol en het pad naar het eindpunt van deductie van het AI-model.

API_FORMAT

De API-berichtindeling voor de eindpuntprovider voor deductie van het AI-model.

Geaccepteerde waarden zijn:

• Azure OpenAI
• OpenAI
• Ollama
• ONNX Runtime

MODEL_TYPE

Het type model dat wordt geopend vanaf de eindpuntlocatie van het AI-modeldeductie.

Geaccepteerde waarden zijn:

• EMBEDDINGS

MODEL

Het specifieke model dat wordt gehost door de AI-provider. Bijvoorbeeld text-embedding-ada-002, text-embedding-3-large of o3-mini.

REFERENTIE

Geef aan welk DATABASE SCOPED CREDENTIAL object wordt gebruikt met het eindpunt voor deductie van het AI-model. Meer informatie over geaccepteerde referentietypen en naamgevingsregels vindt u in sp_invoke_external_rest_endpoint of in de sectie Opmerkingen van dit artikel.

PARAMETERS

Een geldige JSON-tekenreeks die runtimeparameters bevat die moeten worden toegevoegd aan het bericht voor deductie van eindpunten van het AI-model. Voorbeeld:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH hiermee geeft u de map op de lokale SQL Server waar de ONNX runtime uitvoerbare bestanden zich bevinden.

Machtigingen

Extern model maken en wijzigen

Hiervoor is een ALTER ANY EXTERNAL MODEL databasemachtiging vereistCREATE EXTERNAL MODEL.

Voorbeeld:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

of

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

Externe modeltoelagen

Als u een extern model in een AI-functie wilt gebruiken, moet aan een principal de mogelijkheid worden verleend.EXECUTE

Voorbeeld:

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

Aantal nieuwe pogingen

Als de aanroep voor insluitingen HTTP-statuscodes aangeeft die tijdelijke problemen aangeven, kunt u de aanvraag configureren om het automatisch opnieuw te proberen. Als u het aantal nieuwe pogingen wilt opgeven, voegt u de volgende JSON toe aan het PARAMETERSEXTERNAL MODELbestand . Het <number_of_retries> moet een geheel getal zijn tussen nul (0) en tien (10), inclusief en kan niet of negatief zijn NULL .

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

Als u bijvoorbeeld de retry_count op 3 wilt instellen, schrijft u de volgende JSON-tekenreeks:

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

Aantal nieuwe pogingen met andere parameters

Het aantal nieuwe pogingen kan ook worden gecombineerd met andere parameters zolang het een geldige JSON-tekenreeks is.

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

Opmerkingen

HTTPS en TLS

Alleen eindpunten voor AI-modeldeductie die zijn geconfigureerd voor het gebruik van HTTPS met TLS-versleutelingsprotocol, worden ondersteund voor de LOCATION parameter.

Geaccepteerde API-indelingen en modeltypen

In de volgende secties vindt u een overzicht van geaccepteerde API-indelingen voor elk MODEL_TYPE.

API_FORMAT voor EMBEDDINGS

Deze tabel bevat een overzicht van de API-indelingen en URL-eindpuntstructuren voor het EMBEDDINGS modeltype. Als u specifieke nettoladingstructuren wilt weergeven, gebruikt u de koppeling in de kolom API-indeling.

Eindpunten voor insluiten maken

Gebruik deze koppelingen voor de juiste eindpuntprovider voor deductie van ai-modellen voor meer informatie over het maken van insluiteindpunten:

• Azure OpenAI
• OpenAI
• Ollama

Referentienaamregels voor EXTERN MODEL

De gemaakt die door een an DATABASE SCOPED CREDENTIAL wordt EXTERNAL MODEL gebruikt, moet voldoen aan specifieke volgende regels:

• Moet een geldige URL zijn

• Het URL-domein moet een van deze domeinen zijn die zijn opgenomen in de acceptatielijst

• De URL mag geen querytekenreeks bevatten

• Protocol + Fully Qualified Domain Name (FQDN) van de aangeroepen URL moet overeenkomen met Protocol + FQDN van de referentienaam

• Elk deel van het aangeroepen URL-pad moet volledig overeenkomen met het respectieve deel van het URL-pad in de referentienaam

• De referentie moet verwijzen naar een pad dat algemeener is dan de aanvraag-URL. Een referentie die is gemaakt voor het pad https://northwind.azurewebsite.net/customers kan bijvoorbeeld niet worden gebruikt voor de URL-https://northwind.azurewebsite.net

Regels voor sortering en referentienaam

RFC 3986 Section 6.2.2.1 geeft aan dat "Wanneer een URI onderdelen van de algemene syntaxis gebruikt, de equivalentieregels voor de componentsyntaxis altijd van toepassing zijn; namelijk dat het schema en de host niet hoofdlettergevoelig zijn" en RFC 7230 Section 2.7.3 vermeldt dat "alle andere worden vergeleken op een hoofdlettergevoelige manier."

Omdat er een sorteringsregel is ingesteld op databaseniveau, wordt de volgende logica toegepast, zodat deze consistent is met de databasesorteringsregel en de RFC die eerder is genoemd. (De beschreven regel kan mogelijk meer beperkend zijn dan de RFC-regels, bijvoorbeeld als de database is ingesteld op het gebruik van een hoofdlettergevoelige sortering):

1. Controleer of de URL en referentie overeenkomen met behulp van de RFC, wat betekent:

   • Controleer het schema en de host met behulp van een niet-hoofdlettergevoelige sortering (Latin1_General_100_CI_AS_KS_WS_SC)
   • Controleer of alle andere segmenten van de URL worden vergeleken in een hoofdlettergevoelige sortering (Latin1_General_100_BIN2)

2. Controleer of de URL en referentie overeenkomen met behulp van de databasesorteringsregels (en zonder URL-codering).

Beheerde identiteit

Als u beheerde identiteit wilt gebruiken voor verificatie op SQL Server 2025, moet u de optie sp_configure inschakelen met een gebruiker waaraan de machtiging ALTER SETTINGS op serverniveau is verleend.

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

SCHEMABINDING

Het verwijderen van SCHEMABINDING weergaven die zijn gemaakt met EXTERNAL MODEL een (zoals een SELECT instructie die wordt gebruiktAI_GENERATE_EMBEDDINGS) wordt voorkomen door de database-engine die een fout veroorzaakt. De weergavedefinitie zelf moet eerst worden gewijzigd of verwijderd om afhankelijkheden te verwijderen die verwijzen naar een EXTERNAL MODEL.

Catalogusweergave

Metagegevens van extern model kunnen worden weergegeven met query's op de sys.external_models catalogusweergave. Opmerking: u moet toegang hebben tot een model om de metagegevens te kunnen bekijken.

SELECT * FROM sys.external_models;

Voorbeelden met externe eindpunten

Een EXTERN MODEL maken met Azure OpenAI met behulp van beheerde identiteit

In dit voorbeeld wordt een EXTERNAL MODEL van het EMBEDDINGS type gemaakt met behulp van Azure OpenAI en wordt beheerde identiteit gebruikt voor verificatie.

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

Een EXTERN MODEL maken met Azure OpenAI met behulp van API-sleutels en -parameters

In dit voorbeeld wordt een EXTERNAL MODEL van het EMBEDDINGS type gemaakt met behulp van Azure OpenAI en worden API-sleutels gebruikt voor verificatie. In het voorbeeld wordt PARAMETERS ook de parameter dimensies op het eindpunt ingesteld op 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}'
);

Een EXTERN MODEL maken met Ollama en een expliciete eigenaar

In dit voorbeeld wordt een EXTERNAL MODEL van het EMBEDDINGS type gemaakt dat lokaal wordt gehost met Ollama voor ontwikkelingsdoeleinden.

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

Een EXTERN MODEL maken met OpenAI

In dit voorbeeld wordt een EXTERNAL MODEL van het EMBEDDINGS type gemaakt met behulp van de openAI API_FORMAT - en HTTP-headerreferenties voor verificatie.

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

Voorbeeld met een lokale ONNX-runtime

In dit voorbeeld wordt u begeleid bij het instellen van SQL Server 2025 met een ONNX-runtime voor het insluiten van lokale AI-tekst. Deze is alleen van toepassing op Windows.

ONNX Runtime is een opensource-deductie-engine waarmee u machine learning-modellen lokaal kunt uitvoeren, waardoor het ideaal is voor het integreren van AI-mogelijkheden in SQL Server-omgevingen.

Stap 1: Preview-functies voor ontwikkelaars inschakelen in SQL Server 2025

Voer de volgende SQL-opdracht uit om preview-functies van SQL Server 2025 in te schakelen in de database die u voor dit voorbeeld wilt gebruiken:

ALTER DATABASE SCOPED CONFIGURATION  
SET PREVIEW_FEATURES = ON;

Stap 2: de lokale AI-runtime inschakelen op SQL Server 2025

Schakel externe AI-runtimes in door de volgende SQL uit te voeren:

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

Stap 3: de ONNX-runtimebibliotheek instellen

Maak een map op de SQL Server voor het opslaan van de ONNX Runtime-bibliotheekbestanden. In dit voorbeeld C:\onnx_runtime wordt gebruikt.

U kunt de volgende opdrachten gebruiken om de map te maken:

cd C:\
mkdir onnx_runtime

Download vervolgens de ONNX Runtime (versie ≥ 1.19) die geschikt is voor uw besturingssysteem. Nadat u de download hebt uitgezet, kopieert u de onnxruntime.dll (in de lib-map) naar de C:\onnx_runtime map die is gemaakt.

Stap 4: De tokenisatiebibliotheek instellen

Download en bouw de tokenizers-cpp bibliotheek vanuit GitHub. Zodra de dll is gemaakt, plaatst u de tokenizer in de C:\onnx_runtime map.

Stap 5: Het ONNX-model downloaden

Begin met het maken van de model map in C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

In dit voorbeeld wordt het all-MiniLM-L6-v2-onnx model gebruikt, dat kan worden gedownload van Hugging Face.

Kloon de opslagplaats naar de C:\onnx_runtime\model map met de volgende Git-opdracht :

Als dit niet is geïnstalleerd, kunt u Git downloaden via de volgende downloadkoppeling of via winget (winget install Microsoft.Git)

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

Stap 6: Mapmachtigingen instellen

Gebruik het volgende PowerShell-script om de MSSQLLaunchpad-gebruiker toegang te geven tot de ONNX-runtimemap:

$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

Stap 7: Het externe model maken

Voer de volgende SQL uit om uw ONNX-model te registreren als een extern modelobject:

De hier gebruikte waarde parameters is een tijdelijke aanduiding die nodig is voor SQL Server 2025 (17.x) Preview.

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

Stap 8: Insluitingen genereren

Gebruik de ai_generate_embeddings functie om het model te testen door de volgende SQL uit te voeren:

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

Met deze opdracht worden de AIRuntimeHostvereiste DLL's gestart, geladen en de invoertekst verwerkt.

Het resultaat van de SQL-instructie is een matrix met insluitingen:

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

XEvent-telemetrie inschakelen

Voer de volgende SQL uit om telemetrie in te schakelen voor probleemoplossing.

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

Gebruik vervolgens deze SQL-query om de vastgelegde telemetrie te bekijken:

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

Schoonmaken

Voer de volgende SQL uit om het externe modelobject te verwijderen:

DROP EXTERNAL MODEL myLocalOnnxModel;

Voer de volgende PowerShell-opdrachten uit om de mapmachtigingen te verwijderen:

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

Verwijder ten slotte de C:/onnx_runtime map.

Verwante inhoud

• ALTER EXTERNAL MODEL (Transact-SQL)
• DROP EXTERNAL MODEL (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL) (preview)
• sys.external_models
• Een Azure OpenAI maken en implementeren in Azure AI Foundry Models-resource
• Serverconfiguratieopties
• Op rollen gebaseerd toegangsbeheer voor Azure OpenAI in Azure AI Foundry-modellen