CohereのCo.ClassifyをOracle APEXから呼び出してみる

Cohereのトライアル・キーを入手して、APIのCo.Classifyを呼び出すアプリケーションを作成してみます。

以下のように動作します。APIの呼び出すことが目的なので、それほど凝った実装は行いません。

Cohereのホーム・ページにアクセスし、TRY NOWをクリックしてトライアルのアカウントを取得します。こちらのアカウントの取得手順については、Cohereから情報を入手してください。

アカウントを作成したら、DASHBORDのAPI Keysを開き、トライアルのAPIキーをコピーします。

APEXに移り、Cohere APIを呼び出す際に使用するWeb資格証明を作成します。

ワークスペース・ユーティリティのWeb資格証明を開きます。

作成をクリックします。

名前はCohere API、静的IDはCOHERE_APIとします。

認証タイプにHTTPヘッダーを選択し、資格証明名、つまりHTTPヘッダー名としてAuthorizationを指定します。

資格証明シークレットはAuthorizationヘッダーの値になります。Bearerで始めて、空白で区切り、CohereのAPIキーを続けて入力します。

URLに対して有効として、以下を入力します。

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

以上で作成をクリックします。

Web資格証明としてCohere APIが作成されます。

CohereのAPIを呼び出すAPEXアプリケーションを作成します。

アプケーション作成ウィザードを起動し、空のアプリケーションを作成します。名前はCohereとします。

アプリケーションの作成を実行します。

アプリケーションが作成されたら、ページの作成を実行します。空白のページを作成し、Cohereが提供するClassifyのAPIの呼び出しを実装します。

空白ページを選択します。

ページ定義の名前はClassifyとします。ページ・モードは標準です。デフォルトでナビゲーションが作成されます。

ページの作成を実行します。

空白のページが作成されます。

Co.Classifyのリクエストは、JSONドキュメントに複数のinputsとexamplesを含みます（リクエストの詳細はAPI ReferenceのBODY PARAMSを参照のこと）。それぞれを保持するためにAPEXコレクションを作成し、対話グリッドで編集します。

inputsとexamplesを保持するAPEXコレクションを、CLASSIFY_INPUTS、CLASSIFY_EXAMPLESとして作成します。

共有コンポーネントのアプリケーション・プロセスを開きます。

アプリケーション・プロセスの一覧画面で作成をクリックし、アプリケーション・プロセスの作成を開始します。

名前はAPEXコレクションの初期化、ポイントとして新規インスタンス(新規セッション)開始時を選択します。

次へ進みます。

コードとして以下を記述します。

	begin
	apex_collection.create_or_truncate_collection('CLASSIFY_INPUTS');
	apex_collection.create_or_truncate_collection('CLASSIFY_EXAMPLES');
	end;

view raw initialize-apex-collection.sql hosted with ❤ by GitHub

次へ進みます。

条件は不要なので、そのままプロセスの作成を実行します。

アプリケーション・プロセスが作成されます。これでセッションの開始時にAPEXコレクションCLASSIFY_INPUTSとCLASSIFY_EXAMPLESが作成されます。

ページ・デザイナで作成した空白のページClassifyを開きます。

対話グリッドのリージョンを作成します。

識別の名前はInputs、タイプは対話グリッドとします。ソースのタイプにSQL問合せを選択し、SQL問合せとして以下のSELECT文を記述します。

select seq_id, c001 from apex_collections where collection_name = 'CLASSIFY_INPUTS'

APEXコレクションでは、列SEQ_IDが一意の値なので、これを主キーとして取り扱います。

列SEQ_IDを選択し、識別のタイプを非表示に変更します。ソースの主キーをオンにします。

列C001を選択し、識別のタイプをテキスト・フィールド、ヘッダーをC001からinputsに変更します。

対話グリッドの属性を開き、編集の有効をオンに切り替えます。

プロセス・ビューを開き、対話グリッドの操作を行うプロセスInputs - 対話グリッド・データの保存を選択します。

設定のターゲット・タイプをPL/SQL Codeに変更し、挿入/更新/削除するPL/SQLコードとして以下を記述します。

	declare
	C_COLLECTION_NAME constant varchar2(20) := 'CLASSIFY_INPUTS';
	begin
	case :APEX$ROW_STATUS
	when 'C' then
	:SEQ_ID := apex_collection.add_member(
	p_collection_name => C_COLLECTION_NAME
	,p_c001 => :C001
	);
	when 'U' then
	apex_collection.update_member(
	p_collection_name => C_COLLECTION_NAME
	,p_c001 => :C001
	,p_seq => :SEQ_ID
	);
	when 'D' then
	apex_collection.delete_member(
	p_collection_name => C_COLLECTION_NAME
	,p_seq => :SEQ_ID
	);
	end case;
	end;

view raw classify-inputs.sql hosted with ❤ by GitHub

失われた更新の防止はオフ、行のロックはNoとします。APEXコレクションは開始しているAPEXセッションでのみ有効で、他のセッションとデータが共有されることはありません。そのため、これらの設定は不要です。

以上でinputsを操作する対話グリッドが出来上がりました。

続いてexamplesを操作する対話グリッドを作成します。対話グリッドinputsを重複させます。

重複させた（コピーした）対話グリッドの識別の名前をexamplesに変更します。

ソースのSQL問合せを以下に変更します。

select seq_id, c001, c002 from apex_collections where collection_name = 'CLASSIFY_EXAMPLES'

列C001を選択し、ヘッダーをtextに変更します。

列C002を選択し、識別のタイプをテキスト・フィールド、ヘッダーをlabelに変更します。

プロセス・ビューを開き、プロセスInputs - 対話グリッド・データの保存を重複させます。

重複（コピー）したプロセスの識別の名前をExamples - 対話グリッド・データの保存に変更します。編集可能リージョンとしてexamplesを選択します。

設定の挿入/更新/削除するPL/SQLコードは、以下の記述に入れ替えます。

	declare
	C_COLLECTION_NAME constant varchar2(20) := 'CLASSIFY_EXAMPLES';
	begin
	case :APEX$ROW_STATUS
	when 'C' then
	:SEQ_ID := apex_collection.add_member(
	p_collection_name => C_COLLECTION_NAME
	,p_c001 => :C001
	,p_c002 => :C002
	);
	when 'U' then
	apex_collection.update_member(
	p_collection_name => C_COLLECTION_NAME
	,p_c001 => :C001
	,p_c002 => :C002
	,p_seq => :SEQ_ID
	);
	when 'D' then
	apex_collection.delete_member(
	p_collection_name => C_COLLECTION_NAME
	,p_seq => :SEQ_ID
	);
	end case;
	end;

view raw classify-examples.sql hosted with ❤ by GitHub

CohereのCo.ClassifyのAPIのリクエストとなるinputs、examplesを扱う対話グリッドは、出来上がりました。

これらのデータからJSONリクエストを作成し、CohereのAPIを呼び出します。

ボタンを作成します。

識別の名前はSUBMIT、ラベルはSubmit、動作のアクションはデフォルトのページの送信とします。

APIのレスポンスを保持するページ・アイテムを作成します。

識別の名前はP2_RESPONSE、タイプとしてテキスト領域を選択します。ラベルはResponseとします。

外観の高さは20行とします。

プロセス・ビューを開き、ボタンSUBMITを押したときに実行されるプロセスを作成します。

識別の名前はCall Co.Classifyとします。タイプとしてコードを実行を選択します。

ソースのPL/SQLコードとして以下を記述します。

	declare
	l_request clob;
	l_blob blob;
	l_response clob;
	begin
	-- co.Classifyへのリクエストを生成する。
	select json_object(
	key 'inputs' value
	(
	select json_arrayagg(c001 order by seq_id) from apex_collections
	where collection_name = 'CLASSIFY_INPUTS'
	)
	,key 'examples' value
	(
	select
	json_arrayagg(
	json_object(
	key 'text' value c001
	,key 'label' value c002
	)
	)
	from apex_collections where collection_name = 'CLASSIFY_EXAMPLES'
	)
	-- モデルは決め打ちで多言語対応を選択している。
	,key 'model' value 'embed-multilingual-v2.0'
	-- 画面上でトークンの削除ができるため、制限を超えている場合はエラーとする。
	,key 'truncate' value 'NONE'
	returning clob)
	into l_request
	from dual;
	-- Cohere Co.Colassifyを呼び出す。
	-- https://docs.cohere.com/reference/classify
	apex_debug.info(l_request);
	apex_web_service.set_request_headers('Content-Type','application/json');
	l_blob := apex_web_service.make_rest_request_b(
	p_url => 'https://api.cohere.ai/v1/classify'
	,p_http_method => 'POST'
	,p_body => l_request
	,p_credential_static_id => 'COHERE_API'
	);
	-- 応答は整形して表示する。
	select json_serialize(l_blob returning clob pretty) into l_response from dual;
	:P2_RESPONSE := l_response;
	end;

view raw call-cohere-co-classify.sql hosted with ❤ by GitHub

サーバー側の条件のボタン押下時にSUBMITを選択します。

以上でAPEXアプリケーションは完成です。

アプリケーションを実行すると、記事の先頭のGIF動画のように動作します。

CohereのAPIにはこの他にCo.Generate、Co.Embed、Co.Tokenize、Co.Detokenize、Co.Detect_language、Co.Summarize、Co.Rerankがあります。

今回作成したAPEXアプリケーションのエクスポートを以下に置きました。

https://github.com/ujnak/apexapps/blob/master/exports/sample-cohere-api.zip

Oracle APEXのアプリケーション作成の参考になれば幸いです。

追記

レスポンスの表示がJSONのまま、というのもいまひとつなので、以下のSQLをソースとした対話モード・レポートを実装してみました。

	select
	jr.id
	,jr."INPUT"
	,jr.prediction
	,jr.confidence
	--,jr.labels
	from json_table(:P2_RESPONSE, '$.classifications[*]'
	columns (
	id varchar2(80) path '$.id'
	,"INPUT" varchar2(100) path '$.input'
	,prediction varchar2(40) path '$.prediction'
	,confidence number path '$.confidence'
	-- ,labels varchar2(100) format json path '$.labels'
	)
	) jr

view raw classify-response.sql hosted with ❤ by GitHub

更新されたアプリの画面は以下になります。

完