CREATE EXTERNAL MODEL （Transact-SQL）

2025-06-16

适用于： 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-ada-002'
    [ , CREDENTIAL = <credential_name> ]
    [ , PARAMETERS = '{"valid":"JSON"}' ]
  );

论据

external_model_object_name

指定外部模型的用户定义名称。该名称在数据库中必须唯一。

owner_name

指定拥有外部模型的用户或角色的名称。如果未指定，则为当前用户提供所有权。根据权限和角色，需要向用户授予显式权限才能使用特定的外部模型。

位置

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

API_FORMAT

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

接受的值包括：

Azure OpenAI
OpenAI
Ollama

模型类型

从 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}'

权限

外部模型创建和更改

需要 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（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 上使用托管标识进行身份验证，必须使用授予 ALTER SETTINGS 服务器级权限的用户来启用该选项sp_configure。

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 MODEL

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

重要

如果将托管标识与 Azure OpenAI 和 SQL Server 2025 配合使用， Cognitive Services OpenAI Contributor 则必须通过 ARC 向 SQL Server 的系统分配托管标识授予该角色。有关详细信息，请参阅 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 创建 EMBEDDINGS 类型的 EXTERNAL MODEL，并使用 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 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]
);

通过