VYTVOŘIT EXTERNÍ MODEL (Transact-SQL)

Platí na: SQL Server 2025 (17.x) Azure SQL Database SQL database in 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.

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 specifikuje adresář na lokální instanci SQL Serveru, kde se nacházejí spustitelné soubory ONNX Runtime.

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:

Azure OpenAI v rámci modelů Azure AI Foundry
OpenAI
Ollama

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

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

Pro použití spravované identity hostitele Arc/VM jako přihlašovací údaje na úrovni databáze v SQL Server 2025 (17.x) musíte tuto možnost povolit pomocí sp_configure uživatele, kterému je uděleno oprávnění ALTER SETTINGS na úrovni serveru.

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

SCHEMABINDING

Pohledy vytvořené pomocí SCHEMABINDING externího modelu (například SELECT příkaz používající AI_GENERATE_EMBEDDINGS) nelze vyřadit a databázový engine zobrazí 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 pomocí Azure OpenAI s využitím spravované identity

Tento příklad vytváří externí model EMBEDDINGS tohoto typu pomocí Azure OpenAI a používá Managed Identity pro autentizaci.

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

Důležité

Pokud používáte spravovanou identitu s Azure OpenAI a SQL Server 2025 (17.x), role Cognitive Services OpenAI Contributor musí být přidělena systému přiřazené spravované identitě SQL Serveru, kterou aktivuje Azure Arc. Pro více informací viz Řízení přístupu založené na rolích pro Azure OpenAI v Azure AI Foundry Models.

Vytvořte přístupové údaje k 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řte externí model s Azure OpenAI pomocí API klíčů a parametrů

Tento příklad vytváří externí model EMBEDDINGS tohoto typu pomocí Azure OpenAI a používá API klíče pro autentizaci. Příklad také používá PARAMETERS k nastavení parametru dimenzí na koncovém bodu na 725.

Vytvořte přístupové údaje k 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 prostředí SQL Serveru.

Tento příklad vás provede nastavením SQL Server 2025 (17.x) s ONNX Runtime, aby bylo možné generovat textové embedding lokální AI. Platí jenom pro Windows.

Důležité

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

Krok 1: Povolení funkcí verze Preview pro vývojáře na SQL Serveru 2025

Spustěte následující příkaz Transact-SQL (T-SQL) pro povolení funkcí preview SQL Server 2025 (17.x) v databázi, kterou chcete použít pro tento příklad:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Krok 2: Povolení místního modulu runtime AI na SQL Serveru 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 adresář na instanci SQL Serveru, který bude obsahovat knihovní soubory ONNX Runtime. 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 knihovnu z GitHubutokenizers-cpp. 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 ke stažení nebo přes winget (winget install 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' použitá zde je zástupná 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 .

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-12-08