SKAPA EXTERN MODELL (Transact-SQL)

Gäller för: Förhandsversion av SQL Server 2025 (17.x)

Skapar ett externt modellobjekt som innehåller platsen, autentiseringsmetoden och syftet med en SLUTpunkt för AI-modellinferens.

Syntax

Transact-SQL syntaxkonventioner

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

Argumentpunkter

external_model_object_name

Anger det användardefinierade namnet på den externa modellen. Namnet måste vara unikt i databasen.

owner_name

Anger namnet på den användare eller roll som äger den externa modellen. Om det inte anges ges ägarskap till den aktuella användaren. Beroende på behörigheter och roller måste explicit behörighet beviljas till användare för att använda specifika externa modeller.

PLATS

Tillhandahåller anslutningsprotokollet och sökvägen till SLUTpunkten för AI-modellens slutsatsdragning.

API_FORMAT

API-meddelandeformatet för SLUTpunktsprovidern för AI-modellen.

Godkända värden är:

• Azure OpenAI
• OpenAI
• Ollama
• ONNX Runtime

MODEL_TYPE

Den typ av modell som används från ai-modellens slutpunktsplats för slutsatsdragning.

Godkända värden är:

• EMBEDDINGS

MODELL

Den specifika modell som HANTERAS av AI-providern. Till exempel text-embedding-ada-002, text-embedding-3-large, eller o3-mini.

REFERENS

Ange vilket objekt som DATABASE SCOPED CREDENTIAL används med SLUTpunkten för AI-modellens slutsatsdragning. Mer information om godkända typer av autentiseringsuppgifter och namngivningsregler finns i sp_invoke_external_rest_endpoint, eller i avsnittet Kommentarer i den här artikeln.

PARAMETRAR

En giltig JSON-sträng som innehåller körningsparametrar som ska läggas till i meddelandet om slutpunktsförfrågan för AI-modellen. Till exempel:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH anger katalogen på den lokala SQL Server där körbara ONNX-körningsbara filer finns.

Behörigheter

Skapande och ändring av extern modell

Kräver ALTER ANY EXTERNAL MODEL eller CREATE EXTERNAL MODEL databasbehörighet.

Till exempel:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

eller

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

Externa modellbidrag

Om du vill använda en extern modell i en AI-funktion måste ett huvudnamn ges möjlighet till EXECUTE den.

Till exempel:

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

Antal nya försök

Om inbäddningsanropet stöter på HTTP-statuskoder som anger tillfälliga problem kan du konfigurera begäran så att den försöker igen automatiskt. Om du vill ange antalet återförsök lägger du till följande JSON i PARAMETERS på EXTERNAL MODEL. Ska <number_of_retries> vara ett heltal mellan noll (0) och tio (10), inkluderande och får inte vara NULL eller negativa.

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

Om du till exempel vill ange retry_count till 3 skriver du följande JSON-sträng:

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

Antal återförsök med andra parametrar

Antal återförsök kan också kombineras med andra parametrar så länge det är en giltig JSON-sträng.

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

Anmärkningar

HTTPS och TLS

Endast slutpunkter för AI-modellinferens som är konfigurerade att använda HTTPS med TLS-krypteringsprotokoll stöds för parametern LOCATION .

Godkända API-format och modelltyper

I följande avsnitt beskrivs accepterade API-format för varje MODEL_TYPE.

API_FORMAT för EMBEDDINGS

Den här tabellen beskriver API-format och URL-slutpunktsstrukturer för EMBEDDINGS modelltypen. Om du vill visa specifika nyttolaststrukturer använder du länken i kolumnen API Format.

Skapa inbäddningsslutpunkter

Mer information om hur du skapar inbäddningsslutpunkter finns i dessa länkar för lämplig SLUTpunktsprovider för AI-modellinferens:

• Azure OpenAI
• OpenAI
• Ollama

Namnregler för autentiseringsuppgifter för EXTERN MODELL

Den skapade DATABASE SCOPED CREDENTIAL som används av en EXTERNAL MODEL måste följa specifika följande regler:

• Måste vara en giltig URL

• URL-domänen måste vara en av de domäner som ingår i listan över tillåtna domäner

• URL:en får inte innehålla en frågesträng

• Protokoll + Fullständigt domännamn (FQDN) för den anropade URL:en måste matcha Protokoll + FQDN för autentiseringsuppgiftsnamnet

• Varje del av den kallade URL-sökvägen måste matcha helt med respektive del av URL-sökvägen i autentiseringsuppgiftsnamnet

• Autentiseringsuppgifterna måste peka på en sökväg som är mer allmän än begärande-URL:en. Till exempel kan en autentiseringsuppgift som skapats för sökvägen https://northwind.azurewebsite.net/customers inte användas för URL-https://northwind.azurewebsite.net

Namnregler för sortering och autentiseringsuppgifter

RFC 3986 Avsnitt 6.2.2.1 säger att "När en URI använder komponenter i den generiska syntaxen gäller alltid reglerna för komponentsyntaxens likvärdighet. nämligen att systemet och värden är skiftlägesokänsliga", och RFC 7230 avsnitt 2.7.3 nämner att "alla andra jämförs på ett skiftlägeskänsligt sätt".

Eftersom det finns en sorteringsregel som har angetts på databasnivå tillämpas följande logik, för att vara konsekvent med databassorteringsregeln och den RFC som nämndes tidigare. (Den beskrivna regeln kan potentiellt vara mer restriktiv än RFC-reglerna, till exempel om databasen är inställd på att använda en skiftlägeskänslig sortering):

1. Kontrollera om URL:en och autentiseringsuppgifterna matchar med hjälp av RFC, vilket innebär:

   • Kontrollera schemat och värden med hjälp av en skiftlägesokänslig sortering (Latin1_General_100_CI_AS_KS_WS_SC)
   • Kontrollera att alla andra segment i URL:en jämförs i en skiftlägeskänslig sortering (Latin1_General_100_BIN2)

2. Kontrollera att URL:en och autentiseringsuppgifterna matchar med hjälp av databassorteringsreglerna (och utan att göra någon URL-kodning).

Hanterad identitet

Om du vill använda Hanterad identitet för autentisering på SQL Server 2025 måste du aktivera alternativet med hjälp sp_configure av med en användare som har beviljats behörigheten ALTER SETTINGS på servernivå.

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

SCHEMABINDNING

Att ta bort vyer som skapats med SCHEMABINDING och refererar till en EXTERNAL MODEL (till exempel en SELECT -instruktion med ) AI_GENERATE_EMBEDDINGSförhindras med databasmotorn som skapar ett fel. Själva vydefinitionen måste först ändras eller tas bort för att ta bort beroenden som refererar till en EXTERNAL MODEL.

Katalogvy

Externa modellmetadata kan visas med frågor mot sys.external_models katalogvyn. Observera att du måste ha åtkomst till en modell för att kunna visa metadata.

SELECT * FROM sys.external_models;

Exempel med fjärrslutpunkter

Skapa en EXTERN MODELL med Azure OpenAI med hanterad identitet

Det här exemplet skapar en EXTERNAL MODEL av typen EMBEDDINGS med Hjälp av Azure OpenAI och använder Hanterad identitet för autentisering.

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

Skapa en EXTERN MODELL med Azure OpenAI med hjälp av API-nycklar och parametrar

Det här exemplet skapar en EXTERNAL MODEL av typen EMBEDDINGS med Hjälp av Azure OpenAI och använder API-nycklar för autentisering. Exemplet använder PARAMETERS också för att ange dimensionsparametern vid slutpunkten till 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}'
);

Skapa en EXTERN MODELL med Ollama och en explicit ägare

Det här exemplet skapar en EXTERNAL MODEL av typen EMBEDDINGS med hjälp av Ollama lokalt i utvecklingssyfte.

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

Skapa en EXTERN MODELL med OpenAI

I det här exemplet skapas en EXTERNAL MODEL av typen EMBEDDINGS med autentiseringsuppgifterna OpenAI API_FORMAT och HTTP-huvudbaserade autentiseringsuppgifter.

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

Exempel med en lokal ONNX-körning

Det här exemplet vägleder dig genom att konfigurera SQL Server 2025 med en ONNX-körning för att aktivera lokal AI-baserad textinbäddningsgenerering. Det gäller endast i Windows.

ONNX Runtime är en slutsatsdragningsmotor med öppen källkod som gör att du kan köra maskininlärningsmodeller lokalt, vilket gör den idealisk för att integrera AI-funktioner i SQL Server-miljöer.

Steg 1: Aktivera förhandsgranskningsfunktioner för utvecklare på SQL Server 2025

Kör följande SQL-kommando för att aktivera SQL Server 2025-förhandsgranskningsfunktioner i databasen som du vill använda i det här exemplet:

ALTER DATABASE SCOPED CONFIGURATION  
SET PREVIEW_FEATURES = ON;

Steg 2: Aktivera den lokala AI-körningen på SQL Server 2025

Aktivera externa AI-körningar genom att köra följande SQL:

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

Steg 3: Konfigurera ONNX-körningsbiblioteket

Skapa en katalog på SQL Server för att lagra ONNX-körningsbiblioteksfilerna. I det här exemplet C:\onnx_runtime används.

Du kan använda följande kommandon för att skapa katalogen:

cd C:\
mkdir onnx_runtime

Ladda sedan ned ONNX Runtime (version ≥ 1.19) som är lämplig för operativsystemet. När du har packat upp nedladdningen onnxruntime.dll kopierar du (finns i katalogen lib) till katalogen C:\onnx_runtime som skapades.

Steg 4: Konfigurera tokeniseringsbiblioteket

Ladda ned och skapa tokenizers-cpp biblioteket från GitHub. När dll-filen har skapats placerar du tokenizern C:\onnx_runtime i katalogen.

Steg 5: Ladda ned ONNX-modellen

Börja med att model skapa katalogen i C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

I det all-MiniLM-L6-v2-onnx här exemplet används modellen, som kan laddas ned från Hugging Face.

Klona lagringsplatsen till C:\onnx_runtime\model katalogen med följande git-kommando :

Om det inte är installerat kan du ladda ned git från följande nedladdningslänk eller via winget (winget install Microsoft.Git)

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

Steg 6: Ange katalogbehörigheter

Använd följande PowerShell-skript för att ge MSSQLLaunchpad-användaren åtkomst till ONNX-körningskatalogen:

$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

Steg 7: Skapa den externa modellen

Kör följande SQL för att registrera DIN ONNX-modell som ett externt modellobjekt:

Parametervärdet som används här är en platshållare som behövs för förhandsversionen av 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\'  
);

Steg 8: Generera inbäddningar

ai_generate_embeddings Använd funktionen för att testa modellen genom att köra följande SQL:

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

Det här kommandot startar AIRuntimeHost, läser in nödvändiga DLL:er och bearbetar indatatexten.

Resultatet från SQL-instruktionen är en matris med inbäddningar:

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

Aktivera XEvent-telemetri

Kör följande SQL för att aktivera telemetri för felsökning.

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

Använd sedan den här SQL-frågan för att se den insamlade telemetrin:

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

Städa upp

Om du vill ta bort det externa modellobjektet kör du följande SQL:

DROP EXTERNAL MODEL myLocalOnnxModel;

Om du vill ta bort katalogbehörigheterna kör du följande PowerShell-kommandon:

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

Ta slutligen bort C:/onnx_runtime katalogen.

Relaterat innehåll

• ÄNDRA EXTERN MODELL (Transact-SQL)
• SLÄPP EXTERN MODELL (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL) (förhandsversion)
• sys.external_models
• Skapa och distribuera en Azure OpenAI i Azure AI Foundry Models-resurs
• Server-konfigurationsalternativ
• Rollbaserad åtkomstkontroll för Azure OpenAI i Azure AI Foundry Models