Oracle Cloud Infrastructureドキュメント

Java用のSelect AI

Select AI for Javaは、Select AIをOracle Autonomous AI Databaseで構成および使用するためのJavaネイティブAPIを提供するJava SDKです。SDKは、AIプロファイル、資格情報、会話、ベクトル索引、自然言語SQL、要約、翻訳、フィードバック、Javaクラス、インタフェース、メソッドによる合成データ生成などのSelect AI機能を提供します。

SDKは、JDBCを使用してデータベースと通信し、Select AI操作に必要な基礎となるデータベースAPIを使用します。SDK管理のJDBC接続とアプリケーション管理のDataSource接続の両方をサポートします。

このドキュメントでは、SDKのインストール、構成および使用に関するタスク指向のガイダンスを提供します。クラス、メソッド、パラメータおよび例外の詳細は、Select AI for Java APIリファレンスを参照してください。

コンストラクタ、メソッド、リクエスト・クラスおよびレスポンス・クラス、サポートされている属性、パラメータ、例および例外については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

サポートされている環境

Select AI for Javaは次の方法で検証されました。

  • Oracle Autonomous AI Database 26ai
  • Oracle Autonomous AI Database 19c

ノート

ノート: DBMS_CLOUD_AI_AGENTは、Select AI for Javaバージョン1.0.0の範囲外です。

SDKは、データベース接続にOracle JDBC Thinドライバを使用します。SDKは、必要なSelect AIデータベース・パッケージおよび権限を提供する、サポートされているOracleデータベース・デプロイメントで使用できます。アプリケーションをデプロイする前に、サポートされているデータベースおよびJDBCドライバ・バージョンのAIプロバイダ構成および必要な権限を確認します。サポートされる機能とそのデータベース・バージョンについては、Oracle AI Database Select AI機能マトリックスを参照してください。

SDKのダウンロード

Select AI for Javaバージョン1.0.0がMaven Centralに公開されます。

MavenおよびGradleアプリケーションの場合は、SDKを依存性として宣言します。MavenまたはGradleは、Maven CentralからSDKとそのランタイム依存性を解決します。

Maven Centralアーティファクト・ページを使用して、Maven Central上のJava 1.0.0用のSelect AIをダウンロードします

APIの説明、クラス、メソッド、パラメータおよび使用方法の詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

アプリケーションへのSelect AI for Javaの追加

Select AI for Javaは、標準のJava JARとしてパッケージ化されています。SDK JARには、サード・パーティのランタイム依存関係は含まれません。MavenまたはGradleは、公開されたPOMからこれらの依存性を解決します。

Select AI for Javaバージョン1.0.0には、JDK 17以上が必要です。

通常のアプリケーション開発には、公開されたMaven依存性を使用します。詳細は、SDKのダウンロードを参照してください。

MavenアプリケーションへのSDKの追加

アプリケーションのpom.xmlに次の依存関係を追加します。

<dependency>
    <groupId>com.oracle.database.selectai</groupId>
    <artifactId>select-ai</artifactId>
    <version>1.0.0</version>
</dependency>

Mavenは、公開されたPOMからSDKとその推移的ランタイム依存性を解決します。

GradleアプリケーションへのSDKの追加

Groovy DSLを使用するGradleアプリケーションの場合、build.gradleファイルに次の構成を追加します。たとえば:

repositories {
    mavenLocal()
}

dependencies {
    implementation 'com.oracle.database.selectai:select-ai:1.0.0'
}

ノート

ノート: Gradle構成では、Maven Centralアーティファクトが使用されます。Gradleが別途表示されるわけではありません。

ランタイムの依存性

SDK JARは、サード・パーティの依存関係をバンドルしません。SDKをMavenまたはGradleの依存性として使用すると、dependency-managementツールは、公開されたPOMから必要な直接および推移的な依存性を解決します。

SDKは、次のプライマリ・ランタイム依存関係を使用します:

依存関係 バージョン 目的
com.oracle.database.jdbc:ojdbc11 23.26.1.0.0 Oracle JDBC Thinドライバ
com.oracle.database.security:oraclepki 23.26.1.0.0 Oracleウォレットとセキュリティのサポート
org.slf4j:slf4j-api 2.0.17 SDKで使用されるロギングAPI
com.fasterxml.jackson.core:jackson-databind 2.22.0 JSONのシリアライズとデシリアライズ
MavenまたはGradleによって遷移的に解決される依存性 該当なし Jacksonコアと注釈、Oracleセキュリティ・サポートの依存関係など、直接の依存関係に必要な追加のライブラリ

SDKはSLF4J APIに依存しますが、SLF4Jロギング・プロバイダは含まれません。アプリケーションに適した SLF4J 2.xロギングプロバイダを構成します。スタンドアロンSDKのサンプルでは、slf4j-simpleを使用します。

依存性管理システムではなくSDK JARを直接使用する場合は、そのランタイム依存性をアプリケーション・クラスパスで使用可能にする必要もあります。SDK pom.xmlから解決された依存関係を使用して、必要な直接および推移的な依存関係を含めます。

直接JARを使用するためのランタイム依存性をコピーするには、次を実行します。

mvn clean install
mvn -DincludeScope=runtime \
    -DoutputDirectory=target/dependency \
    dependency:copy-dependencies

SDK JARおよびアプリケーション・クラスパスに対するコピーされた依存性を使用します。

java -cp "target/select-ai-1.0.0.jar:target/dependency/*" \
    com.example.Application

Windows PowerShellでは、クラスパスでコロン(:)のかわりにセミコロン(;)を使用します:

java -cp "target/select-ai-1.0.0.jar;target/dependency/*" `
    com.example.Application

Autonomous AI Databaseへの接続

Select AI for Javaでは、JDBC接続を使用してAutonomous AI Databaseと通信します。接続情報を直接提供することも、JDBC DataSourceを指定することもできます。

JDBC接続の管理

Select AIオブジェクトを作成する前に、接続管理アプローチを選択します。1つのアプリケーション全体で1つの一貫性のあるアプローチを使用するか、複数のコンポーネントが同じデータベース・リソースを共有する場合に所有権を明確に文書化します。

SDKでは、次の接続モードがサポートされています:

  • DbConnectionConfig: SDKがJDBC接続を取得および管理するために使用する接続構成。
  • DataSource: アプリケーションによって提供されるDataSource。

DbConnectionは、独立したスタンドアロンの接続所有者APIです。

アプリケーションが接続を提供する場合は、接続が開いて、目的のデータベース・ユーザー用に構成されていることを確認してください。SDKが構成またはDataSourceから接続を取得する場合は、Select AI for Java APIリファレンス(Javadoc)に記載されているライフサイクル・ルールに従います。

アプリケーションで使用する接続管理モデルに一致するモードを選択します。接続プールをすでに使用しているアプリケーションは、そのDataSourceを提供できます。接続プロパティを直接管理するアプリケーションは、SDK接続構成を使用できます。

DbConnectionConfig

DbConnectionConfigを使用して、データベース接続プロパティおよび接続関連オプションを定義します。DbConnectionConfigモードでは、SDKはSelectAIクライアントの単一のJDBC接続を作成して所有します。SDKは、そのクライアントによって実行される操作に対してこの接続を再利用します。SelectAI.close()をコールすると、SDKによってJDBC接続がクローズされます。クライアントは1つの保持されたJDBC接続を使用するため、アプリケーションが外部でアクセスを同期しないかぎり、DbConnectionConfigベースのSelectAIクライアントをシングル・スレッドとして扱います。

DbConnectionConfigは、SelectAIクライアントに対して1つのデータベース接続を使用する単純なアプリケーション、コマンドライン・プログラム、サンプルおよびアプリケーションに使用します。構成には、データベースURL、認証情報、ウォレットまたはセキュリティ設定、およびオプションのランタイム設定を含めることができます。

接続情報およびシークレットは、アプリケーションのソース・コード外に保持します。デプロイメントに推奨される資格証明およびシークレット管理機能を使用します。

サポートされているプロパティ、コンストラクタ、検証ルールおよび認証オプションの完全なリストは、Select AI for Java APIリファレンス(Javadoc)を参照してください。

データ ソース

アプリケーションまたはアプリケーション・サーバーが接続の作成およびプーリングを所有する場合は、DataSourceを使用します。DataSourceモードでは、アプリケーションはDataSourceを所有します。SDKは、操作ごとにDataSourceからJDBC接続を流用し、操作の完了後に流用された接続を閉じます。DataSourceが接続プールを使用する場合、流用した接続をクローズすると、通常、その接続がプールに返されます。SelectAI.close()をコールしても、アプリケーション所有のDataSourceはクローズされません。

アプリケーション・サーバー、SpringまたはJakartaアプリケーション、マルチスレッド・サービスおよびJDBC接続プールを管理するアプリケーションには、DataSourceモードを使用します。DataSourceは、Select AI for Javaを既存のJDBCインフラストラクチャおよびエンタープライズ接続プールと統合できます。

アプリケーションは、DataSource、プール容量、検証およびセキュリティの構成を引き続き行います。SDKは、データベース操作にアプリケーション提供のDataSourceを使用します。

接続ライフサイクル

アプリケーションで使用される所有権モデルに従って、接続およびその他のJDBCリソースをクローズします。操作が完了したときにリソースを解放し、必要以上に長く存続する短い接続を保持しません。

アプリケーションが接続プールを使用する場合は、プール管理リソースを直接クローズするのではなく、プールに接続を返します。

SDKは、選択した接続モードに従ってJDBC接続ライフサイクルを管理します。

接続モード 接続所有権 接続ライフサイクル
DbConnectionConfig SDK SDKは、1つの接続を作成し、クライアント操作のために再利用し、SelectAI.close()がコールされるとクローズします。
DataSource アプリケーション SDKは、操作ごとに接続を流用し、操作の完了後に閉じます。アプリケーションは引き続きDataSourceを所有します。

Profile、Conversation、VectorIndexなどのリソース・オブジェクトは、関連付けられたSelectAIクライアントの接続ライフサイクルを使用します。個別のJDBC接続を作成または所有しません。

スレッド動作

Select AI for Javaでは、接続モードおよびアプリケーションがSDKリソース・オブジェクトを使用する方法に基づいて、様々なスレッド動作がサポートされます。SDKは、すべてのパブリック・オブジェクトに対してグローバルなスレッド・セーフティを保証するものではありません。

DataSourceモードでは、各操作が独自のJDBC接続を取得するため、独立した操作のスレッド間でSelectAIクライアントを共有できます。

DbConnectionConfigモードでは、アプリケーションが保持されているJDBC接続へのアクセスを同期しないかぎり、SelectAIクライアントをシングルスレッドとして扱います。

注意:複数のスレッドが独立した操作のために個別のリソース・インスタンスを使用できます。複数のスレッドで同じリソース・インスタンスが使用されている場合は、アプリケーションがアクセスを同期しないかぎり、そのリソースを同時に変更しないでください。たとえば、複数のスレッドを同時に使用して、Profile、Credential、Conversation、VectorIndexインスタンスなどの同じリソースを変更しないでください。同じリソースを同時に作成、更新、有効化、無効化または削除しないでください。アプリケーションで同じリソース・インスタンスへの同時アクセスが必要な場合は、アプリケーションでアクセスを同期します。

トランザクションの動作

Select AI for JavaはJDBCトランザクション動作を使用します。トランザクションの動作は、接続構成およびSDKで使用されるOracle AI Database APIによって異なります。アプリケーションの要件およびデータベース操作に従って、自動コミットおよびトランザクションの境界を構成します。Select AI for Javaでは、トランザクションを明示的にコミットまたはロールバックせず、JDBC接続のautoCommit設定は変更されません。

DbConnectionConfigモードでは、SDKは操作間でSDK所有のJDBC接続を再利用します。autoCommitが無効な場合、JDBCおよびOracle AI Databaseのトランザクション・セマンティクスに従って、同じ接続を使用するSDK操作およびカスタムJDBC文が接続のトランザクションに参加します。

DataSourceモードでは、SDKは操作ごとにJDBC接続を流用し、操作の完了後に接続をクローズします。SDKは、接続を戻す前に、接続のautoCommit設定を明示的に変更したり、トランザクションをコミットまたはロールバックしたりしません。DataSourceまたは接続プールは、流用された接続がプールに戻されたときに、接続状態および未処理のトランザクションを処理する方法を制御します。

ノート

ノート: DataSourceモードでは、各SDK操作によってDataSourceからの接続が流用されます。したがって、あるSDK操作から別の操作で使用できるコミットされていない変更に依存しないでください。

プロファイル、資格証明、会話およびベクトル索引操作を作成または変更するSDK操作は、JDBC接続および基礎となるOracle AI Database APIのトランザクション動作を使用します。一部の基礎となるデータベースAPIでは、暗黙的なコミットまたはロールバックを実行できます。SDKは、そのデータベースの動作を変更またはオーバーライドしません。

ノート

ノート: DbConnectionConfigモードでは、SelectAI.getConnection()は、SDKがその操作に使用するSDK所有のJDBC接続を返します。この接続は、同じデータベース・セッションでのカスタムJDBC作業に使用できます。SDK操作およびカスタムJDBC文が単一のアトミック・トランザクションを形成できるかどうかは、基礎となるOracle AI Database APIのトランザクション動作によって異なります。

問合せタイムアウト

query-timeoutオプションは、JDBC文のタイムアウトを構成します。SelectAIOptions.queryTimeoutSeconds()を使用して、SDK操作のJDBC文問合せタイムアウトを構成します。デフォルトでは、SDKはJDBC問合せタイムアウトを構成しません。unsetまたはnull値は、SDKがStatement.setQueryTimeout()をコールしないことを意味します。値0は、JDBCのタイムアウトなし動作を使用します。SDKは負の値を拒否します。

構成されたタイムアウトは、SDK操作用に作成されたJDBC文に適用されます。JDBCまたはデータベース文のタイムアウトを制御します。次のものは構成されません。

  • AIプロバイダ・リクエストのタイムアウト
  • HTTP接続または読取りタイムアウト
  • リモート・モデル要求の取消
  • 長時間実行されるDBMS_CLOUD_AI操作に対する個別のタイムアウト

データベース操作がすでにAIプロバイダにリクエストを送信している場合、JDBC文のタイムアウトによってプロバイダ・リクエストの取消しが保証されるわけではありません。JDBCドライバがデータベース・コールを中断するかどうか、および中断するタイミングは、Oracle JDBCおよびデータベースの動作によって異なります。

SelectAIOptions、接続管理およびリソース操作の詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

始める前に

Select AI for Javaを使用する前に:

  1. データベース・リリースがサポートされていることを確認します。
  2. アプリケーションに必要なデータベース接続情報および認証を取得します。
  3. 必要なAIプロバイダおよびデータベース資格証明を構成します。
  4. 目的のワークフローのAIプロファイルを作成または識別します。
  5. データベース・ユーザーに、選択した機能に必要な権限およびネットワーク・アクセスがあることを確認します。
  6. 設定要件については、「Select AIの前提条件の実行」を参照してください。

関連情報:

データベース権限およびネットワーク・アクセスの管理

Select AI for Javaには、特権データベース設定操作用のDatabaseAdminインタフェースが用意されています。通常のアプリケーション操作には、SelectAIインタフェースを使用します。

DatabaseAdminは、個別に制御されたプロビジョニングまたは管理ワークフローでのみ使用します。DatabaseAdminを通常のアプリケーション・ユーザーに公開したり、アプリケーションの一般的なランタイム・パスに含めたりしないでください。

DatabaseAdminインタフェースは、次の管理メソッドを提供します。

  • データベース・ユーザーに対してSelect AIパッケージ権限を付与または取り消します。
  • 外部ホストへのHTTPアクセスを付与または取り消します。
  • 指定したホスト、権限およびオプションのポート範囲に対するネットワーク・アクセス権を付与または取り消します。
  • Select AIデータアクセスを有効または無効にします。

これらの操作には、適切に権限を持つ管理データベース・ユーザーが必要です。アプリケーションを実行するデータベース・ユーザーは、そのユーザーが管理設定も実行しないかぎり、DatabaseAdmin権限を必要としません。

パッケージ権限

DatabaseAdminパッケージ権限メソッドを使用して、Select AIユーザーに必要なデータベース・パッケージ権限を付与または取り消します。

Select AIを使用するには、データベース管理者がDBMS_CLOUD_AIのEXECUTEをデータベース・ユーザーに付与します。Select AI機能には、追加のパッケージ権限が必要な場合があります。たとえば、Retrieval-Augmented Generation (RAG)では、DBMS_CLOUD_PIPELINEへのアクセスが必要です。

資格証明操作ではDBMS_CLOUDを使用し、資格証明を管理するデータベース・ユーザーが対応するDBMS_CLOUD APIにアクセスする必要があります。

パッケージは、管理リクエストで指定されたデータベース・ユーザーに対する変更権限を付与します。これらの権限は、通常のアプリケーション起動時ではなく、データベースまたはアプリケーションのプロビジョニング時に実行します。

ノート

ノート: DBMS_CLOUD_AI_AGENTは、Select AI for Javaバージョン1.0.0の範囲外です。

必要な権限については、Select AIの前提条件の実行を参照してください。

ネットワーク・アクセス

DatabaseAdminネットワーク・アクセス方法は、データベース管理者がSelect AIユーザーのアウトバウンド・アクセスを構成する必要がある場合にのみ使用します。

APIには、次の機能があります。

  • 指定したホストへのHTTPアクセスを付与または取り消すためのHTTPアクセス・メソッド。
  • ホストおよびオプションでTCPポート範囲に対して指定されたネットワーク権限を付与または取り消すための一般的なネットワーク・アクセス方法。

すべてのSelect AIプロバイダまたはデータベース・デプロイメントにネットワークACL構成は必要ありません。選択したプロバイダおよびデプロイメントでネットワーク・アクセスが必要な場合にのみ、ネットワーク・アクセスを構成します。たとえば、Select AIでは、OCI Generative AI用のネットワークACLは必要ありません。

ネットワークACLの変更により、データベース・ネットワークACLの構成が変更されます。ACL構成は、Javaアプリケーションまたはターゲット・ユーザーのスキーマではなく、データベース内に存在します。アクセス制御エントリは、アクセスを受信するデータベース・ユーザーまたはロールを識別するため、ACLを構成しても、すべてのデータベース・ユーザーにネットワーク・アクセスが自動的に付与されるわけではありません。

アプリケーションが必要とするホストのみを指定します。ホストは、ホスト名、IPアドレス、ドメインまたはサポートされているワイルドカードを識別できます。該当する場合は、下位および上位のポート・パラメータを使用して、必要なTCPポート範囲へのアクセスを制限します。ポート範囲を指定しない場合、基礎となるネットワークACLルールによって、ポート制限なしでアクセスが決定されます。

ネットワークACLの変更は、管理者が変更または削除するまで、データベース構成の一部として残ります。これらは、Java SDKプロセスまたはJDBCセッションに関連付けられた一時的な設定ではありません。

注意:ネットワークACLの変更は、データベース・セキュリティ構成に影響を与えます。制御されたプロビジョニングまたは管理ワークフローの一部としてネットワーク・アクセスを構成します。DatabaseAdminネットワーク管理権限を通常のアプリケーション・ランタイムに付与しないでください。

プロバイダ・エンドポイントおよびネットワーク要件については、Select AIの前提条件の実行を参照してください。

Select AIデータ・アクセス

DatabaseAdmin.enableDataAccess()およびDatabaseAdmin.disableDataAccess()を使用して、適用可能なSelect AI機能がデータベース・データまたはベクトル検索ドキュメント・コンテンツを大規模言語モデルに送信できるかどうかを制御します。

この設定は、ナレーション・アクション、Retrieval-Augmented Generation (RAG)、合成データ生成など、データ・アクセスを必要とするSelect AI機能に適用されます。

Select AIデータアクセス設定を変更できるのは管理者だけです。基礎となるDBMS_CLOUD_AI.ENABLE_DATA_ACCESSプロシージャおよびDBMS_CLOUD_AI.DISABLE_DATA_ACCESSプロシージャは、データベース・ユーザーまたはスキーマ・パラメータを受け入れません。

Select AIデータ・アクセスに対する変更を、管理データベース構成として処理します。通常のアプリケーションの起動時ではなく、プロビジョニング時または明示的に認可された管理変更を介して、必要な設定を構成します。

注意: Select AIデータ・アクセスを無効にすると、データベース・データまたは取得したドキュメント・コンテンツをAIプロバイダに送信する必要があるSelect AI機能が制限される可能性があります。この設定を変更する前に、影響を受けるSelect AI機能を確認してください。

管理およびランタイム操作

Oracleでは、通常のアプリケーション処理とは別に管理設定を保持することをお薦めします。

工程 推奨される使用方法
Select AIパッケージ権限の付与または取消し ワンタイム・プロビジョニングまたは認可された管理変更
HTTPアクセスの付与または取消し ワンタイム・プロビジョニングまたは認可されたネットワーク構成の変更
一般的なネットワーク・アクセスの付与または取消し ワンタイム・プロビジョニングまたは認可されたネットワーク構成の変更
Select AIデータ・アクセスの有効化または無効化 管理構成の制御
プロファイル、会話およびベクトル索引の作成と使用 通常のアプリケーション・ワークフロー(必要な権限と構成が行われた後)
プロンプトおよびその他のSelect AIリクエストの処理 通常アプリケーション・ランタイム

通常のアプリケーション・ランタイムには、最小権限のデータベース・ユーザーを使用します。アプリケーションを起動時に独自の前提条件を構成できるように、アプリケーション・ユーザーのみに管理権限を付与しないでください。

必要なSelect AI権限、資格証明、プロバイダ構成およびネットワーク要件については、Select AIの前提条件の実行を参照してください。

DatabaseAdminメソッド、パラメータおよび例外については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

実行可能な操作

Select AI for Java SDKは、Select AIリソースを操作するためのJava APIを提供します。

次の表に、Select AI for Javaの主な機能をまとめます。

能力 摘要
自然言語からSQLへ GenerateActionを使用して、自然言語プロンプトからSQLを生成します。
生成されたSQLの実行 自然言語プロンプトからSQLを生成し、Profile.runsql()を使用して生成されたSQLを実行します。
生成済SQLの表示 Profile.showsql()を使用して、SQLを実行せずに自然言語プロンプトから生成されたSQLを返します。
生成されたSQLの説明 SQLを生成し、Profile.explainsql()を使用してSQLの自然言語の説明を返します。
問合せ結果のナレーション SQLを生成して実行し、Profile.narrate()を使用して問合せ結果の自然言語ナレーションを返します。
チャット Profile.chat()を使用して、AIプロファイルで構成されたAIプロバイダに一般的な自然言語プロンプトを送信します。
拡張プロンプトの表示 Select AIがProfile.showprompt()を使用してAIプロバイダ用に準備する拡張プロンプトを返します。
AIプロファイル AIプロバイダ、資格証明、モデル設定、データベース・オブジェクトおよびベクトル索引を定義するAIプロファイルを作成および管理します。
資格証明 AIプロバイダまたはオブジェクト・ストレージ・アクセスに使用されるデータベース資格証明を作成および削除します。
会話 関連プロンプト間のコンテキストを維持する会話を作成および管理します。
検索拡張生成 Select AIがRAGの関連コンテンツを取得するために使用できるベクトル索引を作成および管理します。ベクトル索引を使用するようにAIプロファイルを構成し、RAG対応プロファイルを使用してベクトル・ストアから関連コンテンツを取得し、AIプロバイダに送信されるプロンプトを拡張します。詳細は、Select AI with Retrieval Augmented Generation (RAG)を参照してください。
合成データ 1つのデータベース・オブジェクトまたは関連オブジェクトのグループに対して合成データを生成します。詳細は、合成データの生成を参照してください。
要約 Profile.summarize()を使用して、外部の場所で識別されるインライン・テキストまたはコンテンツを要約します。詳細は、Generate a Summary with Select AIを参照してください。
翻訳 Profile.translate()を使用して、AIプロファイルで構成されたプロバイダを使用して、サポートされている言語のテキストを翻訳します。Select AI Translateは、OCI、Google、AWS、およびAzureをサポートしています。各プロバイダには、独自の認証、認可およびサービス要件があります。翻訳に使用できる言語は、選択したプロバイダとその翻訳サービスによって異なります。プロバイダ固有の要件およびサポートされる翻訳機能については、翻訳を参照してください。
フィードバック Profile.feedback()を使用して、NL2SQL生成の肯定的または否定的なフィードバックを提供します。ポジティブ・フィードバックは、将来参照するために生成されたSQLを確認します。負のフィードバックでは、生成されたSQLの問題を特定し、予想されるSQLまたは追加のガイダンスを提供できます。Select AIは、フィードバックをAIプロファイルおよび指定されたSQL IDまたはSQLテキストに関連付け、フィードバックをプロファイル固有のフィードバック・ベクトル索引に格納します。Select AIでは、保存されたフィードバックを、後続のSQL生成時に同様のプロンプトのヒントとして使用できます。詳細は、「フィードバック」を参照してください。
ネットワーク構成 DatabaseAdminインタフェースのメソッドを介して、DatabaseAdminを介してパッケージ権限、データ・アクセス、HTTPアクセスおよびネットワークACLアクセスを管理します。
JDBC接続管理 SDK所有のJDBC接続またはアプリケーション管理DataSourceを使用します。

Java APIの詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

サポートされているクラス

Select AI for Javaには、アプリケーション操作、管理構成、接続管理およびSelect AIリソース構成用のパブリック・インタフェースおよびモデル・クラスが用意されています。

アプリケーション・コードでは、com.oracle.database.selectaiのパブリック・インタフェースおよびcom.oracle.database.selectai.modelの関連モデル・タイプを使用する必要があります。com.oracle.database.selectai.implのクラスは内部実装クラスであり、直接アプリケーションでの使用を目的としていません。

プライマリ・アプリケーション・クラス

これらのクラスは、一般的な Select AIアプリケーションワークフローに使用します。

クラスまたはインターフェイス 目的
SelectAI Select AIのメインアプリケーションエントリポイントを提供します。これを使用して、プロファイル、資格証明、会話およびベクトル索引を操作し、コレクションレベルの操作を実行します。
Profile AIプロファイルを作成および管理し、プロンプト、要約、翻訳、フィードバックおよび合成データ操作を提供します。
Credential データベース資格証明を作成および削除します。
Conversation Select AI会話およびそのプロンプト・メタデータを作成および管理します。
VectorIndex Retrieval-Augmented Generation (RAG)で使用されるベクトル索引を作成および管理します。

管理クラス

通常のアプリケーション処理とは別に、DatabaseAdminインタフェースを使用します。

クラスまたはインターフェイス 目的
DatabaseAdmin Select AIパッケージ権限、データアクセス、HTTPアクセス、およびネットワークACL構成を管理します。

DatabaseAdminは、個別に制御されたプロビジョニングまたは管理ワークフローでのみ使用します。詳細は、データベース権限およびネットワーク・アクセスの管理を参照してください。

構成およびリクエスト・モデル

次のモデル・クラスを使用して、SDKのリソースおよび操作を構成します。

Class 目的
DbConnectionConfig SDK所有の接続のJDBC接続構成を定義します。
SelectAIOptions JDBC文の問合せタイムアウトなど、オプションのSDK設定を定義します。
ProfileAttributes AIプロファイル属性を定義します。
CredentialConfig データベース資格証明構成を定義します。
ConversationAttributes 会話メタデータを定義します。
VectorIndexConfig ベクトル索引作成構成を定義します。
VectorIndexAttributes ベクトル索引属性を定義します。
Feedback NL2SQL生成のフィードバックを定義します。
SummaryParams オプションの要約パラメータを定義します。
SyntheticDataSingleRequest 1つのデータベース・オブジェクトに対する合成データ・リクエストを定義します。
SyntheticDataBatchRequest 複数のデータベース・オブジェクトに対する合成データ・リクエストを定義します。
SelectAIException SDKを介してJDBC、データベース、DBMS_CLOUDおよびDBMS_CLOUD_AIエラーを報告します。

接続APIおよび拡張ポイント

SDKは、直接JDBC接続アクセスまたはカスタム接続処理を必要とするアプリケーションに対して、パブリック接続インタフェースおよび拡張ポイントを提供します。

クラスまたはインターフェイス 目的
DbConnection スタンドアロンのSDK所有JDBC接続を提供します。アプリケーションは、接続が不要になったときにDbConnectionをクローズします。
ConnectionProvider SDK操作用のJDBC接続を提供するパブリック抽象化を定義します。
ConnectionCallback<T> ConnectionProviderを介して提供されるJDBC接続を使用する作業を定義します。

ほとんどのアプリケーションでは、DbConnectionConfigまたはアプリケーション管理のDataSourceをSelectAIとともに使用します。接続拡張ポイントは、アプリケーションでカスタムJDBC接続処理が必要な場合にのみ使用します。

接続の所有権、ライフサイクル、トランザクションおよびスレッドの動作については、Autonomous AI Databaseへの接続を参照してください。

プロバイダ・クラス

Select AI for Javaは、サポートされているAIプロバイダのProvider列挙およびプロバイダ固有の構成クラスを通じてAIプロバイダを表します。AIプロファイルを構成するときは、適切なプロバイダ構成を使用してください。

Select AI for Javaには、次のプロバイダ構成クラスが含まれています。

  • OpenAIProviderProfile
  • CohereProviderProfile
  • AzureProviderProfile
  • OCIGenAIProviderProfile
  • GoogleProviderProfile
  • HuggingFaceProviderProfile
  • AWSProviderProfile

ProfileAttributesで構成するプロバイダに適したプロバイダ構成を使用します。プロバイダの前提条件および構成要件については、Select AIの前提条件の実行を参照してください。

内部実装クラス

com.oracle.database.selectai.implパッケージのクラスは、パブリックSDKインタフェースを実装し、JDBCとデータベースの内部相互作用を管理します。

ノート

ノート: com.oracle.database.selectai.implパッケージのクラスは、パブリックSDKインタフェースの内部実装を提供します。これらのクラスは、アプリケーション向けAPIとしてサポートされておらず、パブリックAPIとは無関係に変更できます。かわりに、com.oracle.database.selectaiのパブリック・インタフェースおよびファクトリ・メソッドを使用してください。

パブリック・クラス、インタフェース、モデル・タイプ、メソッドおよび拡張ポイントの詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

資格証明の操作

データベース資格証明には、Autonomous AI DatabaseがAIプロバイダまたはオブジェクト・ストレージなどの外部サービスにアクセスするために使用する認証情報が格納されます。

AIプロファイルまたはそれを参照するベクトル索引を作成する前に、必要な資格証明を作成します。資格証明を作成するデータベース・ユーザーは資格証明を所有し、資格証明名はそのユーザーのスキーマ内で識別します。

資格証明の作成および管理

SelectAI.credential(CredentialConfig)を使用して、資格証明構成からCredentialオブジェクトを作成します。このメソッドは、Java Credentialオブジェクトのみを作成します。データベース内に資格証明は作成しません。戻されたCredentialオブジェクトでCredential.create()をコールして、データベース資格証明を作成します。

次のCredentialメソッドを使用します。

  • create(): データベース資格証明を作成します。
  • drop(): データベース資格証明を削除します。
  • drop(boolean force): データベース資格証明を削除し、forceがtrueの場合は、すでに存在しない資格証明を正常な結果として処理します。

CredentialConfigクラスは、資格証明名とサポートされている認証情報を含む資格証明作成の詳細を定義します。

資格証明所有権

資格証明を作成するデータベース・ユーザーは、資格証明を所有します。資格証明名は、そのユーザーのスキーマ内の資格証明を識別します。

SDKは、資格証明のストアド・シークレット値を取得するメソッドを提供しません。パスワード、秘密キー、フィンガープリント、OCIDsおよび完全な資格証明構成を保護します。ソース・コード、ログ、エラー・レポートまたはプロンプトにシークレットを含めないでください。

AIプロバイダ資格証明

AIプロバイダの資格情報は、構成されたAIプロバイダへのアクセスに必要な認証情報を格納します。

AIプロファイルにプロバイダ認証用のデータベース資格が必要な場合は、AIプロバイダ資格を構成します。プロファイルは、プロファイル構成を介して資格証明を名前で参照します。

OCI認証の場合、CredentialConfigでは、資格証明名、ユーザーOCID、テナンシOCID、秘密キーおよびフィンガープリントを含む資格証明構成がサポートされます。

オブジェクト・ストレージ資格証明

ベクトル索引がそこに格納されているコンテンツを使用する場合、データベース資格証明を使用してオブジェクト・ストレージへのアクセスを認証します。

Select AI for Java SDKでは、オブジェクト・ストレージ資格証明に個別のJavaタイプを定義しません。Credentialインタフェースのメソッドを使用して、データベース資格証明を作成します。ベクトル索引構成でオブジェクト・ストレージ・アクセスの資格証明を指定します。

VectorIndexAttributesは、オブジェクト・ストレージ資格証明属性と、ソースの場所などの他のベクトル索引属性を定義します。

同じ認証情報が必要な場合、複数のSelect AIリソースで同じデータベース資格証明を参照できます。

資格証明の削除

Credential.drop()またはCredential.drop(boolean force)を使用して、資格証明を削除します。

資格証明を削除しても、それを参照するAIプロファイルまたはベクトル索引は自動的に更新されません。リソースがまだ削除された資格証明を参照している場合、その資格証明を必要とする操作は失敗する可能性があります。

注意:資格証明を削除する前に、その資格証明を参照するAIプロファイル、ベクトル索引およびその他のリソースを特定します。必要に応じて、これらの依存関係を更新または削除します。

OCIリソース・プリンシパルとInstance Principals

一部のOCI認証構成では、格納されたユーザー資格証明のかわりにリソース・プリンシパルまたはインスタンス・プリンシパルを使用できます。選択したプロバイダおよびデータベース環境でこれらの認証方法がサポートされている場合、ユーザー署名情報をデータベース資格証明に格納せずに、サポートされているOCI認証構成を使用できます。

プロバイダ固有の認証要件については、Select AIの前提条件の実行を参照してください。

資格証明の構成、サポートされている認証プロパティ、ライフサイクル操作および例外については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

AIプロファイルの操作

AIプロファイルは、Select AIがAIプロバイダと通信する方法、およびSelect AIが使用できるデータベース・オブジェクトとベクトル索引を定義します。プロファイルには、プロバイダ、モデル、資格証明、オブジェクト・リスト、会話、翻訳およびベクトル索引の設定を含めることができます。

Profileインタフェースを使用して、AIプロファイルを作成および管理し、Select AI操作を実行します。Profileインタフェースのすべてのメソッドは同期的です。呼び出し側のスレッドは、各操作の完了またはエラーの返却を待機します。

AIプロファイルの構成

AIプロファイルを構成するには、ProfileAttributesクラスを使用します。プロファイル構成は、使用するプロバイダおよびSelect AI機能によって異なります。

プロバイダおよびそのプロバイダに必要なその他の属性を指定します。プロバイダ固有の属性には、モデル、資格証明、エンドポイント、リージョン、コンパートメントおよびその他のプロバイダ設定を含めることができます。

選択したプロバイダおよび認証方法に必要となるデータベース資格証明を構成します。サポートされている認証方法の中には、格納されたデータベース資格証明を必要としないものがあります。

プロバイダ設定を定義するには、ProviderProfileのプロバイダ固有の構成クラスを使用します。各プロバイダの必須属性およびオプション属性については、Select AIの前提条件の実行を参照してください。

AIプロファイルの作成

SelectAI.profile(String profileName, ProfileAttributes profileAttributes, String description, ProfileStatus status)を使用して、プロファイル構成で初期化されるJava Profileオブジェクトを作成します。

この方法では、データベースにAIプロファイルは作成されません。戻されたオブジェクトでProfile.create()をコールして、データベース・プロファイルを作成します。

次に例を示します:

ProfileAttributes attributes =
    ProfileAttributes.builder()
        .provider(Provider.OCI)
        // Add provider-specific attributes.
        .build();

Profile profile =
    selectAI.profile(
        "MY_PROFILE",
        attributes,
        "Select AI profile",
        ProfileStatus.ENABLED);

profile.create();

必要なProfileAttributes値は、選択したプロバイダ、認証方法およびプロファイル機能によって異なります。必要な資格証明は、それを参照するプロファイルを作成する前に構成してください。

プロバイダの完全なプロファイル作成例は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

既存のAIプロファイルの使用

SelectAI.profile(String profileName)を使用して、現在のスキーマ内の既存のAIプロファイルを開きます。このメソッドは、プロファイル操作に使用できるProfileオブジェクトを返します。

次に例を示します:

Profile profile = selectAI.profile("MY_PROFILE");

String sql = profile.showsql("Show the total sales by region");

Profileインタフェースを使用して、次のことを行います。

  • runsql()を使用してSQLを生成および実行します。
  • showsql()で実行せずにSQLを生成します。
  • explainsql()を使用して生成されたSQLについて説明します。
  • narrate()を使用して問合せ結果をナレーションします。
  • chat()を使用して、構成されたAIプロバイダとチャットします。
  • showprompt()を使用して拡張プロンプトを返します。
  • ProfileAttributesを介してAIプロファイルにベクトル索引が構成されたRetrieval-Augmented Generation (RAG)を使用します。
  • summarize()を使用してコンテンツを要約します。
  • translate()を使用してコンテンツを変換します。
  • feedback()を使用して、生成されたSQLのフィードバックを送信します。
  • generateSyntheticData()を使用して合成データを生成します。

NL2SQLのデータベース・オブジェクトの構成

プロファイル オブジェクト リスト設定を使用して、Select AIがSQLの生成時に考慮するデータベース オブジェクトを制御します。

ProfileAttributesクラスは、オブジェクト・リスト構成およびObjectListMode値AUTOMATEDおよびALLをサポートしています。プロファイルのオブジェクトリスト設定は、Select AIが自然言語SQL生成に使用できるようにするデータベースメタデータを決定します。

オブジェクト・リストはデータベース権限を付与しません。データベース・ユーザーは、プロファイルが使用するオブジェクトに対して必要な権限を持っている必要があります。

オブジェクトリストの構成とオブジェクト選択の動作については、Manage AI Profilesを参照してください。

RAGのベクトル索引の構成

ベクトル索引をAIプロファイルに関連付けて、Retrieval-Augmented Generation (RAG)を使用します。ProfileAttributesクラスは、プロファイルが使用するベクトル索引設定を提供します。

RAG対応プロファイルを使用すると、Select AIは、構成されたベクトル索引から関連コンテンツを取得し、そのコンテンツをAIプロバイダに送信された拡張プロンプトに追加します。

プロファイルで使用する前に、必要なベクトル索引を作成して構成します。詳細は、Select AI with Retrieval Augmented Generation (RAG)を参照してください。

Select AIインタフェース間でプロファイルを使用

Profile.create()メソッドは、データベース・リソースとしてAIプロファイルを作成します。Java Profileオブジェクトは、そのデータベース・プロファイルのJava表現を提供します。

プロファイルはJavaプロセスではなくデータベース内に存在するため、同じデータベース・プロファイルにアクセスできる他のSelect AIインタフェースは、データベース権限およびサポートされているプロファイル機能に従ってプロファイルを使用できます。これには、SQLおよびPL/SQLインタフェース、およびサポートされているその他のSelect AI SDKまたはAPIが含まれます。

コンテンツの要約と翻訳

Profile.summarize()メソッドを使用して、インライン・コンテンツまたはコンテンツを外部の場所に要約します。要約リクエストごとに、インライン・コンテンツまたはロケーションURIのいずれかを指定しますが、両方は指定しません。

Profile.translate()メソッドを使用して、プロファイルに構成されているサポートされている翻訳プロバイダでテキストを変換します。プロバイダ固有の認証、言語サポートおよびサービス要件が適用されます。

詳細は、Generate a Summary with Select AIおよびTranslateを参照してください。

SQLフィードバックの入力

Profile.feedback()メソッドを使用して、NL2SQL生成の正または負のフィードバックを送信します。

ポジティブ・フィードバックは、将来参照するために生成されたSQLを確認します。否定的なフィードバックは、生成されたSQLの問題を特定し、予想されるSQLまたは追加のガイダンスを提供することができます。Select AIでは、関連する保存済フィードバックを、後続のSQL生成時に同様のプロンプトのヒントとして使用できます。

詳細は、「フィードバック」を参照してください。

Profileインタフェース、ProfileAttributesクラス、プロバイダ固有の構成、プロファイル・ライフサイクル・メソッド、生成メソッドおよび例の詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

会話の操作

Conversationオブジェクトは、データベースに格納されているSelect AI会話を表します。会話を使用して、関連するSelect AIインタラクション全体でコンテキストとプロンプト履歴を保持します。

会話は、会話IDで識別されるデータベース・リソースです。1つのAIプロファイルに永続的に関連付けられるわけではありません。アプリケーションは、アプリケーションのプロファイル構成およびデータベース権限に従って、会話コンテキストをサポートするSelect AI操作で会話識別子を使用できます。

会話の作成

SelectAI.conversation(ConversationAttributes)を使用して、会話属性で初期化されるJava Conversationオブジェクトを作成します。

このメソッドでは、データベース内に会話は作成されません。戻されたオブジェクトに対してConversation.create()をコールして、データベース会話を作成します。create()メソッドは、生成された会話識別子を返します。

会話属性

ConversationAttributesを使用して、次のような会話メタデータを構成します。

  • タイトル
  • 説明
  • 保持日
  • 会話の長さ

retentionDays属性は、Select AIが会話を保持する期間を指定します。conversationLength属性は、Select AIが関連する対話のために保持する会話コンテキストの量を指定します。

Conversation.getConversationAttributes()を使用して、既存の会話の現在の属性を取得します。サポートされている会話属性を更新するには、Conversation.setAttributes()を使用します。

Select AIは、会話プロンプト履歴をデータベースに格納します。Conversation.listPrompts()を使用して、作成時間順に会話に記録されたプロンプトを取得します。個々のプロンプトを削除するには、Conversation.deletePrompt()を使用します。deletePrompt()を使用して個々のプロンプトを削除しても、会話は削除されません。Conversation.drop()を使用して、データベースから会話を削除します。

後続のアプリケーション操作で同じ会話にアクセスする必要がある場合は、会話識別子を保持します。

既存の会話の使用

SelectAI.conversation(String conversationId)を使用して、会話識別子で既存の会話をオープンします。

会話をオープンまたは作成した後、Conversationインタフェースを使用して次のことを行います。

  • getConversationId()を使用して会話識別子を取得します。
  • getConversationAttributes()を使用して会話属性を取得します。
  • setAttributes()を使用して会話属性を更新します。
  • listPrompts()との会話用に格納されたプロンプトをリストします。
  • deletePrompt()を使用して個々のプロンプトを削除します。
  • drop()との会話を削除します。

会話ライフサイクル

Java Conversationオブジェクトは、Javaオブジェクトがスコープ外になったとき、またはSelectAIクライアントがクローズしたときに、対応するデータベース会話を自動的に削除しません。

データベースの会話ライフサイクルを明示的に管理します。アプリケーションが会話を必要としなくなった場合は、Conversation.drop()をコールします。

ノート

ノート:現在のSelect AI for Java SDKでは、セッションがクローズしたときに会話を自動的に削除する個別のパブリック・セッション・ライフサイクルは定義されません。Conversationインタフェースおよび会話識別子を使用して会話を管理します。

会話のスレッド動作

SDKでは、Conversationオブジェクトに対するグローバルなスレッド・セーフティ保証は提供されません。

複数のスレッドで、独立した操作に個別のConversationインスタンスを使用できます。アプリケーションがアクセスを同期しないかぎり、同じConversationインスタンスに対するプロンプトの更新、削除または削除に同時に複数のスレッドを使用しないでください。

一般的なSDKスレッド動作および接続モードの考慮事項は、スレッド動作を参照してください。

会話のガイドライン

会話識別子および会話コンテンツをアプリケーション・データとして扱います。会話には、データベース・インタラクションまたは機密ビジネス情報から導出されたプロンプトおよびメタデータを含めることができます。

アプリケーションのセキュリティおよびロギング・ポリシーで許可されている場合を除き、会話識別子、プロンプトまたは会話の内容をログ、エラー・レポートまたはその他の出力に含めないでください。アプリケーションのアクセス制御要件に従って、会話へのデータベース・アクセスを制限します。

Conversationインタフェース、ConversationAttributesクラス、会話ライフサイクル・メソッド、プロンプト・メタデータおよび例の詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

ベクトル索引の使用

ベクトル索引では、Retrieval-Augmented Generation (RAG)ワークフローがサポートされています。ベクトル索引には、Select AIがAIレスポンスの関連情報を取得できるように、ソース・コンテンツの検索可能な表現が格納されます。

ベクトル索引を作成、取得、更新、有効化、無効化および削除するには、VectorIndexインタフェースを使用します。ソースの場所、資格証明、埋込み設定、および目的のRAGワークフローに必要なその他の属性を使用してベクトル索引を構成します。

RAGでのベクトル索引の使用

ベクトル索引を作成したら、RAGに索引を使用するようにAIプロファイルを構成します。

ベクトル索引は、取得されたソース・コンテンツを提供します。RAG対応プロファイルは、ユーザーのプロンプトおよび取得されたコンテンツの処理に使用されるAIプロバイダおよびモデル構成を提供します。

これらのプロファイルが必要なRAG構成をサポートしている場合、同じベクトル索引を複数のプロファイルで使用できます。

ベクトル索引の作成

ベクトル索引構成からJava VectorIndexオブジェクトを作成するには、SelectAI.vectorIndex(VectorIndexConfig)を使用します。このメソッドは、Javaオブジェクトを作成します。データベース内にベクトル索引は作成しません。

VectorIndex.create()をコールして、データベースにベクトル索引を作成します。

SDKでベクトル索引が作成されると、データベースでは次の処理が実行されます。

  1. 構成されたソースの場所からコンテンツを読み取ります。
  2. ベクトル索引用に構成されたプロファイルおよびプロバイダを使用して、埋込みを生成します。
  3. RAG操作中に取得するために生成されたベクトルを格納します。

VectorIndexConfigクラスは、ベクトル索引名、プロファイル名、ステータス、説明、完了待機設定、ベクトル索引属性など、作成時の構成を提供します。

RAGプロファイルの埋め込み

ベクトル索引構成で指定されたプロファイルは、ソース・コンテンツの埋込みを作成するためにデータベースが使用するプロバイダおよび埋込み構成を提供します。

埋込みの作成に使用されるプロファイルは、アプリケーションがRAGリクエストに使用するプロファイルを自動的に決定しません。ProfileAttributes構成でベクトル索引を指定することで、RAGのプロファイルを個別に構成します。

RAGワークフローは、さまざまな役割でAIプロファイルを使用します。次の表に、ワークフローの各リソースを、対応するSelect AI for Javaリソースまたは構成にマップします。

リソース Javaリソースまたは構成 目的
埋込みプロファイル ProfileおよびProfileAttributes ソース・コンテンツの埋込みの作成に使用されるプロバイダおよび埋込み構成を提供します。ベクトル索引を構成するときに、VectorIndexConfigにプロファイル名を指定します。
ベクトル索引 VectorIndex、VectorIndexConfigおよびVectorIndexAttributes 生成されたベクトルを格納し、取得するコンテンツを提供するベクトル索引を構成および管理します。
RAGプロファイル ProfileおよびProfileAttributes プロファイル構成内のベクトル索引を参照し、RAGリクエストの処理に使用されるプロバイダおよびモデル構成を提供します。

RAG対応プロファイルがリクエストを処理すると、Select AIはベクトル索引から関連コンテンツを取得し、そのコンテンツをAIプロバイダに送信された拡張プロンプトに追加します。

詳細は、Select AI with Retrieval Augmented Generation (RAG)を参照してください。

ベクトル索引作成のモニター

ベクトル索引の作成は、VectorIndexConfigのwaitForCompletion設定に基づいて、同期または非同期で実行できます。

waitForCompletion 動作
true VectorIndex.create()は、ベクトル索引の作成が完了するまで待機してから戻ります。
false VectorIndex.create()は、ベクトル索引の作成が終了するまで待機せずに戻ります。

VectorIndex.getStatus()を使用して、データベース・バックアップ・ベクトル索引の現在のステータスを取得します。VectorIndex.getVectorIndexAttributes()を使用して、現在の属性を取得します。

ベクトル索引の作成に失敗した場合、VectorIndex.create()はSelectAIExceptionを介してデータベースまたはJDBCの障害を報告します。

SDKは、ベクトル索引作成用の個別の進行状況インタフェースまたは非同期ジョブ・オブジェクトを提供しません。

ベクトル索引のリフレッシュ

ベクトル索引では、構成済のリフレッシュ・レートを使用して、索引によるソース・コンテンツの変更処理方法を制御できます。

ソース・ドキュメントが変更されると、データベースでは、構成されたリフレッシュ動作に従ってベクトル索引が更新されます。VectorIndexAttributesでリフレッシュ率を構成します。

構成されたリフレッシュ動作で必要な更新がサポートされている場合、ソース・コンテンツが変更されるため、アプリケーションはベクトル索引のみを再作成する必要はありません。

ベクトル索引がコンテンツを処理またはリフレッシュしている間は、必要なソースの場所および資格証明を引き続き使用可能にする必要があります。

サポートされているリフレッシュ属性および構成については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

ベクトル索引の更新

サポートされているベクトル索引属性を更新するには、VectorIndex.update(VectorIndexAttributes)または単一属性のupdate()メソッドを使用します。

一部の属性は、ベクトル索引の作成時にのみ適用され、後で変更することはできません。データベースは、属性を更新できるかどうかを決定します。

データベースが変更に対してサポートする属性のみを使用して、更新リクエストを作成します。たとえば、chunk_sizeは作成時属性であり、ベクトル索引の作成後に更新することはできません。

変更を行う前に、VectorIndex.getVectorIndexAttributes()を使用して既存のベクトル索引の現在の属性を取得します。

ベクトル索引の有効化または無効化

次の方法を使用して、Select AIがRAG取得にベクトル索引を使用できるかどうかを制御します。

メソッド 効果
VectorIndex.enable() RAG取得のベクトル索引を有効にします。
VectorIndex.disable() ベクトル索引を無効にします。Select AIでは、再度有効にするまで、ベクトル索引は取得に使用されません。

ベクトル索引を有効または無効にしても、ベクトル・データは削除されません。

ベクトル索引の削除

ベクトル索引を削除するには、VectorIndex.drop(boolean force)を使用します。

このフォームは、ベクトル索引メタデータとバッキング・ベクトル・データの両方を削除します。

バッキング・ベクトル・データを削除するかどうかを制御する必要がある場合は、VectorIndex.drop(boolean includeData, boolean force)を使用します。

includeData 動作
true ベクトル索引メタデータとともにバッキング・ベクトル・データを削除します。
false 基礎となるデータベース操作でこのオプションがサポートされている場合、バッキング・ベクトル・データを保持します。

注意:ベクトル索引を削除する前に、それを使用するRAG対応のプロファイルまたはアプリケーションを特定してください。ドロップ・オプションを選択する前に、基礎となるベクトル・データを保持する必要があるかどうかを確認します。

実行可能な完全なサンプル・ソースについては、vectorindexを参照してください。

データベース構成およびRAGの概念については、Select AIの前提条件の実行およびSelect AI with Retrieval Augmented Generation (RAG)を参照してください。

サポートされている属性、作成オプション、ステータス値、更新メソッドおよびドロップ・メソッドの詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

合成データの生成

Select AI for Javaでは、単一のデータベース・オブジェクトまたは複数の関連データベース・オブジェクトの合成データを生成できます。テスト、開発、プロトタイピングおよび分析に合成データを使用します。合成データ生成では、関連付けられたProfileオブジェクトで構成されたAIプロバイダを使用します。

Profile.generateSyntheticData(SyntheticDataSingleRequest)を使用して、1つのデータベース・オブジェクトの合成データを生成します。Profile.generateSyntheticData(SyntheticDataBatchRequest)を使用して、複数のオブジェクトの合成データを生成します。

リクエストは次を指定できます。

  • データベース・オブジェクト名
  • オブジェクト所有者
  • 生成する行数。
  • ユーザーガイダンス。
  • サポートされている生成パラメータ。

生成されたデータは、リクエストで指定されたデータベース・オブジェクトをターゲットとします。Javaメソッドは、データベース操作が成功したかどうかを示すブール結果を返します。生成された行はコール元に返されません。

合成データを生成するための前提条件

合成データを生成する前に:

  • ターゲット・データベース・オブジェクトが存在することを確認します。
  • ターゲット・オブジェクトへのアクセスおよび変更に必要な権限をデータベース・ユーザーに付与します。
  • 合成データ生成をサポートするプロバイダのAIプロファイルを構成します。
  • Select AIデータ・アクセスを有効にします。
  • プロバイダ固有の構成および認証要件を完了します。

必要なSelect AI権限およびデータベース設定については、Select AIの前提条件の実行を参照してください。

関連オブジェクトのデータの生成

複数の関連データベース・オブジェクトのデータを生成する必要がある場合は、SyntheticDataBatchRequestを使用します。

バッチ要求には、複数のオブジェクトとその生成設定を含めることができます。このフォームは、生成されたデータが指定されたオブジェクト間の関係を反映する必要がある場合に使用します。

このリクエストでは、合成データ生成のために指定された数の行がサポートされます。有効な制限は、基礎となるデータベース機能、プロバイダおよびデータベース・リソースによって異なります。

単一オブジェクトまたはバッチ生成操作が失敗した場合、SDKはSelectAIExceptionを介してデータベースまたはJDBCの障害を報告します。

注意:

合成データ生成では、大規模言語モデルを使用して、要求されたデータを生成します。生成されたデータをダウンストリーム・システムで使用する前に確認します(特に、ターゲット・オブジェクトに次のものがある場合)。

  • 主要キー制約。
  • 外部キー制約。
  • 一意な制約。
  • 制約を確認します。
  • アプリケーション固有の検証ルール。

合成データ生成を使用して、実際の個人情報や機密性の高い生産データを再現しないでください。

合成データ生成のトランザクション動作

合成データの生成は、Profileオブジェクトが使用するJDBC接続のトランザクション動作に従います。

SDKは、トランザクションを明示的にコミットまたはロールバックしません。DbConnectionConfigモードでは、操作はSDK所有のJDBC接続を使用します。DataSourceモードでは、この操作では、アプリケーション管理のDataSourceから流用された接続が使用されます。

トランザクションの動作の詳細は、Autonomous AI Databaseへの接続を参照してください。

サポートされているパラメータおよび例外の詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

既存のオブジェクトの取得および更新

Select AI for Javaは、プロファイル、会話、資格証明およびベクトル索引をデータベース・バックJavaオブジェクトとして表します。

サポートされている取得メソッドを使用して、既存のオブジェクトに関する現在の情報を取得します。返される情報には、オブジェクトに応じて、名前、識別子、説明、ステータス、属性およびメタデータを含めることができます。

基礎となるSelect AIデータベースAPIでサポートされている属性のみを更新します。更新によって、必ずしも完全なオブジェクトが置き換えられるわけではありません。アプリケーションが現在のデータベース状態を必要とする場合にオブジェクトを取得し、オブジェクト固有の操作を実行する前にオブジェクトが存在することを確認します。

コレクションの取得は、接続されたデータベース・ユーザーがアクセスできるオブジェクトを返します。

サポートされている取得メソッド、更新操作、リクエスト・オブジェクトおよび戻り値については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

オブジェクトの削除

アプリケーションが不要になったプロファイル、資格証明、会話およびベクトル索引を削除します。

オブジェクトを削除する前に:

  • オブジェクトが不要になったことを確認します。
  • 依存プロファイル、資格証明、会話およびベクトル索引を確認します。
  • 接続されているデータベース・ユーザーがオブジェクトを削除できることを確認します。
  • 必要なメタデータまたは構成をデータベース外に保持します。

一部のリソース・メソッドは、すでに存在しないオブジェクトを正常に処理する強制削除オプションを提供します。このオプションは、アプリケーションが不在オブジェクトを最終状態として安全に受け入れることができる場合にのみ使用します。

オブジェクト固有の削除メソッド、依存性動作および例外については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

同期APIの使用

Select AI for Java 1.0.0では、同期Java APIのみが提供されます。SDKでは、非同期APIやストリーミング・プロファイル操作は提供されません。アプリケーションが各データベース操作の終了を待ってから続行できる場合は、同期APIを使用します。

同期メソッドは、データベース操作の完了を待機するか、またはエラーを返すと、制御がコール元のアプリケーションに戻ります。そのため、AIプロバイダと通信したり、長時間実行されるデータベース処理を実行する操作は、コール側のスレッドを長期間ブロックできます。

マルチスレッド・アプリケーションの場合は、DataSourceモードを使用し、予想される同時実行性およびワークロードに対して接続プールのサイズを設定します。JDBC問合せのタイムアウトの詳細は、トランザクション動作を参照してください。

ノート

ノート: JDBC問合せタイムアウトでは、AIプロバイダ・リクエストのタイムアウトは構成されず、すでに進行中のプロバイダ・リクエストの取消しは保証されません。

このリリースで使用可能な同期メソッドについては、Select AI for Java APIリファレンス(Javadoc)を参照してください。

エラーの処理

Select AI for Javaは、標準のJava例外を介してローカルで検出された検証エラーを報告し、SelectAIExceptionを介してデータベース、JDBC、DBMS_CLOUD、DBMS_CLOUD_AIおよびプロバイダの障害を報告します。

SDKは、JDBC処理の前に確認できるリクエスト情報を検証します。データベースおよびJDBCドライバは、データベース権限、リソース状態、パッケージ要件、プロバイダ構成、ネットワーク・アクセスおよびその他のデータベース側の要件を検証します。

SDK例外の処理

SDKでは、一般的なエラー条件に次の例外が使用されます。

例外 発生時
IllegalArgumentException アプリケーションで無効な引数または構成値が指定されています。たとえば、nullまたは空白の必須値、無効なポート範囲、負のタイムアウト値、無効な資格証明の組合せなどがあります。
IllegalStateException アプリケーションで、無効なライフサイクル状態のSDKリソースが使用されています。たとえば、操作には、すでに作成またはオープンされているリソースが必要です。
SelectAIException JDBC、DBMS_CLOUD、DBMS_CLOUD_AIまたは構成されたAIプロバイダが、SDKを介して障害を報告します。

SelectAIExceptionは、Exceptionから継承し、呼出し側が明示的に処理または宣言する必要があるチェック例外にします。パブリック・データベース・バックアップ・メソッドは、プロファイル生成およびライフサイクル・メソッド、会話操作、ベクトル索引操作、資格証明操作、DatabaseAdmin操作、SDK所有の接続の作成とクリーンアップなどのSelectAIExceptionを宣言します。

個々のメソッドの例外宣言については、Select AI for Java API Reference (Javadoc)を参照してください。

クライアント側およびデータベース側の検証

SDKは、Javaリクエストから妥当性を判断できる場合に、JDBC処理の前にサポートされている入力を検証します。

SDKは、次のような条件を検出します。

  • リソース名がNULLまたは空白です。
  • 必要に応じて、プロンプトおよびアクションがNULLまたは空白です。
  • ユーザー、ホストまたは権限が無効です。
  • ポートの範囲が無効です。
  • 負の問合せタイムアウト値。
  • 資格証明の組合せが無効です。
  • まだ作成またはオープンされていないリソースに対する操作。

これらの条件は通常、JDBC処理の前にIllegalArgumentExceptionまたはIllegalStateExceptionになります。

データベースは、データベース構成、リソースまたはリモート・サービスに依存する条件を検証します。次の条件があります。

  • データベース権限
  • リソースの存在と状態。
  • DBMS_CLOUDおよびDBMS_CLOUD_AIの要件。
  • プロバイダの構成
  • 資格証明の有効性。
  • ネットワークACL構成。
  • オブジェクト・リスト・ルール
  • ベクトル索引の制限。
  • リモートAIプロバイダのレスポンス。

SDKは、SelectAIExceptionを介してこれらのデータベース側の障害を報告します。

SelectAIExceptionの処理

SelectAIExceptionをキャッチして、データベース・バックアップのSelect AI操作からの障害を処理します。

次に例を示します:

try (SelectAI selectAI = SelectAI.create(dataSource)) {
    Profile profile = selectAI.profile("MY_PROFILE");
    String response = profile.chat("Show the top five products");
} catch (SelectAIException exception) {
    System.err.println(exception.getMessage());
    System.err.println(exception.getErrorCode());
    System.err.println(exception.getSqlState());
}

障害をトラブルシューティングするために十分な診断情報を記録しますが、パスワード、秘密キー、トークン、または完全な資格証明構成は記録しません。

例外階層、エラーの詳細および操作固有の動作については、Select AI for Java API Reference (Javadoc)を参照してください。

エラー詳細の検査

使用可能なエラー情報を調べるには、次のSelectAIExceptionメソッドを使用します。

メソッド 摘要
getErrorCode() 使用可能な場合、JDBCまたはOracleエラー・コードを返します。
getSqlState() 使用可能な場合、SQLStateを返します。
getCause() 基礎となる例外(使用可能な場合、基礎となるJDBC例外を含む)を返します。

プロバイダ障害では、個別のJavaプロバイダ例外タイプを使用しません。通常、DBMS_CLOUDまたはDBMS_CLOUD_AIはプロバイダ障害を受け取り、データベース・レイヤーおよびJDBCレイヤーを介して報告し、SDKは障害をSelectAIExceptionにラップします。

たとえば、AIプロバイダによって返されるHTTPエラーは、ORA-20400などのOracleエラーとして表示される場合があります。操作に使用可能な診断情報のSelectAIExceptionエラーの詳細および根本的な原因を調べます。

完全なSelectAIExceptionメソッドおよび戻り値については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

失敗した操作の再試行

Select AI for Javaでは、失敗した操作は自動的に再試行されません。

接続障害が一時的であったことを確認した後、読取り専用メタデータ操作の再試行を検討できます。

作成、更新、削除、管理、生成またはチャット操作を自動的に再試行しないでください。アプリケーションが障害を受信する前に、データベースまたはAIプロバイダが要求の処理を開始した可能性があります。

データベースの状態を変更したり、AIプロバイダにリクエストを送信したりできる操作を再試行する前に、現在の操作またはリソース状態を確認し、リクエストの繰返しが安全であることを確認します。

タイムアウトおよびサーバー側の作業

queryTimeoutSeconds設定は、JDBC文のタイムアウトを構成します。次のように構成されるとはかぎりません。

  • AIプロバイダ・エンドポイント・タイムアウト。
  • HTTP接続または読取りタイムアウト。
  • リモート・モデル要求の取消。
  • 長時間実行されているDBMS_CLOUD_AI操作の取消し。

JDBCタイムアウトにより、データベース側またはプロバイダ側の処理が続行される間、アプリケーションがJDBC文を待機することを停止できます。

注意:タイムアウトした操作が処理を停止したと想定しないでください。操作を再試行する前に、影響を受けるデータベース・リソースまたは操作の状態を確認し、AIプロバイダが引き続き元のリクエストを処理しているかどうかを検討してください。

詳細については、「トランザクション動作」を参照してください。

エラーをトラブルシューティングする

操作が失敗すると、次のようになります。

  1. SelectAIExceptionメッセージ、Oracleエラー・コード、SQLStateおよび基礎となる原因(使用可能な場合)を確認します。
  2. データベース・ユーザーに必要な権限があることを確認します。
  3. 参照されるプロファイル、資格証明、会話またはベクトル索引が存在し、必要な状態であることを確認します。
  4. 必要に応じてプロバイダの構成と資格証明を確認します。
  5. プロバイダまたはデータ・ソースで必要な場合は、ネットワーク・アクセスおよびACL構成を確認します。
  6. プロバイダの障害については、DBMS_CLOUDまたはDBMS_CLOUD_AIを介して返されるOracleエラーおよび基礎となる診断情報を確認してください。
  7. タイムアウトまたは接続の失敗の場合は、リクエストを再試行する前に操作またはリソースの状態を確認してください。

SelectAIException、メソッド固有の例外、検証動作およびエラー処理の詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

Select AI for Javaの例

Select AI for Javaの機能を構成および使用する方法を示すサンプルJavaコードについては、Select AI for Javaの例を参照してください。これらの例をSelect AI for Java APIリファレンス(Javadoc)とともに使用して、各ワークフローで使用されるクラス、メソッドおよび構成を理解します。