外部モデルを作成(Transact-SQL)

対象者: SQL Server 2025 (17.x) Azure SQL DatabaseSQL database in Microsoft Fabric

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

構文

Transact-SQL 構文表記規則

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 はローカル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 状態コードが検出された場合は、要求を自動的に再試行するように構成できます。 再試行回数を指定するには、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 モデル推論エンドポイント プロバイダーに次のリンクを使用してください。

• Azure AI Foundry モデルにおける Azure OpenAI
• OpenAI
• オラマ

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

外部モデルで使用される作成された 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ルールよりも制限が厳しい可能性があります。)

1. RFC を使用して URL と資格情報が一致するかどうかを確認します。これは次のことを意味します。

   • 大文字と小文字を区別しない照合順序を使用してスキームとホストを確認する (Latin1_General_100_CI_AS_KS_WS_SC)
   • 大文字と小文字を区別する照合順序で URL の他のすべてのセグメントが比較されていることを確認する (Latin1_General_100_BIN2)

2. URL と資格情報がデータベースの照合順序規則を使用して一致することを確認します (URL エンコードは行いません)。

マネージド ID

SQL Server 2025(17.x)でArc/VMホストのマネージドIDをデータベースレベルの認証情報として使用するには、ALTER SETTINGSサーバーレベルの権限が付与されたユーザーと共にsp_configureを有効にしなければなりません。

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

SCHEMABINDING

外部モデルを参照するビュー(例えばAI_GENERATE_EMBEDDINGSを使ったSELECT文)SCHEMABINDINGを参照するビューはドロップできず、データベースエンジンはエラーを出します。 外部モデルを参照する依存関係を削除するには、まずビュー定義を修正または削除する必要があります。

カタログビュー

外部モデルのメタデータは 、sys.external_models カタログビューでクエリすることで閲覧できます。 メタデータを見るにはモデルへのアクセスが必要です。

SELECT *
FROM sys.external_models;

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

マネージド ID を使用して Azure OpenAI で EXTERNAL MODEL を作成する

この例はAzure OpenAIを用いて EMBEDDINGS タイプの外部モデルを作成し、 認証にはマネージドID を使用しています。

SQL Server 2025(17.x)以降のバージョンでは、 SQL ServerをAzure Arcに接続 し、 プライマリマネージドIDを有効にする必要があります。

Von Bedeutung

Azure OpenAIおよびSQL Server 2025(17.x)でマネージドIDを使用する場合、Azure Arcによって有効化されたSQL Serverのシステム割り当てマネージドIDに認知サービスOpenAI貢献者の役割が付与されなければなりません。詳細については、Azure AI Foundry Modelsの「Role-based access control for Azure OpenAI」を参照してください。

管理型IDを使って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/]
);

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

この例はAzure OpenAIを用いて EMBEDDINGS タイプの外部モデルを作成し、認証にはAPIキーを使用しています。 また、この例では、 PARAMETERS を使用して、エンドポイントのディメンション パラメーターを 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 を使用して外部モデルを作成する

この例では、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 にのみ適用されます。

Von Bedeutung

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

手順 1: SQL Server 2025 で開発者プレビュー機能を有効にする

この例で使いたいデータベースでSQL Server 2025(17.x)プレビュー機能を有効にするには、以下の Transact-SQL(T-SQL)コマンドを実行してください。

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

次に、あなたの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 ディレクトリを削除します。

関連コンテンツ

• 外部モデルの変形(Transact-SQL)
• 外部モデルをドロップ(Transact-SQL)
• AI_GENERATE_EMBEDDINGS(Transact-SQL)
• AI_GENERATE_CHUNKS(Transact-SQL)
• sys.external_models
• Azure AI Foundry Models リソースで Azure OpenAI を作成してデプロイする
• サーバー構成オプション
• Azure AI Foundry モデルでの Azure OpenAI のロールベースのアクセス制御