CREATE EXTERNAL MODEL （Transact-SQL）

2025-08-21

适用于： SQL Server 2025 （17.x）预览版

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

语法

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_TYPEAPI 格式的接受格式。

EMBEDDINGS 的API_FORMAT

下表概述了模型类型的 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

创建嵌入终结点

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

EXTERNAL MODEL 的凭据名称规则

DATABASE SCOPED CREDENTIAL创建的EXTERNAL MODEL创建必须遵循特定的以下规则：

必须是有效的 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 编码）。

托管身份

若要在 SQL Server 2025 上使用托管标识进行身份验证，必须使用sp_configure的用户来启用该选项。

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

SCHEMABINDING

使用数据库引擎引发错误时，会阻止删除创建SCHEMABINDING和引用EXTERNAL MODEL语句SELECTAI_GENERATE_EMBEDDINGS的视图。必须先修改或删除视图定义本身，以删除引用的 EXTERNAL MODEL依赖项。

目录视图

可以通过查询 sys.external_models 目录视图来查看外部模型元数据。请注意，必须有权访问模型才能查看元数据。

SELECT * FROM sys.external_models;

远程终结点的示例

使用托管标识通过 Azure OpenAI 创建 EXTERNAL MODEL

此示例使用 Azure OpenAI 创建 EXTERNAL MODEL 类型 EMBEDDINGS ，并使用托管标识进行身份验证。

重要

如果将托管标识与 Azure OpenAI 和 SQL Server 2025 配合使用，则必须向 Azure Arc 启用的 SQL Server 系统分配的托管标识授予认知服务 OpenAI 参与者角色。有关详细信息，请参阅 Azure AI Foundry 模型中 Azure OpenAI 的基于角色的访问控制。

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

使用 API 密钥和参数通过 Azure OpenAI 创建 EXTERNAL MODEL

此示例使用 Azure OpenAI 创建 EXTERNAL MODEL 类型 EMBEDDINGS ，并使用 API 密钥进行身份验证。该示例还用于 PARAMETERS 将终结点上的维度参数设置为 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 MODEL

此示例使用本地托管的 Ollama 创建一个EXTERNAL MODELEMBEDDINGS类型，以便进行开发。

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

使用 OpenAI 创建外部模型

此示例使用基于 OpenAI EXTERNAL MODEL 和 HTTP 标头的EMBEDDINGS凭据创建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 运行时设置 SQL Server 2025，以启用本地 AI 支持的文本嵌入生成。它仅适用于 Windows。

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

重要

此功能要求安装 SQL Server 机器学习服务。

步骤 1：在 SQL Server 2025 上启用开发人员预览功能

运行以下 SQL 命令，在要用于此示例的数据库中启用 SQL Server 2025 预览功能：

ALTER DATABASE SCOPED CONFIGURATION  
SET PREVIEW_FEATURES = ON;

步骤 2：在 SQL Server 2025 上启用本地 AI 运行时

通过运行以下 SQL 启用外部 AI 运行时：

EXEC 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 命令将存储库克隆到目录中：

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

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

步骤 6：设置目录权限

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

$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：创建外部模型

运行以下 SQL 以将 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 以下 SQL，使用函数测试模型：

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

此命令启动 AIRuntimeHost、加载所需的 DLL 并处理输入文本。

SQL 语句的结果是嵌入数组：

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

启用 XEvent 遥测

运行以下 SQL 以启用遥测进行故障排除。

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

接下来，使用此 SQL 查询查看捕获的遥测数据：

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

清理

若要删除外部模型对象，请运行以下 SQL：

DROP EXTERNAL MODEL myLocalOnnxModel;

若要删除目录权限，请运行以下 PowerShell 命令：

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

最后，删除 C:/onnx_runtime 目录。

反馈

此页面是否有帮助？