Freigeben über

EXTERNES MODELL ERSTELLEN (Transact-SQL)

Gilt für: SQL Server 2025 (17.x) Azure SQL-DatenbankAzure SQL Managed InstanceSQL-Datenbank in Microsoft Fabric

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

Hinweis

CREATE EXTERNAL MODEL ist in Azure SQL Managed Instance mit der Always-up-to-dateupdate policy verfügbar.

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 gibt das Verzeichnis in der lokalen SQL Server Instanz an, in der sich die ausführbaren DATEIEN der ONNX-Runtime 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:

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

So verwenden Sie die managed Identity des Arc/VM-Hosts als Anmeldeinformationen auf Datenbankebene in SQL Server 2025 (17.x) ), müssen Sie die Option aktivieren, indem Sie sp_configure mit einem Benutzer verwenden, der die Berechtigung auf Serverebene ALTER SETTINGS aktiviert hat.

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

SCHEMABINDING

Ansichten, die mit SCHEMABINDING erstellt wurden, die auf ein externes Modell verweisen (z. B. eine SELECT-Anweisung mit AI_GENERATE_EMBEDDINGS), können nicht gelöscht werden, und die Datenbank-Engine löst einen Fehler aus. 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

In diesem Beispiel wird ein externes Modell des typs EMBEDDINGS mit Azure OpenAI erstellt und Managed Identity für die Authentifizierung verwendet.

In SQL Server 2025 (17.x) und höheren Versionen müssen Sie Connect your SQL Server to Azure Arc and enable the primary managed identity.

Von Bedeutung

Wenn Sie verwaltete Identität mit Azure OpenAI und SQL Server 2025 (17.x) verwenden, muss der Cognitive Services OpenAI-Mitwirkender Rolle der vom System zugewiesenen verwalteten Identität SQL Server gewährt werden, die von Azure Arc aktiviert ist. Weitere Informationen finden Sie unter Role-based access control for Azure OpenAI in Azure AI Foundry Models.

Erstellen Sie Zugriffsanmeldeinformationen für Azure OpenAI mithilfe 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 eines externen Modells mit Azure OpenAI mithilfe von API-Schlüsseln und -Parametern

In diesem Beispiel wird mithilfe Azure OpenAI ein externes Modell des typs EMBEDDINGS erstellt und API-Schlüssel für die Authentifizierung verwendet. Im Beispiel wird PARAMETERS auch der Dimensionsparameter am Endpunkt auf 725 festgelegt.

Erstellen Sie Zugriffsanmeldeinformationen für Azure OpenAI mithilfe eines Schlüssels:

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 das Einrichten von SQL Server 2025 (17.x) mit ONNX-Runtime, um die lokale KI-gestützte Texteinbettungsgenerierung zu ermöglichen. Sie gilt nur für Windows.

Von Bedeutung

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

Sicherheitsaspekte

Sie können das AI-Runtime-Hostfeature verwenden, um Ihre eigenen LLMs und ONNX-Bibliotheken mit SQL Server zu konfigurieren und zu verwenden. Da Microsoft keine Modelle und Bibliotheken von Drittanbietern überprüft oder überwacht, sind Sie dafür verantwortlich, geeignete Modelle und Bibliotheken auszuwählen, Inhalte zu filtern, die Laufzeit zu sichern und die Einhaltung der geltenden Richtlinien und Vorschriften sicherzustellen.

Vorsicht

Ein schädliches oder kompromittiertes ONNX-Modell könnte Daten exfiltrieren oder nicht autorisierten Code ausführen. Verwenden Sie nur Modelle aus vertrauenswürdigen, überprüften Quellen.

Um diese Risiken zu mindern, sollten Sie die folgenden bewährten Sicherheitsmethoden berücksichtigen:

  • Implementieren sie starke Zugriffssteuerungen: Stellen Sie sicher, dass nur autorisierte Benutzer Zugriff auf vertrauliche Daten und ONNX-Runtime-Modelle haben. Überprüfen Sie alle Modelle, bevor Sie sie in SQL Server laden. Verwenden Sie das Prinzip der geringsten Rechtesowie Datenbankrollen und -berechtigungen.
  • Überwachen und Überwachen des Zugriffs: Überwachen und überwachen Sie regelmäßig den Zugriff auf die Datenbank und AI_GENERATE_EMBEDDINGS Funktionsaufrufe, um verdächtige Aktivitäten zu erkennen.
  • Führen Sie regelmäßige Sicherheitsbewertungen durch: Führen Sie Sicherheitsüberprüfungen und Sicherheitsüberprüfungen durch, um potenzielle Risiken zu identifizieren und zu mindern.

Schritt 1: Aktivieren von Entwicklervorschaufeatures auf SQL Server 2025

Führen Sie den folgenden Transact-SQL (T-SQL)-Befehl aus, um SQL Server 2025 (17.x) Vorschaufeatures 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

Erstellen Sie ein Verzeichnis in 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 the tokenizers-cpp library aus GitHub herunter und erstellen Sie sie. 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 :

Wenn Sie git aus dem folgenden Download-Link oder über winget (winget install Microsoft herunterladen können. 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 Parameterwert ist ein Platzhalter für 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 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

  • Last updated on