Поделиться через

CREATE EXTERNAL MODEL (Transact-SQL)

Применимо к: Предварительная версия SQL Server 2025 (17.x)

Создает внешний объект модели, содержащий расположение, метод проверки подлинности и назначение конечной точки вывода модели ИИ.

Синтаксис

Соглашения о синтаксисе Transact-SQL

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

Аргументы

external_model_object_name

Задает определяемое пользователем имя внешней модели. В базе данных это имя должно быть уникальным.

owner_name

Указывает имя пользователя или роли, которая владеет внешней моделью. Если это не указано, то владение предоставляется текущему пользователю. В зависимости от разрешений и ролей явные разрешения необходимо предоставить пользователям для использования определенных внешних моделей.

МЕСТОПОЛОЖЕНИЕ

Предоставляет протокол подключения и путь к конечной точке вывода модели ИИ.

Формат_API

Формат сообщения API для поставщика конечной точки вывода модели ИИ.

Допустимые значения:

  • Azure OpenAI
  • OpenAI
  • Ollama

MODEL_TYPE

Тип модели, к которой осуществляется доступ из расположения конечной точки вывода модели ИИ.

Допустимые значения:

  • EMBEDDINGS

МОДЕЛЬ

Конкретная модель, размещенная поставщиком ИИ. Например, text-embedding-ada-002, text-embedding-3-large или o3-mini.

УЧЁТНЫЕ ДАННЫЕ

Укажите, какой DATABASE SCOPED CREDENTIAL объект используется с конечной точкой вывода модели ИИ. Дополнительные сведения о принятых типах учетных данных и правилах именования можно найти в sp_invoke_external_rest_endpoint или в разделе "Примечания " этой статьи.

ПАРАМЕТРЫ

Допустимая строка JSON, содержащая параметры среды выполнения, добавляемая к сообщению запроса конечной точки вывода модели ИИ. Рассмотрим пример.

'{ "Dimensions": 1536 }'

Разрешения

Создание и изменение внешней модели

Требуется ALTER ANY EXTERNAL MODEL или CREATE EXTERNAL MODEL разрешение базы данных.

Рассмотрим пример.

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

или

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

Предоставление внешних моделей

Чтобы использовать внешнюю модель в функции ИИ, субъекту необходимо предоставить ему возможность EXECUTE .

Рассмотрим пример.

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

Счетчик повторов

Если вызов внедрения обнаруживает коды состояния HTTP, указывающие на временные проблемы, можно настроить запрос для автоматического повтора. Чтобы указать количество повторных попыток, добавьте следующий код JSON в поле .PARAMETERSEXTERNAL MODEL. Должно <number_of_retries> быть целое число от нуля (0) до десяти (10), включительно и не может быть NULL или отрицательным.

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

Например, чтобы задать retry_count значение 3, необходимо написать следующую строку JSON:

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

Число повторных попыток с другими параметрами

Число повторных попыток также можно объединить с другими параметрами, если это допустимая строка JSON.

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

Замечания

HTTPS и TLS

Для параметра поддерживаются LOCATION только конечные точки вывода модели ИИ, настроенные для использования ПРОТОКОЛА ШИФРОВАНИя TLS.

Допустимые форматы API и типы моделей

В следующих разделах описаны принятые форматы API для каждого из них MODEL_TYPE.

API_FORMAT для EMBEDDINGS

В этой таблице описаны структуры конечных точек API и форматов URL-адресов для EMBEDDINGS типа модели. Чтобы просмотреть определенные структуры полезных данных, используйте ссылку в столбце "Формат API".

Формат API Формат пути расположения
Azure OpenAI https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI https://{server_name}/v1/embeddings
Ollama https:localhost://{port}/api/embed

Создание конечных точек внедрения

Дополнительные сведения о создании конечных точек внедрения используйте эти ссылки для соответствующего поставщика конечных точек вывода модели ИИ:

Правила имен учетных данных для EXTERNAL MODEL

Созданное DATABASE SCOPED CREDENTIAL приложение EXTERNAL MODEL должно соответствовать определенным правилам:

  • Должен быть допустимым URL-адресом

  • Домен URL-адреса должен быть одним из этих доменов, включенных в список разрешений.

  • URL-адрес не должен содержать строку запроса

  • Протокол + полное доменное имя (FQDN) вызываемого URL-адреса должно соответствовать протоколу +FQDN имени учетных данных.

  • Каждая часть вызываемого URL-пути должна полностью соответствовать соответствующей части пути URL-адреса в имени учетных данных.

  • Учетные данные должны указывать на путь, который является более универсальным, чем URL-адрес запроса. Например, учетные данные, созданные для пути https://northwind.azurewebsite.net/customers , нельзя использовать для URL-адреса. https://northwind.azurewebsite.net

Правила параметров сортировки и имени учетных данных

В разделе RFC 3986 6.2.2.1 указано, что "Если универсальный код ресурса (URI) использует компоненты универсального синтаксиса, правила эквивалентности компонентов всегда применяются; а именно, что схема и узел не учитывает регистр" и RFC 7230 в разделе 2.7.3 упоминается, что "все остальные сравниваются с учетом регистра".

Так как на уровне базы данных задано правило сортировки, применяется следующая логика, которая будет согласована с правилом сортировки базы данных, и ранее упоминалось RFC. (Описанное правило может быть более строгим, чем правила RFC, например, если база данных настроена для использования параметров сортировки с учетом регистра):

  1. Проверьте, совпадают ли URL-адреса и учетные данные с помощью RFC, то есть:

    • Проверьте схему и узел с помощью нечувствительной сортировки регистра (Latin1_General_100_CI_AS_KS_WS_SC)
    • Проверьте все остальные сегменты URL-адреса сравниваются в параметров сортировки с учетом регистра (Latin1_General_100_BIN2)

  2. Убедитесь, что URL-адрес и учетные данные соответствуют правилам сортировки базы данных (и без кодирования URL-адресов).

Управляемая идентичность

Чтобы использовать управляемое удостоверение для проверки подлинности в SQL Server 2025, необходимо включить этот параметр с sp_configure пользователем, которому предоставлено разрешение ALTER SETTINGS на уровне сервера.

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

SCHEMABINDING

Удаление представлений, созданных с SCHEMABINDING помощью инструкции и ссылки на нее EXTERNAL MODEL (например SELECT , инструкции с помощью AI_GENERATE_EMBEDDINGS) предотвращается с помощью ядра СУБД, вызывающего ошибку. Определение представления должно быть сначала изменено или удалено для удаления зависимостей, ссылающихся на .EXTERNAL MODEL

Представление каталога

Метаданные внешней модели просматриваются путем запроса sys.external_models представления каталога. Обратите внимание, что для просмотра метаданных необходимо иметь доступ к модели.

SELECT * FROM sys.external_models;

Примеры

Создание ВНЕШНЕЙ МОДЕЛИ с помощью Azure OpenAI с помощью управляемого удостоверения

В этом примере создается EXTERNAL MODELEMBEDDINGS тип с помощью Azure OpenAI и используется управляемое удостоверение для проверки подлинности.

Это важно

При использовании управляемого удостоверения с Azure OpenAI и SQL Server 2025 роль участника OpenAI Cognitive Services должна быть предоставлена управляемому удостоверению, назначаемому системой SQL Server, включенной Azure Arc. Дополнительные сведения см. в статье "Управление доступом на основе ролей" для Azure OpenAI в моделях 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/]
);

Создание ВНЕШНЕЙ МОДЕЛИ с помощью Azure OpenAI с помощью ключей и параметров API

В этом примере создается EXTERNAL MODELEMBEDDINGS тип с помощью Azure OpenAI и используются ключи API для проверки подлинности. В примере также используется PARAMETERS для задания параметра Dimensions в конечной точке значение 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}'
);

Создание ВНЕШНЕЙ МОДЕЛИ с помощью Ollama и явного владельца

В этом примере создается EXTERNAL MODELEMBEDDINGS тип с помощью Ollama, размещенного локально для целей разработки.

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

Создание ВНЕШНЕЙ МОДЕЛИ с помощью OpenAI

В этом примере создается EXTERNAL MODEL тип с использованием учетных данных на основе заголовка EMBEDDINGS OpenAI API_FORMAT и HTTP для проверки подлинности.

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

Связанный контент