AI連携

1. 概要

AI連携機能は、iPLAss から外部のAIサービスを利用する機能です。
以下の機能を提供しています。

AI連携機能

プロンプト
- 外部のAIサービスとチャットリクエストを行います。
データ連携
- 外部のAIサービスが利用するデータを配信します。

本機能を利用するには、以下の設定が必要になります。

設定

サービスプロバイダの設定
メタデータプロンプト、システムプロンプトの設定
メタデータデータ連携の設定

2. サービスプロバイダ

外部のAIサービスを利用するために、外部サービスの接続設定が必要になります。
サービスプロバイダでは、外部AIサービスプロバイダの接続設定を管理します。

プロンプト、データ連携ではここで設定したサービスプロバイダを利用します。

2.1. サービスプロバイダ設定

サービスプロバイダは Service-Config で設定します。
AiIntegrationService の "aiServiceProvider" プロパティに、利用するサービスプロバイダを指定してください。
設定の詳細については、Service-Config AiIntegrationServiceを参照してください。

サービスプロバイダ設定の一例を記載します。

サービスプロバイダ設定例

<!-- AI統合 -->
<service>
    <interface>org.iplass.mtp.impl.ai.AiIntegrationService</interface>
    <class>org.iplass.mtp.impl.ai.AiIntegrationService</class>

    (1)
    <depend>org.iplass.mtp.impl.awsv2.AWSSetting</depend>

    (2)
    <property name="aiServiceProvider" class="org.iplass.mtp.impl.ai.awsv2.AWSSettingAiServiceProviderConfig" additional="true" >
        <property name="name" value="AwsSettingAws" />
    </property>

    (3)
    <property name="aiServiceProvider" class="org.iplass.mtp.impl.ai.awsv2.AWSAiServiceProviderConfigImpl" additional="true" >
        <property name="name" value="Tenant_1_2_OnlyAws" />
        <property name="credentialsProviderFactory" class="org.iplass.mtp.impl.awsv2.DefaultCredentialsProviderFactory" />
        <property name="clientConfig" class="org.iplass.mtp.impl.awsv2.AWSClientConfig">
            <property name="region" value="ap-northeast-1" />
        </property>

        <property name="tenantId" value="1" />
        <property name="tenantId" value="2" />
    </property>
</service>

1	AWSSettingAiServiceProviderConfig で、AWSSetting の設定を利用するので、depend に AWSSetting を指定しています。
2	AWSSettingAiServiceProviderConfig クラスを利用して、AWSSetting の設定を利用するAIサービスプロバイダを設定します。
3	AWSAiServiceProviderConfigImpl クラスを利用して、特定のテナントに対して利用可能なAIサービスプロバイダを設定します。

Know Narrator を利用する場合のサービスプロバイダ設定の一例を記載します。
Know Narrator 用のサービスプロバイダは org.iplass.mtp.impl.ai.knownarrator.KnowNarratorAiServiceProviderConfigImpl クラスを利用して設定します。

サービスプロバイダ設定例（Know Narrator）

<!-- AI統合 -->
<service>
    <interface>org.iplass.mtp.impl.ai.AiIntegrationService</interface>

    <property name="aiServiceProvider" class="org.iplass.mtp.impl.ai.knownarrator.KnowNarratorAiServiceProviderConfigImpl" additional="true">
        <property name="name" value="KnowNarrator" />
        <property name="apiBaseUrl" value="https://your-knownarrator-endpoint" />
        <property name="subscriptionKey" value="YOUR_SUBSCRIPTION_KEY" />
        <property name="userPermissionId" value="YOUR_USER_PERMISSION_ID" />
    </property>
</service>

3. プロンプト

プロンプトでは、AIに対しての指示の設定、指示を行うAIサービスの設定を行います。
プロンプトメタデータは AdminConsole を介して設定します。
メタデータ構成としては、プロンプト設定とプラットフォーム設定があります。

3.1. プロンプト設定

プロンプト設定では、AIに対しての標準的な指示を設定します。
プロンプトおよびシステムプロンプトの連携設定を行います。

プロンプトの設定項目
項目	説明
System Prompt	定義されたシステムプロンプトを参照することができます。 AIリクエスト実行時に、システムプロンプトに設定された内容をプロンプトの定義に共通の内容として利用することができます。システムプロンプトについては、システムプロンプトを参照してください。
Prompt	AIに対する指示プロンプトを設定します。Groovy Template 形式で設定することができます。プロンプトにはプレースホルダーを定義することができます。プレースホルダーは `${placeholder_name}` の形式で定義します。プレースホルダーには、独自に定義するものと予約されているものがあります。独自に定義するものは、項目 Prompt Placeholder で項目を定義してください。予約済プレースホルダーは次の通りです。予約済プレースホルダー `inputText`: ユーザーからの入力テキストを表します。プロンプト例 ## あなたの役割あなたは優秀なアシスタントです。ユーザーからの質問に対して、正確かつ簡潔に答えることが求められます。ユーザーからの質問に対して、必要に応じて、質問の内容を理解するための追加の質問を行うことができます。 ## 質問に答えてください。質問: ${inputText}
Prompt Placeholder	プロンプト実行時に動的に値を設定したい箇所にプレースホルダを設定することができます。グリッド入力項目 Name: プレースホルダーの名前を設定します。使用可能な文字列は、英数字とアンダースコアのみで構成される文字列になります。 Notes: プレースホルダーの説明です。任意入力項目です。 Name に `description` と入力した場合、プロンプトでは `${description}` を利用することができます。プレースホルダーの利用例は、プレースホルダーの利用を参照してください。

3.2. プラットフォーム設定

プラットフォーム設定では、サービスプロバイダが提供可能なAIサービスの種類や詳細を設定します。
利用するサービスプロバイダを選択し、利用するAIサービスを選択してください。

プラットフォーム共通の設定項目は次の通りです。

プラットフォーム共通の設定項目
項目	説明
Provider Name	サービスプロバイダの名前を設定します。選択するプロバイダ名は、本プロンプト利用時に使用します。ドロップダウンリストに表示される内容は、サービスプロバイダで設定した内容になります。
Platform Type	プラットフォームのタイプを設定します。プラットフォームタイプは、サービスプロバイダで利用可能なAIサービスです。 Provider Name で選択したサービスプロバイダによってドロップダウンリストに表示される内容は異なります。また、プラットフォームタイプによって、設定する内容は異なります。

iPLAss では、以下のプラットフォームを提供しています。

サービスプロバイダによるプラットフォーム

AWSプラットフォーム
- Amazon Bedrock サービスを利用することができます。
Know Narratorプラットフォーム
- Know Narrator API を利用することができます。
カスタムプラットフォーム
- 独自に作成したプロンプトを実行することができます。

AWSプラットフォーム

AWSプラットフォームでは Amazon Bedrock の以下のサービスを利用することができます。

AWSで利用可能なプラットフォームタイプ

Bedrock
- Amazon Bedrock サービスのモデルに対してリクエストを行います。
Bedrock - Agent
- AWS上に定義した Amazon Bedrock Agent に対してリクエストを行います。
Bedrock - Flow
- AWS上に定義した Amazon Bedrock Flow サービスに対してリクエストを行います。
Bedrock - Knowledge Base
- AWS上に定義した Amazon Bedrock Knowledge Base を利用したリクエストを行います。

Bedrock

Bedrock Converse API を利用し、Amazon Bedrock サービスで利用可能なモデルに対してリクエストを行うことができます。
Converse API の詳細については、Amazon Bedrock のドキュメントを参照してください。

状態には対応していません。

設定項目は次の通りです。

項目説明

項目	説明
Model ID	Amazon Bedrock サービスのモデルのIDを設定します。設定するモデルのIDは、Converse API に対応しているモデルIDを設定してください。 Converse API に対応しているモデルIDの詳細については、Amazon Bedrock のドキュメントを参照してください。
Guardrail - Guardrail ID	AWS で設定した Amazon Bedrock のガードレールのIDを設定します。ガードレールの設定については Amazon Bedrock のドキュメントを参照してください。
Guardrail - Guardrail Version	AWS で設定した Amazon Bedrock のガードレールのIDに対応するバージョンを設定します。 1 ～のバージョン番号もしくは `DRAFT` を設定します。
Inference Config - Max Tokens	Bedrock 推論パラメータ maxTokens を設定します。数値を設定してください。
Inference Config - Stop Sequences	Bedrock 推論パラメータ stopSequences を設定します。カンマ区切りで複数設定可能です。 `END, STOP` のようにカンマ区切りで複数の停止シーケンスを設定できます。
Inference Config - Temperature	Bedrock 推論パラメータ temperature を設定します。0.0 から 1.0 の範囲の数値を設定してください。
Inference Config - TopP	Bedrock 推論パラメータ topP を設定します。0.0 から 1.0 の範囲の数値を設定してください。
Structured Output Config - Schema Name	構造化されたデータのスキーマの名前を設定します。 Structured Output Config は利用するモデルが対応している必要があります。対応するモデルは Amazon Bedrock のドキュメントを参照してください。
Structured Output Config - Schema Description	構造化されたデータのスキーマの説明を設定します。 Structured Output Config は利用するモデルが対応している必要があります。対応するモデルは Amazon Bedrock のドキュメントを参照してください。
Structured Output Config - Json Schema	AIリクエストを実行した際の応答を構造化されたデータとして受け取るための設定項目です。構造化されたデータのスキーマを Json Schema 形式で設定します。 Structured Output Config は利用するモデルが対応している必要があります。対応するモデルは Amazon Bedrock のドキュメントを参照してください。
Request Before Customize	AIリクエストを実行する前に、リクエストの内容をカスタマイズするための設定項目です。 AdminConsole で設定できない内容を設定する場合に利用します。 Groovy Script 形式でカスタマイズ処理を実装します。カスタマイズするリクエストインスタンスは、`software.amazon.awssdk.services.bedrockruntime.model.ConverseRequest.Builder` クラスのインスタンスになります。

Model ID

Amazon Bedrock サービスのモデルのIDを設定します。
設定するモデルのIDは、Converse API に対応しているモデルIDを設定してください。
Converse API に対応しているモデルIDの詳細については、Amazon Bedrock のドキュメントを参照してください。

Guardrail - Guardrail ID

AWS で設定した Amazon Bedrock のガードレールのIDを設定します。
ガードレールの設定については Amazon Bedrock のドキュメントを参照してください。

Guardrail - Guardrail Version

AWS で設定した Amazon Bedrock のガードレールのIDに対応するバージョンを設定します。
1 ～のバージョン番号もしくは DRAFT を設定します。

Inference Config - Max Tokens

Bedrock 推論パラメータ maxTokens を設定します。数値を設定してください。

Inference Config - Stop Sequences

Bedrock 推論パラメータ stopSequences を設定します。カンマ区切りで複数設定可能です。
END, STOP のようにカンマ区切りで複数の停止シーケンスを設定できます。

Inference Config - Temperature

Bedrock 推論パラメータ temperature を設定します。0.0 から 1.0 の範囲の数値を設定してください。

Inference Config - TopP

Bedrock 推論パラメータ topP を設定します。0.0 から 1.0 の範囲の数値を設定してください。

Structured Output Config - Schema Name

構造化されたデータのスキーマの名前を設定します。
Structured Output Config は利用するモデルが対応している必要があります。対応するモデルは Amazon Bedrock のドキュメントを参照してください。

Structured Output Config - Schema Description

構造化されたデータのスキーマの説明を設定します。
Structured Output Config は利用するモデルが対応している必要があります。対応するモデルは Amazon Bedrock のドキュメントを参照してください。

Structured Output Config - Json Schema

AIリクエストを実行した際の応答を構造化されたデータとして受け取るための設定項目です。
構造化されたデータのスキーマを Json Schema 形式で設定します。
Structured Output Config は利用するモデルが対応している必要があります。対応するモデルは Amazon Bedrock のドキュメントを参照してください。

Request Before Customize

AIリクエストを実行する前に、リクエストの内容をカスタマイズするための設定項目です。
AdminConsole で設定できない内容を設定する場合に利用します。
Groovy Script 形式でカスタマイズ処理を実装します。

カスタマイズするリクエストインスタンスは、software.amazon.awssdk.services.bedrockruntime.model.ConverseRequest.Builder クラスのインスタンスになります。

Bedrock - Agent

Bedrock InvokeAgent API を利用し、Amazon Bedrock Agent で定義したエージェントに対してリクエストを行うことができます。
InvokeAgent API の詳細については、Amazon Bedrock のドキュメントを参照してください。

状態に対応しており、保持する値は以下の通りです。

状態に保存する内容

メモリID
セッションID

設定項目は次の通りです。

項目説明

項目	説明
Agent ID	Amazon Bedrock Agent で定義したエージェントのIDを設定します。
Agent Alias ID	Amazon Bedrock Agent で定義したエージェントのIDに対するエイリアスIDを設定します。
Enable Trace	Amazon Bedrock Agent の実行のトレースを有効にするかどうかを設定します。チェックすることでトレースを有効にすることができます。トレースを有効にした場合、プログラムでトレースイベントをハンドリングして、エージェントの実行の詳細を取得することができます。
Use Memory	Amazon Bedrock Agent の実行でメモリ機能を利用するかどうかを設定します。チェックすることでメモリ機能を利用することができます。メモリ機能を利用する場合、エージェント設定で「メモリ - セッション要約を有効にする」を有効にする必要があります。
Request Before Customize	AIリクエストを実行する前に、リクエストの内容をカスタマイズするための設定項目です。 AdminConsole で設定できない内容を設定する場合に利用します。 Groovy Script 形式でカスタマイズ処理を実装します。カスタマイズするリクエストインスタンスは、`software.amazon.awssdk.services.bedrockagentruntime.model.InvokeAgentRequest.Builder` クラスのインスタンスになります。

Agent ID

Amazon Bedrock Agent で定義したエージェントのIDを設定します。

Agent Alias ID

Amazon Bedrock Agent で定義したエージェントのIDに対するエイリアスIDを設定します。

Enable Trace

Amazon Bedrock Agent の実行のトレースを有効にするかどうかを設定します。チェックすることでトレースを有効にすることができます。
トレースを有効にした場合、プログラムでトレースイベントをハンドリングして、エージェントの実行の詳細を取得することができます。

Use Memory

Amazon Bedrock Agent の実行でメモリ機能を利用するかどうかを設定します。チェックすることでメモリ機能を利用することができます。
メモリ機能を利用する場合、エージェント設定で「メモリ - セッション要約を有効にする」を有効にする必要があります。

Request Before Customize

カスタマイズするリクエストインスタンスは、software.amazon.awssdk.services.bedrockagentruntime.model.InvokeAgentRequest.Builder クラスのインスタンスになります。

Bedrock - Flow

Bedrock InvokeFlow API を利用し、Amazon Bedrock Flow で定義したフローに対してリクエストを行うことができます。
InvokeFlow API の詳細については、Amazon Bedrock のドキュメントを参照してください。

状態に対応しており、保持する値は以下の通りです。

状態に保存する内容

実行ID
フロー完了理由などのフローの実行に関する情報

設定項目は次の通りです。

項目説明

項目	説明
Flow ID	Amazon Bedrock Flow で定義したフローのIDを設定します。
Flow Alias ID	Amazon Bedrock Flow で定義したフローのIDに対するエイリアスIDを設定します。
Enable Trace	Amazon Bedrock Flow の実行のトレースを有効にするかどうかを設定します。チェックすることでトレースを有効にすることができます。トレースを有効にした場合、プログラムでトレースイベントをハンドリングして、フローの実行の詳細を取得することができます。
Request Before Customize	AIリクエストを実行する前に、リクエストの内容をカスタマイズするための設定項目です。 AdminConsole で設定できない内容を設定する場合に利用します。 Groovy Script 形式でカスタマイズ処理を実装します。カスタマイズするリクエストインスタンスは、`software.amazon.awssdk.services.bedrockagentruntime.model.InvokeFlowRequest.Builder` クラスのインスタンスになります。

Flow ID

Amazon Bedrock Flow で定義したフローのIDを設定します。

Flow Alias ID

Amazon Bedrock Flow で定義したフローのIDに対するエイリアスIDを設定します。

Enable Trace

Amazon Bedrock Flow の実行のトレースを有効にするかどうかを設定します。チェックすることでトレースを有効にすることができます。
トレースを有効にした場合、プログラムでトレースイベントをハンドリングして、フローの実行の詳細を取得することができます。

Request Before Customize

カスタマイズするリクエストインスタンスは、software.amazon.awssdk.services.bedrockagentruntime.model.InvokeFlowRequest.Builder クラスのインスタンスになります。

Bedrock - Knowledge Base

Bedrock RetrieveAndGenerate API を利用し、Amazon Bedrock Knowledge Base で定義したナレッジを利用したリクエストを行うことができます。
RetrieveAndGenerate API の詳細については、Amazon Bedrock のドキュメントを参照してください。

状態に対応しており、保持する値は以下の通りです。

状態に保存する内容

セッションID

設定項目は次の通りです。

項目説明

項目	説明
Model ID	Amazon Bedrock サービスのモデルのIDを設定します。設定するモデルのIDは、RetrieveAndGenerate API に対応しているモデルIDを設定してください。 RetrieveAndGenerate API に対応しているモデルIDの詳細については、Amazon Bedrock のドキュメントを参照してください。
Knowledge Base ID	Amazon Bedrock Knowledge Base で定義したナレッジベースIDを設定します。
Guardrail - Guardrail ID	AWS で設定した Amazon Bedrock のガードレールのIDを設定します。ガードレールの設定については Amazon Bedrock のドキュメントを参照してください。
Guardrail - Guardrail Version	AWS で設定した Amazon Bedrock のガードレールのIDに対応するバージョンを設定します。 1 ～のバージョン番号もしくは `DRAFT` を設定します。
Inference Config - Max Tokens	Bedrock 推論パラメータ maxTokens を設定します。数値を設定してください。
Inference Config - Stop Sequences	Bedrock 推論パラメータ stopSequences を設定します。カンマ区切りで複数設定可能です。
Inference Config - Temperature	Bedrock 推論パラメータ temperature を設定します。0.0 から 1.0 の範囲の数値を設定してください。
Inference Config - TopP	Bedrock 推論パラメータ topP を設定します。0.0 から 1.0 の範囲の数値を設定してください。
Request Before Customize	AIリクエストを実行する前に、リクエストの内容をカスタマイズするための設定項目です。 AdminConsole で設定できない内容を設定する場合に利用します。 Groovy Script 形式でカスタマイズ処理を実装します。カスタマイズするリクエストインスタンスは、`software.amazon.awssdk.services.bedrockagentruntime.model.RetrieveAndGenerateRequest.Builder` クラスのインスタンスになります。

Model ID

Amazon Bedrock サービスのモデルのIDを設定します。
設定するモデルのIDは、RetrieveAndGenerate API に対応しているモデルIDを設定してください。
RetrieveAndGenerate API に対応しているモデルIDの詳細については、Amazon Bedrock のドキュメントを参照してください。

Knowledge Base ID

Amazon Bedrock Knowledge Base で定義したナレッジベースIDを設定します。

Guardrail - Guardrail ID

AWS で設定した Amazon Bedrock のガードレールのIDを設定します。
ガードレールの設定については Amazon Bedrock のドキュメントを参照してください。

Guardrail - Guardrail Version

AWS で設定した Amazon Bedrock のガードレールのIDに対応するバージョンを設定します。
1 ～のバージョン番号もしくは DRAFT を設定します。

Inference Config - Max Tokens

Bedrock 推論パラメータ maxTokens を設定します。数値を設定してください。

Inference Config - Stop Sequences

Bedrock 推論パラメータ stopSequences を設定します。カンマ区切りで複数設定可能です。

Inference Config - Temperature

Bedrock 推論パラメータ temperature を設定します。0.0 から 1.0 の範囲の数値を設定してください。

Inference Config - TopP

Bedrock 推論パラメータ topP を設定します。0.0 から 1.0 の範囲の数値を設定してください。

Request Before Customize

カスタマイズするリクエストインスタンスは、software.amazon.awssdk.services.bedrockagentruntime.model.RetrieveAndGenerateRequest.Builder クラスのインスタンスになります。

Know Narratorプラットフォーム

Know Narratorプラットフォームでは、Know Narrator API を利用し、Know Narrator に対してリクエストを行うことができます。
利用するサービスプロバイダには、Know Narrator 用のサービスプロバイダ設定を指定してください。

Know Narratorプラットフォームでは、以下のプラットフォームタイプを利用することができます。

Know Narratorで利用可能なプラットフォームタイプ

Know Narrator Chat
- Know Narrator Chat API を利用し、チャット形式のリクエストを行います。
Know Narrator Search
- Know Narrator Search API を利用し、ナレッジ（データソース）を検索した上でリクエストを行います。

Know Narrator Chat

Know Narrator Chat API を利用し、Know Narrator に対してチャット形式のリクエストを行うことができます。
Know Narrator Chat を利用する場合は、プラットフォームタイプを KNOW_NARRATOR に設定してください。
Know Narrator Chat API の詳細については、Know Narrator のドキュメントを参照してください。

状態に対応しており、保持する値は以下の通りです。

状態に保存する内容

会話ID

会話IDを引き継ぐことで、前回の会話の内容を引き継いだ継続的な会話を行うことができます。
継続した会話を行う場合は、レスポンスの next メソッドを利用して、会話IDを引き継いだ次のリクエストを作成してください。

設定項目は次の通りです。

項目説明

項目	説明
Provider ID	Know Narrator のAIプロバイダリソースIDを設定します。必須項目です。
Model ID	Know Narrator で利用するモデルのIDを設定します。必須項目です。
Temperature	サンプリング温度を設定します。0.0 から 2.0 の範囲の数値を設定してください。任意項目です。
Request Before Customize	AIリクエストを実行する前に、リクエストの内容をカスタマイズするための設定項目です。 AdminConsole で設定できない内容を設定する場合に利用します。 Groovy Script 形式でカスタマイズ処理を実装します。カスタマイズするリクエストインスタンスは、`org.apache.hc.client5.http.entity.mime.MultipartEntityBuilder` クラスのインスタンスになります。

Provider ID

Know Narrator のAIプロバイダリソースIDを設定します。必須項目です。

Model ID

Know Narrator で利用するモデルのIDを設定します。必須項目です。

Temperature

サンプリング温度を設定します。0.0 から 2.0 の範囲の数値を設定してください。任意項目です。

Request Before Customize

カスタマイズするリクエストインスタンスは、org.apache.hc.client5.http.entity.mime.MultipartEntityBuilder クラスのインスタンスになります。

Know Narrator Search

Know Narrator Search API を利用し、登録済みのナレッジ（データソース）を検索した上で回答を生成するリクエストを行うことができます。
Know Narrator Search を利用する場合は、プラットフォームタイプを KNOW_NARRATOR_KNOWLEDGE_CHAT に設定してください。
利用するサービスプロバイダには、Know Narrator 用のサービスプロバイダ設定を指定してください。
Know Narrator Search API の詳細については、Know Narrator のドキュメントを参照してください。

状態に対応しており、保持する値は以下の通りです。

状態に保存する内容

会話ID

設定項目は次の通りです。

項目説明

項目	説明
Deployment Name	Know Narrator で利用するモデルのデプロイメント名を設定します。必須項目です。
Search Mode	ナレッジを検索する際の検索モードを設定します。`keyword`、`hybrid`、`vector`、`hybrid_with_hyde` から選択します。デフォルトは `hybrid` です。任意項目です。
Temperature	サンプリング温度を設定します。0.0 から 2.0 の範囲の数値を設定してください。任意項目です。
Top P	核サンプリング（Top P）の値を設定します。0.0 から 1.0 の範囲の数値を設定してください。任意項目です。
Reasoning Effort	推論の深さを設定します。`low`、`medium`、`high` から選択します。任意項目です。
Request Before Customize	AIリクエストを実行する前に、リクエストの内容をカスタマイズするための設定項目です。 AdminConsole で設定できない内容を設定する場合に利用します。 Groovy Script 形式でカスタマイズ処理を実装します。カスタマイズするリクエストインスタンスは、JSONリクエストボディを表す `java.util.Map<String, Object>` クラスのインスタンスになります。

Deployment Name

Know Narrator で利用するモデルのデプロイメント名を設定します。必須項目です。

Search Mode

ナレッジを検索する際の検索モードを設定します。keyword、hybrid、vector、hybrid_with_hyde から選択します。
デフォルトは hybrid です。任意項目です。

Temperature

サンプリング温度を設定します。0.0 から 2.0 の範囲の数値を設定してください。任意項目です。

Top P

核サンプリング（Top P）の値を設定します。0.0 から 1.0 の範囲の数値を設定してください。任意項目です。

Reasoning Effort

推論の深さを設定します。low、medium、high から選択します。任意項目です。

Request Before Customize

カスタマイズするリクエストインスタンスは、JSONリクエストボディを表す java.util.Map<String, Object> クラスのインスタンスになります。

レスポンスからは、回答テキストに加えて、回答の根拠となった参照ドキュメントの一覧（参照ID、ファイル名、スコア）や、検索結果に関する警告情報を取得することができます。

カスタムプラットフォーム

カスタムプラットフォームでは独自のプロンプトアプリケーションを利用することができます。
カスタムプラットフォームを利用する場合は、プラットフォームタイプを CUSTOM に設定してください。

設定項目は次の通りです。

項目説明

項目	説明
Logic Class Name	プロンプトリクエストを行うクラスの完全修飾クラス名を設定します。設定するクラスは、`org.iplass.mtp.impl.ai.prompt.AiPlatformCustom` インターフェースを実装している必要があります。本クラスのインスタンスは再利用されるため、スレッドセーフである必要があります。リソース開放が必要な場合は、`java.io.Closeable` インターフェースを実装してください。
Value Map	Logic Class Name で指定したクラスのインスタンスを生成する際に、初期値として設定することができます。 Value Map はキーバリュー形式で設定され、キーと値は両方とも文字列で設定します。

Logic Class Name

プロンプトリクエストを行うクラスの完全修飾クラス名を設定します。
設定するクラスは、org.iplass.mtp.impl.ai.prompt.AiPlatformCustom インターフェースを実装している必要があります。
本クラスのインスタンスは再利用されるため、スレッドセーフである必要があります。

リソース開放が必要な場合は、java.io.Closeable インターフェースを実装してください。

Value Map

Logic Class Name で指定したクラスのインスタンスを生成する際に、初期値として設定することができます。
Value Map はキーバリュー形式で設定され、キーと値は両方とも文字列で設定します。

実装例

カスタムプロンプトは、org.iplass.mtp.impl.ai.prompt.AiPlatformCustom インターフェースを実装することで作成できます。
以下は、カスタムプロンプトの実装例です。

実装例

import java.io.Closeable;
import java.io.IOException;
import java.util.Map;

import org.iplass.mtp.ai.prompt.AiPlatformRequest;
import org.iplass.mtp.ai.prompt.AiPlatformResponse;
import org.iplass.mtp.impl.ai.prompt.AiPlatformCustom;
import org.iplass.mtp.impl.ai.prompt.AiPlatformRequestInformation;
import org.iplass.mtp.impl.ai.prompt.MetaAiPrompt.AiPromptRuntime;

public class ExampleAiLogic implements AiPlatformCustom, Closeable {
    private AiPromptRuntime promptRuntime;
    private Map<String, String> valueMap;

    @Override
    public AiPlatformResponse requestPrompt(AiPlatformRequest request, AiPlatformRequestInformation requestInfo) {
        // カスタムプロンプトのリクエスト処理を実装してください。
        return null;
    }

    @Override
    public void setPromptRuntime(AiPromptRuntime promptRuntime) {
        // initialize() メソッドの前に実行されます。
        // AiPromptRuntime が設定されます。
        this.promptRuntime = promptRuntime;
    }

    @Override
    public void setValueMap(Map<String, String> valueMap) {
        // initialize() メソッドの前に実行されます。
        // プラットフォーム設定の Value Map で設定した値が渡されます。
        this.valueMap = valueMap;
    }

    @Override
    public void initialize() {
        // 初期化処理を実装します。
        // promptRuntime や valueMap を使用して初期化を行います。
    }

    @Override
    public void close() throws IOException {
        // 必要な場合は、リソースの解放処理を実装します。
    }
}

3.3. プロンプト利用方法

基本的なプロンプトの利用方法は、プロンプトメタデータの定義名を指定してリクエストを実行します。
プロンプトメタデータの定義名を指定しない場合は、DEFAULT という定義名のプロンプトメタデータを利用します。

プロンプトを経由してAIサービスを利用することで、外部サービスを意識せずにAIサービスを利用することができます。

プロンプトのリクエスト・レスポンスで対応しているデータ種別は、以下の通りです。

対応データ種別

テキスト

対応するデータ種別について、AIサービスで利用するモデルが対応している必要があります。

リクエスト

プロンプトを利用してAIサービスにリクエストを行うには、プロンプトメタデータの定義名を指定してリクエストを作成し、リクエストを実行します。

レスポンス

プロンプトを利用してAIサービスにリクエストを行うと、レスポンスが返却されます。
レスポンスには、AIサービスからの応答テキストや、状態などが含まれます。

応答テキストは JSON などに構造化されている場合があります。
この場合は、レスポンスからテキストを取得し、JSON などの形式でパースして利用してください。

状態

プロンプトでリクエストを実行したら状態を保存します。
状態には、セッションIDなどの継続した会話を行うための情報が含まれています。
状態に対応状況は、外部のAIサービスやプラットフォーム実装によって異なります。

状態を次のリクエストで利用することで、前回のリクエストの内容を引き継いで会話を続ける、などができます。

基本的なプロンプト利用

基本的なプロンプトの利用方法は、以下の例の通りです。

基本的なプロンプト利用例

public class ExamplePrompt {
    /** プロンプトメタデータの定義名 */
    private static final String PROMPT_NAME = "prompt_definition_name";

    /**
     * プロンプトの利用例
     * プロンプト名を指定してプロンプトを利用する例です。
     */
    public String exampleUseSpecificPrompt() {
        var aiManager = ManagerLocator.manager(AiManager.class);

        // 前回のリクエストで保存した状態の読み取り
        var state = loadState();

        // prompt_definition_name という名前のプロンプトメタデータを利用してリクエストを作成する例
        var request = aiManager.createRequest(PROMPT_NAME, state, AiPlatformPayload.text("プロンプトテキスト"));
        // prompt_definition_name という名前のプロンプトメタデータを利用してリクエストを実行する例
        var response = aiManager.request(PROMPT_NAME, request);

        // 次のリクエストで利用できるように状態を保存する
        saveState(response.getState());

        // レスポンステキストの取得
        var responseText = response.getText();
        return responseText;
    }

    /**
     * プロンプトの利用例
     * DEFAULT を指定してプロンプトを利用する例です。
     */
    public String exampleUseDefaultPrompt() {
        var aiManager = ManagerLocator.manager(AiManager.class);

        // 前回のリクエストで保存した状態の読み取り
        var state = loadState();

        // DEFAULT という名前のプロンプトメタデータを利用してリクエストを作成する例
        var request = aiManager.createRequest(state, AiPlatformPayload.text("プロンプトテキスト"));
        // DEFAULT という名前のプロンプトメタデータを利用してリクエストを実行する例
        var response = aiManager.request(request);

        // 次のリクエストで利用できるように状態を保存する
        saveState(response.getState());

        // レスポンステキストの取得
        var responseText = response.getText();
        return responseText;
    }

    /**
     * 状態の読み取り処理
     */
    private AiPlatformState loadState() {
        // 状態の取得はご利用の環境に応じてカスタマイズしてください
        return null;
    }

    /**
     * 状態の保存処理
     */
    private void saveState(AiPlatformState state) {
        // 状態の保存はご利用の環境に応じてカスタマイズしてください
    }
}

プレースホルダーの利用

プロンプトの設定項目で説明した通り、独自のプレースホルダーを用意することができます。
独自のプレースホルダーを設定した場合は、プレースホルダーに対応する値をリクエストの作成時に設定する必要があります。
プレースホルダーの値を設定するには、キー名とそれに対応する値をリクエストに追加する必要があります。

プレースホルダーとして placeholder_name1 と placeholder_name2 を定義した場合の例、
placeholder_name1 と placeholder_name2 キーに対応する値をリクエストに追加する必要があります。

この場合、プロンプトには ${placeholder_name1} と ${placeholder_name2} を利用することができます。

プロンプトでプレースホルダーを利用する例

public class ExamplePrompt {
    (1)
    public String exampleUsePlaceholder() {
        var aiManager = ManagerLocator.manager(AiManager.class);

        (2)
        // プレースホルダーに対応する値を設定する例。 <A> と <B> は等価です。
        var request = aiManager.createRequest(AiPlatformPayload.text("プロンプトテキスト"));
        // <A> 個別にキー・値を設定する場合
        request.putBinding("placeholder_name1", "プレースホルダーの値1");
        request.putBinding("placeholder_name2", "プレースホルダーの値2");
        // <B> プレースホルダーの値をまとめて設定する場合
        request.setBindings(Map.of(
            "placeholder_name1", "プレースホルダーの値1",
            "placeholder_name2", "プレースホルダーの値2"
        ));

        var response = aiManager.request(request);

        // レスポンステキストの取得
        var responseText = response.getText();
        return responseText;
    }
}

1	プレースホルダーとして `placeholder_name1` と `placeholder_name2` を定義した場合の例。
2	`placeholder_name1` と `placeholder_name2` キーに対応する値をリクエストに追加する。

上の例を実行した場合に、プロンプトの定義例と結果例は以下のようになります。

プロンプト定義例

{
    "prompt": "${inputText}",
    "placeholder_name1": "${placeholder_name1}",
    "placeholder_name2": "${placeholder_name2}"
}

AIサービスにリクエストするプロンプト結果例

{
    "prompt": "プロンプトテキスト",
    "placeholder_name1": "プレースホルダーの値1",
    "placeholder_name2": "プレースホルダーの値2"
}

レスポンスから複数のデータ取得

AIリクエストのレスポンスは、テキスト以外のデータ型が含まれることがあります。
レスポンスからテキスト以外のデータを取得するには、対応するメソッドを利用してください。

レスポンスから複数データを取得する例

public class ExamplePrompt {
    public void exampleGetMultipleData() {
        var aiManager = ManagerLocator.manager(AiManager.class);

        // プロンプトのリクエストの作成と実行
        var request = aiManager.createRequest(AiPlatformPayload.text("プロンプトテキスト"));
        var response = aiManager.request(request);

        // ここからレスポンスの情報を取得する例

        // 返却されるデータが事前に判明している場合
        // テキスト
        String text = response.getText();
        // 画像
        List<AiPlatformPayloadImage> payloadImageList = response.getPayloadImage();

        // 返却されるデータが不明な場合
        // すべてのデータ
        List<AiPlatformPayload> payloadList = response.getPayloads();
        // データタイプ別に処理する
        response.acceptPayloads(new PayloadConsumer() {
            @Override
            public void visit(AiPlatformPayloadText text) {
                // テキストの処理
            }

            @Override
            public void visit(AiPlatformPayloadImage image) {
                // 画像の処理
            }
        });
    }
}

4. システムプロンプト

システムプロンプトは、サービスプロバイダに依存しないプロンプトの集まりです。
よく利用する役割や指示などをシステムプロンプトとして定義しておくことを目的とします。

システムプロンプトは、プロンプトから参照して利用します。
また、システムプロンプト同士を参照して利用することもできます。

システムプロンプトは AdminConsole を介して設定します。

4.1. システムプロンプト設定

設定項目は次の通りです。

システムプロンプトの設定項目
項目	説明
System Prompt	システムプロンプトを定義します。プロンプトの定義に共通の内容を設定することができます。
System Prompt Relation	システムプロンプト同士を参照して利用することができます。参照を設定した場合は、定義中のシステムプロンプトに参照しているシステムプロンプトの内容を含めることができます。システムプロンプトが循環的に参照された場合、定義されたプロンプトは１度だけ展開されるようになっています。また、存在しないシステムプロンプトを指定した場合でも、エラーにはならず定義されたプロンプトは展開されないようになっています。（プロンプトが存在しなくなるケースとしては、メタデータのインポートや、定義してあったシステムプロンプトを削除するケースなどが考えられます。）

5. データ連携

データ連携では、外部のサービスプロバイダに対してデータを提供することができます。
連携可能なデータは、データ読み取り元設定で設定するデータ読み取り元から読み取ったデータになります。
データ連携先は、データ連携先の設定で設定します。

データ連携は AdminConsole を介して設定します。
構成としては、データ読み取り元設定とデータ連携先設定があります。

5.1. データ連携の全体設定

全体設定では、データ連携の全体に関する設定を行います。

全体の設定項目
項目	説明
Enabled	このデータ連携設定が有効かどうかを設定します。チェックすることで有効にすることができます。無効のままデータ連携を実行することはできません。
Incremental Update	差分更新を行うかどうかを設定します。チェックすることで差分更新を行うことができます。差分更新を行う場合、前回のデータ連携の実行以降にデータ読み取り元で更新されたデータのみを連携するようになります。差分更新は、データ読み取り元の実装によって対応している必要があります。

5.2. データ読み取り元設定

データ連携する元データに関する設定を行います。
共通設定では、データ読み取り元の種類を設定します。データ読み取り元を決定後に、選択した種類に応じた詳細な設定を行います。

データ読み取り元の共通設定項目
項目	説明
Source Type	データ読み取り元の種類を設定します。

エンティティ

データ読み取り元が、エンティティ設定です。エンティティのデータを連携することができます。
読み取りデータの型は、org.iplass.mtp.entity.GenericEntity です。

差分更新を行う場合は、前回のデータ連携の実行以降に更新されたエンティティを連携するようになります。

エンティティ読み取り元の設定項目
項目	説明
Entity Name	データ連携のデータ読み取り元とするエンティティの名前。

EQL

データ読み取り元をEQLクエリとした設定です。
読み取りデータの型は、Object[] です。

差分更新を行う場合は、前回のデータ連携の実行以降に更新されたEQLのFROM句で指定されたエンティティのデータを連携するようになります。

EQL読み取り元の設定項目
項目	説明
EQL	EQLクエリを設定します。
Column Info	EQLクエリの結果のカラム情報を設定します。 EQLに設定する列としてファンクションやリテラルを設定した場合、その項目に名前を設定することを目的とします。設定項目は以下となります。 Index: EQLのカラムのインデックスを設定します。0から始まる整数で設定します。 Name: インデックスに対応する列のカラム名前を設定します。データ連携先へ連携する際に、このカラム名前を利用することができます。

5.3. データ連携先の設定

データ連携する先に関する設定を行います。
共通設定では、データ連携先の種類を設定します。データ連携先を決定後に、選択した種類に応じた詳細な設定を行います。
データ連携先で受付可能なデータ型は、選択したデータ連携先の種類に依存します。

データ連携先共通の設定項目
項目	説明
Provider Name	サービスプロバイダの名前を設定します。選択するプロバイダ名は、データ連携実行時に使用します。ドロップダウンリストに表示される内容は、サービスプロバイダで設定した内容になります。
Destination Type	データ連携先のタイプを設定します。利用可能なタイプは、サービスプロバイダで対応しているデータ連携先の種類に依存します。 Provider Name で選択したサービスプロバイダによってドロップダウンリストに表示される内容は異なります。また、データ連携先のタイプによって、設定する内容は異なります。
Processor Factory Class Name	プロセッサは読み取り元の情報からデータ連携先が要求するデータの形式に変換する機能です。本設定項目ではプロセッサを生成するための完全修飾クラス名を設定します。クラスは `org.iplass.mtp.impl.ai.dataconnect.AiDataProcessorFactory` インターフェースを実装している必要があります。プロセッサの設定は必須ではありません。設定しない場合はデフォルトのプロセッサが利用されます。詳細については、プロセッサを参照してください。

利用可能なデータ連携先

AWS
- AWSサービスに対してデータを連携します。
カスタム
- 独自に作成した機能を利用して、データを連携します。

AWS

AWS へのデータ連携機能を設定することができます。

JSON to S3

JSON ファイルを S3 にアップロードする機能です。
Amazon Bedrock Knowledge Base のデータソースとして利用することを目的としています。
受け入れ可能なデータ型は Map<String, Object> です。

設定項目は以下の通りです。

項目説明

項目	説明
Output Type	ファイル出力方法を決定します。出力方法 One record to File データ読み取り元のレコード単位でファイルを出力します。 All Records to File データ読み取り元の全レコードをまとめて1ファイルとして出力します。
JSON Write Format	JSON書き込みフォーマットを選択します。利用可能なフォーマットは、 JSON もしくは JSONL です。
Bucket Name	ファイルをアップロードする S3 バケットの名前を設定します。
Prefix	S3 バケット内のオブジェクトキーのプレフィックスを設定します。
Object Key Generate Type	オブジェクトキーの生成方法を設定します。 `Class` を選択した場合は、Class Name を設定してください。 `Script` を選択した場合は、Script を設定してください。
Object Key Generate - Class Name	オブジェクトキーを生成するクラスの完全修飾名を設定します。
Object Key Generate - Script	オブジェクトキーを生成するスクリプトを設定します。

Output Type

ファイル出力方法を決定します。

出力方法

One record to File
- データ読み取り元のレコード単位でファイルを出力します。
All Records to File
- データ読み取り元の全レコードをまとめて1ファイルとして出力します。

JSON Write Format

JSON書き込みフォーマットを選択します。利用可能なフォーマットは、 JSON もしくは JSONL です。

Bucket Name

ファイルをアップロードする S3 バケットの名前を設定します。

Prefix

S3 バケット内のオブジェクトキーのプレフィックスを設定します。

Object Key Generate Type

オブジェクトキーの生成方法を設定します。
Class を選択した場合は、Class Name を設定してください。
Script を選択した場合は、Script を設定してください。

Object Key Generate - Class Name

オブジェクトキーを生成するクラスの完全修飾名を設定します。

Object Key Generate - Script

オブジェクトキーを生成するスクリプトを設定します。

カスタム

独自に作成したデータ連携処理を設定することができます。
設定項目は以下の通りです。

項目説明

項目	説明
Custom Destination Class Name	データ連携処理を実行するクラスの完全修飾名を設定します。クラスは `org.iplass.mtp.impl.ai.dataconnect.AiDataDestination` インターフェースを実装している必要があります。初期化処理が必要な場合は、`org.iplass.mtp.impl.ai.dataconnect.AiDataInitializable` インターフェースを実装してください。終了処理が必要な場合は、`org.iplass.mtp.impl.ai.dataconnect.AiDataCloseable` インターフェースを実装してください。カスタムデータ連携処理を設定する場合は、データ連携先共通の設定項目のProcessor Factory Class Nameを設定する必要があります。

Custom Destination Class Name

データ連携処理を実行するクラスの完全修飾名を設定します。クラスは org.iplass.mtp.impl.ai.dataconnect.AiDataDestination インターフェースを実装している必要があります。
初期化処理が必要な場合は、org.iplass.mtp.impl.ai.dataconnect.AiDataInitializable インターフェースを実装してください。
終了処理が必要な場合は、org.iplass.mtp.impl.ai.dataconnect.AiDataCloseable インターフェースを実装してください。

カスタムデータ連携処理を設定する場合は、データ連携先共通の設定項目のProcessor Factory Class Nameを設定する必要があります。

5.4. プロセッサ

プロセッサは、読み取り元からデータ連携先へのデータ変換を行う機能です。
プロセッサインスタンスは、org.iplass.mtp.impl.ai.dataconnect.AiDataProcessorFactory で設定したクラスによって生成されます。
プロセッサは org.iplass.mtp.impl.ai.dataconnect.AiDataProcessor を実装する必要があります。

標準提供している読み取り元、データ連携先の組み合わせに対しては、デフォルトのプロセッサが用意されています。
ただし、データの変換方法をカスタマイズしたい場合や、独自のデータ連携先を利用する場合は、プロセッサおよびプロセッサファクトリを実装して設定する必要があります。

5.5. データ連携方法

作成したデータ連携を行うには、データ連携メタデータの定義名を指定します。

基本的なデータ連携方法

AiManager から connectData メソッドを呼び出すことで、データ連携を実行できます。
実行結果は、データ連携の実行結果クラスから取得できます。

データ連携の実行例

public class ExampleDataConnect {
    public void connectData() {
        var name = "dataconnect.metadata.name";

        var aiManager = ManagerLocator.manager(AiManager.class);

        // データ連携の実行
        var status = aiManager.connectData(name);

        // 実行ID
        var executionId = status.getExecutionId(); (1)
        var historyOid = status.getHistoryOid(); (2)
    }
}

1	データ連携の実行IDを取得します。実行IDはデータ連携の実行ごとに一意な値となり、履歴の参照やログ確認などに利用できます。
2	データ連携の実行履歴エンティティのOIDを取得します。データ連携の実行履歴エンティティには、データ連携の実行に関する情報が保存されます。

データ連携の実行履歴確認

データ連携の履歴はAIデータ連携履歴エンティティに保存されます。
Admin Console の Tools > EntityExplorer > mtp.ai.dataconnect.DataConnectHistory から確認してください。
履歴には、実行ID、実行開始日時、実行終了日時、実行結果などの情報が保存されます。

実行結果は、execute_state 列の値で確認することができます。

execute_stateの状況
値	説明
RUNNING	データ連携を実行中です。
SUCCEEDED	データ連携が成功しました。
FAILED	データ連携が失敗しました。