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

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

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 上的 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 路徑的每一部分都必須與憑證名稱中該路徑的相應部分完全相符。
憑證必須指向比請求網址更通用的路徑。例如，為路徑 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 的外部模型

此範例使用 Azure OpenAI 建立該 EMBEDDINGS 類型的外部模型，並使用 Managed Identity 進行認證。

在 SQL Server 2025（17.x）及更新版本中，您必須將 SQL Server 連接到 Azure Arc ，並啟用主要管理身份。

這很重要

如果您使用管理身份搭配 Azure OpenAI 和 SQL Server 2025 （17.x），則必須將認知服務 OpenAI 貢獻者角色授予由 Azure Arc 啟用的 SQL Server 系統指派管理身份。欲了解更多資訊，請參閱 Azure AI Foundry 模型中的 Azure OpenAI 角色基礎存取控制。

使用管理身份建立 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 將端點的 dimensions 參數設定為 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

此範例使用本地托管的 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

此範例利用 OpenAI API_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 Runtime 是一個開源推理引擎，可讓您在本機運行機器學習模型，使其成為將 AI 功能整合到 SQL Server 環境中的理想選擇。

這個範例將引導你如何設定 SQL Server 2025（17.x）搭配 ONNX 執行環境，以啟用本地 AI 驅動的文字嵌入生成。它僅適用於 Windows。

這很重要

此功能需要安裝 SQL Server Machine Learning Services 。

步驟 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 Runtime （1.19 或更高版本）。解壓縮下載後，將（位於 lib 目錄中）複製 onnxruntime.dll 到 C:\onnx_runtime 已建立的目錄。

步驟 4：設定代幣化庫

從 GitHub 下載並建置tokenizers-cpp程式庫。建立 dll 後，將分詞器放在目錄中 C:\onnx_runtime 。

備註

確保創建的 dll 命名為 tokenizers_cpp.dll

步驟 5：下載 ONNX 模型

首先在中model建立C:\onnx_runtime\目錄。

cd C:\onnx_runtime
mkdir model

此範例使用 all-MiniLM-L6-v2-onnx 模型，可從 Hugging Face 下載。

使用下列 C:\onnx_runtime\model 命令將存放庫複製到目錄中：

如果未安裝，您可以從以下下載連結或透過 winget （winget 安裝 Microsoft.Git）下載 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.dll 和 tokenizer_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