CREATE EXTERNAL MODEL (Transact-SQL)

2025-06-30

Dotyczy: SQL Server 2025 (wersja zapoznawcza 17.x)

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

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 zostanie określony, własność zostanie nadana bieżącemu użytkownikowi. W zależności od uprawnień i ról jawne uprawnienia muszą zostać przyznane użytkownikom w celu korzystania z określonych 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

TYP_MODELU

Typ modelu uzyskiwany z lokalizacji punktu końcowego wnioskowania modelu sztucznej inteligencji.

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

Wskaż, który DATABASE SCOPED CREDENTIAL obiekt jest używany z punktem końcowym wnioskowania modelu sztucznej inteligencji. Więcej informacji na temat akceptowanych typów poświadczeń i reguł nazewnictwa można znaleźć w sp_invoke_external_rest_endpoint lub w sekcji Uwagi w tym artykule.

PARAMETRY

Prawidłowy ciąg JSON zawierający parametry środowiska uruchomieniowego do dołączenia do komunikatu żądania punktu końcowego wnioskowania modelu AI. Przykład:

'{ "Dimensions": 1536 }'

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ć retry_count wartość 3, należy napisać następujący ciąg JSON:

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

Liczba ponownych prób z innymi parametrami

Liczba ponownych prób może być również połączona z innymi parametrami, o ile jest to prawidłowy ciąg JSON.

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

Uwagi

Protokoły HTTPS i TLS

Dla parametru są obsługiwane tylko punkty końcowe wnioskowania modelu sztucznej inteligencji skonfigurowane do używania LOCATION protokołu HTTPS z protokołem szyfrowania TLS.

Zaakceptowane formaty interfejsu API i typy modeli

W poniższych sekcjach opisano akceptowane formaty interfejsu API dla każdego MODEL_TYPEelementu .

API_FORMAT osadzania

W tej tabeli przedstawiono formaty interfejsu API i struktury punktów końcowych adresu URL dla 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

DATABASE SCOPED CREDENTIAL Utworzony przez obiekt EXTERNAL MODEL musi być zgodny z określonymi następującymi regułami:

Musi być prawidłowym adresem URL
Domena adresu URL musi być jedną z tych 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ływanej ścieżki adresu URL musi być całkowicie zgodna z odpowiednią częścią ścieżki adresu URL w nazwie poświadczeń
Poświadczenie musi wskazywać ścieżkę, która jest bardziej ogólna niż adres URL żądania. Na przykład nie można użyć poświadczeń utworzonych dla ścieżki https://northwind.azurewebsite.net/customers dla adresu URL https://northwind.azurewebsite.net

Reguły sortowania i nazw poświadczeń

RFC 3986 Sekcja 6.2.2.1 stwierdza, że "Gdy identyfikator URI używa składników składni ogólnej, reguły równoważności składni składników są zawsze stosowane; mianowicie, że schemat i host są bez uwzględniania wielkości liter" i RFC 7230 Sekcja 2.7.3 wspomina, że "wszystkie inne są porównywane w sposób uwzględniający wielkość liter".

Ponieważ na poziomie bazy danych jest ustawiona reguła sortowania, stosowana jest następująca logika, aby była spójna z regułą sortowania bazy danych i wcześniej wymienioną specyfikacją RFC. (Opisana reguła może być potencjalnie bardziej restrykcyjna niż reguły RFC, na przykład jeśli baza danych ma używać sortowania z uwzględnieniem wielkości liter):

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

Zarządzana Tożsamość

Aby użyć tożsamości zarządzanej do uwierzytelniania w programie SQL Server 2025, należy włączyć tę opcję za pomocą użytkownika sp_configure , któremu udzielono uprawnień na poziomie serwera ALTER SETTINGS.

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

POWIĄZANIE SCHEMATU

Usuwanie widoków utworzonych za SCHEMABINDING pomocą polecenia i odwoływanie EXTERNAL MODEL się do elementu (na przykład SELECT instrukcji przy użyciu AI_GENERATE_EMBEDDINGSpolecenia ) jest blokowane z powodu wystąpienia błędu przez aparat bazy danych. Aby usunąć zależności odwołujące się do elementu , należy najpierw zmodyfikować lub usunąć definicję EXTERNAL MODELwidoku.

Widok wykazu

Metadane modelu zewnętrznego sys.external_models są wyświetlane przez wykonywanie zapytań względem widoku wykazu. Należy pamiętać, że musisz mieć dostęp do modelu, aby móc wyświetlać metadane.

SELECT * FROM sys.external_models;

Przykłady

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

W tym przykładzie EMBEDDINGS utworzono EXTERNAL MODEL typ przy użyciu usługi Azure OpenAI i użyto tożsamości zarządzanej do uwierzytelniania.

Ważne

W przypadku korzystania z tożsamości zarządzanej z usługami Azure OpenAI i SQL Server 2025 rola Współautor openAI usług Cognitive Services musi zostać udzielona tożsamości zarządzanej przypisanej przez system programu SQL Server przez usługę Azure Arc. Aby uzyskać więcej informacji, zobacz Kontrola dostępu oparta na rolach dla usługi Azure OpenAI w modelach usługi Azure AI Foundry.

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

Tworzenie modelu ZEWNĘTRZNEgo za pomocą usługi Azure OpenAI przy użyciu kluczy interfejsu API i parametrów

Ten przykład tworzy typ EXTERNAL MODEL przy użyciu interfejsu EMBEDDINGS Azure OpenAI i używa kluczy interfejsu API do uwierzytelniania. W przykładzie użyto PARAMETERS również parametru Dimensions w punkcie końcowym na wartość 725.

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

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

W tym przykładzie EXTERNAL MODEL tworzony jest EMBEDDINGS typ przy użyciu aplikacji Ollama hostowanej lokalnie na potrzeby programowania.

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

W tym przykładzie EXTERNAL MODEL tworzony jest EMBEDDINGS typ przy użyciu poświadczeń opartych na nagłówku OpenAI API_FORMAT i HTTP na potrzeby 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]
);