STWÓRZ ZEWNĘTRZNY MODEL (Transact-SQL)

Dotyczy do: SQL Server 2025 (17.x) Azure SQL Database SQL database in Microsoft Fabric

Tworzy obiekt modelu zewnętrznego zawierający lokalizację, metodę uwierzytelniania i cel punktu końcowego wnioskowania modelu sztucznej inteligencji.

Składnia

Transact-SQL konwencje składni

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

Argumenty (w programowaniu)

external_model_object_name

Określa nazwę zdefiniowaną przez użytkownika dla modelu zewnętrznego. Nazwa musi być unikatowa w bazie danych.

owner_name

Określa nazwę użytkownika lub roli, która jest właścicielem modelu zewnętrznego. Jeśli nie określisz tego argumentu, obecny użytkownik staje się właścicielem. W zależności od uprawnień i ról, możesz potrzebować przyznać użytkownikom wyraźne uprawnienia do korzystania z konkretnych modeli zewnętrznych.

LOKALIZACJA

Udostępnia protokół łączności i ścieżkę do punktu końcowego wnioskowania modelu sztucznej inteligencji.

API_FORMAT

Format komunikatu interfejsu API dla dostawcy punktu końcowego wnioskowania modelu sztucznej inteligencji.

Akceptowane wartości to:

Azure OpenAI
OpenAI
Ollama
ONNX Runtime

TYP_MODELU

Typ modelu do którego uzyskuje się dostęp z lokalizacji punktu końcowego wnioskowania modelu AI.

Akceptowane wartości to:

EMBEDDINGS

Model

Określony model hostowany przez dostawcę sztucznej inteligencji. Na przykład, text-embedding-ada-002, text-embedding-3-large lub o3-mini.

POŚWIADCZENIE

Określa DATABASE SCOPED CREDENTIAL obiekt używany z końcowym wnioskowaniem modelu AI. Aby uzyskać więcej informacji o akceptowanych typach uprawnień i zasadach nazewnictwa, zobacz sp_invoke_external_rest_endpoint lub sekcję Uwagi w tym artykule.

PARAMETRY

Poprawny ciąg JSON zawierający parametry wykonawcze, które można dodać do komunikatu wnioskowania o wnioskowanie AI w końcowym punkcie. Przykład:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH określa katalog na lokalnej instancji SQL Server, gdzie znajdują się pliki wykonywalne ONNX Runtime.

Uprawnienia

Tworzenie i zmienianie modelu zewnętrznego

Wymaga ALTER ANY EXTERNAL MODEL uprawnień lub CREATE EXTERNAL MODEL bazy danych.

Przykład:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Lub:

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

Granty modelu zewnętrznego

Aby można było używać modelu zewnętrznego w funkcji sztucznej inteligencji, należy przyznać EXECUTE jej uprawnienia podmiotu zabezpieczeń.

Przykład:

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

Liczba ponownych prób

Jeśli wywołanie osadzania napotka kody stanu HTTP wskazujące tymczasowe problemy, możesz skonfigurować żądanie, aby automatycznie ponowić próbę. Aby określić liczbę ponownych prób, dodaj następujący kod JSON do PARAMETERS obiektu w pliku EXTERNAL MODEL. Wartość <number_of_retries> powinna być liczbą całkowitą z zakresu od zera (0) do dziesięciu (10), włącznie i nie może być NULL ani ujemna.

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

Na przykład, aby ustawić na retry_count 3, użyj następującego ciągu JSON:

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

Liczba ponownych prób z innymi parametrami

Możesz łączyć liczbę powtórek z innymi parametrami, o ile ciąg JSON jest poprawny.

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

Uwagi

Protokoły HTTPS i TLS

Dla parametrów LOCATION obsługiwane są tylko końcowe wnioskowania modeli AI skonfigurowane do korzystania z HTTPS z protokołem szyfrowania TLS.

Zaakceptowane formaty interfejsu API i typy modeli

Poniższe sekcje przedstawiają akceptowane formaty API dla każdego MODEL_TYPE.

API_FORMAT osadzania

Ta tabela przedstawia formaty API oraz struktury punktów końcowych URL dla danego EMBEDDINGS typu modelu. Aby wyświetlić określone struktury ładunków, użyj linku w kolumnie Format interfejsu API.

Format interfejsu API	Format ścieżki lokalizacji
Azure OpenAI	https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
Otwarta sztuczna inteligencja	https://{server_name}/v1/osadzanie
Ollama	https:localhost://{port}/api/embed

Tworzenie osadzonych punktów końcowych

Aby uzyskać więcej informacji na temat tworzenia punktów końcowych osadzania, użyj tych linków dla odpowiedniego dostawcy punktu końcowego wnioskowania modelu sztucznej inteligencji:

Reguły nazw poświadczeń dla modelu zewnętrznego

Stworzone DATABASE SCOPED CREDENTIAL przez zewnętrzny model muszą spełniać następujące zasady:

Musi być prawidłowym adresem URL
Domena URL musi być jedną z domen uwzględnionych na liście dozwolonych.
Adres URL nie może zawierać ciągu zapytania
Protokół + w pełni kwalifikowana nazwa domeny (FQDN) wywoływanego adresu URL musi być zgodna z protokołem i nazwą FQDN nazwy poświadczeń
Każda część wywołanej ścieżki URL musi całkowicie odpowiadać odpowiedniej części ścieżki URL w nazwie poświadczenia.
Dane uwierzytelniające muszą wskazywać ścieżkę bardziej ogólną niż adres URL żądania. Na przykład dane uwierzytelniające utworzone dla ścieżki https://northwind.azurewebsite.net/customers nie mogą być użyte dla adresu URL https://northwind.azurewebsite.net.

Reguły sortowania i nazw poświadczeń

RFC 3986 Sekcja 6.2.2.1 stwierdza, że "Gdy URI wykorzystuje komponenty składni ogólnej, zasady równoważności składni komponentów zawsze mają zastosowanie; mianowicie, że schemat i gospodarz nie są wrażliwe na wielka i literalna." RFC 7230 Sekcja 2.7.3 wspomina, że "wszystkie pozostałe są porównywane w sposób wrażliwy na wielka a literalność."

Ponieważ reguła sortowania jest ustalana na poziomie bazy danych, stosuje się następującą logikę, aby zachować spójność reguły zbiorczej bazy danych i reguł RFC. (Opisana reguła może być potencjalnie bardziej restrykcyjna niż reguły RFC, na przykład jeśli baza danych jest ustawiona na używanie sortacji na wielka czy wielka litera.)

Sprawdź, czy adres URL i poświadczenia są zgodne przy użyciu specyfikacji RFC, co oznacza:
- Sprawdź schemat i host przy użyciu sortowania bez uwzględniania wielkości liter (Latin1_General_100_CI_AS_KS_WS_SC)
- Sprawdź, czy wszystkie inne segmenty adresu URL są porównywane w sortowaniu uwzględniającym wielkość liter (Latin1_General_100_BIN2)
Sprawdź, czy adres URL i poświadczenia są zgodne przy użyciu reguł sortowania bazy danych (i bez kodowania adresu URL).

Tożsamość zarządzana

Aby użyć zarządzanej tożsamości hosta Arc/VM jako dane dane w SQL Server 2025 (17.x), musisz włączyć tę opcję z sp_configure użytkownikiem, który otrzymał uprawnienia ALTER SETTINGS na poziomie serwera.

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

POWIĄZANIE SCHEMATU

Widoki utworzone z użyciem SCHEMABINDING zewnętrznego modelu (np. SELECT instrukcji używającej AI_GENERATE_EMBEDDINGS) nie mogą zostać usunięte, a silnik bazy danych zgłasza błąd. Aby usunąć zależności odwołujące się do modelu zewnętrznego, najpierw musisz zmodyfikować lub usunąć definicję widoku.

Widok katalogu

Możesz przeglądać metadane zewnętrznego modelu, zapytując sys.external_models katalogu. Musisz mieć dostęp do modelu, aby zobaczyć jego metadane.

SELECT *
FROM sys.external_models;

Przykłady z zdalnymi punktami końcowymi

Tworzenie modelu ZEWNĘTRZNEgo przy użyciu usługi Azure OpenAI przy użyciu tożsamości zarządzanej

Ten przykład tworzy zewnętrzny model tego EMBEDDINGS typu za pomocą Azure OpenAI i korzysta z Managed Identity do uwierzytelniania.

W SQL Server 2025 (17.x) i nowszych wersjach musisz połączyć SQL Server z Azure Arc i włączyć główną tożsamość zarządzaną.

Ważne

Jeśli korzystasz z Managed Identity z Azure OpenAI i SQL Server 2025 (17.x), rola Cognitive Services Contributor OpenAI musi być przypisana do systemowej tożsamości zarządzanej SQL Server włączonej przez Azure Arc. Więcej informacji można znaleźć w artykule Kontrola dostępu oparta na rolach dla Azure OpenAI w Azure AI Foundry Models.

Utwórz dane dostępu do Azure OpenAI za pomocą tożsamości zarządzanej:

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

Stwórz zewnętrzny model:

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

Stwórz zewnętrzny model w Azure OpenAI, używając kluczy i parametrów API

Ten przykład tworzy zewnętrzny model tego EMBEDDINGS typu za pomocą Azure OpenAI i korzysta z kluczy API do uwierzytelniania. W przykładzie użyto PARAMETERS również polecenia , aby ustawić parametr wymiarów w punkcie końcowym na wartość 725.

Utworzenie danych dostępu do Azure OpenAI za pomocą klucza:

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

Stwórz zewnętrzny model:

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

Tworzenie modelu ZEWNĘTRZNEgo przy użyciu Ollama i jawnego właściciela

Ten przykład tworzy zewnętrzny model tego typu, EMBEDDINGS wykorzystujący Ollamę hostowaną lokalnie do celów rozwojowych.

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

Tworzenie modelu ZEWNĘTRZNEgo za pomocą interfejsu OpenAI

Ten przykład tworzy zewnętrzny model tego typu EMBEDDINGS , wykorzystując poświadczenia oparte na OpenAI API_FORMAT i nagłówkach HTTP do uwierzytelniania.

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

Przykład z uruchomieniem ONNX Runtime lokalnie

Środowisko uruchomieniowe ONNX to aparat wnioskowania typu open source, który umożliwia uruchamianie modeli uczenia maszynowego lokalnie, dzięki czemu idealnie nadaje się do integrowania funkcji sztucznej inteligencji w środowiskach programu SQL Server.

Ten przykład przeprowadza Cię przez konfigurację SQL Server 2025 (17.x) z ONNX Runtime, aby umożliwić lokalne generowanie tekstu oparte na AI. Dotyczy tylko systemu Windows.

Ważne

Ta funkcja wymaga zainstalowania usług SQL Server Machine Learning Services .

Krok 1. Włączanie funkcji dla deweloperów w wersji zapoznawczej w programie SQL Server 2025

Uruchom następujące polecenie Transact-SQL (T-SQL), aby włączyć funkcje podglądu SQL Server 2025 (17.x) w bazie danych, którą chcesz użyć w tym przykładzie:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Krok 2. Włączanie lokalnego środowiska uruchomieniowego sztucznej inteligencji w programie SQL Server 2025

Włącz zewnętrzne środowiska uruchomieniowe AI, uruchamiając następujące zapytanie T-SQL:

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

Krok 3: Skonfiguruj bibliotekę ONNX Runtime

Utworzenie katalogu na instancji SQL Server do przechowywania plików bibliotek ONNX Runtime. W tym przykładzie C:\onnx_runtime jest używany.

Do utworzenia katalogu można użyć następujących poleceń:

cd C:\
mkdir onnx_runtime

Następnie pobierz wersję ONNX Runtime (1.19 lub nowszą), która będzie odpowiednia dla Twojego systemu operacyjnego. Po rozpakuj pobrany plik onnxruntime.dll (znajdujący się w katalogu lib) do utworzonego C:\onnx_runtime katalogu.

Krok 4. Konfigurowanie biblioteki tokenizacji

Pobierz i skompiluj bibliotekę tokenizers-cpp z usługi GitHub. Po utworzeniu biblioteki DLL umieść tokenizator w C:\onnx_runtime katalogu.

Uwaga / Notatka

Upewnij się, że utworzona biblioteka dll ma nazwę tokenizers_cpp.dll

Krok 5. Pobieranie modelu ONNX

Zacznij od utworzenia katalogu w pliku modelC:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

W tym przykładzie all-MiniLM-L6-v2-onnx użyto modelu, który można pobrać z funkcji Hugging Face.

Sklonuj repozytorium do C:\onnx_runtime\model katalogu za pomocą następującego polecenia git :

Jeśli nie jest zainstalowany, możesz pobrać narzędzie git z następującego linku pobierania lub za pośrednictwem pakietu winget (winget install Microsoft.Git)

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

Krok 6. Ustawianie uprawnień katalogu

Użyj poniższego skryptu PowerShell, aby zapewnić użytkownikowi MSSQLLaunchpad dostęp do katalogu ONNX Runtime:

$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

Krok 7. Tworzenie modelu zewnętrznego

Wykonaj następujące zapytanie, aby zarejestrować swój model ONNX jako zewnętrzny obiekt modelu:

Wartość 'PARAMETERS' użyta tutaj jest zastępczym potrzebnym dla 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 powinien wskazywać na katalog zawierający model.onnx pliki i tokenizer.json .
LOCAL_RUNTIME_PATH powinien wskazywać katalog zawierający onnxruntime.dll pliki i tokenizer_cpp.dll pliki.

Krok 8. Generowanie osadzania

Użyj ai_generate_embeddings funkcji do przetestowania modelu, wykonując następujące zapytanie:

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

To polecenie uruchamia polecenie , załaduj AIRuntimeHostwymagane biblioteki DLL i przetwarza tekst wejściowy.

Wynik z poprzedniego zapytania to tablica osadzeń:

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

Włącz logowanie systemowe XEvent

Uruchom następujące zapytanie, aby włączyć logowanie systemowe do rozwiązywania problemów.

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

Następnie użyj tego zapytania, zobacz zarejestrowane logi systemowe:

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

Czyszczenie

Aby usunąć zewnętrzny obiekt modelu, wykonaj następujące polecenie T-SQL:

DROP EXTERNAL MODEL myLocalOnnxModel;

Aby usunąć uprawnienia katalogu, uruchom następujące polecenia programu PowerShell:

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

Na koniec usuń C:/onnx_runtime katalog.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-12-08