CREATE EXTERNAL MODEL (Transact-SQL)

Applies to: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL v databázi Microsoft Fabric

Vytvoří objekt externího modelu, který obsahuje umístění, metodu ověřování a účel koncového bodu odvozování modelu AI.

Poznámka:

CREATE EXTERNAL MODEL je k dispozici v Azure SQL Managed Instance s Always-up-to-dateupdate policy.

Syntaxe

Transact-SQL konvence syntaxe

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

Argumenty

external_model_object_name

Určuje uživatelem definovaný název externího modelu. Název musí být v databázi jedinečný.

owner_name

Určuje název uživatele nebo role, která vlastní externí model. Pokud tento argument nespecifikujete, současný uživatel se stane vlastníkem. V závislosti na oprávněních a rolích možná budete muset uživatelům udělit explicitní povolení používat konkrétní externí modely.

UMÍSTĚNÍ

Poskytuje protokol připojení a cestu ke koncovému bodu odvozování modelu AI.

API_FORMAT

Formát zprávy rozhraní API pro poskytovatele koncového bodu odvozování modelu AI

Přijaté hodnoty jsou:

  • Azure OpenAI
  • OpenAI
  • Ollama
  • ONNX Runtime

Typ modelu

Typ modelu, ke kterému se přistupuje z lokalizace koncového bodu inference AI modelu.

Přijaté hodnoty jsou:

  • EMBEDDINGS

MODEL

Konkrétní model hostovaný poskytovatelem AI. Například , text-embedding-ada-002, text-embedding-3-largenebo o3-mini.

OSVĚDČENÍ

Specifikuje DATABASE SCOPED CREDENTIAL objekt použitý s endpointem inference AI modelu. Pro více informací o přijatých typech přihlašovacích údajů a pravidlech pojmenování viz sp_invoke_external_rest_endpoint nebo sekci Poznámky v tomto článku.

Parametry

Platný JSON řetězec, který obsahuje parametry za běhu, které se přidávají ke zprávě o požadavku na koncovém konci AI modelu. Například:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH určuje adresář v místní instanci SQL Server, kde jsou umístěné spustitelné soubory MODULU RUNTIME ONNX.

Povolení

Vytvoření a změna externího modelu

Vyžaduje ALTER ANY EXTERNAL MODEL nebo CREATE EXTERNAL MODEL oprávnění k databázi.

Například:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Nebo:

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

Granty externího modelu

Pokud chcete ve funkci AI použít externí model, musí mu být udělena schopnost EXECUTE objektu zabezpečení.

Například:

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

Počet opakování

Pokud volání vkládání narazí na stavové kódy HTTP označující dočasné problémy, můžete požadavek nakonfigurovat tak, aby se automaticky zopakoval. Pokud chcete zadat počet opakování, přidejte do PARAMETERS pole na kartě EXTERNAL MODEL. Mělo <number_of_retries> by to být celé číslo mezi nulou (0) a deseti (10včetně) a nesmí být NULL ani záporné.

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

Například pro nastavení na retry_count 3 použijte následující JSON řetězec:

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

Počet opakování s jinými parametry

Můžete kombinovat počet opakování s jinými parametry, pokud je JSON řetězec platný.

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

Poznámky

HTTPS a TLS

Pro parametr LOCATION jsou podporovány pouze koncové body pro inferenci AI modelů nakonfigurované pro použití HTTPS s protokolem TLS pro šifrování.

Přijaté formáty rozhraní API a typy modelů

Následující sekce popisují akceptované formáty API pro každé MODEL_TYPE.

API_FORMAT pro VKLÁDÁNÍ

Tato tabulka popisuje formáty API a struktury koncových adres URL pro daný EMBEDDINGS typ modelu. Pokud chcete zobrazit konkrétní struktury datové části, použijte odkaz ve sloupci Formát rozhraní API.

Formát rozhraní API Formát cesty k umístění
Azure OpenAI https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI https://{server_name}/v1/embeddings
Ollama https:localhost://{port}/api/embed

Vytváření koncových bodů pro vkládání

Další informace o vytváření koncových bodů vkládání najdete na těchto odkazech pro příslušného poskytovatele koncového bodu odvozování modelu AI:

Pravidla pro označení přihlašovacích údajů pro externí model

Vytvořené DATABASE SCOPED CREDENTIAL externím modelem musí dodržovat tato pravidla:

  • Musí to být platná adresa URL.

  • URL doména musí být jednou z těchto domén zahrnutých v seznamu povolených.

  • Adresa URL nesmí obsahovat řetězec dotazu.

  • Protokol + plně kvalifikovaný název domény (FQDN) volané adresy URL se musí shodovat s protokolem a plně kvalifikovaným názvem domény názvu přihlašovacích údajů.

  • Každá část volané URL cesty musí zcela odpovídat příslušné části URL cesty v názvu přihlašovacích údajů.

  • Přihlašovací údaje musí ukazovat na cestu, která je obecnější než URL požadavku. Například přihlašovací údaje vytvořené pro path https://northwind.azurewebsite.net/customers nelze použít pro URL https://northwind.azurewebsite.net.

Pravidla kolace a názvu přihlašovacích údajů

RFC 3986 Oddíl 6.2.2.1 uvádí, že "Když URI používá komponenty obecné syntaxe, pravidla ekvivalence syntaxe jednotlivých komponent vždy platí; konkrétně, že schéma a moderátor nejsou citlivé na velikost písmen." RFC 7230 oddíl 2.7.3 uvádí, že "všechny ostatní jsou porovnávány způsobem citlivým na velikost a pád."

Protože je pravidlo kolace nastaveno na úrovni databáze, platí následující logika, která udržuje jednotné pravidlo třídění databáze a pravidla RFC. (Popsané pravidlo by mohlo být potenciálně restriktivnější než pravidla RFC, například pokud je databáze nastavena na použití sortace citlivé na velikost písmen.)

  1. Pomocí dokumentu RFC zkontrolujte, jestli se adresa URL a přihlašovací údaje shodují. To znamená:

    • Zkontrolujte schéma a hostitele pomocí kolace nerozlišující malá a velká písmena (Latin1_General_100_CI_AS_KS_WS_SC).
    • Zkontrolujte porovnání všech ostatních segmentů adresy URL v kolaci s rozlišováním velkých a malých písmen (Latin1_General_100_BIN2).

  2. Pomocí pravidel kolace databáze (a bez kódování adresy URL) zkontrolujte, jestli se adresa URL a přihlašovací údaje shodují.

Spravovaná identita

Použití spravované identity hostitele Arc/VM jako přihlašovacích údajů na úrovni databáze v SQL Server 2025 (17.) x), musíte povolit možnost pomocí sp_configure s uživatelem, který je granted oprávnění na úrovni serveru ALTER SETTINGS.

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

SCHEMABINDING

Zobrazení vytvořená pomocí příkazu SCHEMABINDING, která odkazují na externí model (například příkaz SELECT pomocí příkazu AI_GENERATE_EMBEDDINGS), nelze odstranit a Database Engine vyvolá chybu. Pro odstranění závislostí odkazujících na externí model je nejprve nutné upravit nebo zrušit definici pohledu.

Zobrazení katalogu

Metadata externího modelu můžete zobrazit dotazem v sys.external_models katalogu. Musíte mít přístup k modelu, abyste mohli zobrazit jeho metadata.

SELECT *
FROM sys.external_models;

Příklady se vzdálenými koncovými body

Vytvoření EXTERNÍHO MODELU s Azure OpenAI pomocí spravované identity

Tento příklad vytvoří externí model typu EMBEDDINGS pomocí Azure OpenAI a pro ověřování používá Managed Identity.

V SQL Server 2025 (17.x) a novějších verzích musíte připojit SQL Server k Azure Arc a pojení primární spravované identity.

Důležité

Pokud používáte spravovanou identitu s Azure OpenAI a SQL Server 2025 (17.x), musí být role Sourcové služby OpenAI udělena SQL Server spravovanou identitu přiřazenou systémem povolenou Azure Arc. Další informace najdete v tématu Řízení přístupu na základěrole pro Azure OpenAI v modelech Azure AI Foundry.

Vytvořte přihlašovací údaje pro přístup pro Azure OpenAI pomocí spravované identity:

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

Vytvořte externí 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/]
);

Vytvoření externího modelu s Azure OpenAI pomocí klíčů a parametrů rozhraní API

Tento příklad vytvoří externí model typu EMBEDDINGS pomocí Azure OpenAI a k ověřování používá klíče rozhraní API. Příklad také používá PARAMETERS k nastavení parametru dimenzí na koncovém bodu na 725.

Vytvořte přihlašovací údaje pro přístup pro Azure OpenAI pomocí klíče:

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

Vytvořte externí 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}'
);

Vytvoření EXTERNÍHO MODELU s Ollama a explicitním vlastníkem

Tento příklad vytváří externí model EMBEDDINGS tohoto typu využívající Ollamu hostovanou lokálně pro vývojové účely.

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

Vytvoření EXTERNÍho MODELU pomocí OpenAI

Tento příklad vytváří externí model EMBEDDINGS tohoto typu s využitím přihlašovacích údajů založených na OpenAI API_FORMAT a HTTP hlavičkách pro autentizaci.

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

Příklad s lokálně běžícím runtime ONNX

ONNX Runtime je opensourcový modul pro odvozování, který umožňuje spouštět modely strojového učení místně, takže je ideální pro integraci funkcí AI do SQL Server prostředí.

Tento příklad vás provede nastavením SQL Server 2025 (17.x) s modulem runtime ONNX, aby se povolilo generování textu využívajících místní AI. Platí pouze pro Windows.

Důležité

Tato funkce vyžaduje instalaci služeb SQL Server Machine Learning.

Bezpečnostní aspekty

Pomocí funkce Hostitel modulu runtime AI můžete nakonfigurovat a používat vlastní knihovny LLM a ONNX s SQL Server. Vzhledem k tomu, že Microsoft neověřuje ani nemonitoruje modely a knihovny třetích stran, zodpovídáte za výběr vhodných modelů a knihoven, filtrování obsahu, zabezpečení modulu runtime a zajištění souladu s příslušnými zásadami a předpisy.

Upozornění

Škodlivý nebo ohrožený model ONNX může exfiltrovat data nebo spustit neoprávněný kód. Používejte pouze modely z důvěryhodných ověřených zdrojů.

Pokud chcete tato rizika zmírnit, zvažte následující osvědčené postupy zabezpečení:

  • Implementujte silné řízení přístupu: Zajistěte, aby k citlivým datům a modelům modulu runtime ONNX měli přístup jenom autorizovaní uživatelé. Před načtením do SQL Server ověřte všechny modely. Použijte princip nejnižších oprávnění, stejně jako databázové role a oprávnění.
  • Monitorování a audit přístupu: Pravidelně monitorujte a auditujte přístup k databázi a AI_GENERATE_EMBEDDINGS volání funkcí za účelem zjištění podezřelé aktivity.
  • Provádění pravidelných posouzení zabezpečení: Proveďte kontroly ohrožení zabezpečení a kontroly zabezpečení za účelem identifikace a zmírnění potenciálních rizik.

Krok 1: Povolení funkcí ve verzi Preview pro vývojáře v SQL Server 2025

Spuštěním následujícího příkazu Transact-SQL (T-SQL) povolte v databázi funkce preview SQL Server 2025 (17.x), které chcete použít v tomto příkladu:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Krok 2: Povolení místního modulu runtime AI v SQL Server 2025

Povolte externí AI runtime spuštěním následujícího T-SQL dotazu:

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

Krok 3: Nastavte knihovnu ONNX Runtime

Vytvořte v instanci SQL Server adresář pro uložení souborů knihovny MODULU RUNTIME ONNX. V tomto příkladu C:\onnx_runtime se používá.

K vytvoření adresáře můžete použít následující příkazy:

cd C:\
mkdir onnx_runtime

Dále si stáhněte verzi ONNX Runtime (1.19 nebo vyšší), která je vhodná pro váš operační systém. Po rozbalení stahování zkopírujte onnxruntime.dll (umístěný v adresáři lib) do vytvořeného C:\onnx_runtime adresáře.

Krok 4: Nastavení knihovny tokenizace

Stáhněte a sestavte v tokenizers-cpp knihovnu z GitHub. Po vytvoření knihovny DLL umístěte tokenizátor do C:\onnx_runtime adresáře.

Poznámka:

Ujistěte se, že vytvořená knihovna DLL má název tokenizers_cpp.dll

Krok 5: Stažení modelu ONNX

Začněte vytvořením model adresáře v souboru C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

Tento příklad používá all-MiniLM-L6-v2-onnx model, který lze stáhnout z Hugging Face.

Naklonujte úložiště do C:\onnx_runtime\model adresáře pomocí následujícího příkazu Git :

Pokud není nainstalovaný, můžete git stáhnout z následujícího odkazu download link nebo prostřednictvím wingetu (instalace wingetu Microsoft). Git)

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

Krok 6: Nastavení oprávnění adresáře

Použijte následující PowerShell skript, abyste uživateli MSSQLLaunchpad poskytli přístup k adresáři ONNX Runtime:

$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

Krok 7: Vytvoření externího modelu

Spustěte následující dotaz pro registraci vašeho ONNX modelu jako externího modelového objektu:

Hodnota PARAMETERS je zástupný symbol potřebný pro 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 Mělo by ukazovat na adresář obsahující model.onnx soubory a tokenizer.json soubory.
  • LOCAL_RUNTIME_PATH Mělo by ukazovat na adresář obsahující onnxruntime.dll soubory a tokenizer_cpp.dll soubory.

Krok 8: Generování vkládání

Použijte ai_generate_embeddings tuto funkci k otestování modelu spuštěním následujícího dotazu:

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

Tento příkaz spustí AIRuntimeHost, načtěte požadované knihovny DLL a zpracuje vstupní text.

Výsledkem předchozího dotazu je pole vnoření:

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

Povolit systémové logování XEvent

Spusť následující dotaz pro povolení systémového logování pro řešení problémů.

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

Dále použijte tento dotaz a podívejte se na zachycené systémové logy:

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

Vyčištění

Pro odstranění externího objektu modelu spusťte následující příkaz T-SQL:

DROP EXTERNAL MODEL myLocalOnnxModel;

Pokud chcete odebrat oprávnění adresáře, spusťte následující příkazy PowerShellu:

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

Nakonec adresář odstraňte C:/onnx_runtime .

Související obsah

  • Last updated on