Oracle Cloud Infrastructureドキュメント

エンタープライズAI NL2SQLクイック・スタート・ガイド

エンタープライズAI NL2SQLを使用して、自然言語の質問をOCI生成AIのエンタープライズ・データの検証済SQLに変換します。

NL2SQLでは、セマンティック・ストアを使用して、ビジネス用語をデータベース・フィールド、表および結合にマップします。SQLのみを生成します。データベース・ツールMCPサーバーは、エンド・ユーザーの権限を使用して、ソース・データベースに対する問合せを承認および実行します。

始める前に

NL2SQLを使用する前に、ソース・データベースがあることを確認し、必要なデータベース接続を構成します。

少なくとも、次のものが必要です。

  • ソースのOracle Autonomous AI Database
  • データベース・ツール・サービス・エンリッチメント接続
  • データベース・ツール・サービス問合せ接続

開始

次のステップでは、データベースへの接続方法、NL2SQLセマンティク・ストアの準備方法、およびMCP互換クライアントを介した自然言語の質問の送信方法の概要を示します。

  1. 必要なデータベース接続を作成します。

    エンリッチメント用に1つの接続と、問合せ用に権限の低い別々の接続を作成します。

  2. セマンティック・ストアを作成してエンリッチします。

    2つの接続を選択し、承認済スキーマを選択して、エンリッチメントが終了するまで待機します。

  3. データベースツールのMCPサーバーとMCPツールセットを構成します。

    サーバーを構成し、クライアントがNL2SQLを使用してSQLを生成し、ソース・データベースに対して承認済SQLを実行できるようにするツールセットを作成します。

  4. クライアントを接続し、質問する。

    Oracleクライアントまたは独自のMCP互換チャットまたはエージェント・クライアントを使用します。

ヒント

データベース・ツールMCPサーバーを構成し、クライアントを統合する手順は、「データベース・ツールMCPサーバーの作成およびクライアントとの統合のステップ」を参照してください。

実行時:クライアントはデータベース・ツールMCPサーバーに質問を送信します。NL2SQLはSQLを生成し、MCPサーバーはリクエストを承認し、エンド・ユーザーのデータベース権限を使用して問合せを実行します。

セマンティック・ストアの作成

NL2SQLを使用するには、OCI Generative AIでセマンティック・ストアを作成します。

セマンティック・ストアは、構造化データを含むベクトル・ストアによってバックアップされ、次の2つのデータベース・ツール・サービス接続が含まれます。

  • エンリッチメントの接続
  • クエリー接続

コンソール

コンソールでベクトル・ストアを作成し、「構造化データ」を選択します。セマンティック・ストア・オプションで、エンリッチメント接続、問合せ接続、およびNL2SQLで使用できるスキーマを選択します。

OCI Generative AI APIの使用

OCI生成AI APIでCreateSemanticStore操作を使用して、セマンティック・ストアを作成します。

ベースURL エンドポイント・パス 認証
https://generativeai.${region}.oci.oraclecloud.com/20231130 /semanticStores IAMセッションのみ

CreateSemanticStore操作では、OCI IAMベースの認証を使用します。

データベース・ツール接続

NL2SQLでは、異なる目的で2つのデータベース接続を使用します。

エンリッチメントの接続

エンリッチメント接続は、エンリッチメント中に使用される、より高い権限を持つ接続です。次の権限が必要です。

  • 問合せの実行
  • 必要なデータ定義言語(DDL)操作を実行します。
  • データベースから許可されたサンプル値にアクセスします。

OCI Generative AIは、この接続を使用してスキーマ情報を読み取り、SQLの生成に必要なメタデータを構築します。

クエリー接続

「問合せ接続」は、エンド・ユーザーのかわりに問合せを実行するために使用される、権限の低い接続です。

エンリッチメントと問合せ接続を分離して、エンリッチメントと問合せ実行を区別し、より安全なアクセス制御をサポートします。

エンリッチメント

エンリッチメント・プロセスは、接続されたデータベースからスキーマ・メタデータを読み取ります。このメタデータには、表、列、データベース・コメント、注釈およびシノニムを含めることができます。OCI生成AIは、この情報を使用して、質問の用語を適切なデータベース・オブジェクトにマップし、使用可能なスキーマ・コンテキストに基づいてSQLを生成します。

エンリッチメントを実行するタイミングを選択します。

  • 作成時: エンリッチメントは、セマンティック・ストアの作成後に自動的に開始されます。
  • 手動: エンリッチメントは、後で別のAPI操作によって開始されます。

エンリッチメントを手動で開始するには、GenerateEnrichmentJob操作をコールします。

自然言語からのSQLの生成

エンリッチメントが完了したら、GenerateSqlFromNl操作をコールして、自然言語入力をSQLに変換します。

この操作:

  • 自然言語入力を受け入れます
  • エンリッチされたセマンティック・メタデータを使用します。
  • 生成されたSQLを返します。
重要

GenerateSqlFromNl操作では、データベースに対してSQLは実行されません。

クエリー実行

データベース・ツールMCPサーバーは、実行フローを管理します。

  1. SQLを生成するためにNL2SQLサービスを呼び出します。
  2. リクエストを承認します。
  3. ソース・データベースに対して問合せを実行します。
  4. 適切なガードレールを適用します。
  5. 実行にエンド・ユーザーのアイデンティティを使用します。

これにより、既存のデータベース権限によって制御されるソース・データベースでの問合せの実行が維持されます。

チャットまたはエージェント・クライアントの接続

データベース・ツールMCPサーバーに接続するように、OracleクライアントまたはMCP互換のチャットまたはエージェント・クライアントを構成します。MCPサーバーは、NL2SQLをコールしてSQLを生成し、リクエストの認可後に問合せを実行します。

クライアントは、OCIレスポンスAPIをMCPコールとともに使用して、データベース・ツールMCPサーバーに接続することもできます。

統合ノート: NL2SQLをResponses APIのtoolsエントリとして直接追加しないでください。MCPベースのフローの場合は、データベース・ツールMCPサーバーを使用します。APIベースのフローの場合は、GenerateSqlFromNlを直接コールします。

長時間実行リクエスト用

一部のワークフローでは、通常のチャット・リクエストよりも時間がかかる場合があります。レスポンスAPIクライアントでバックグラウンド処理がサポートされている場合は、返されたレスポンスIDを格納し、リクエストが終了するまでステータスを確認します。ユーザーが必要に応じてリクエストを取り消す方法を指定します。バックグラウンド処理では、クライアント・タイムアウトが失敗した問合せとして扱われません。

ベータ版を試す

設定後、既知の表を使用する簡単な質問から開始します。次に例を示します。

先月最も売れた製品はどれですか(5つ選択してください)。

クライアントが生成されたSQLを返し、実行が有効な場合、ユーザーのデータベース権限に従った結果であることを確認します。

NL2SQL API操作

次のOCI生成AI API操作は、NL2SQLをサポートしています。

セマンティック・ストア
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
拡充ジョブ
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
SQLの生成
GenerateSqlFromNl