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

2025-06-30

A következőkre vonatkozik: SQL Server 2025 (17.x) előzetes verzió

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-ada-002'
    [ , CREDENTIAL = <credential_name> ]
    [ , PARAMETERS = '{"valid":"JSON"}' ]
  );

É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 nincs megadva, a tulajdonjog az aktuális felhasználónak lesz megadva. Az engedélyektől és szerepköröktől függően explicit engedélyt kell adni a felhasználóknak adott 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

MODELL_TÍPUS

Az AI-modell következtetési végpontjának helyéről elérhető modell típusa.

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

DATABASE SCOPED CREDENTIAL Az AI-modell következtetési végpontjához használt objektum megjelölése. Az elfogadott hitelesítő adatok típusairól és elnevezési szabályairól további információt sp_invoke_external_rest_endpoint vagy a cikk Megjegyzések szakaszában talál.

PARAMÉTEREK

Érvényes JSON-sztring, amely futásidejű paramétereket tartalmaz, amelyeket hozzá kell fűzni az AI-modell következtetési végpontkérési üzenetéhez. Például:

'{ "Dimensions": 1536 }'

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> } }

Ha például a retry_count 3 értéket szeretné beállítani, a következő JSON-sztringet kell írnia:

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

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

Az újrapróbálkozások száma más paraméterekkel is kombinálható, amennyiben érvényes JSON-sztringről van szó.

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

Megjegyzések

HTTPS és TLS

A paraméter csak a HTTPS TLS titkosítási protokollal való használatára konfigurált AI-modell következtetési LOCATION végpontjait támogatja.

Elfogadott API-formátumok és modelltípusok

Az alábbi szakaszok az egyes MODEL_TYPEapi-formátumokat ismertetik.

API_FORMAT a EMBEDDINGS-hez

Ez a táblázat a modelltípus API-formátumait és URL-végpontstruktúráit EMBEDDINGS ismerteti. 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:

Külső MODELL hitelesítőadat-névszabályai

Az egy DATABASE SCOPED CREDENTIAL által létrehozottnak EXTERNAL MODEL be kell tartania a következő szabályokat:

Érvényes URL-címnek kell lennie
Az URL-tartománynak az engedélyezési lista egyik tartományának 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-elérési út minden részének teljesen meg kell egyeznie az URL-elérési út megfelelő részével a hitelesítő adatok nevében
A hitelesítő adatoknak egy általánosabb elérési útra kell mutatniuk, mint a kérelem URL-címe. A https://northwind.azurewebsite.net/customers elérési úthoz létrehozott hitelesítő adatok például nem használhatók az URL-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 az általános szintaxis összetevőit használja, az összetevő szintaxisának egyenértékűségi szabályai mindig érvényesek; nevezetesen, hogy a rendszer és a gazdagép nem érzékeny a kis- és nagybetűkre", és az RFC 7230 2.7.3 szakasza megemlíti, hogy "minden mást kis- és nagybetűk megkülönböztetésével hasonlítanak össze".

Mivel az adatbázis szintjén egy rendezési szabály van beállítva, a rendszer az alábbi logikát alkalmazza, hogy összhangban legyen az adatbázis-rendezési szabállyal és a korábban említett RFC-vel. (A leírt szabály esetleg szigorúbb lehet az RFC-szabályoknál, például ha az adatbázis kis- és nagybetűk megkülönböztetésére van beállítva):

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

Ha felügyelt identitást szeretne használni az SQL Server 2025 hitelesítéséhez, engedélyeznie kell a beállítást egy olyan felhasználóval sp_configure , aki rendelkezik az ALTER SETTINGS kiszolgálószintű engedélyével.

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

SÉMAKÖTÉS

Ha az adatbázismotor hibát jelez, a rendszer megakadályozza a létrehozott SCHEMABINDING nézetek elvetését, és hivatkozik egy EXTERNAL MODEL (például SELECT egy utasítást használó) parancsra AI_GENERATE_EMBEDDINGS. Magát a nézetdefiníciót először módosítani vagy elvetni kell, hogy eltávolítsa azokat a függőségeket, amelyre hivatkozik.EXTERNAL MODEL

Katalógusnézet

A külső modell metaadatai a sys.external_models katalógusnézet lekérdezésével tekinthetők meg. Vegye figyelembe, hogy a metaadatok megtekintéséhez hozzáféréssel kell rendelkeznie egy modellhez.

SELECT * FROM sys.external_models;

Példák

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

Ez a példa létrehoz egy típust EXTERNAL MODEL az EMBEDDINGS Azure OpenAI használatával, és felügyelt identitást használ a hitelesítéshez.

Fontos

Ha felügyelt identitást használ az Azure OpenAI és az SQL Server 2025 használatával, a Cognitive Services OpenAI-közreműködői szerepkört meg kell adni az SQL Server Azure Arc által engedélyezett, rendszer által hozzárendelt felügyelt identitásának. További információ: Szerepköralapú hozzáférés-vezérlés az Azure OpenAI-hoz az Azure AI Foundry-modellekben.

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

Külső modell létrehozása az Azure OpenAI-val API-kulcsok és paraméterek használatával

Ez a példa létrehoz egy típust EXTERNAL MODEL az EMBEDDINGS Azure OpenAI használatával, és API-kulcsokat használ a hitelesítéshez. A példa a Dimenziók paraméter végponton való beállítását is 725-ös értékre állítja PARAMETERS .

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

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

Ez a példa létrehoz egy típust EXTERNAL MODEL a EMBEDDINGS helyileg üzemeltetett Ollama használatával 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 létrehoz egy típust EXTERNAL MODEL az EMBEDDINGS OpenAI API_FORMAT - és HTTP-fejlécalapú hitelesítő adatokkal a hitelesítéshez.

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

Megosztás a következőn keresztül: