CREATE EXTERNAL MODEL (Transact-SQL)

Applies to: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL データベース>

AI モデル推論エンドポイントの場所、認証方法、および目的を含む外部モデルオブジェクトを作成します。

注

CREATE EXTERNAL MODEL は、Always-up-to-dateupdate ポリシーとAzure SQL Managed Instanceで使用できます。

構文

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

モデルタイプ

AIモデルからアクセスされるモデルの種類、推論エンドポイントの位置。

指定できる値は次のとおりです。

EMBEDDINGS

モデル

AI プロバイダーによってホストされる特定のモデル。 (text-embedding-ada-002、text-embedding-3-large、または o3-mini など)。

資格情報

AIモデル推論エンドポイントで使用される DATABASE SCOPED CREDENTIAL オブジェクトを指定します。承認される資格の種類や命名ルールの詳細については、この記事の sp_invoke_external_rest_endpoint または備考セクションをご覧ください。

パラメーター

AIモデル推論エンドポイントのリクエストメッセージに付加するための実行パラメータを含む有効なJSON文字列。例えば次が挙げられます。

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH は、ONNX ランタイム実行可能ファイルが配置されているローカル SQL Server インスタンス上のディレクトリを指定します。

権限

外部モデルの作成と変更

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 状態コードが検出された場合は、要求を自動的に再試行するように構成できます。再試行回数を指定するには、PARAMETERSのEXTERNAL MODELに次の JSON を追加します。 <number_of_retries>は、0 (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パラメータについては、TLS暗号化プロトコルでHTTPSを使用するよう設定されたAIモデル推論エンドポイントのみがサポートされています。

受け入れ可能な API 形式とモデルの種類

以下のセクションでは、各 MODEL_TYPE で認められているAPIフォーマットを概説します。

埋め込み用の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
オラマ	https://localhost:{port}/api/embed

埋め込みエンドポイントを作成する

埋め込みエンドポイントの作成の詳細については、適切な AI モデル推論エンドポイントプロバイダーに次のリンクを使用してください。

外部モデルの認証名ルール

外部モデルで使用される作成された DATABASE SCOPED CREDENTIAL は以下のルールに従う必要があります:

有効な URL である必要があります
URLドメインは許可リストに含まれるドメインのいずれかでなければなりません。
URL にクエリ文字列を含めてはなりません
呼び出された URL のプロトコル + 完全修飾ドメイン名 (FQDN) は、資格情報名のプロトコル + 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 エンコードは行いません)。

マネージド ID

Arc/VM ホストの管理 ID を SQL Server 2025 (17.x) のデータベースレベルの資格情報として使用するには )、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;

リモートエンドポイントの例

マネージド ID を使用Azure OpenAI を使用して外部モデルを作成する

この例では、Azure OpenAI を使用して EMBEDDINGS 型の外部モデルを作成し、認証に Managed Identity を使用します。

SQL Server 2025 (17.x) 以降のバージョンでは、SQL Serverを Azure Arc に<>接続し>プライマリマネージド ID を

Von Bedeutung

Azure OpenAI と SQL Server 2025 (17.x) でマネージド ID を使用する場合、Cognitive Services OpenAI 共同作成者ロールは、Azure Arc によって有効SQL Serverのシステム割り当てマネージド ID に付与される必要があります。詳細については、「Azure AI Foundry モデルの OpenAI Azureの Role ベースのアクセス制御」を参照してください。

マネージド ID を使用して OpenAI Azureアクセス資格情報を作成します。

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

API キーとパラメーターを使用Azure OpenAI を使用して外部モデルを作成する

この例では、Azure OpenAI を使用して EMBEDDINGS 型の外部モデルを作成し、認証に API キーを使用します。また、この例では、 PARAMETERS を使用して、エンドポイントのディメンションパラメーターを 725 に設定します。

キーを使用して OpenAI をAzureするためのアクセス資格情報を作成します。

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 を使用して外部モデルを作成する

この例では、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環境に統合するのに最適です。

この例では、ONNX Runtime を使用して SQL Server 2025 (17.x) を設定し、ローカル AI を利用したテキスト埋め込み生成を有効にする方法について説明します。 Windowsにのみ適用されます。

Von Bedeutung

この機能を使用するには、SQL Server Machine Learning Services がインストールされている必要があります。

セキュリティの考慮事項

AI ランタイムホスト機能を使用して、SQL Serverで独自の LLM と ONNX ライブラリを構成して使用できます。 Microsoftはサードパーティのモデルとライブラリを検証または監視しないため、適切なモデルとライブラリの選択、コンテンツのフィルター処理、ランタイムのセキュリティ保護、適用されるポリシーと規制への準拠の確保を担当します。

注意事項

悪意のある ONNX モデルまたは侵害された 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ランタイムライブラリの設定

onNX ランタイムライブラリファイルを保持するディレクトリを SQL Server インスタンスに作成します。この例では、 C:\onnx_runtime を使用します。

次のコマンドを使用してディレクトリを作成できます。

cd C:\
mkdir onnx_runtime

次に、あなたのOSに適した 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 からダウンロードできるモデルを使用します。

次の C:\onnx_runtime\model コマンドを使用して、リポジトリをディレクトリに複製します。

インストールされていない場合は、次のダウンロードリンクまたは winget (winget install 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 2026-04-08