生成AIエージェントのSQLツール・ガイドライン

生成AIエージェントのSQLツールは、Oracle Database (ベース・データベースおよびAutonomous Database)をサポートしています。

表を作成し、優先データベースにデータをロードします。SQLツールを使用して問合せ文を生成し、その問合せを自己修正または実行する場合は、問合せおよび実行のデータを含むデータベースへのデータベース・ツール接続を設定する必要があります。接続の作成の詳細は、データベース・ツール接続の作成(ガイドライン)を参照してください。

SQLツールを使用して問合せ文を生成するのみで、ツールがSQL問合せを自己修正または実行できない場合に、データベースに表を作成する必要がない場合があります。ただし、エージェントでSQLツールを作成する場合は、データベース表スキーマを指定する必要があります。

生成AIエージェントでエージェントにSQLツールを追加する場合は、有効なデータベース・スキーマを指定する必要があります。スキーマが無効な場合、SQLツールの作成は検証ステップで失敗します。

有効なスキーマは、適切に構造化されたデータベース・ブループリントで、次のものが含まれます。

• 表: エンティティの定義(Customers、Ordersなど)

• 列: 属性を指定します(たとえば、CustomerID、OrderDate)。

• 主キー: 行を一意に識別します(たとえば、CustomerID)。

• 外部キー: リンク表(たとえば、OrdersのCustomerIDはCustomersを参照)。

• 制約: ルールを強制します(たとえば、NOT NULL、UNIQUE)。

有効なスキーマの例:

CREATE TABLE Employees (
    EmployeeID INT PRIMARY KEY,
    Name VARCHAR(100) NOT NULL,
    DepartmentID INT,
    HireDate DATE NOT NULL,
    FOREIGN KEY (DepartmentID) REFERENCES Departments(DepartmentID)
);

適切に構造化されたスキーマにより、データの整合性と効率性が保証されます。

無効なスキーマの例:

CREATE TABLE Employees (
    EmployeeID,
    Name VARCHAR(100),
    DepartmentID INT,
    HireDate DATE
);

構造を持たない無効なスキーマは、潜在的なデータの不整合および非効率につながる可能性があります。この例では、次の理由によりスキーマは無効です。

• スキーマに主キー(EmployeeID、DepartmentID)がありません。
• EmployeeIDのデータ型がありません。

SQLツールを作成する場合は、小さいモデルを使用するか大きいモデルを使用するかを選択できます。

小規模なモデルでは、応答時間が短縮され、コンピュート・コストが削減される場合があります。「2025年1月の総売上高の取得」などの単純な問合せには、小規模なモードを選択します。

大規模なモデルでは、精度が向上しますが、レイテンシとコンピュート・コストが高くなります。「Q1 2023でパフォーマンスの高い上位5社の製品の平均売上を地域別にグループ化して表示」など、より複雑な問合せに対してラージ・モデルを選択します。

SQLツールは、Oracle SQLおよびSQLiteの方言をサポートしています。

エージェントは、任意の方言に基づいて、Oracle SQLまたはSQLiteの構文ルールに沿った問合せを生成できます。

SQLiteとOracle SQLの構文の違いの例:

Oracle: SELECT * FROM users FETCH FIRST 5 ROWS ONLY;
SQLite: SELECT * FROM users LIMIT 5;

Oracle: SELECT 'Hello' || ' World' FROM dual;
SQLite: SELECT 'Hello' || ' World';

SQLステートメントの生成後にSQLクエリーを実行するためにSQLツールを有効にして使用する場合は、次の要件が設定されていることを確認します。

• データベースのプライベート・サブネットで構成するイングレス・ルールについては、ネットワーキング要件(クロスリージョンおよびクロステナンシのサポートなし)を参照してください。

• データベース・パスワード・シークレットを格納するには、OCI Vaultのボールトが必要です。ボールトをデータベースと同じコンパートメントに作成します。

• 自律型データベースで相互TLS (mTLS)認証が有効になっている場合は、ウォレットをダウンロードしてファイルを抽出する必要があります。Walletのセキュリティ要件を参照してください。

SQLツールを有効にすると、SQL文の生成後に自己修正して問合せを実行できます。SQL実行または自己修正が有効な場合、問合せおよび実行のデータを含むデータベースへのデータベース・ツール接続が必要です。

接続の作成の詳細は、データベース・ツール接続の作成(ガイドライン)を参照してください。

オブジェクト・ストレージ・バケットを使用して、SQLツールへの入力ファイルを格納できます。SQL実行がSQLツールで有効になっている場合、実行中のSQL問合せの出力ファイルをオブジェクト・ストレージに格納できます。

サービスを使用できる前のポリシーの追加の説明に従って、すべての生成AIエージェント・リソースへのアクセス権をユーザーに付与してください。

次の項も確認し、SQLツールでエージェントで特定の関数を使用する必要があるタスク(SQL実行の有効化など)を完了します。

• 動的グループ
• オブジェクト・ストレージ
• SQL実行、自己修正および出力ストレージ

ALL {resource.type='genaiagent'}

Allow dynamic-group <dynamic-group-name> to inspect buckets in compartment <compartment-name> where target.bucket.name = '<bucket-name>'

Allow dynamic-group <dynamic-group-name> to read objects in compartment <compartment-name> where target.bucket.name = '<bucket-name>'

Allow dynamic-group <dynamic-group-name> to use database-tools-connections in compartment <compartment-name>
Allow dynamic-group <dynamic-group-name> to read database-tools-family in compartment <compartment-name>
Allow dynamic-group <dynamic-group-name> to read secret-family in compartment <compartment-name>

allow dynamic-group <dynamic-group-name> to {BUCKET_INSPECT, BUCKET_READ, OBJECT_INSPECT, OBJECT_READ, OBJECT_CREATE, OBJECT_OVERWRITE, PAR_MANAGE} in compartment <compartment-name> where target.bucket.name = 
'<bucket-name>'

データベース・スキーマに関するコンテキストは、ユーザーが尋ねる可能性のある質問の例と、回答例として予想されるSQL問合せの形式で指定できます。コンテキスト内学習の例は、類似したユーザー問合せへの回答に役立ちます。

例:

Question: Show all employees who were born in CA.
Oracle SQL: SELECT * FROM Employees WHERE BIRTHSTATE = 'CA';

Question: Get the employeeid of employees who joined in 2020.
Oracle SQL: SELECT employeeID FROM Employees WHERE hireDate = '2020';

エージェントの動作を変更するためのプロンプトを1つ以上指定できます。

次に例を示します:

Always use aggregators such as COUNT, SUM, AVG, MIN, and MAX in Oracle SQL queries that contain GROUP BY.
If the Oracle SQL query contains ORDER BY, then show the ORDER BY metric in the SELECT clause as well.
If all columns must be returned, use the (*) notation.
Ensure to include all relevant WHERE filtering conditions even when the number of conditions is larger than those of in-context learning examples.

表および列の説明を追加すると、問合せの精度が向上し、あいまいさが処理され、モデルが複雑な問合せおよび特定の用語をよりよく理解できるようになります。たとえば、Ordersのstatus列をOrder status: pending, shipped, or deliveredと記述すると、モデルがユーザー問合せで正しく解釈するのに役立ちます。

次に例を示します:

Description of the important tables in the schema:

Employees         Employee names and other information
Departments       Department names and other information 

Description of the important columns of the tables in the schema:

EMPLOYEES TABLE

employees.employeeID     A unique code assigned to each employee. employeeID links the data in this file with records in the other files.
employees.departmentID   A unique code that identifies the department an employee belongs to
employees.birthYear      Year employee was born
employees.birthMonth     Month employee was born
employees.birthState     State where employee was born
employees.birthCity      City where employee was born
employees.nameFirst      Employee's first name
employees.nameLast       Employee's last name
employees.nameMiddle     Employee's middle name
employees.hireDate       Year employee joined the company

---------------------------------------------------------------------
DEPARTMENTS TABLE

department.departmentID    A unique code assigned to each department
department.departmentName  Name of the department
department.locationID      Unique code that identifies the location of a department
department.managerID       Unique code that identifies the department's manager