CREATE EXTERNAL MODEL （Transact-SQL）

applies to： SQL Server 2025 （17.x） < >Azure SQL DatabaseAzure SQL Managed InstanceSQL 数据库Microsoft Fabric

创建一个外部模型对象，该对象包含 AI 模型推理终结点的位置、身份验证方法和用途。

注释

CREATE EXTERNAL MODEL在 Always-up-to-dateupdate 策略 Azure SQL Managed Instance中提供。

语法

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

指定拥有外部模型的用户或角色的名称。如果你不明确说明这个论点，当前用户就会成为所有者。根据权限和角色，你可能需要明确授权用户使用特定的外部模型。

位置

提供 AI 模型推理终结点的连接协议和路径。

API_FORMAT

AI 模型推理终结点提供程序的 API 消息格式。

接受的值包括：

Azure OpenAI
OpenAI
Ollama
ONNX Runtime

模型类型

从AI模型推断端点位置访问的模型类型。

接受的值包括：

EMBEDDINGS

型

由 AI 提供程序托管的特定模型。例如，text-embedding-ada-002、text-embedding-3-large 或 o3-mini。

凭据

指定 DATABASE SCOPED CREDENTIAL 与AI模型推理端点共用的对象。有关接受的凭证类型和命名规则的更多信息，请参见本文 sp_invoke_external_rest_endpoint 或备注部分。

参数

一个有效的JSON字符串，包含用于附加到AI模型推理端点请求消息的运行时参数。例如：

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH指定 ONNX 运行时可执行文件所在的本地SQL Server实例上的目录。

权限

外部模型创建和更改

需要 ALTER ANY EXTERNAL MODEL 或 CREATE EXTERNAL MODEL 数据库权限。

例如：

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

或者：

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

外部模型授予

若要在 AI 函数中使用外部模型，必须向其授予主体的能力 EXECUTE 。

例如：

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

重试计数

如果嵌入调用遇到指示临时问题的 HTTP 状态代码，则可以将请求配置为自动重试。若要指定重试次数，请将以下 JSON 添加到 PARAMETERS on 中 EXTERNAL 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 ，仅支持配置为使用 HTTPS 和 TLS 加密协议的 AI 模型推理端点。

接受的 API 格式和模型类型

以下章节概述了每个 MODEL_TYPE的可接受的 API 格式。

EMBEDDINGS 的API_FORMAT

下表概述 EMBEDDINGS 了模型类型的API格式和URL端点结构。若要查看特定的有效负载结构，请使用 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

创建嵌入终结点

有关创建嵌入终结点的详细信息，请使用以下链接获取相应的 AI 模型推理终结点提供程序：

外部模型的凭证名称规则

外部模型所用的创建 DATABASE SCOPED CREDENTIAL 物必须遵循以下规则：

必须是有效的 URL
URL 域名必须是允许列表中包含的域名之一。
URL 不得包含查询字符串
调用 URL 的协议 + 完全限定域名（FQDN）必须与凭据名称的 Protocol + 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规则更为严格，例如如果数据库设置为使用大小写区分的排序。）

使用 RFC 检查 URL 和凭据是否匹配，这意味着：
- 使用不区分大小写的排序规则检查方案和主机（Latin1_General_100_CI_AS_KS_WS_SC）
- 检查 URL 的所有其他段是否在区分大小写的排序规则中进行比较（Latin1_General_100_BIN2）
使用数据库排序规则检查 URL 和凭据是否匹配（无需执行任何 URL 编码）。

托管标识

若要使用 managed identity Arc/VM 主机作为 SQL Server 2025（17.x.x）中的数据库级别凭据）、必须对启用该选项>启用 ALTER SETTINGS 服务器级权限。

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

SCHEMABINDING

无法使用引用外部模型的 SCHEMABINDING 创建的视图（如使用 SELECT 的 AI_GENERATE_EMBEDDINGS 语句），并且Database Engine引发错误。要移除引用外部模型的依赖，首先必须修改或取消视图定义。

目录视图

您可以通过查询 sys.external_models 目录视图查看外部模型元数据。您必须访问模型才能查看其元数据。

SELECT *
FROM sys.external_models;

远程终结点的示例

使用托管标识创建具有 Azure OpenAI 的外部模型

此示例使用 Azure OpenAI 创建 EMBEDDINGS 类型的外部模型，并使用 Managed Identity 进行身份验证。

在 SQL Server 2025（17.x）及更高版本中，必须连接SQL Server以Azure Arc和可启用主托管标识。

重要

如果将托管标识用于 Azure OpenAI 和 SQL Server 2025 （17.x），则必须向 Cognitive Services OpenAI 参与者角色授予SQL Server系统分配的托管标识Azure Arc。有关详细信息，请参阅 Azure AI Foundry Models 中的 Azure OpenAI 基于Role 的访问控制。

使用托管标识创建访问凭据以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/]
);

使用 API 密钥和参数创建具有 Azure OpenAI 的外部模型

此示例使用 Azure OpenAI 创建 EMBEDDINGS 类型的外部模型，并使用 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 和显式所有者创建 EXTERNAL MODEL

这个例子创建了一个外部模型， 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 创建外部模型

本示例使用基于OpenAIEMBEDDINGS和HTTP头的凭证创建了该API_FORMAT类型的外部模型进行认证。

-- 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 运行时示例

ONNX Runtime 是一个开源推理引擎，可用于在本地运行机器学习模型，因此非常适合将 AI 功能集成到SQL Server环境中。

此示例指导你使用 ONNX 运行时设置 SQL Server 2025 （17.x），以启用本地 AI 驱动的文本嵌入生成。它仅适用于Windows。

重要

此功能要求安装 SQL Server Machine Learning Services。

安全注意事项

可以使用 AI 运行时主机功能配置和使用自己的 LLM 和 ONNX 库和 SQL Server。由于Microsoft不验证或监视第三方模型和库，因此你负责选择适当的模型和库、筛选内容、保护运行时并确保符合任何适用的策略和法规。

注意

恶意或泄露的 ONNX 模型可能会泄露数据或执行未经授权的代码。仅使用来自受信任的已验证源的模型。

若要缓解这些风险，请考虑以下安全最佳做法：

实现强访问控制：确保只有授权用户有权访问敏感数据和 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 查询，启用外部 AI 运行时：

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

步骤3：建立ONNX运行时库

在SQL Server实例上创建一个目录以保存 ONNX 运行时库文件。在此示例中， C:\onnx_runtime 使用。

可以使用以下命令创建目录：

cd C:\
mkdir onnx_runtime

接下来，下载适合你作系统的 ONNX 运行时版本（1.19 或更高版本）。解压缩下载后，将 onnxruntime.dll （位于 lib 目录中） C:\onnx_runtime 复制到已创建的目录。

步骤 4：设置令牌化库

从 GitHub 下载并生成 tokenizers-cpp 库。创建 dll 后，将 tokenizer C:\onnx_runtime 放在目录中。

注释

确保创建的 dll 命名 为tokenizers_cpp.dll

步骤 5：下载 ONNX 模型

首先在 model . 中创建 C:\onnx_runtime\目录。

cd C:\onnx_runtime
mkdir model

此示例使用 all-MiniLM-L6-v2-onnx 可从拥抱人脸下载的模型。

使用以下 C:\onnx_runtime\model 命令将存储库克隆到目录中：

如果未安装，可以从以下 download 链接或通过 winget 下载 git（winget install Microsoft）。Git）

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

步骤 6：设置目录权限

使用以下PowerShell脚本为MSSQLLaunchpad用户提供访问ONNX运行时目录的权限：

$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.dlltokenizer_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 目录。

反馈

此页面是否有帮助？

Last updated on 2026-04-08