よくある質問(FAQ)とトラブルシューティング

インストール

26aiデータベースを使用してエージェント・ファクトリを構成するにはどうすればよいですか。

設定ガイドのステップに従って、エージェント・ファクトリをOracle AI Database 26aiに接続します。次を参照してください

会社には既存のOCIアカウントがありますが、管理者ではありません。

Free Tierアカウントにサインアップする場合、アカウントはデフォルトで管理者グループ内にあります。ただし、会社に既存のOCIアカウントがあり、管理者グループに属していない場合は、管理者に次のポリシーを割り当てるよう依頼してください:

allow group <your-group-name> to manage generative-ai-family in compartment <your-compartment>

詳細は、生成AIへのアクセスの取得を参照してください。

インストール中に'デバイスに使用可能な領域がありません'というメッセージが表示された場合はどうすればよいですか。

このエラーは、/tmpディレクトリの領域が少ないために発生する可能性があります。

• 次のコマンドを実行します

  mkdir /scratch/podman_tmp

• podmanを十分な空き領域があるTMPDIRに指定するように~/.config/containers/containers.confを編集します。たとえば、/scratchディレクトリに十分なメモリー(約100GB)がある場合、ディレクトリ/scratch/podman_tmpを作成し、~/.config/containers/containers.confの内容を次のように変更します:

  [engine]
  env = ["TMPDIR=/scratch/podman_tmp"]

領域およびRAMの要件はどのくらいですか。

環境	推奨ディスク領域	推奨RAM
クイックスタート	30 GB	10 GB
本番	10 GB	8 GB

本番インストールとクイックスタート・インストールの違いは何ですか。

本番モードでは、データベースおよびLLMエンドポイントの詳細を手動で設定できます。この設定により、独自の資格証明を使用し、サポートされているLLMプロバイダ(vLLM、OpenAI、Ollamaなど)と、OCI GenAIが提供する事前トレーニング済の基礎モデルの完全なカタログに接続できます。リソース使用量: 約10 GBのデバイス・ストレージと8 GBのRAM。

クイックスタート・モードでは、同じ環境でローカルに動作するコンテナを介して、Oracle AI Database 26ai Freeのインスタンスを設定し、事前トレーニング済のLlama3.2 LLMを備えたOllamaを設定します。これにより、エージェント・ファクトリの使用を開始できます。事前の設定は不要です。リソース使用量: 約30 GBのデバイス・ストレージと10 GBのRAM。

サマリー

機能	クイックスタート	本番
設定	自動化されたローカル・コンテナ	手動でのユーザー提供のエンドポイント
データベース	Oracle Database 26ai Free	ユーザーのOracle Database 26ai
LLM	Ollama + Llama3.2プリセット	ユーザーが選択したLLM (vLLM、OCIなど)
ストレージ使用量	30 GB	10 GB
RAM使用量	10 GB	8 GB
使用されるポート	1521、11434 (+8080常時)	8080

アプリケーションではどのようなプラットフォームがサポートされていますか。

現在サポートされているオペレーティング・システムは次のとおりです:

• Oracle Linux 8 (AMDx86_64)
• Oracle Linux 8 (ARM64)
• MAC OS ARM64 (AppleシリコンM.xチップセット)
• MAC OS Intelチップセット

アプリケーションではどのポートが使用されますか。

デフォルトでは、Oracle AI Database Private Agent Factoryを実行しているコンテナはポート8080を使用します。

クイックスタート・モードでインストールすると、Oracle AI Database 26ai Freeインスタンスはポート1521で実行され、Ollamaインスタンスはポート11434で実行されます。インストールの問題を回避するために、これらのポートがシステムで使用できることを確認します。

アプリケーションをインストールするための前提条件は何ですか。

プラットフォームに関係なく、次の前提条件が必要です:

Oracle AI Database 26ai Oracle AI Database 26aiのインスタンスにアクセスする必要があります。この目的のために専用ユーザーを作成することをお薦めします。このユーザーは、本番データの格納ではなく、これらの表の管理にのみ使用する必要があります。

LLMエンドポイント。Oracle AI Database Private Agent Factoryは、大規模言語モデルとの統合を利用して適切に機能しています。選択した使用可能なLLMインスタンスでアプリケーションを接続するには、適切な認証資格証明またはアクセス・キーが必要です。

どのデータベース・バージョンがサポートされていますか?

Oracle AI Database Private Agent Factoryには、Oracle AI Database 26ai(自己管理インスタンスと自律型インスタンスの両方)が必要です。

アプリケーションを実行する前に、max_string_sizeデータベース・パラメータをEXTENDEDに設定する必要があります。

データベース・ユーザーがアプリケーションを使用するために必要な権限は何ですか。

アプリケーション設定に必要なデータベース・ユーザーには、次の権限が必要です。****および****を必要なユーザー名とパスワードに置き換えてから、次のコマンドを実行します。

CREATE USER <DB_USER> IDENTIFIED BY <DB_PASSWORD> DEFAULT TABLESPACE USERS QUOTA unlimited ON USERS;

GRANT CONNECT, RESOURCE, CREATE TABLE, CREATE SYNONYM, CREATE DATABASE LINK, CREATE ANY INDEX, INSERT ANY TABLE, CREATE SEQUENCE, CREATE TRIGGER, CREATE USER, DROP USER TO <DB_USER>;

GRANT CREATE SESSION TO <DB_USER> WITH ADMIN OPTION;

GRANT READ, WRITE ON DIRECTORY DATA_PUMP_DIR TO <DB_USER>;

GRANT SELECT ON V_$PARAMETER TO <DB_USER>;

exit;

max_string_sizeデータベース・パラメータを拡張する方法

1. SQL*Plusまたは任意のツールを使用して、SYSDBAユーザーとしてPDB (プラガブル・データベース)にログインします。

2. パラメータの現在の値を確認します:

   SELECT value FROM v$parameter WHERE name = 'max_string_size';

3. 出力がすでにEXTENDEDの場合、これ以上のアクションは必要ありません。それ以外の場合は、SYSDBAユーザーとして次のスクリプトを実行します。この手順により、データベースが再起動されます。

   ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;
   SHUTDOWN NORMAL;
   STARTUP UPGRADE;
   @$ORACLE_HOME/rdbms/admin/utl32k.sql
   SHUTDOWN IMMEDIATE; STARTUP;
   @$ORACLE_HOME/rdbms/admin/utlrp.sql

4. マルチテナント(CDB/PDB)アーキテクチャを使用している場合は、アプリケーション・スキーマがインストールされるPDBについて、次の操作を繰り返します:

   1. CDBルートから、UPGRADEモードでPDBを開きます。

      ALTER PLUGGABLE DATABASE <PDB_NAME> OPEN UPGRADE;

   2. セッションをPDBに切り替えます。

      ALTER SESSION SET CONTAINER=<PDB_NAME>;

   3. PDBで移行スクリプトを実行します。

      @$ORACLE_HOME/rdbms/admin/utl32k.sql

   4. CDBルートに再度切り替えます。

      ALTER SESSION SET CONTAINER=CDB$ROOT;

   5. PDBを閉じてから開きます。

      ALTER PLUGGABLE DATABASE <PDB_NAME> CLOSE IMMEDIATE;
      ALTER PLUGGABLE DATABASE <PDB_NAME> OPEN;

5. PDBに切り替えて、変更が成功したことを確認します。この問合せの出力はEXTENDEDである必要があります。

SELECT value FROM v$parameter WHERE name = 'max_string_size';

ナレッジ・エージェントのインストールの失敗をトラブルシューティングするにはどうすればよいですか。

事前構築済のナレッジ・アシスタントを含むナレッジ・エージェントを正常にインストールするには、エージェント・ファクトリに、事前認証済リクエスト(PAR)ファイルを使用してOCIオブジェクト・ストレージにアクセスするためのデータベースが必要です。WALLET_LOCATIONまたはENCRYPTION_WALLET_LOCATIONがデータベース・サーバーのsqlnet.oraファイルで指定されているかどうかを確認します。いずれかが構成されている場合は、必要なOCI証明書がウォレットに追加されていることを確認します。証明書が存在しない場合は、それらをウォレットに追加してオブジェクト・ストレージ・ファイルへのアクセスを有効にし、ナレッジ・エージェントのインストールの失敗を防止します。データベースでウォレットが使用されていない場合は、このステップをスキップできます。

ここをクリックして、ウォレットに追加する必要がある証明書をダウンロードします。次の例では、SSLウォレットが/u01/app/oracle/dcs/commonstore/wallets/sslにあり、証明書を/home/oracle/dbcに解凍したと想定しています:

#! /bin/bash
# Check if the certificates are available under "Trusted Certificates"
orapki wallet display -wallet /u01/app/oracle/dcs/commonstore/wallets/ssl

# Add certificates if they are missing
for i in $(ls /home/oracle/dbc/DigiCert*cer)
do
orapki wallet add -wallet /u01/app/oracle/dcs/commonstore/wallets/ssl -trusted_cert -cert $i -pwd <SSL Wallet password>
done

詳細は、証明書を使用したSSLウォレットの作成を参照してください。

MCPサーバー

「認証が必要です」というエラーが表示されます

authTypeをBearerまたはBasicに設定し、有効な資格証明を指定します。OAuthの場合、サーバーURLが/mcpエンドポイントを指しており、トークンの有効期限が切れていないことを確認してください。

404エラーが表示されます

serverUrlのパスが間違っている可能性があります。/mcp、/mcp/jsonrpcなどの正しいMCPエンドポイント・パス、またはサーバーのドキュメント化されたルートを使用します。

1つのエージェントに複数のMCPサーバーを接続できますか。エージェントは、どのMCPサーバーを呼び出してどのツールを実行するかをどのように決定しますか。

はい、1つのエージェントに複数のMCPサーバーを接続できます。LLMは、各ツールの説明およびユーザーの問合せとどの程度一致するかに基づいて、適切なサーバーおよびツールを選択します。複数のツールが使用可能な場合でも、モデルはリクエストに最も関連性の高いツールを選択します。

MCPサーバーはストリーム可能なHTTPをサポートしていますか。

はい。OAuth/Bearerで保護されたサーバーでは、認証付きのStreamableHTTPTransportがサポートされ、推奨されています。

カスタム・エージェント

カスタム・エージェントは会話型ですか、それともステートレスですか。

エージェント・ビルダーのLLMでは、会話型メモリーがサポートされています。ナレッジ・エージェントは現在ステートレスであり、一度に1つの質問に応答します。

サブエージェントをエージェントに接続できますか。

はい。1つのエージェントに複数のサブエージェントを接続できます。メイン・エージェントは、サブエージェントを編成および調整し、ユーザーの問合せに基づいて正しいサブエージェントを選択し、最終的なレスポンスを集約します。

カスタム・エージェントの構築時にカスタム・ナレッジ・ベースを指定できますか。

はい。ナレッジ・エージェントの構築時に、カスタム・ナレッジ・ベースを指定できます。ナレッジ・ベースは、Webソース、ファイル・システムまたはSharePointを使用して作成できます。

データ分析エージェントでは、スキーマ・レベルのデータ探索をサポートしていますか。

まだサポートしていません。現在、データ探索は表レベルおよびビュー・レベルでサポートされています。スキーマ・レベルの探索はロードマップに含まれています。

エージェント・ファクトリは、外部プラットフォームおよびOCI内でエージェント間プロトコルをサポートしていますか。

現時点では、ありません。この機能はロードマップに含まれています。

LLMコンテナはOllamaに基づいていますか。

エージェント・ファクトリは、Ollama、vLLM、OCI生成AI、OpenAIなど、複数のサービス・オプションをサポートしています。

オンプレミスで使用するための追加ライセンス・コストはありますか。それともデータベースに含まれていますか。

含まれています。エージェント・ファクトリは、Oracle AI Database 26aiの無料アドオンです。

コンテナはExadata環境(オンプレミスではExaCC、ExaCS、Exadata)で実行できますか。

サポートされているコンテナ・ランタイム(Podmanなど)が使用可能なExadata VMベースのデプロイメントでサポートされます。ベアExadataデータベース・ノードではサポートされていません。詳細は、最新のプラットフォーム・サポート・マトリックスを参照してください。

データ・ソースを設定または接続できるユーザーを制御するにはどうすればよいですか。ロールベースの認可はありますか。

はい。エージェント・ファクトリには、チャット専用ユーザー、エディタおよび管理者の3つのロールを備えたユーザー管理が含まれており、AIエージェント・ライフサイクル全体にわたって職務を分離できます。

エージェント・ファクトリでプロトタイピングした後、エージェントはどこで実行されますか。

エージェントは独自のコンテナで実行されます。Oracle AI DatabaseおよびLLMサービス(たとえば、vLLM/Ollamaを介して、または直接OCI生成AIやOpenAIなどのサービスに対して)に接続します。

アプリケーションでは、エージェント・ファクトリAPIをコールして、ユーザーがWebページからエージェントと対話できるようにできますか。

はい。公開されたエージェントは、アプリケーションがエージェント・フロー/ワークフローを起動するためにコールできるREST APIを公開します。

複数のエージェントがコラボレートしてプロンプトに応答できますか。

はい。マルチエージェント・パターンがサポートされています。

LLMのかわりにSLMを使用できますか。

はい。vLLM、Ollama、OCI生成AIおよびOpenAIを介してサポートされる様々なモデル・サイズおよびプロバイダを使用できます。

エージェント・ファクトリのコンテナはマルチクラウド・デプロイメントで使用可能ですか。

はい。エージェント・ファクトリは、Oracle AI Databaseが実行されるすべての場所で実行されます。

メタデータを含む注釈を自動的に生成できますか。これはカスタマイズ可能ですか?

現在、注釈は自動的に生成されます。カスタマイズは、今後のリリースで計画されています。

他のエージェント・プラットフォームからワークフローを移行できますか。

はい、オープン・エージェント仕様に準拠している場合、可能です。

エージェントとフローはどのように監視されますか。

エージェント評価/監視レイヤーは開発中で、今後のリリースで計画されています。

トラブルシューティング用に診断ZIPを生成するにはどうすればよいですか。

• アプリケーションがインストールされたディレクトリであるステージング・ディレクトリに移動します。
• make diagnoseコマンドを実行します
• このコマンドは、必要なログとシステム情報を含む診断ZIPファイルを生成します。