SKAPA EXTERN MODELL (Transact-SQL)

Gäller för: SQL Server 2025 (17.x) Azure SQL DatabaseSQL database in Microsoft Fabric

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 du inte specificerar detta argument blir den nuvarande användaren ägare. Beroende på behörigheter och roller kan du behöva ge uttryckliga tillstånd till användare 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

Typen av modell som nås från AI-modellens slutpunktsplats.

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

Specificerar objektet DATABASE SCOPED CREDENTIAL som används med AI-modellens slutpunkt. För mer information om godkända behörighetstyper och namngivningsregler, se sp_invoke_external_rest_endpoint eller avsnittet Kommentarer i denna artikel.

PARAMETRAR

En giltig JSON-sträng som innehåller körtidsparametrar att lägga till AI-modellens slutpunktsförfrågningsmeddelande. Till exempel:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH specificerar katalogen på den lokala SQL Server-instansen där ONNX Runtime-exekverbara 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> } }

Till exempel, för att sätta till retry_count 3, använd följande JSON-sträng:

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

Antal återförsök med andra parametrar

Du kan kombinera omprövningsräkning med andra parametrar så länge JSON-strängen är giltig.

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

Anmärkningar

HTTPS och TLS

För parametern LOCATION stöds endast AI-modellinferens-endpoints konfigurerade för att använda HTTPS med TLS-krypteringsprotokollet.

Godkända API-format och modelltyper

Följande avsnitt beskriver accepterade API-format för varje MODEL_TYPE.

API_FORMAT för EMBEDDINGS

Denna tabell visar API-formaten och URL-endpointstrukturerna för EMBEDDINGS modelltypen. Om du vill visa specifika nyttolaststrukturer använder du länken i kolumnen API Format.

API-format	Sökvägsformat för plats
Azure OpenAI	https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI	https://{server_name}/v1/embeddings
Ollama	https://localhost:{port}/api/embed

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 i Azure AI Foundry-modeller
• OpenAI
• Ollama

Regler för legitimationsnamn för extern modell

Den som skapas DATABASE SCOPED CREDENTIAL av en extern modell måste följa dessa regler:

• Måste vara en giltig URL

• URL-domänen måste vara en av de domäner som ingår i tillåtslistan.

• 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 anropade URL-sökvägen måste helt matcha respektive del av URL-vägen i legitimationsnamnet.

• Behörigheten måste peka på en sökväg som är mer generell än förfrågnings-URL:n. Till exempel kan en inloggningsinformation som skapats för sökväg https://northwind.azurewebsite.net/customers inte användas för URL https://northwind.azurewebsite.net:en .

Namnregler för sortering och autentiseringsuppgifter

RFC 3986 avsnitt 6.2.2.1 anger att "När en URI använder komponenter av den generiska syntaxen gäller alltid reglerna för komponentsyntaxekvivalens; nämligen att schemat och värden är kasus-okänsliga." RFC 7230 avsnitt 2.7.3 nämner att "alla andra jämförs på ett fallkänsligt sätt."

Eftersom en samlingsregel är satt på databasnivå gäller följande logik för att hålla databasens och RFC-reglerna konsekventa. (Den beskrivna regeln kan potentiellt vara mer restriktiv än RFC-reglerna, till exempel om databasen är inställd på att använda en kasuskänslig kollation.)

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

För att använda den hanterade identiteten för Arc/VM-värden som en databasnivålegitimation i SQL Server 2025 (17.x) måste du aktivera alternativet genom att använda sp_configure med en användare som har serverbehörigheten ALTER SETTINGS.

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

SCHEMABINDNING

Vyer skapade med SCHEMABINDING den referensen till en extern modell (såsom ett SELECT uttalande med AI_GENERATE_EMBEDDINGS) kan inte tas bort, och databasmotorn ger ett felmeddelande. För att ta bort beroenden som refererar till en extern modell måste du först ändra eller ta bort vydefinitionen.

Katalogvy

Du kan se extern modellmetadata genom att söka i sys.external_models katalogvyn. Du måste ha tillgång till en modell för att kunna se dess metadata.

SELECT *
FROM sys.external_models;

Exempel med fjärrslutpunkter

Skapa en EXTERN MODELL med Azure OpenAI med hanterad identitet

Detta exempel skapar en extern modell av typen EMBEDDINGS med Azure OpenAI och använder Managed Identity för autentisering.

I SQL Server 2025 (17.x) och senare versioner måste du koppla din SQL Server till Azure Arc och aktivera den primära hanterade identiteten.

Viktigt!

Om du använder Managed Identity med Azure OpenAI och SQL Server 2025 (17.x) måste rollen Cognitive Services OpenAI Contributor tilldelas SQL Servers systemtilldelade managed identity som aktiveras av Azure Arc. För mer information, se Rollbaserad åtkomstkontroll för Azure OpenAI i Azure AI Foundry Models.

Skapa åtkomstuppgifter till Azure OpenAI med en hanterad identitet:

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

Skapa den externa modellen:

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

Skapa en extern modell med Azure OpenAI med hjälp av API-nycklar och parametrar

Detta exempel skapar en extern modell av typen EMBEDDINGS med Azure OpenAI och använder API-nycklar för autentisering. Exemplet använder PARAMETERS också för att ange dimensionsparametern vid slutpunkten till 725.

Skapa åtkomstuppgifter till Azure OpenAI med en nyckel:

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

Skapa den externa modellen:

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

Skapa en EXTERN MODELL med Ollama och en explicit ägare

Detta exempel skapar en extern modell av typen EMBEDDINGS som använder Ollama som är lokalt värd för utvecklingsändamål.

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

Detta exempel skapar en extern modell av typen EMBEDDINGS med OpenAI API_FORMAT - och HTTP-headerbaserade inloggningsuppgifter för autentisering.

-- 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 ONNX Runtime som körs lokalt

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.

Detta exempel guidar dig genom att ställa in SQL Server 2025 (17.x) med ONNX Runtime för att möjliggöra lokal AI-driven textinbäddning. Det gäller endast i Windows.

Viktigt!

Den här funktionen kräver att SQL Server Machine Learning Services är installerat.

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

Kör följande Transact-SQL (T-SQL)-kommando för att aktivera SQL Server 2025 (17.x) förhandsvisningsfunktioner i den databas du vill använda för detta exempel:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

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

Aktivera extern AI-körtid genom att köra följande T-SQL-fråga:

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

Steg 3: Sätt upp ONNX Runtime-biblioteket

Skapa en katalog på SQL Server-instansen för att hålla ONNX Runtime-biblioteksfilerna. 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 ner en version av ONNX Runtime (1.19 eller högre) som passar ditt operativsystem. 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.

Anmärkning

Kontrollera att den skapade dll-filen heter tokenizers_cpp.dll

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

$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 fråga för att registrera din ONNX-modell som ett externt modellobjekt:

Värdet 'PARAMETERS' som används här är en platshållare som behövs för 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 ska peka på katalogen som innehåller model.onnx och tokenizer.json filer.
• LOCAL_RUNTIME_PATH ska peka på katalogen som innehåller onnxruntime.dll och tokenizer_cpp.dll filer.

Steg 8: Generera inbäddningar

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

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 föregående fråga är en array av inbäddningar:

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

Aktivera XEvent-systemloggning

Kör följande fråga för att aktivera systemloggning 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 denna fråga, se de infångade systemloggarna:

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

Städa upp

För att ta bort det externa modellobjektet, kör följande T-SQL-sats:

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