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

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

重試計數

如果內嵌呼叫遇到指出暫時問題的 HTTP 狀態代碼，您可以設定要求來自動重試。若要指定重試次數，請將下列 JSON 新增至 PARAMETERS 上的 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

參數僅支援設定為使用 HTTPS 搭配 TLS 加密通訊協定的 LOCATION AI 模型推斷端點。

接受的 API 格式和模型類型

下列各節概述每個 MODEL_TYPE的已接受 API 格式。

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 網域必須是allowlist中包含的其中一個網域
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

使用 Database Engine 引發錯誤時，會防止卸除以 SCHEMABINDING 建立並參考 EXTERNAL MODEL 的檢視（例如使用 AI_GENERATE_EMBEDDINGSSELECT 語句）。必須先修改或卸除檢視定義本身，才能移除參考的 EXTERNAL MODEL相依性。

目錄檢視

藉由查詢 sys.external_models 目錄檢視來檢視外部模型元數據。請注意，您必須能夠存取模型，才能檢視元數據。

SELECT * FROM sys.external_models;

範例

使用受控識別建立具有 Azure OpenAI 的外部模型

此範例會使用 Azure OpenAI 建立 EMBEDDINGS 類型的 EXTERNAL MODEL，並使用受控識別進行驗證。

這很重要

如果使用受控識別搭配 Azure OpenAI 和 SQL Server 2025， Cognitive Services OpenAI Contributor 則必須將角色授與 SQL Server 的系統指派受控識別 BY ARC。如需詳細資訊，請參閱 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 的外部模型

此範例會使用 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

此範例會 EXTERNAL MODEL 使用本機裝載的 Ollama 來建立型別的 EMBEDDINGS ，以供開發之用。

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

使用 OpenAI 建立 EXTERNAL MODEL

此範例會EXTERNAL MODELEMBEDDINGS使用 OpenAI API_FORMAT 和 HTTP 標頭型認證來建立型別的，以進行驗證。

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

共用方式為