SQL で外部モデルを作成および管理する

完了済み

Tip

詳細については、「 テキストと画像 」タブを参照してください。

外部モデルは、Transact-SQL を使用して SQL Server と Azure SQL 内から AI モデルを参照する方法を提供します。 外部モデルは、モデル エンドポイントへの接続を表し、SQL 組み込みの AI 関数がそのモデルを呼び出す方法を定義します。

外部モデルを作成することで、モデル固有のロジックをアプリケーション コードに埋め込まずに、データベース エンジン内で AI 機能を直接使用できるようになります。

外部モデルとは

外部モデルは、AI モデル エンドポイントに関するメタデータを格納するデータベース オブジェクトです。 このメタデータには、エンドポイント URL、認証の詳細、モデル固有の構成などの情報が含まれます。

外部モデルは、SQL Server 内で実行されるモデルではありません。 代わりに、SQL Server が AI 関数の実行時に外部 AI サービスを呼び出すマネージド参照として機能します。

作成後、外部モデルをクエリとワークロード間で再利用できるため、SQL から AI 機能にアクセスするための一貫性のある一元的な管理方法が提供されます。

外部モデルを作成する

CREATE EXTERNAL MODEL ステートメントを使用して外部モデルを作成します。 このステートメントでは、モデル名を定義し、それを外部エンドポイントに関連付けます。

外部モデルを作成しても、モデルが呼び出されたり、出力が生成されたりすることはありません。 これにより、埋め込み生成や他の AI 支援操作などの AI 関数が後で参照できる再利用可能な定義が確立されます。

外部モデルはデータベース オブジェクトであるため、名前付け規則、アクセス許可、スクリプトによるデプロイなど、標準の SQL プラクティスを使用して管理できます。

外部モデルを変更する

外部モデルは、エンドポイント、資格情報、または構成設定が更新されると、時間の経過と同時に変更される可能性があります。 これらの変更を反映するには、 ALTER EXTERNAL MODEL ステートメントを使用します。

外部モデルを変更すると、依存クエリや関数の書き換えを必要とせずにメタデータが更新されます。 この更新プログラムを使用すると、既存の SQL ロジックをそのまま維持しながら、モデル構成を一元的に調整できます。

外部モデル レベルで変更を管理することで、アプリケーション ロジックと AI サービス構成の結合を減らすことができます。

AI 関数で外部モデルを使用する

SQL Server には、AI 関連の操作を実行するために外部モデルを参照する組み込みの AI 関数が用意されています。 これらの関数は、データベースで定義されている外部モデル エンドポイントを呼び出して埋め込みを生成するなどのタスクを処理します。

AI 関数は、外部モデル定義を使用して、呼び出すエンドポイントと要求の認証方法を決定します。 この分離により、Transact-SQL コードは接続や資格情報の詳細ではなく、データ処理に集中できます。

外部モデルを作成する前に、AI エンドポイントの認証の詳細を格納するデータベース スコープの資格情報が必要です。 Azure OpenAI エンドポイントでは、次の 2 つの認証オプションがサポートされています。

  • マネージド ID (Azure SQL Database に推奨): データベースのマネージド ID は、Azure OpenAI で直接認証されます。 Azure OpenAI リソースに対する Cognitive Services OpenAI ユーザー ロールを付与します。

    CREATE DATABASE SCOPED CREDENTIAL [https://<resource-name>.cognitiveservices.azure.com/]
        WITH IDENTITY = 'Managed Identity',
        SECRET = '{"resourceid":"https://cognitiveservices.azure.com"}';
    
  • API キー: キーを HTTP ヘッダーに格納します。 このアプローチは、Azure SQL Database と SQL Server 2025 の両方で機能します。

    CREATE DATABASE SCOPED CREDENTIAL [https://<resource-name>.cognitiveservices.azure.com/]
        WITH IDENTITY = 'HTTPEndpointHeaders',
        SECRET = '{"api-key":"<your-api-key>"}';
    

T-SQL コードで API キーをハードコーディングすることは避けてください。 セキュリティを強化し、キーのローテーションを容易にするために、可能な場合はマネージド ID を使用します。

Important

外部エンドポイントを呼び出す必要があるユーザーまたはロールに EXECUTE ANY EXTERNAL ENDPOINT アクセス許可を付与します。 GRANT EXECUTE ANY EXTERNAL ENDPOINT TO [user_or_role];

資格情報が設定された状態で、外部モデルを作成できます。 次の例は、最小限のワークフローを示しています。

CREATE EXTERNAL MODEL my_external_model
WITH (
    LOCATION   = 'https://<resource-name>.cognitiveservices.azure.com/openai/deployments/<deployment-name>/embeddings?api-version=<api-version>',
    API_FORMAT = 'Azure OpenAI',
    MODEL_TYPE = EMBEDDINGS,
    MODEL      = 'text-embedding-3-small',
    CREDENTIAL = [https://<resource-name>.cognitiveservices.azure.com/],
    PARAMETERS = '{"dimensions":<n>}'
);

外部モデルが作成されると、AI 関数はクエリでそれを参照できます。

SELECT
    id,
    AI_GENERATE_EMBEDDINGS(
        description USE MODEL my_external_model
    ) AS embedding
FROM dbo.documents;

この例では、外部モデルによって、SQL Server が AI サービスに接続する方法が定義されています。 AI_GENERATE_EMBEDDINGS関数は、その定義を使用して、エンドポイントまたは認証の詳細をクエリに埋め込まずに、description列の埋め込みを生成します。

外部モデルと AI 関数を組み合わせると、SQL Server では、Transact-SQL を介して完全に定義、実行、および管理される AI ワークフローが有効になります。

外部モデルをデータベース オブジェクトとして管理する

外部モデルはデータベース スコープオブジェクトであるため、既存のデータベース管理プラクティスに自然に適合します。 アクセス許可を使用してアクセスを制御し、それらをデプロイ パイプラインに含め、他のスキーマ オブジェクトと共にライフサイクルを管理できます。

外部モデルを最上位のデータベース オブジェクトとして扱うことで、AI 機能を SQL ベースのソリューションに統合する際の一貫性、保守性、予測可能な動作を保証できます。

重要なポイント

外部モデルは、AI モデル エンドポイントに関するメタデータを格納するデータベース オブジェクトです。これにより、SQL Server はアプリケーション コードに接続の詳細を埋め込まずに外部 AI サービスを呼び出せるようにします。 CREATE EXTERNAL MODELで作成し、ALTER EXTERNAL MODELで更新し、AI_GENERATE_EMBEDDINGSなどの組み込みの AI 関数でそれらを参照します。 これらはデータベース スコープであるため、他のスキーマ オブジェクトと共にアクセス許可、ライフサイクル、デプロイを管理できます。