CREATE EXTERNAL MODEL (Transact-SQL)

Применимо к: SQL Server 2025 (17.x) База данных SQL AzureУправляемый экземпляр SQL AzureSQL базы данных в Microsoft Fabric

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

Синтаксис

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-model-name'
    [ , CREDENTIAL = <credential_name> ]
    [ , PARAMETERS = '{"valid":"JSON"}' ]
    [ , LOCAL_RUNTIME_PATH = 'path to the ONNX Runtime files' ]
  );

Аргументы

external_model_object_name

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

owner_name

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

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

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

Формат_API

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

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

• Azure OpenAI
• OpenAI
• Ollama
• ONNX Runtime

MODEL_TYPE

Тип модели, к которой можно получить доступ из AI-модели, определяет местоположение конечной точки.

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

• EMBEDDINGS

МОДЕЛЬ

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

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

Задаёт DATABASE SCOPED CREDENTIAL объект, используемый с конечной точкой вывода модели ИИ. Для получения дополнительной информации о типах принятых удостоверений и правилах именования смотрите sp_invoke_external_rest_endpoint или раздел «Замечания » в этой статье.

ПАРАМЕТРЫ

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

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH указывает каталог в локальном экземпляре SQL Server, где находятся исполняемые файлы среды выполнения ONNX.

Разрешения

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

Требуется 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> } }

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

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

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

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

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

Замечания

HTTPS и TLS

Для параметра LOCATION поддерживаются только конечные точки вывода модели ИИ, настроенные на использование HTTPS с протоколом шифрования TLS.

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

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

API_FORMAT для EMBEDDINGS

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

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

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

• Azure OpenAI в моделях Azure AI Foundry
• OpenAI
• Ollama

Правила имени учетных данных для внешней модели

Созданная DATABASE SCOPED CREDENTIAL модель, используемая внешней моделью, должна следовать следующим правилам:

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

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

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

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

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

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

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

Раздел 6.2.2.1 RFC 3986 гласит, что «Когда URI использует компоненты общего синтаксиса, всегда применяются правила эквивалентности синтаксиса компонентов; а именно, что схема и ведущий не чувствительны к регистру.» Раздел 2.7.3 RFC 7230 отмечает, что «все остальные сравниваются с учётом регистра».

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

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

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

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

Манажируемая идентичность

Чтобы использовать удостоверение управляемого удостоверения узла Arc/VM в качестве учетных данных уровня базы данных в SQL Server 2025 (17.x), Этот параметр необходимо включить с помощью sp_configure с пользователем, granted разрешение на уровне сервера ALTER SETTINGS.

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

SCHEMABINDING

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

Вид в каталоге

Вы можете просмотреть метаданные внешней модели, задавая запросы к sys.external_models каталогу. Для просмотра её метаданных необходимо иметь доступ к модели.

SELECT *
FROM sys.external_models;

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

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

В этом примере создается внешняя модель типа EMBEDDINGS с помощью openAI Azure и используется Managed Identity для проверки подлинности.

В SQL Server 2025 (17.x) и более поздних версиях необходимо подключить SQL Server к Azure Arc и enable основному управляемому удостоверению.

Создайте учетные данные доступа для Azure OpenAI с помощью управляемого удостоверения:

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

Создайте внешнюю модель:

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

Создание внешней модели с помощью Azure OpenAI с помощью ключей и параметров API

В этом примере создается внешняя модель типа EMBEDDINGS с помощью Azure OpenAI и использует ключи API для проверки подлинности. В примере также используется PARAMETERS для задания параметра измерения в конечной точке значение 725.

Создайте учетные данные доступа для Azure OpenAI с помощью ключа:

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

Создайте внешнюю модель:

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

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

Этот пример создаёт внешнюю модель типа EMBEDDINGS с использованием локально размещенной 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

В этом примере создаётся внешняя модель такого 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]
);

Пример с локальным запуском ONNX Runtime

ONNX Runtime — это механизм вывода с открытым исходным кодом, который позволяет локально запускать модели машинного обучения, что делает его идеальным для интеграции возможностей ИИ в SQL Server средах.

В этом примере описано, как настроить SQL Server 2025 (17.x) с помощью onNX Runtime, чтобы включить создание встроенного текста на основе ИИ. Применяется только к Windows.

Вопросы безопасности

Вы можете использовать функцию узла среды выполнения ИИ для настройки и использования собственных библиотек LLM и ONNX с SQL Server. Так как Майкрософт не проверяет или отслеживает сторонние модели и библиотеки, вы несете ответственность за выбор соответствующих моделей и библиотек, фильтрацию содержимого, защиту среды выполнения и обеспечение соответствия любым применимым политикам и нормативным требованиям.

Чтобы устранить эти риски, рассмотрите следующие рекомендации по обеспечению безопасности:

• Реализуйте строгие элементы управления доступом: убедитесь, что у авторизованных пользователей есть доступ к конфиденциальным данным и моделям среды выполнения ONNX. Проверьте все модели перед загрузкой их в SQL Server. Используйте принцип наименьших привилегий, а также роли и привилегии базы данных.
• Мониторинг и аудит доступа: регулярно отслеживайте и проверяйте доступ к базе данных и AI_GENERATE_EMBEDDINGS вызовам функций для обнаружения подозрительных действий.
• Проводите регулярные оценки безопасности: выполняйте проверки уязвимостей и проверки безопасности для выявления и устранения потенциальных рисков.

Шаг 1. Включение предварительных версий функций разработчика в SQL Server 2025 г.

Выполните следующую команду Transact-SQL (T-SQL), чтобы включить предварительные версии функций SQL Server 2025 (17.x) в базе данных, которые вы хотите использовать для этого примера:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Шаг 2. Включение локальной среды выполнения ИИ в SQL Server 2025 г.

Включите внешние AI-серверы выполнения, выполнив следующий запрос T-SQL:

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

Шаг 3: Настройте библиотеку ONNX Runtime

Создайте каталог в экземпляре SQL Server для хранения файлов библиотеки среды выполнения ONNX. В этом примере C:\onnx_runtime используется.

Для создания каталога можно использовать следующие команды:

cd C:\
mkdir onnx_runtime

Далее скачайте версию ONNX Runtime (1.19 или выше), подходящую для вашей операционной системы. После распакуйте скачивание, скопируйте onnxruntime.dll (расположенную в каталоге lib) в C:\onnx_runtime созданный каталог.

Шаг 4. Настройка библиотеки токенизации

Скачайте и создайте библиотеку tokenizers-cpp library из GitHub. После создания библиотеки DLL поместите токенизатор в C:\onnx_runtime каталог.

Шаг 5. Скачивание модели ONNX

Начните с создания model каталога в C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

В этом примере используется all-MiniLM-L6-v2-onnx модель, которую можно скачать из Hugging Face.

Клонируйте репозиторий в каталог с помощью следующей C:\onnx_runtime\model команды Git :

If not install, можно скачать git со следующей ссылки download link или winget (winget install Майкрософт. Git)

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

Шаг 6. Настройка разрешений каталога

Используйте следующий скрипт PowerShell для предоставления пользователю MSSQLLaunchpad доступа к каталогу 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

Шаг 7. Создание внешней модели

Выполните следующий запрос, чтобы зарегистрировать вашу модель ONNX как внешний объект модели:

Здесь используется значение PARAMETERS, необходимое для 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 должно указывать на каталог, содержащий model.onnx и tokenizer.json файлы.
• LOCAL_RUNTIME_PATH должно указывать на каталоги, содержащие onnxruntime.dll файлы tokenizer_cpp.dll .

Шаг 8. Создание внедрения

Используйте ai_generate_embeddings функцию для тестирования модели, выполнив следующий запрос:

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

Эта команда запускает AIRuntimeHostнеобходимые библиотеки DLL и обрабатывает входной текст.

Результатом предыдущего запроса является массив вложенных элементов:

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

Включить логирование системы XEvent

Выполните следующий запрос, чтобы включить системное логирование для устранения неполадок.

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

Далее используйте этот запрос, чтобы посмотреть захваченные системные журналы:

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

Очистка

Чтобы удалить внешний объект модели, выполните следующий оператор T-SQL:

DROP EXTERNAL MODEL myLocalOnnxModel;

Чтобы удалить разрешения каталога, выполните следующие команды PowerShell:

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

Наконец, удалите C:/onnx_runtime каталог.

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

• ALTER EXTERNAL MODEL (Transact-SQL)
• DROP EXTERNAL MODEL (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL)
• sys.external_models
• Create и развертывание Azure OpenAI в ресурсе модели Azure AI Foundry
• Параметры конфигурации сервера
• Role для управления доступом Azure OpenAI в Azure AI Foundry models