MAAK EXTERN MODEL AAN (Transact-SQL)

Van toepassing op: SQL Server 2025 (17.x) Azure SQL Database SQL database in Microsoft Fabric

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 je dit argument niet specificeert, wordt de huidige gebruiker de eigenaar. Afhankelijk van de rechten en rollen moet je mogelijk expliciete toestemming geven aan gebruikers om specifieke externe modellen te 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 benaderd vanaf de locatie van het AI-modelinferentie-eindpunt.

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

Specificeert het DATABASE SCOPED CREDENTIAL object dat wordt gebruikt met het AI-modelinferentie-eindpunt. Voor meer informatie over geaccepteerde kwalificatietypen en naamgevingsregels, zie sp_invoke_external_rest_endpoint of de sectie Opmerkingen van dit artikel.

PARAMETERS

Een geldige JSON-string die runtime-parameters bevat om toe te voegen aan het AI-model inferentie-endpoint verzoekbericht. Voorbeeld:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH specificeert de map op de lokale SQL Server-instantie waar de uitvoerbare bestanden van ONNX Runtime 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> } }

Om bijvoorbeeld de retry_count op 3 te zetten, gebruik je de volgende JSON-string:

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

Aantal nieuwe pogingen met andere parameters

Je kunt het aantal herkansingen combineren met andere parameters zolang de JSON-string geldig is.

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

Opmerkingen

HTTPS en TLS

Voor de LOCATION parameter worden alleen AI-modelinferentie-endpoints ondersteund die zijn geconfigureerd om HTTPS te gebruiken met het TLS-encryptieprotocol.

Geaccepteerde API-indelingen en modeltypen

De volgende secties beschrijven geaccepteerde API-formaten voor elke MODEL_TYPE.

API_FORMAT voor EMBEDDINGS

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

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

Eindpunten voor insluiten maken

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

Regels voor inloggegevensnamen voor extern model

De door een extern model gegenereerde DATABASE SCOPED CREDENTIAL moet de volgende regels volgen:

Moet een geldige URL zijn
Het URL-domein moet een van die domeinen zijn die in de toestemmingslijst zijn opgenomen.
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 respectievelijke deel van het URL-pad in de credentialnaam.
De credential moet wijzen op een pad dat generieker is dan de verzoek-URL. Bijvoorbeeld, een credential die voor het pad https://northwind.azurewebsite.net/customers is aangemaakt kan niet worden gebruikt voor de URL https://northwind.azurewebsite.net.

Regels voor sortering en referentienaam

RFC 3986 Sectie 6.2.2.1 stelt dat "Wanneer een URI componenten van de generieke syntaxis gebruikt, gelden altijd de component-syntaxisequivalentieregels; namelijk dat het schema en de host niet hoofdletters kunnen bepalen." RFC 7230 Sectie 2.7.3 vermeldt dat "alle andere worden op een naam-of-hoofd gevoelige manier vergeleken."

Omdat een collatieregel op databaseniveau wordt ingesteld, geldt de volgende logica om de databasecollatieregel en de RFC-regels consistent te houden. (De beschreven regel kan mogelijk restrictiever zijn dan de RFC-regels, bijvoorbeeld als de database is ingesteld op een hoofdlettergevoelige ranglijst.)

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)
Controleer of de URL en referentie overeenkomen met behulp van de databasesorteringsregels (en zonder URL-codering).

Beheerde identiteit

Om de beheerde identiteit van de Arc/VM-host als database-niveau credential in SQL Server 2025 (17.x) te gebruiken, moet je de optie inschakelen door te gebruiken sp_configure met een gebruiker die de server-level toestemming ALTER SETTINGS heeft toegekend.

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

SCHEMABINDING

Weergaven die met die referentie naar een extern model zijn gemaakt SCHEMABINDING (zoals een SELECT instructie met AI_GENERATE_EMBEDDINGS) kunnen niet worden verwijderd, en de Database Engine geeft een foutmelding. Om afhankelijkheden die naar een extern model verwijzen te verwijderen, moet je eerst de weergavedefinitie aanpassen of verwijderen.

Catalogusweergave

Je kunt externe modelmetadata bekijken door de catalogusweergave van de sys.external_models te bevragen. Je moet toegang hebben tot een model om de metadata ervan te bekijken.

SELECT *
FROM sys.external_models;

Voorbeelden met externe eindpunten

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

Dit voorbeeld creëert een extern model van het EMBEDDINGS type met Azure OpenAI en gebruikt Managed Identity voor authenticatie.

In SQL Server 2025 (17.x) en latere versies moet je je SQL Server verbinden met Azure Arc en de primaire beheerde identiteit inschakelen.

Belangrijk

Als je Managed Identity gebruikt met Azure OpenAI en SQL Server 2025 (17.x), moet de rol Cognitive Services OpenAI Contributor worden toegekend aan de door SQL Server toegewezen beheerde identiteit die door Azure Arc wordt ingeschakeld. Voor meer informatie, zie Rolgebaseerde toegangscontrole voor Azure OpenAI in Azure AI Foundry Models.

Maak toegangsgegevens aan Azure OpenAI met behulp van een beheerde identiteit:

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

Maak het externe model:

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

Maak een extern model met Azure OpenAI met behulp van API-sleutels en parameters

Dit voorbeeld creëert een extern model van het EMBEDDINGS type met Azure OpenAI en gebruikt API-sleutels voor authenticatie. In het voorbeeld wordt PARAMETERS ook de parameter dimensies op het eindpunt ingesteld op 725.

Maak toegangsgegevens aan Azure OpenAI met een sleutel:

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

Maak het externe model:

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

Een EXTERN MODEL maken met Ollama en een expliciete eigenaar

Dit voorbeeld creëert een extern model van het EMBEDDINGS type met behulp van Ollama die lokaal wordt gehost 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

Dit voorbeeld creëert een extern model van het EMBEDDINGS type met behulp van OpenAI- API_FORMAT en HTTP-header-gebaseerde credentials voor authenticatie.

-- 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 ONNX Runtime die lokaal draait

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.

Dit voorbeeld leidt je bij het opzetten van SQL Server 2025 (17.x) met ONNX Runtime om lokale AI-gestuurde tekst-embeddinggeneratie mogelijk te maken. Deze is alleen van toepassing op Windows.

Belangrijk

Deze functie vereist dat SQL Server Machine Learning Services is geïnstalleerd.

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

Voer het volgende Transact-SQL (T-SQL) commando uit om de previewfuncties van SQL Server 2025 (17.x) in de database die je wilt gebruiken in dit voorbeeld in te schakelen:

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 T-SQL-query uit te voeren:

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

Stap 3: Stel de ONNX Runtime-bibliotheek in

Maak een map aan op de SQL Server-instantie om de ONNX Runtime-bibliotheekbestanden te bevatten. 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 een versie van ONNX Runtime (1.19 of hoger) die geschikt is voor jouw 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.

Opmerking

Zorg ervoor dat de gemaakte dll de naam heefttokenizers_cpp.dll

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 Runtime-directory:

$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 query uit om je ONNX-model als extern modelobject te registreren:

De hier gebruikte waarde 'PARAMETERS' is een tijdelijke oplossing voor 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 moet wijzen naar de map die de bestanden bevat model.onnxtokenizer.json .
LOCAL_RUNTIME_PATHmoet wijzen op mappen die en onnxruntime.dll bestanden bevattentokenizer_cpp.dll.

Stap 8: Insluitingen genereren

Gebruik de ai_generate_embeddings functie om het model te testen door de volgende query 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 vorige query is een array van embeddings:

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

Schakel XEvent systeemlogging in

Voer de volgende query uit om systeemlogging voor probleemoplossing in te schakelen.

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 zoekopdracht, zie de vastgelegde systeemlogs:

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

Schoonmaken

Om het externe modelobject te verwijderen, voer je de volgende T-SQL-instructie uit:

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.

Feedback

Is deze pagina nuttig?

Last updated on 2025-12-08