CREATE EXTERNAL MODEL （Transact-SQL）

2025-05-19

适用于： 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

MODEL_TYPE

从 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

注解

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

例子

使用 Azure OpenAI 创建外部模型

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

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

通过查询 sys.external_models 目录视图来验证是否创建了新的外部模型。

SELECT * FROM sys.external_models;

使用 Ollama、默认参数和显式所有者创建 EXTERNAL MODEL

此示例使用本地托管的 Ollama 创建一个EXTERNAL MODELEMBEDDINGS类型，以便进行开发。该示例还用于 PARAMETERS 将终结点上的 Dimensions 参数设置为 725。

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

使用 OpenAI 创建外部模型

此示例使用基于 OpenAI API_FORMAT 和 HTTP 标头的EMBEDDINGS凭据创建EXTERNAL MODEL类型的身份验证。

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

通过