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 není zadáno, je vlastnictví uděleno aktuálnímu uživateli. V závislosti na oprávněních a rolích je potřeba uživatelům udělit explicitní oprávnění, aby mohli 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ý se přistupuje z umístění koncového bodu odvozování modelu AI.

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Í

Určuje, který DATABASE SCOPED CREDENTIAL objekt se používá s koncovým bodem odvozování modelu AI. Další informace o přijatých typech přihlašovacích údajů a pravidlech pojmenování najdete v sp_invoke_external_rest_endpoint nebo v části Poznámky tohoto článku.

Parametry

Platný řetězec JSON obsahující parametry modulu runtime, které se mají připojit ke zprávě požadavku koncového bodu odvozování modelu AI. Například:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH určuje adresář na místním SQL Serveru, 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> } }

Pokud například chcete nastavit retry_count hodnotu 3, napíšete následující řetězec JSON:

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

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

Počet opakování lze také kombinovat s dalšími parametry, pokud se jedná o platný řetězec JSON.

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

Poznámky

HTTPS a TLS

Parametr podporuje LOCATION pouze koncové body odvozování modelů AI, které jsou nakonfigurované tak, aby používaly protokol HTTPS s protokolem šifrování TLS.

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

Následující části popisují akceptované formáty rozhraní API pro každý MODEL_TYPE.

API_FORMAT pro VKLÁDÁNÍ

Tato tabulka popisuje struktury koncových bodů rozhraní API a formátů adresy URL pro 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 názvu přihlašovacích údajů pro EXTERNÍ MODEL

Vytvořené uživatelem DATABASE SCOPED CREDENTIALEXTERNAL MODEL musí dodržovat určitá následující pravidla:

Musí to být platná adresa URL.
Doména adresy URL 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 pojmenované cesty URL se musí zcela shodovat s odpovídající částí cesty URL v názvu přihlašovacích údajů.
Přihlašovací údaje musí odkazovat na cestu, která je obecnější než adresa URL požadavku. Například přihlašovací údaje vytvořené pro cestu https://northwind.azurewebsite.net/customers nejde použít pro adresu 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 "Pokud identifikátor URI používá součásti obecné syntaxe, pravidla ekvivalence syntaxe součástí vždy platí; a sice, že režim a hostitel nerozlišují malá a velká písmena" a rfc 7230 oddíl 2.7.3 uvádí, že "všechny ostatní se porovnávají způsobem citlivým na malá a velká písmena".

Vzhledem k tomu, že na úrovni databáze existuje sada pravidel kolace, použije se následující logika, která bude koherentní s pravidlem kolace databáze a dokument RFC zmíněn dříve. (Popsané pravidlo může být potenciálně více omezující než pravidla RFC, například pokud je databáze nastavená tak, aby používala kolaci s rozlišováním velkých a malých 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

Chcete-li použít spravovanou identitu pro ověřování na SQL Serveru 2025, musíte povolit možnost pomocí sp_configure uživatele, který má udělené oprávnění ALTER SETTINGS na úrovni serveru.

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

SCHEMABINDING

Vyřazení SCHEMABINDING zobrazení vytvořených pomocí EXTERNAL MODEL příkazu (například SELECT příkazu usingAI_GENERATE_EMBEDDINGS) se zabrání v případě, že databázový stroj vyvolá chybu. Samotná definice zobrazení musí být nejprve upravena nebo vyřazena, aby se odebraly závislosti odkazující na EXTERNAL MODEL.

Zobrazení katalogu

Metadata externího modelu je možné zobrazit pomocí dotazu na sys.external_models zobrazení katalogu. Poznámka: Abyste mohli zobrazit metadata, musíte mít přístup k modelu.

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 vytvoří typ EXTERNAL MODELEMBEDDINGS pomocí Azure OpenAI a pro ověřování používá spravovanou identitu .

Důležité

Pokud používáte spravovanou identitu s Azure OpenAI a SQL Serverem 2025, musí být role přispěvatele OpenAI služeb Cognitive Services udělena spravované identitě přiřazené systémem SQL Serveru, kterou povolil Azure Arc. Další informace najdete v tématu Řízení přístupu na základě role pro Azure OpenAI v modelech Azure AI Foundry.

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

Vytvoření EXTERNÍho MODELU pomocí Azure OpenAI pomocí klíčů a parametrů rozhraní API

Tento příklad vytvoří typ EXTERNAL MODELEMBEDDINGS 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.

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

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

Tento příklad vytvoří EXTERNAL MODEL typ EMBEDDINGS pomocí Ollama hostovaného místně pro účely vývoje.

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 vytvoří EXTERNAL MODEL typ EMBEDDINGS pomocí přihlašovacích údajů založených na hlavičce OpenAI API_FORMAT a HTTP pro ověřování.

-- 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 místním modulem runtime ONNX

Tento příklad vás provede nastavením SQL Serveru 2025 s modulem runtime ONNX, který umožňuje generování textu využívajícího místní AI. Platí jenom pro Windows.

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.

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

Spuštěním následujícího příkazu SQL povolte funkce SQL Serveru 2025 Preview v databázi, kterou chcete použít v tomto příkladu:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Krok 2: Povolení místního modulu runtime AI na SQL Serveru 2025

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

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

Krok 3: Nastavení knihovny modulu runtime ONNX

Vytvořte na SQL Serveru 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 modul runtime ONNX (verze ≥ 1.19), 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

Pomocí následujícího skriptu PowerShellu poskytněte uživateli MSSQLLaunchpad přístup k adresáři modulu runtime ONNX:

$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

Spuštěním následujícího SQL zaregistrujte model ONNX jako objekt externího modelu:

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í

ai_generate_embeddings Pomocí funkce otestujte model spuštěním následujícího SQL:

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říkazu SQL je pole embeddings:

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

Povolení telemetrie XEvent

Spuštěním následujícího SQL povolte telemetrii pro řešení potíží.

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 SQL, podívejte se na zachycenou telemetrii:

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í

Pokud chcete odebrat objekt externího modelu, spusťte následující příkaz 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-11-19