KÜLSŐ MODELL LÉTREHOZÁSA (Transact-SQL)

Vonatkozik a következőkre: SQL Server 2025 (17.x) Azure SQL DatabaseSQL database in Microsoft Fabric

Létrehoz egy külső modellobjektumot, amely egy AI-modell következtetési végpontjának helyét, hitelesítési módját és célját tartalmazza.

Szemantika

Transact-SQL szintaxis konvenciók

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

Érvek

external_model_object_name

Megadja a külső modell felhasználó által definiált nevét. A névnek egyedinek kell lennie az adatbázisban.

owner_name

A külső modellt birtokbavevő felhasználó vagy szerepkör nevét adja meg. Ha nem határozod meg ezt az érvet, a jelenlegi felhasználó lesz a tulajdonos. A jogosultságoktól és szerepkörektől függően előfordulhat, hogy kifejezetten engedélyt kell adni a felhasználóknak bizonyos külső modellek használatára.

HELYSZÍN

Megadja az AI-modell következtetési végpontjának csatlakozási protokollt és elérési útját.

API_FORMAT

Az AI-modell következtetési végpontszolgáltatójának API-üzenetformátuma.

Az elfogadott értékek a következők:

• Azure OpenAI
• OpenAI
• Ollama
• ONNX Runtime

MODELL_TÍPUS

Az MI modell típusa, amelyet az AI modell következtetési végpontjának helyéről érnek el.

Az elfogadott értékek a következők:

• EMBEDDINGS

MODELL

Az AI-szolgáltató által üzemeltetett konkrét modell. Például, text-embedding-ada-002vagy text-embedding-3-largeo3-mini.

IGAZOLVÁNY

Megadja az DATABASE SCOPED CREDENTIAL objektumot, amelyet az AI modell következtetési végpontjával használnak. További információért az elfogadott képesítéstípusokról és elnevezési szabályokról lásd a cikk sp_invoke_external_rest_endpoint vagy a megjegyzések részét.

PARAMÉTEREK

Egy érvényes JSON string, amely futási paramétereket tartalmaz, amelyeket az AI modell következtetési végpont kérés üzenetéhez lehet csatolni. Például:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH megadja a helyi SQL Server példányban található könyvtárat, ahol az ONNX futtatható fájlok találhatók.

Engedélyek

Külső modell létrehozása és módosítása

Adatbázis-engedélyre van ALTER ANY EXTERNAL MODEL szükségCREATE EXTERNAL MODEL.

Például:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Vagy:

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

Külső modelltámogatások

Ha külső modellt szeretne használni egy AI-függvényben, a rendszerbiztonsági tagnak meg kell adni annak a képességét EXECUTE .

Például:

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

Újrapróbálkozások száma

Ha a beágyazási hívás átmeneti problémákat jelző HTTP-állapotkódokkal találkozik, konfigurálhatja a kérést az automatikus újrapróbálkozásokra. Az újrapróbálkozések számának megadásához adja hozzá a következő JSON-t a következőhöz.PARAMETERSEXTERNAL MODEL A <number_of_retries> nulla (0) és a tíz (10) közötti egész számnak kell lennie, beleértve, és nem lehet NULL vagy negatív.

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

Például a 3-ra állításához retry_count a következő JSON láncsort használjuk:

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

Újrapróbálkozások száma más paraméterekkel

Kombinálhatod az újrapróbálkozási számot más paraméterekkel, amennyiben a JSON string érvényes.

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

Megjegyzések

HTTPS és TLS

A LOCATION paraméter esetében csak olyan AI modell következtetési végpontok támogatottak, amelyek úgy konfiguráltak, hogy használják az HTTPS-t a TLS titkosítási protokollval.

Elfogadott API-formátumok és modelltípusok

Az alábbi szakaszok bemutatják az elfogadott API formátumokat minden MODEL_TYPEegyes .

API_FORMAT a EMBEDDINGS-hez

Ez a táblázat a modelltípus API formátumait és URL végpontstruktúráit EMBEDDINGS vázolja fel. Adott hasznos adatstruktúrák megtekintéséhez használja az API Formátum oszlopában található hivatkozást.

API-formátum	Hely elérési útja formátuma
Azure OpenAI	https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI	https://{server_name}/v1/beágyazások
Ollama	https://localhost:{port}/api/embed

Beágyazási végpontok létrehozása

A beágyazási végpontok létrehozásával kapcsolatos további információkért használja az alábbi hivatkozásokat a megfelelő AI-modell következtetési végpontszolgáltatójához:

• Azure OpenAI az Azure AI Foundry-modellekben
• OpenAI
• Ollama

Hitelesítési névszabályok külső modellhez

A külső modell által létrehozott DATABASE SCOPED CREDENTIAL alkotásoknak az alábbi szabályokat kell követniük:

• Érvényes URL-címnek kell lennie

• Az URL domain az engedélyezett listán szereplő domain egyikének kell lennie.

• Az URL-cím nem tartalmazhat lekérdezési sztringet

• A hívott URL protokoll + teljes tartománynévnek (FQDN) meg kell egyeznie a hitelesítőadat-név protokoll + teljes tartományneve

• A hívott URL út minden részének teljesen meg kell egyeznie az URL útjának megfelelő részével a hitelesítés névben.

• Az igazolványnak egy olyan útvonalra kell mutatnia, amely általánosabb, mint a kérés URL-je. Például egy úthoz https://northwind.azurewebsite.net/customers létrehozott hitelesítő érték nem használható az URL-hez https://northwind.azurewebsite.net.

Rendezési és hitelesítő adatok névszabályai

Az RFC 3986 6.2.2.1. szakasza kimondja, hogy "Amikor egy URI a generikus szintaxis komponenseit használja, a komponensszintaxis-ekvivalencia szabályai mindig érvényesek; nevezetesen, hogy a rendszer és a host a kis- és korosztály érzéketlen." Az RFC 7230 2.7.3. szakasza megemlíti, hogy "minden más esetben kiskor-érzékeny módon hasonlítják össze."

Mivel az adatbázis szintjén egy összeállítási szabályt állítanak be, a következő logika érvényes az adatbázis-összeállítási szabály és az RFC szabályok következetességének megőrzéséhez. (A leírt szabály akár korlátozóbb is lehet, mint az RFC szabályok, például ha az adatbázis kis- és kisméretre érzékeny összeállítást alkalmaz.

1. Ellenőrizze, hogy az URL-cím és a hitelesítő adatok megegyeznek-e az RFC használatával, ami a következőt jelenti:

   • Ellenőrizze a sémát és a gazdagépet a kis- és nagybetűk megkülönböztetésével (Latin1_General_100_CI_AS_KS_WS_SC)
   • Ellenőrizze, hogy az URL-cím összes többi szegmense összehasonlítva van-e a kis- és nagybetűk megkülönböztetésével (Latin1_General_100_BIN2)

2. Ellenőrizze, hogy az URL-cím és a hitelesítő adatok egyeznek-e az adatbázis-rendezési szabályokkal (és az URL-kódolás nélkül).

Felügyelt identitás

Az Arc/VM host menedzselt identitását adatbázis-szintű hitelesítésként használni az SQL Server 2025 (17.x) programjában, ezt az opciót olyan felhasználóval kell engedélyezni sp_configure , aki megkapta az ALTER SETTINGS szerverszintű engedélyt.

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

SÉMAKÖTÉS

Az ilyen külső modell hivatkozásával létrehozott nézetek SCHEMABINDING (például egy SELECT utasítás, amely ) AI_GENERATE_EMBEDDINGSnem hagyható ki, és az Database Engine hibát okoz. Ahhoz, hogy eltávolítsuk a külső modellre hivatkozó függőségeket, először módosítani vagy el kell távolítani a nézet definícióját.

Katalógus nézet

Külső modell metaadatokat megtekinthetsz a sys.external_models katalógus nézetének lekérdezésével. Hozzáférésre van szükséged egy modellhez, hogy megtekinthesd annak metaadatait.

SELECT *
FROM sys.external_models;

Példák távoli végpontokkal

Külső modell létrehozása az Azure OpenAI-val felügyelt identitással

Ez a példa Azure OpenAI segítségével létrehoz egy külső modellt a EMBEDDINGS típusból, és a Managed Identity segítségével autentikál.

Az SQL Server 2025 (17.x) és újabb verziókban az SQL Serveredet az Azure Arc-hoz kell csatlakoztatnod , és be kell kapcsolnod az elsődleges menedzselt identitást.

Fontos

Ha a Managed Identity-t Azure OpenAI-val és SQL Server 2025-tel (17.x) használod, a Cognitive Services OpenAI Contributor szerepét az SQL Server rendszerhez rendelt menedzselt identitásának kell megadni, amelyet az Azure Arc engedélyez. További információért lásd: Role-based access control for Azure OpenAI in Azure AI Foundry Models.

Hozzon létre hozzáférési jogosultságokat Azure OpenAI-hoz egy menedzselt identitás segítségével:

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

Készítsd el a külső modellt:

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

Külső modell létrehozása Azure OpenAI-val API kulcsokkal és paraméterekkel

Ez a példa Azure OpenAI segítségével külső modellt EMBEDDINGS hoz létre a típusból, és API kulcsokat használ hitelesítéshez. A példa a végpont dimenzióparaméterének 725-ös értékre történő beállítására is használ PARAMETERS .

Hozzon létre hozzáférési credentials-okat Azure OpenAI-hoz egy kulcs segítségével:

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

Készítsd el a külső modellt:

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

Külső modell létrehozása Ollama és explicit tulajdonos használatával

Ez a példa egy külső modellt hoz létre olyan EMBEDDINGS típusból, amely Ollama-t használ, amelyet helyben üzemeltetnek fejlesztési célokra.

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

Külső modell létrehozása az OpenAI használatával

Ez a példa egy külső modellt hoz létre az EMBEDDINGS OpenAI API_FORMAT és HTTP fejléc-alapú hitelesítési adatok felhasználásával.

-- 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élda az ONNX Runtime-ra helyi futtatásával

Az ONNX Runtime egy nyílt forráskódú következtetési motor, amely lehetővé teszi gépi tanulási modellek helyi futtatását, így ideális az AI-képességek SQL Server-környezetekbe való integrálásához.

Ez a példa vezeti az SQL Server 2025 (17.x) beállítását ONNX Runtime-mal, hogy lehetővé tegye a helyi MI-alapú szövegbeágyazást. Csak Windows rendszeren érvényes.

Fontos

Ehhez a funkcióhoz telepítve kell lennie az SQL Server Machine Learning Services szolgáltatásnak.

1. lépés: Fejlesztői előzetes verziójú funkciók engedélyezése az SQL Server 2025-ben

Futtatd a következő Transact-SQL (T-SQL) parancsot, hogy engedélyezd az SQL Server 2025 (17.x) előnézeti funkciókat abban az adatbázisban, amit ehhez a példához szeretnél:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

2. lépés: A helyi AI-futtatókörnyezet engedélyezése az SQL Server 2025-ben

Engedélyezze a külső AI futási idők futtatását a következő T-SQL lekérdezéssel:

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

3. lépés: Állítsd be az ONNX Runtime könyvtárat

Hozz létre egy könyvtárat az SQL Server példányon, amely tartalmazza az ONNX Runtime könyvtárfájlokat. Ebben a példában C:\onnx_runtime a rendszer használja.

A címtár létrehozásához a következő parancsokat használhatja:

cd C:\
mkdir onnx_runtime

Ezután töltsd le az ONNX Runtime verziót (1.19 vagy ankarabb), ami illik az operációs rendszeredhez. A letöltés befejezése után másolja a onnxruntime.dll (lib könyvtárban található) könyvtárat a C:\onnx_runtime létrehozott könyvtárba.

4. lépés: A tokenizálási kódtár beállítása

Töltse le és hozza létre a könyvtárat a tokenizers-cpp GitHubról. A dll létrehozása után helyezze a tokenizert a C:\onnx_runtime könyvtárba.

Megjegyzés:

Győződjön meg arról, hogy a létrehozott dll nevetokenizers_cpp.dll

5. lépés: Az ONNX-modell letöltése

Először hozza létre a könyvtárat a model következőben C:\onnx_runtime\: .

cd C:\onnx_runtime
mkdir model

Ez a példa a all-MiniLM-L6-v2-onnx modellt használja, amely az Ölelés arcról tölthető le.

Klónozza az adattárat a könyvtárba a C:\onnx_runtime\model következő Git-paranccsal :

Ha nincs telepítve, letöltheti a gitet a következő letöltési hivatkozásról vagy a wingeten keresztül (winget install Microsoft.Git)

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

6. lépés: Címtárengedélyek beállítása

Használja a következő PowerShell szkriptet az MSSQLLaunchpad felhasználójának hozzáféréséhez az ONNX Runtime könyvtárához:

$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

7. lépés: A külső modell létrehozása

Futtasd le a következő lekérdezést, hogy regisztráld az ONNX modellt külső modellobjektumként:

Az itt használt 'PARAMETERS' érték egy helykitöltő, amely SQL Server 2025 (17.x) esetén szükséges.

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

• LOCATIONa fájlokat model.onnx tartalmazó könyvtárra tokenizer.json kell mutatnia.
• LOCAL_RUNTIME_PATH a mappát tartalmazó onnxruntime.dll és tokenizer_cpp.dll fájlokra kell mutatnia.

8. lépés: Beágyazások létrehozása

Használja a ai_generate_embeddings függvényt a modell tesztelésére a következő lekérdezés futtatásával:

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

Ez a parancs elindítja a AIRuntimeHostszükséges DLL-eket, és feldolgozza a bemeneti szöveget.

Az előző lekérdezés eredménye egy beágyazások tömbje:

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

Engedélyezze az XEvent rendszernaplózást

Futtatd a következő lekérdezést, hogy engedélyezd a rendszernaplózást hibakereséshez.

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

Ezután használd ezt a lekérdezést, és nézd meg a rögzített rendszernaplókat:

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

Takarítás

A külső modellobjektum eltávolításához futtassuk le a következő T-SQL utasítást:

DROP EXTERNAL MODEL myLocalOnnxModel;

A címtárengedélyek eltávolításához futtassa a következő PowerShell-parancsokat:

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

Végül törölje a könyvtárat C:/onnx_runtime .

Kapcsolódó tartalom

• KÜLSŐ MODELL MÓDOSÍTÁSA (Transact-SQL)
• KÜLSŐ MODELL (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL)
• sys.external_models
• Azure OpenAI létrehozása és üzembe helyezése az Azure AI Foundry Models erőforrásban
• kiszolgáló konfigurációs beállításai
• Szerepköralapú hozzáférés-vezérlés az Azure OpenAI-hoz az Azure AI Foundry-modellekben