CREATE EXTERNAL MODEL （Transact-SQL）

适用于： SQL Server 2025 （17.x） Azure SQL Database SQL database in Microsoft Fabric

创建一个外部模型对象，该对象包含 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 指定本地SQL Server实例中ONNX运行时可执行文件所在的目录。

权限

外部模型创建和更改

需要 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 编码）。

托管标识

要在 SQL Server 2025（17.x）中使用 Arc/VM 主机的托管身份作为数据库级凭证，您必须通过与被授予 ALTER SETTINGS 服务器级权限的用户一起使用sp_configure来启用该选项。

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 创建 EXTERNAL MODEL

本例使用Azure OpenAI创建该 EMBEDDINGS 类型的外部模型，并使用托管身份进行身份验证。

在SQL Server 2025（17.x）及更高版本中，你必须将SQL Server连接到Azure Arc 并启用主托管身份。

重要

如果您使用Azure OpenAI和SQL Server 2025（17.x）的托管身份，必须将认知服务OpenAI贡献者角色授予由 Azure Arc启用的SQL Server系统分配的管理身份。欲了解更多信息，请参见 Azure AI Foundry Models中的基于角色的访问控制。

使用管理身份创建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 密钥和参数

本示例使用 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 创建外部模型

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

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

本示例将引导你如何搭建带有 ONNX 运行时的 SQL Server 2025（17.x），以实现本地 AI 驱动的文本嵌入生成。它仅适用于 Windows。

重要

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

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

如果未安装，可以从以下下载链接或通过 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 2025-12-08