EXTERNES MODELL ERSTELLEN (Transact-SQL)

Gilt für: SQL Server 2025 (17.x) Azure SQL DatabaseSQL database in Microsoft Fabric

Erstellt ein externes Modellobjekt, das den Speicherort, die Authentifizierungsmethode und den Zweck eines AI-Modell-Ableitungsendpunkts enthält.

Syntax

Transact-SQL-Syntaxkonventionen

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

Argumente

external_model_object_name

Gibt den benutzerdefinierten Namen für das externe Modell an. Dieser Name muss innerhalb der Datenbank eindeutig sein.

"owner_name"

Gibt den Namen des Benutzers oder der Rolle an, der das externe Modell besitzt. Wenn du dieses Argument nicht spezifizierst, wird der aktuelle Nutzer zum Eigentümer. Je nach Berechtigungen und Rollen müssen Sie möglicherweise explizite Berechtigungen für bestimmte externe Modelle erteilen.

LAGERPLATZ

Stellt das Konnektivitätsprotokoll und den Pfad zum AI-Modell-Ableitungsendpunkt bereit.

API_FORMAT

Das API-Nachrichtenformat für den KI-Modell-Endpunktanbieter.

Akzeptierte Werte sind:

• Azure OpenAI
• OpenAI
• Ollama
• ONNX Runtime

MODEL_TYPE

Der Typ des Modells, der vom Standort des KI-Modell-Inferenzendpunkts abgerufen wird.

Akzeptierte Werte sind:

• EMBEDDINGS

MODELL

Das vom KI-Anbieter gehostete spezifische Modell. Beispiel: text-embedding-ada-002, text-embedding-3-large oder o3-mini.

BERECHTIGUNGSNACHWEIS

Spezifiziert das Objekt, das DATABASE SCOPED CREDENTIAL mit dem KI-Modell-Inferenz-Endpunkt verwendet wird. Weitere Informationen zu anerkannten Qualifikationstypen und Namensregeln finden Sie in sp_invoke_external_rest_endpoint oder im Abschnitt Bemerkungen dieses Artikels.

PARAMETER

Eine gültige JSON-Zeichenkette, die Laufzeitparameter enthält, die an die KI-Modell-Inferenz-Endpunktsanforderungsnachricht angehängt werden können. Beispiel:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH spezifiziert das Verzeichnis auf der lokalen SQL-Server-Instanz, in der sich die ONNX-Runtime-Executables befinden.

Erlaubnisse

Erstellung und Änderung des externen Modells

Erfordert ALTER ANY EXTERNAL MODEL oder CREATE EXTERNAL MODEL Datenbankberechtigung.

Beispiel:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Oder:

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

Externe Modellerteilungen

Um ein externes Modell in einer KI-Funktion zu EXECUTE verwenden, muss ihm ein Prinzipal gewährt werden.

Beispiel:

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

Anzahl von Wiederholungen

Wenn beim Einbettungsaufruf HTTP-Statuscodes auftreten, die temporäre Probleme angeben, können Sie die Anforderung so konfigurieren, dass die Anforderung automatisch erneut versucht wird. Um die Anzahl der Wiederholungen anzugeben, fügen Sie der Datei den folgenden JSON-Code hinzu.To specify the number of retries, add the following JSON to the on the PARAMETERSEXTERNAL MODEL. Dies <number_of_retries> sollte eine ganze Zahl zwischen Null (0) und zehn (10), einschließlich und darf nicht oder negativ sein NULL .

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

Zum Beispiel verwenden Sie zum Beispiel die folgende JSON-Zeichenkette, um die retry_count auf 3 zu setzen:

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

Wiederholungsanzahl mit anderen Parametern

Du kannst die Anzahl der Wiederholungen mit anderen Parametern kombinieren, solange der JSON-String gültig ist.

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

Bemerkungen

HTTPS und TLS

Für den Parameter LOCATION werden nur KI-Modell-Inferenz-Endpunkte unterstützt, die mit dem TLS-Verschlüsselungsprotokoll für HTTPS konfiguriert sind.

Akzeptierte API-Formate und Modelltypen

Die folgenden Abschnitte beschreiben akzeptierte API-Formate für jedes MODEL_TYPE.

API_FORMAT für EMBEDDINGS

Diese Tabelle beschreibt die API-Formate und URL-Endpunktstrukturen für den Modelltyp EMBEDDINGS . Verwenden Sie den Link in der Spalte "API-Format", um bestimmte Nutzlaststrukturen anzuzeigen.

API-Format	Pfadformat des Speicherorts
Azure OpenAI	https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI	https://{server_name}/v1/embeddings
Ollama	https:localhost://{port}/api/embed

Erstellen von Einbettungsendpunkten

Für weitere Informationen zum Erstellen von Einbettungsendpunkten verwenden Sie diese Links für den entsprechenden KI-Modell-Ableitungsendpunktanbieter:

• Azure OpenAI im Kontext von Azure AI Foundry-Modellen
• OpenAI
• Ollama

Berechtigungsnamensregeln für das externe Modell

Das von einem externen Modell erstellte DATABASE SCOPED CREDENTIAL Exemplar muss folgende Regeln befolgen:

• Muss eine gültige URL sein

• Die URL-Domain muss eine der Domains sein, die in der Erlaubnisliste enthalten sind.

• Die URL darf keine Abfragezeichenfolge enthalten.

• Protokoll + Vollqualifizierter Domänenname (FQDN) der aufgerufenen URL muss mit Protokoll + FQDN des Anmeldeinformationsnamens übereinstimmen.

• Jeder Teil des aufgerufenen URL-Pfads muss vollständig mit dem jeweiligen Teil des URL-Pfads im Credential-Namen übereinstimmen.

• Die Zugangsdaten müssen auf einen Pfad verweisen, der generischer ist als die Anfrage-URL. Zum Beispiel kann eine für den Pfad https://northwind.azurewebsite.net/customers erstellte Zugangsdaten nicht für die URL https://northwind.azurewebsite.netverwendet werden.

Regeln für die Sortierung und Anmeldeinformationen

RFC 3986 Abschnitt 6.2.2.1 besagt: "Wenn eine URI Komponenten der generischen Syntax verwendet, gelten immer die Komponentensyntaxäquivalenzregeln; nämlich, dass das Schema und der Gastgeber-Moderator nicht buchstabenabhängig sind." RFC 7230 Abschnitt 2.7.3 erwähnt, dass "alle anderen in einer fallsensitiven Weise verglichen werden."

Da eine Kollektionsregel auf Datenbankebene festgelegt ist, gilt folgende Logik, um die Datenbank-Kollierungsregel und die RFC-Regeln konsistent zu halten. (Die beschriebene Regel könnte potenziell restriktiver sein als die RFC-Regeln, zum Beispiel wenn die Datenbank so eingestellt ist, dass sie eine far-sensitive Sortierung verwendet.)

1. Überprüfen Sie, ob die URL und anmeldeinformationen mit rfc übereinstimmen, was bedeutet:

   • Überprüfen sie das Schema und den Host mithilfe einer Sortierung ohne Groß-/Kleinschreibung (Latin1_General_100_CI_AS_KS_WS_SC)
   • Überprüfen, ob alle anderen Segmente der URL in einer Sortierung mit Groß-/Kleinschreibung verglichen werden (Latin1_General_100_BIN2)

2. Überprüfen Sie, ob die URL und die Anmeldeinformationen mit den Datenbanksortierungsregeln übereinstimmen (und ohne URL-Codierung).

Verwaltete Identität

Um die verwaltete Identität des Arc/VM-Hosts als Datenbankzugangsdaten in SQL Server 2025 (17.x) zu verwenden, müssen Sie die Option aktivieren, indem sp_configure Sie mit einem Benutzer zusammenarbeiten, dem die Serverberechtigung ALTER SETTINGS gewährt wird.

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

SCHEMABINDING

Ansichten, die mit SCHEMABINDING diesem Referenzmodell auf ein externes Modell erstellt werden (wie z. B. eine SELECT Anweisung mit AI_GENERATE_EMBEDDINGS) können nicht verworfen werden, und die Datenbank-Engine erzeugt einen Fehler. Um Abhängigkeiten zu entfernen, die auf ein externes Modell verweisen, müssen Sie zunächst die Ansichtsdefinition ändern oder weglassen.

Katalogansicht

Sie können externe Modellmetadaten ansehen, indem Sie die sys.external_models Katalogansicht abfragen. Man muss Zugriff auf ein Modell haben, um dessen Metadaten einzusehen.

SELECT *
FROM sys.external_models;

Beispiele für Remoteendpunkte

Erstellen eines EXTERNEN MODELLS mit Azure OpenAI mit verwalteter Identität

Dieses Beispiel erstellt ein externes Modell des Typs EMBEDDINGS mit Azure OpenAI und verwendet Managed Identity zur Authentifizierung .

In SQL Server 2025 (17.x) und neueren Versionen müssen Sie Ihren SQL Server mit Azure Arc verbinden und die primäre verwaltete Identität aktivieren.

Von Bedeutung

Wenn Sie Managed Identity mit Azure OpenAI und SQL Server 2025 (17.x) verwenden, muss die Rolle Cognitive Services OpenAI Contributor der von Azure Arc aktivierten systemzugewiesenen verwalteten Identität von SQL Server zugewiesen werden. Weitere Informationen finden Sie unter Rollenbasierte Zugriffskontrolle für Azure OpenAI in Azure AI Foundry Models.

Erstelle Zugriffszugangsdaten für Azure OpenAI mit einer verwalteten Identität:

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

Erstellen Sie das externe Modell:

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

Erstellen Sie ein externes Modell mit Azure OpenAI unter Verwendung von API-Schlüsseln und -Parametern

Dieses Beispiel erstellt ein externes Modell des Typs EMBEDDINGS mit Azure OpenAI und verwendet API-Schlüssel zur Authentifizierung. Im Beispiel wird PARAMETERS auch der Dimensionsparameter am Endpunkt auf 725 festgelegt.

Erstelle Zugriffszugangsdaten zu Azure OpenAI mit einem Schlüssel:

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

Erstellen Sie das externe Modell:

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

Erstellen eines EXTERNEN MODELLS mit Ollama und einem expliziten Besitzer

Dieses Beispiel erstellt ein externes Modell des Typs EMBEDDINGS , das Ollama lokal für Entwicklungszwecke verwendet.

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

Erstellen eines EXTERNEN MODELLS mit OpenAI

Dieses Beispiel erstellt ein externes Modell dieses Typs EMBEDDINGS , das die OpenAI- API_FORMAT und HTTP-headerbasierten Zugangsdaten zur Authentifizierung verwendet.

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

Beispiel mit ONNX Runtime, das lokal ausgeführt wird

ONNX Runtime ist ein Open-Source-Ableitungsmodul, mit dem Sie Machine Learning-Modelle lokal ausführen können, sodass sie ideal für die Integration von KI-Funktionen in SQL Server-Umgebungen geeignet ist.

Dieses Beispiel führt Sie durch die Einrichtung von SQL Server 2025 (17.x) mit ONNX Runtime, um lokale, KI-gestützte Text-Embedding-Generierung zu ermöglichen. Sie gilt nur für Windows.

Von Bedeutung

Dieses Feature erfordert, dass SQL Server Machine Learning Services installiert ist.

Schritt 1: Aktivieren von Entwicklervorschaufeatures in SQL Server 2025

Führen Sie den folgenden Transact-SQL (T-SQL)-Befehl aus, um die Vorschaufunktionen von SQL Server 2025 (17.x) in der Datenbank zu aktivieren, die Sie für dieses Beispiel verwenden möchten:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Schritt 2: Aktivieren der lokalen KI-Laufzeit auf SQL Server 2025

Aktivieren Sie externe KI-Laufzeiten, indem Sie die folgende T-SQL-Abfrage ausführen:

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

Schritt 3: Richte die ONNX Runtime-Bibliothek ein

Erstelle ein Verzeichnis auf der SQL-Server-Instanz, um die ONNX Runtime-Bibliotheksdateien zu speichern. In diesem Beispiel C:\onnx_runtime wird verwendet.

Sie können die folgenden Befehle verwenden, um das Verzeichnis zu erstellen:

cd C:\
mkdir onnx_runtime

Laden Sie als Nächstes eine Version von ONNX Runtime (1.19 oder höher) herunter, die für Ihr Betriebssystem geeignet ist. Kopieren Sie nach dem Aufheben des Downloads das onnxruntime.dll Verzeichnis (im Lib-Verzeichnis) in das C:\onnx_runtime erstellte Verzeichnis.

Schritt 4: Einrichten der Tokenisierungsbibliothek

Laden Sie die Bibliothek von GitHub herunter, und erstellen Sie sietokenizers-cpp. Nachdem die DLL erstellt wurde, platzieren Sie den Tokenizer im C:\onnx_runtime Verzeichnis.

Hinweis

Stellen Sie sicher, dass die erstellte DLL tokenizers_cpp.dll

Schritt 5: Herunterladen des ONNX-Modells

Erstellen Sie zunächst das model Verzeichnis in C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

In diesem Beispiel wird das all-MiniLM-L6-v2-onnx Modell verwendet, das von Hugging Face heruntergeladen werden kann.

Klonen Sie das Repository in das C:\onnx_runtime\model Verzeichnis mit dem folgenden Git-Befehl :

Falls nicht installiert, können Sie Git über den folgenden Downloadlink oder über winget herunterladen (winget install Microsoft.Git)

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

Schritt 6: Festlegen von Verzeichnisberechtigungen

Verwenden Sie das folgende PowerShell-Skript, um dem MSSQLLaunchpad-Benutzer Zugriff auf das ONNX Runtime-Verzeichnis zu gewähren:

$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

Schritt 7: Erstellen des externen Modells

Führen Sie folgende Abfrage aus, um Ihr ONNX-Modell als externes Modellobjekt zu registrieren:

Der hier verwendete Wert 'PARAMETERS' ist ein Platzhalter, der für SQL Server 2025 (17.x) benötigt wird.

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 sollte auf das Verzeichnis zeigen, das Dateien enthält model.onnxtokenizer.json .
• LOCAL_RUNTIME_PATH sollte auf das Verzeichnis onnxruntime.dll verweisen, das Dateien enthält tokenizer_cpp.dll .

Schritt 8: Generieren von Einbettungen

Verwenden Sie die Funktion, ai_generate_embeddings um das Modell zu testen, indem Sie folgende Abfrage ausführen:

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

Mit diesem Befehl werden die AIRuntimeHosterforderlichen DLLs geladen und der Eingabetext verarbeitet.

Das Ergebnis der vorherigen Abfrage ist ein Array von Einbettungen:

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

Aktivieren Sie das Systemlogging von XEvent

Führen Sie die folgende Abfrage aus, um das Systemlogging zur Fehlersuche zu aktivieren.

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

Als Nächstes verwenden Sie diese Abfrage: Siehe die erfassten Systemprotokolle:

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

Aufräumen

Um das externe Modellobjekt zu entfernen, führen Sie folgende T-SQL-Anweisung aus:

DROP EXTERNAL MODEL myLocalOnnxModel;

Führen Sie die folgenden PowerShell-Befehle aus, um die Verzeichnisberechtigungen zu entfernen:

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

Löschen Sie schließlich das C:/onnx_runtime Verzeichnis.

Verwandte Inhalte

• EXTERNES MODELL ÄNDERN (Transact-SQL)
• AUSSERMODELL FALLEN LASSEN (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL)
• sys.external_models
• Erstellen und Bereitstellen einer Azure OpenAI in Azure AI Foundry Models-Ressource
• Serverkonfigurationsoptionen
• Rollenbasierte Zugriffssteuerung für Azure OpenAI in Azure AI Foundry-Modellen