CREATE EXTERNAL MODEL (Transact-SQL)

2025-06-27

Gilt für: SQL Server 2025 (17.x) Vorschau

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

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 nicht angegeben, wird dem aktuellen Benutzer der Besitz zugewiesen. Je nach Berechtigungen und Rollen muss Benutzern explizite Berechtigungen erteilt werden, um bestimmte externe Modelle zu verwenden.

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

MODEL_TYPE

Auf den Typ des Modells, auf das über den Standort des AI-Modells zugegriffen wird, wird der Endpunktstandort abgeleitet.

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

Geben Sie an, welches DATABASE SCOPED CREDENTIAL Objekt mit dem AI-Modell-Ableitungsendpunkt verwendet wird. Weitere Informationen zu akzeptierten Anmeldeinformationstypen und Benennungsregeln finden Sie in sp_invoke_external_rest_endpoint oder im Abschnitt "Anmerkungen " dieses Artikels.

PARAMETER

Eine gültige JSON-Zeichenfolge, die Laufzeitparameter enthält, die an die Anforderungsmeldung des AI-Modells angefügt werden sollen. Beispiel:

'{ "Dimensions": 1536 }'

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

Wenn Sie z. B. den retry_count Wert 3 festlegen möchten, schreiben Sie die folgende JSON-Zeichenfolge:

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

Wiederholungsanzahl mit anderen Parametern

Die Wiederholungsanzahl kann auch mit anderen Parametern kombiniert werden, solange es sich um eine gültige JSON-Zeichenfolge ist.

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

Bemerkungen

HTTPS und TLS

Nur KI-Modell-Ableitungsendpunkte, die für die Verwendung von HTTPS mit TLS-Verschlüsselungsprotokoll konfiguriert sind, werden für den LOCATION Parameter unterstützt.

Akzeptierte API-Formate und Modelltypen

In den folgenden Abschnitten werden akzeptierte API-Formate für die einzelnen MODEL_TYPEGliederungen beschrieben.

API_FORMAT für EMBEDDINGS

In dieser Tabelle werden die API-Formate und URL-Endpunktstrukturen für den EMBEDDINGS Modelltyp beschrieben. 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:

Anmeldeinformationsnamensregeln für EXTERNES MODELL

Die von einer DATABASE SCOPED CREDENTIAL erstellte Anwendung EXTERNAL MODEL muss bestimmten folgenden Regeln entsprechen:

Muss eine gültige URL sein
Die URL-Domäne muss eine dieser Domänen sein, die in der Zulassungsliste 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 Anmeldeinformationsnamen übereinstimmen.
Die Anmeldeinformationen müssen auf einen Pfad verweisen, der allgemeiner als die Anforderungs-URL ist. Beispielsweise kann eine für den Pfad https://northwind.azurewebsite.net/customers erstellte Anmeldeinformation nicht für die URL verwendet werden. https://northwind.azurewebsite.net

Regeln für die Sortierung und Anmeldeinformationen

RFC 3986 Section 6.2.2.1 gibt an, dass "Wenn ein URI Komponenten der generischen Syntax verwendet, gelten die Regeln für die Komponentensyntax immer; nämlich, dass das Schema und der Host die Groß-/Kleinschreibung nicht beachten" und RFC 7230 Section 2.7.3 erwähnt, dass "alle anderen in einer Groß-/Kleinschreibung verglichen werden".

Da eine Sortierregel auf Datenbankebene festgelegt ist, wird die folgende Logik angewendet, um mit der Datenbanksortierungsregel und dem zuvor erwähnten RFC in Einklang zu stehen. (Die beschriebene Regel könnte möglicherweise restriktiver sein als die RFC-Regeln, z. B. wenn die Datenbank für die Verwendung einer Sortierung mit Groß-/Kleinschreibung festgelegt ist):

Ü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)
Überprüfen Sie, ob die URL und die Anmeldeinformationen mit den Datenbanksortierungsregeln übereinstimmen (und ohne URL-Codierung).

Verwaltete Identität

Um verwaltete Identität für die Authentifizierung in SQL Server 2025 zu verwenden, müssen Sie die Option mit sp_configure einem Benutzer aktivieren, der die Berechtigung auf Serverebene ALTER SETTINGS erteilt hat.

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

SCHEMABINDING

Das Ablegen von Ansichten, die mit SCHEMABINDING einer (z. B. einer SELECT Anweisung mitAI_GENERATE_EMBEDDINGS) erstellt und referenziert EXTERNAL MODEL wurden, wird verhindert, dass das Datenbankmodul einen Fehler ausgelöst hat. Die Ansichtsdefinition selbst muss zuerst geändert oder gelöscht werden, um Abhängigkeiten zu entfernen, die auf eine EXTERNAL MODEL.

Katalogansicht

Externe Modellmetadaten werden durch Abfragen der sys.external_models Katalogansicht angezeigt. Beachten Sie, dass Sie Zugriff auf ein Modell haben müssen, um die Metadaten anzeigen zu können.

SELECT * FROM sys.external_models;

Beispiele

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

In diesem Beispiel wird ein EXTERNAL MODEL Typ EMBEDDINGS mit Azure OpenAI erstellt und verwaltete Identität für die Authentifizierung verwendet.

Von Bedeutung

Wenn Sie verwaltete Identität mit Azure OpenAI und SQL Server 2025 verwenden, muss die Rolle " Cognitive Services OpenAI-Mitwirkender " der vom System zugewiesenen verwalteten Identität von SQL Server gewährt werden, die von Azure Arc aktiviert ist. Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung für Azure OpenAI in Azure AI Foundry Models.

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

Erstellen eines EXTERNEN MODELLS mit Azure OpenAI mithilfe von API-Schlüsseln und -Parametern

In diesem Beispiel wird ein EXTERNAL MODEL Typ EMBEDDINGS mit Azure OpenAI erstellt und API-Schlüssel für die Authentifizierung verwendet. Im Beispiel wird PARAMETERS auch der Dimensions-Parameter am Endpunkt auf 725 festgelegt.

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

Erstellen eines EXTERNEN MODELLS mit Ollama und einem expliziten Besitzer

In diesem Beispiel wird ein EXTERNAL MODEL Typ erstellt, der Ollama verwendet, der EMBEDDINGS lokal für Entwicklungszwecke gehostet wird.

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

In diesem Beispiel wird ein EXTERNAL MODEL Typ EMBEDDINGS erstellt, der die OpenAI API_FORMAT - und HTTP-Header-basierten Anmeldeinformationen für die 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]
);

Freigeben über