次の方法で共有

CREATE EXTERNAL MODEL (Transact-SQL)

適用対象: SQL Server 2025 (17.x) プレビュー

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-ada-002'
    [ , CREDENTIAL = <credential_name> ]
    [ , PARAMETERS = '{"valid":"JSON"}' ]
  );

論争

external_model_object_name

外部モデルのユーザー定義名を指定します。 名前は、データベース内で一意である必要があります。

owner_name

外部モデルを所有するユーザーまたはロールの名前を指定します。 指定しない場合は、現在のユーザーに所有権が付与されます。 アクセス許可とロールに応じて、特定の外部モデルを使用するには、明示的なアクセス許可をユーザーに付与する必要があります。

場所

接続プロトコルと AI モデル推論エンドポイントへのパスを提供します。

API_FORMAT

AI モデル推論エンドポイント プロバイダーの API メッセージ形式。

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

  • Azure OpenAI
  • OpenAI
  • Ollama

モデルタイプ

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

権限

外部モデルの作成と変更

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) から 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 モデル推論エンドポイント プロバイダーに次のリンクを使用してください。

EXTERNAL MODEL の資格情報名規則

DATABASE SCOPED CREDENTIALによって使用される作成されたEXTERNAL MODELは、次の特定の規則に従う必要があります。

  • 有効な 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 で認証にマネージド ID を使用するには、sp_configureされているユーザーに対してを使用してオプションを有効にする必要があります。

EXECUTE sp_configure 'allow server scoped db credentials', 1;

RECONFIGURE WITH OVERRIDE;

SCHEMABINDING

SCHEMABINDINGで作成されたビューを削除し、EXTERNAL MODEL (AI_GENERATE_EMBEDDINGS を使用した SELECT ステートメントなど) を参照すると、データベース エンジンでエラーが発生することが防止されます。 EXTERNAL MODELを参照する依存関係を削除するには、最初にビュー定義自体を変更または削除する必要があります。

カタログ ビュー

外部モデル メタデータは、 sys.external_models カタログ ビューに対してクエリを実行して表示されます。 メタデータを表示できるようにするには、モデルへのアクセス権が必要です。

SELECT * FROM sys.external_models;

例示

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

この例では、Azure OpenAI を使用して EMBEDDINGS 型の EXTERNAL MODEL を作成し、認証に マネージド ID を 使用します。

Von Bedeutung

Azure OpenAI と SQL Server 2025 でマネージド ID を使用する場合、 ロールは、ARC によって SQL Server のシステム割り当てマネージド ID に付与される必要があります。 詳細については、 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 で EXTERNAL MODEL を作成する

この例では、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 を作成する

この例では、開発目的でローカルでホストされている Ollama を使用して、EXTERNAL MODEL型の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 EXTERNAL MODEL と HTTP ヘッダー ベースの資格情報を使用して、EMBEDDINGSの種類の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]
);

関連コンテンツ