日日是Oracle APEX: CohereのConnectorとしてOracle REST Data ServicesのREST APIを呼び出す

2024年3月22日金曜日

CohereのConnectorとしてOracle REST Data ServicesのREST APIを呼び出す

Cohereが最近ベータ版として提供を開始したConnectorsという機能があります。

Introduction to Connectors
https://docs.cohere.com/docs/connectors

Coralへリクエストを送信する際に、connectorsに自分で作成したコネクタを含めることにより、LLMに外部の知識を追加することができるようになります。

Oracle REST Data ServicesにREST APIを作成し、自作コネクタとして定義してCohereのPlaygroundから呼び出してみました。以下、作業の手順を記載します。

とりあえず、Playgroundから呼び出すだけ呼び出してみました。

作成したConnectorはDashboardから確認できます。なぜか最初のConnectorはAPIからでないと作成できませんでした。１つConnectorが作成されていると、New connectorのボタンが表示されるようになります。

CohereのConnectorとして登録するORDSのREST APIを作成します。

モジュールはcohere、テンプレートはsearchとします。CohereからはPOSTメソッドが呼び出されます。

ハンドラのコードとして以下を記述します。特に何かを検索せず、リクエストにqueryとして渡される文字列をそのままtextとして返します。

認証による保護はかけません。Connectorはservice_auth、oauth2（認可コード・グラント）、user_access_token（パス・スルー）の３種類の認証手順を使ってConnector（今回はOracle REST Data ServicesのREST API）を呼び出すことができますが、どれもORDSのREST APIの保護と（今までの調査の範囲では）互換がなさそうです。ORDSのREST APIをCohereのConnectorとして呼び出す際のAPIの保護に関しては課題です。

https://docs.cohere.com/docs/connector-authentication

以下より、CohereのConnector APIを呼び出して、Oracle REST Data ServicesのREST APIをConnectorとして追加するAPEXアプリケーションを作成します。

CohereのAPIキーがWeb資格証明COHERE_API_KEYとして登録しておきます。

認証タイプとしてHTTPヘッダーを選択します。資格証明名はAuthorization、　資格証明シークレットはBearerで始めて空白で区切り、CohereのAPIキーを続けた文字列を設定します。

空のアプリケーションを作成します。名前はCohere Connectorsとします。

アプリケーションが作成されたら、共有コンポーネントのRESTデータ・ソースを開きます。Connectorの操作はRESTデータ・ソースとして実装します。

RESTデータ・ソースの作成を開始します。

RESTデータ・ソースの作成は最初からを選択し、次へ進みます。続く画面で、RESTデータ・ソースの一般的な設定を行います。

RESTデータ・ソース・タイプとして簡易HTTPを選択します。名前はCohere Connectors API、URLエンドポイントとして以下を設定します。

https://api.cohere.ai/v1/connectors

次へ進みます。

リモート・サーバー、ベースURL、サービスURLパスなどが自動的に設定されます。

変更は不要なので、そのまま次へ進みます。

ページ区切りタイプはページ区切りなしです。

次へ進みます。

認証が必要ですをオンにし、資格証明としてCOHERE_API_KEYを選択します。

検出をクリックします。

標準のConnectorであるweb-searchとcohere-public-docsが検出されます。

RESTデータ・ソースの作成をクリックします。

RESTデータ・ソースCohere Connector APIが作成されます。

このRESTデータ・ソースを開き、Connectorの作成、更新、削除を行なう操作を追加します。

操作の追加をクリックします。

HTTPメソッドとしてPOST、データベース操作として行の挿入を選択します。リクエスト本文テンプレートとして以下を記述します。

{  
  "name":"#NAME#",  
  "description":"#DESCRIPTION#",  
  "url":"#URL!RAW#",  
  "service_auth": {  
    "type": "#TYPE#",
    "token": "#TOKEN!RAW#"
  }
}

以上を設定し、一旦、作成をクリックします。

作成された操作POSTを再度開き、操作パラメータの本文との同期をクリックします。

Content-Typeヘッダーを操作パラメータとして追加します。

パラメータの追加をクリックします。

タイプとしてHTTPヘッダーを選択します。名前はContent-Type、目的は入力、デフォルト値はapplication/jsonです。静的をオンにし値の変更を禁止します。

パラメータの追加をクリックします。

以上でConnectorの作成を行なう操作は追加できました。

変更の適用をクリックします。

先ほど同じ手順で操作で、Connectorの更新を行なう操作を追加します。

URLパターンに/:idを設定します。HTTPメソッドはPATCH、データベース操作は行の更新です。リクエスト本文テンプレートとして以下を記述します。

{  
  "service_auth": {  
    "type": "#TYPE#",
    "token": "#TOKEN!RAW#"
  }
}

一旦、操作PATCHを作成し、再度操作を開いた後に、本文の同期とContent-Typeヘッダーの追加を行います。

URLパターンのidも、操作パラメータとして追加します。

Connectorの削除を行なう操作を追加します。

URLパターンは/:id、HTTPメソッドとしてDELETE、データベース操作として行の削除を選択します。

操作DELETEではリクエスト本文パラメータとContent-Typeヘッダーは不要です。操作パラメータにURLパターンのidを追加します。

以上でCohereのConnectorを操作するRESTデータ・ソースは完成です。

Connectorの一覧と操作を行なうページを、フォーム付き対話モード・レポートのページとして作成します。

ページの作成を開始し、対話モード・レポートを選択します。

レポートの名前はConnectors、フォーム・ページを含めるをオンにし、フォーム・ページ名はConnector Detailとします。

データ・ソースとしてRESTデータ・ソースを選択し、RESTデータ・ソースとしてCohere Connector APIを選択します。

次へ進みます。

主キー列1としてID (Varchar2)を選択します。

ページの作成をクリックします。

対話モード・レポートとフォームのページが作成されます。

対話モード・レポートのページはそのままで利用できますが、フォームはレポートの列と作成、更新、削除の操作が受け付けるパラメータが異なるため、調整が必要です。

ページ・デザイナでフォームのページを開きます。

ページ・アイテムとしてP3_ID、P3_URL、P3_NAME、P3_DESCRIPTION、P3_TYPE、P3_TOKENを作成します。P3_IDのタイプは非表示で作成済みですが、他のページ・アイテムは作成されていないものもあります。P3_DESCRIPTIONはタイプをテキスト領域、それ以外はテキスト・フィールドとして作成します。