建立外部模型（Transact-SQL）

適用於： SQL Server 2025 （17.x） Azure SQL Database Azure SQL Managed Instance SQL 資料庫 in Microsoft Fabric

建立外部模型物件，其中包含 AI 模型推斷端點的位置、驗證方法和用途。

備註

CREATE EXTERNAL MODEL 在 Azure SQL Managed Instance 中可用，採用 Always-up-to-dateupdate policy。

語法

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 編碼）。

受管理的識別

若要在 2025 SQL Server（17.x）中使用 Arc/VM 主機的 managed identity作為資料庫層級憑證，您必須使用 sp_configure 啟用該選項，且使用者被授權為已獲得 ALTER SETTINGS 伺服器層權限。

EXECUTE sp_configure 'allow server scoped db credentials', 1;
RECONFIGURE WITH OVERRIDE;

SCHEMABINDING

使用 SCHEMABINDING 建立且參考外部模型的視圖（例如使用 SELECT 的 AI_GENERATE_EMBEDDINGS 陳述句）無法被丟棄，且Database Engine會產生錯誤。要移除引用外部模型的依賴，必須先修改或移除視圖定義。

目錄檢視

您可以透過查詢 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）中使用受管身份，Cognitive Services OpenAI 貢獻者角色必須授予由 Azure Arc 啟用的 SQL Server 系統指定的管理身份。欲了解更多資訊，請參閱基於角色的存取控制，Azure OpenAI 在Azure AI Foundry模型中。

使用管理身份建立 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 金鑰和參數建立外部模型

此範例使用 OpenAI 建立 EMBEDDINGS 類型的外部模型Azure並使用 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 EMBEDDINGS 與 HTTP 標頭憑證建立該類型的外部模型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]
);

本地執行 ONNX 執行環境的範例

ONNX Runtime 是一款開源推論引擎，允許你在本地執行機器學習模型，非常適合將 AI 功能整合進SQL Server環境。

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

這很重要

此功能需安裝 SQL Server Machine Learning 服務。

安全性考慮

你可以使用 AI 執行時主機功能，透過 SQL Server 配置並使用自己的 LLM 和 ONNX 函式庫。由於 Microsoft 不驗證或監控第三方模型與函式庫，您需負責選擇合適的模型與函式庫、過濾內容、保護執行時安全，並確保遵守任何適用的政策與法規。

謹慎

惡意或被入侵的 ONNX 模型可能會外洩資料或執行未經授權的程式碼。只使用可信且經過驗證來源的模型。

為降低這些風險，請考慮以下安全最佳實務：

實施強健的存取控制：確保只有授權使用者能存取敏感資料及 ONNX 執行時模型。在載入 SQL Server 前，請先驗證所有模型。使用最低許可權的原則，以及資料庫角色和許可權。
監控與稽核存取：定期監控並稽核資料庫及 AI_GENERATE_EMBEDDINGS 函數呼叫的存取，以偵測可疑活動。
定期進行安全評估：進行漏洞掃描與安全審查，以識別並降低潛在風險。

步驟 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 下載並建置 the 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 命令將存放庫複製到目錄中：

如果沒安裝，你可以從以下download link或透過 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」值是 2025 SQL Server （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 。

ALTER 外部模型（Transact-SQL）
DROP EXTERNAL MODEL （Transact-SQL）
AI_GENERATE_EMBEDDINGS （Transact-SQL）
AI_GENERATE_CHUNKS （Transact-SQL）
sys.external_models
在Azure AI Foundry Models資源
伺服器組態選項
基於角色的存取控制，適用於Azure Azure AI Foundry模型中的 OpenAI

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-08