ガードレール（Guardrails）

备注

ガードレールは実験的な機能です。API と動作は将来のバージョンで変更される可能性があります。

ガードレールは、LLM の入力と出力を検証し、期待どおりであることを保証するための仕組みです。ガードレールでは、例えば次のようなことができます：

• ユーザー入力が範囲外でないことを確認する
• LLM を呼び出す前に入力が一定の条件を満たすことを保証する（例：プロンプトインジェクション攻撃 への対策）
• 出力形式が正しいことを保証する（例：正しいスキーマを持つ JSON ドキュメントであること）
• LLM の出力がビジネスルールと制約に整合していることを保証する（例：これが会社 X のチャットボットである場合、応答に競合他社 Y への言及が含まれないこと）
• 幻覚（hallucinations）を検出する

これらはあくまで例です。ガードレールではほかにも多くのことができます。

备注

ガードレールは AI Services を使用する場合にのみ利用できます。より高水準の構成要素であり、ChatModel や StreamingChatModel には適用できません。

;

この実装はもともと Quarkus LangChain4j 拡張 で行われ、ここにバックポートされました。

ガードレールの実装

理想的には、ガードレールの実装は 単一責任の原則 に従うべきです。つまり、各ガードレールクラスは 1 つのことだけを検証します。その後、ガードレールをチェーンして複数の事柄を防ぐようにします。

チェーン内のガードレールの順序は重要です。チェーン内で最初に失敗したガードレールが全体の失敗を引き起こします。最も多くの失敗を捕捉するガードレールをチェーンの前半に置き、失敗頻度が非常に低いより特化したガードレールをチェーンの後半に置くようにしてください。

検証するテキストを 書き換える ガードレールは、チェーン内のどこにでも宣言できます。書き換えを呼び出し側に届けるために、最後に宣言する必要はありません。詳細はチェーン内の書き換えガードレールを参照してください。

また、ガードレール自体が他のサービスを呼び出したり、他の LLM 対話を起動したりできることにも留意してください。こうしたガードレールに実行コストや金銭的コストが伴う場合は、それを考慮に入れてください。より「高価」なガードレールはチェーンの末尾に置くとよいでしょう。

备注

用語 高価（expensive） は、実行に時間がかかること、または金銭的コストが伴うことを意味します。

チェーン内の書き換えガードレール

ガードレールは、受け取ったテキストを受け入れるか拒否するだけではありません。success with rewrite（successWith(...)）を返すことで、チェーン内の残りのガードレール、そして最終的に呼び出し側が目にするテキストを置き換えます。マスキングや伏せ字処理、フォーマット修正を行うガードレールは、この仕組みで動作します。

書き換えは、次のルールに従ってチェーンに沿って合成されます。これらは、操作が同期でも非同期/ストリーミングでも、入力ガードレールと出力ガードレールの両方に適用されます：

• 書き換えガードレールの後に続く各ガードレールは、元のテキストではなく 書き換えられた テキストを検証します。
• 書き換えは、後続の単純な success() があっても維持されます。success() は 「受け取ったテキストは許容できる」 という意味であり、後続のガードレールが受け取るテキストはすでに書き換え済みのテキストなので、それを承認しても元のテキストには戻りません。
• 後の書き換えは、前の書き換えを上書きします。書き換えはチェーンの順序で合成されるため、最後に書き換えたガードレールが優先されます。
• 出力ガードレールでは、success with result（successWithResult(Object)）で付与された結果オブジェクトが現在のテキストとともに保持されます。後続の単純な success() はそれを保持し、後続の結果オブジェクトはそれを置き換え、後続のテキストのみの書き換え（successWith(String)）はそれを破棄します。
• その結果、書き換えガードレールは、書き換えを呼び出し側に返すためにチェーンの最後である必要はありません。

备注

出力ガードレールチェーン内のいずれかのガードレールが出力を書き換えた後は、後続の fatal with retry または fatal with reprompt の結果は許可されません。LLM が、すでに書き換えられたテキストに対して新しい応答を生成するよう求められることになるためです。この場合、実行は OutputGuardrailException で中断され、そのメッセージには Retry or reprompt is not allowed after a rewritten output が含まれます。

入力ガードレール

入力ガードレールは、LLM が呼び出される前に実行される関数です。入力ガードレールが失敗すると、LLM の呼び出しが防止されます。入力ガードレールは LLM 呼び出し直前の最後のステップです。RAG 操作が行われた 後に 呼び出されます。

入力ガードレールの実装

入力ガードレールは InputGuardrail インターフェースを実装することで実現します。InputGuardrail インターフェースには validate メソッドの 2 つのバリアントがあり、少なくとも 1 つを実装する必要があります：

InputGuardrailResult validate(UserMessage userMessage);
InputGuardrailResult validate(InputGuardrailRequest params);

最初のバリアントは、単純なガードレール、またはガードレールが UserMessage へのアクセスだけを必要とする場合に使用します。

2 番目のバリアントは、チャットメモリ/履歴、ユーザーメッセージテンプレート、拡張（augmentation）結果、テンプレートに渡された変数など、より多くの情報を必要とする複雑なガードレール向けです。詳細は InputGuardrailRequest を参照してください。

できることの例：

• 拡張結果に十分なドキュメントがあることを確認する
• ユーザーが同じ質問を何度もしていないことを保証する
• 潜在的なプロンプトインジェクション攻撃を緩和する
• コミュニティの Prompt Repetition モジュールで、対象となる単一テキスト入力を書き換える

入力ガードレールは、操作が同期でも非同期/ストリーミングでも使用できます。

入力ガードレールの結果

入力ガードレールは次の結果を取り得ます。InputGuardrail インターフェースには、これらの結果を提供するヘルパーメソッドがあります：

結果	InputGuardrail 上のヘルパーメソッド	説明
success	success()	- 入力は有効です。 - チェーン内の次のガードレールが実行されます。 - 最後のガードレールが通過すれば LLM が呼び出されます。 - チェーン内の前のガードレールがユーザーメッセージを書き換えた場合、success は 書き換えられた ユーザーメッセージが有効であることを意味します。書き換えは維持されます。チェーン内の書き換えガードレールを参照してください。
success with alternate result	successWith(String)	- success と似ていますが、次のステップ（チェーン内の次のガードレールまたは LLM の呼び出し）に進む前にユーザーメッセージが変更されます。 - ガードレールによる書き換えは、チェーン内の前のガードレールによる書き換えを上書きします。
failure	failure(String) または failure(String, Throwable)	- 入力は無効ですが、考えられるすべての検証問題を蓄積するため、チェーン内の後続ガードレールは引き続き実行されます。 - LLM は呼び出されません。 - Throwable が渡された場合、呼び出し側は InputGuardrailException をキャッチして cause を確認できます。ここに渡された Throwable になります。
fatal	fatal(String) または fatal(String, Throwable)	- 入力は無効であり、InputGuardrailException で実行が中断されます。 - LLM は呼び出されません。 - Throwable が渡された場合、呼び出し側は InputGuardrailException をキャッチして cause を確認できます。ここに渡された Throwable になります。

入力ガードレールの宣言

入力ガードレールの宣言方法はいくつかあり、優先順位の高い順に次のとおりです：

1. AiServices ビルダーに直接設定された InputGuardrail 実装のクラス名またはインスタンス。
2. 個々の AI Service メソッドに付けられた @InputGuardrails アノテーション。
3. AI Service クラスに付けられた @InputGuardrails アノテーション。 宣言方法に関係なく、入力ガードレールは常にリストに現れる順序で実行されます。リスト内のいずれかのガードレールによって書き換えられたユーザーメッセージは、それに続くガードレールから見え、後続のガードレールが再度書き換えない限り、LLM にも渡されます。

AiServices ビルダー

AiServices ビルダーに直接設定された InputGuardrail 実装のクラス名またはインスタンスが最も高い優先順位を持ちます。つまり、他の方法で宣言されていても、ビルダーに直接宣言されたものが使用されます。

public interface Assistant {
    String chat(String question);
    String doSomethingElse(String question);
}

var assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .inputGuardrailClasses(FirstInputGuardrail.class, SecondInputGuardrail.class)
    .build();

または

public interface Assistant {
    String chat(String question);
    String doSomethingElse(String question);
}

var assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .inputGuardrails(new FirstInputGuardrail(), new SecondInputGuardrail())
    .build();

信息

プロンプト反復（prompt repetition）を使って対象となる単一テキスト入力を書き換える、既製の実験的入力ガードレールが必要な場合は、コミュニティの Prompt Repetition モジュールを参照してください。

最初のシナリオでは、InputGuardrail を実装するクラスが渡されます。これらのクラスの新しいインスタンスはリフレクションを使って動的に作成されます。

信息

クラスをインスタンスに変換する方法はカスタマイズできます。例えば、依存性注入を使うフレームワーク（Quarkus や Spring など）は、拡張ポイント を使って、毎回リフレクションで新しいインスタンスを作成するのではなく、クラスインスタンスの管理方法に基づいてインスタンスを提供できます。

個々の AI Service メソッドへのアノテーション

個々の AI Service メソッドに付けられた @InputGuardrails アノテーション が次に高い優先順位を持ちます。

public interface Assistant {
    @InputGuardrails({ FirstInputGuardrail.class, SecondInputGuardrail.class })
    String chat(String question);
    
    String doSomethingElse(String question);
}

var assistant = AiServices.create(Assistant.class, chatModel);

この例では、chat メソッドだけがガードレールを持ちます。

• chat メソッドでは、まず FirstInputGuardrail が呼び出されます。
• それが成功した場合にのみ LLM が呼び出されます。
• FirstInputGuardrail が fatal 結果にならなかった場合にのみ、SecondInputGuardrail が呼び出されます。
• FirstInputGuardrail または SecondInputGuardrail のいずれもユーザーメッセージを書き換えられます。
• FirstInputGuardrail がユーザーメッセージを書き換えた場合、SecondInputGuardrail は新しいユーザーメッセージを入力として受け取ります。

doSomethingElse メソッドにはガードレールがありません。

AI Service クラスへのアノテーション

AI Service クラスに付けられた @InputGuardrails アノテーション が最も低い優先順位を持ちます。

@InputGuardrails({ FirstInputGuardrail.class, SecondInputGuardrail.class })
public interface Assistant {
    String chat(String question);
    String doSomethingElse(String question);
}

var assistant = AiServices.create(Assistant.class, chatModel);

この例では、chat と doSomethingElse の両メソッドがガードレールを持ちます。

• 前の例と同様に、まず FirstInputGuardrail が呼び出されます。
• それが成功した場合にのみ LLM が呼び出されます。
• FirstInputGuardrail が fatal 結果にならなかった場合にのみ、SecondInputGuardrail が呼び出されます。
• FirstInputGuardrail または SecondInputGuardrail のいずれもユーザーメッセージを書き換えられます。
• FirstInputGuardrail がユーザーメッセージを書き換えた場合、SecondInputGuardrail は新しいユーザーメッセージを入力として受け取ります。

入力ガードレールのユニットテスト

langchain4j-test モジュールには、AssertJ に基づくユニットテスト用ユーティリティがあります。

Maven

<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-test</artifactId>
  <scope>test</scope>
</dependency>

Gradle (Groovy)

testImplementation 'dev.langchain4j:langchain4j-test'

Gradle (Kotlin)

testImplementation("dev.langchain4j:langchain4j-test")

依存関係を追加したら、次のような検証を行えます：

import static dev.langchain4j.test.guardrail.GuardrailAssertions.assertThat;

import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.guardrail.GuardrailResult.Result;

class Tests { 
    MyInputGuardrail inputGuardrail = new MyInputGuardrail();
    
    @Test 
    void test() {
        var userMessage = UserMessage.from("Some user message");
        var result = inputGuardrail.validate(userMessage);
        
        // These are just some examples of what you can do
        assertThat(result)
                .isSuccessful()
                .hasResult(Result.FATAL)
                .hasFailures()
                .hasSingleFailureWithMessage("Prompt injection detected")
                .assertSingleFailureSatisfied(failure -> assertThat(failure)...)
                .withFailures().....
    }
}

信息

詳細は GuardrailAssertions および InputGuardrailResultAssert クラスを参照してください。

標準提供の入力ガードレール

一般的なユースケース向けに、LangChain4j が入力ガードレールの実装をいくつか提供しています：

ガードレールクラス	説明
MessageModeratorInputGuardrail	ModerationModel を使ってユーザーメッセージを検証し、有害・不適切・ポリシー違反の可能性のあるコンテンツを検出する入力ガードレールです。 - ヘイトスピーチ、暴力、自傷、性的コンテンツ、またはモデレーションモデルが定義する他のカテゴリについて受信メッセージを確認します。 - メッセージがフラグ付けされた場合、検証は fatal 結果で失敗し、メッセージの以降の処理を防ぎます。 - LLM に送る前にユーザー入力がコンテンツポリシーに準拠していることを保証するのに役立ちます。
PatternBasedPromptInjectionGuardrail	OWASP LLM01 由来の正規表現を使ってプロンプトインジェクション試行を検出する、パターンベースの入力ガードレールです。 - 指示の上書き、ロールハイジャック、ジェイルブレイク、システムプロンプト漏洩、区切り文字インジェクション、エンコードされたペイロードをカバーします。 - 外部依存ゼロでサブミリ秒のレイテンシがあり、LLM ベースの分類器の前に置くガードレールチェーンの最初（最も安価な）ゲートとして適しています。 - サブクラスでドメイン固有のパターンを追加し、失敗メッセージをカスタマイズできます。
DecisionModelInputGuardrail	決定モデルでユーザーメッセージをチェックする入力ガードレールです。 - 各チェックは「はい/いいえ」の質問で、「はい」はそのメッセージを拒否しなければならないことを意味します。例：「このメッセージはアシスタントの指示を上書きしようとしていますか？」「このメッセージは銀行業務以外のことについてですか？」 - すべてのチェックは 1 回の呼び出しで回答されます。いずれかのチェックがしきい値に達すると、メッセージは fatal 結果で拒否されます。

出力ガードレール

出力ガードレールは、LLM が出力を生成したあとに実行される関数です。出力ガードレールの失敗は、応答を改善するための再試行（retry）や再プロンプト（reprompt）といったより高度なシナリオを可能にします。関数/ツール呼び出しを含む他のすべての操作が完了した 後に 呼び出されます。

出力ガードレールの実装

入力ガードレールと同様に、出力ガードレールは OutputGuardrail インターフェースを実装することで実現します。OutputGuardrail インターフェースには validate メソッドの 2 つのバリアントがあり、少なくとも 1 つを実装する必要があります：

OutputGuardrailResult validate(AiMessage responseFromLLM);
OutputGuardrailResult validate(OutputGuardrailRequest params);

最初のバリアントは、単純なガードレール、またはガードレールが結果の AiMessage へのアクセスだけを必要とする場合に使用します。

2 番目のバリアントは、チャット応答全体、チャットメモリ/履歴、ユーザーメッセージテンプレート、テンプレートに渡された変数、あるいは応答を生成するためにモデルに送信されたリクエスト（chatRequest()：すべてのツール呼び出しとツール結果を含むツール呼び出しループの最後のリクエスト、または再プロンプト後は再プロンプトされた呼び出しのリクエスト。たとえば AI Service の外でガードレールを実行する場合などは null になることがあります）など、より多くの情報を必要とする複雑なガードレール向けです。詳細は OutputGuardrailRequest を参照してください。

できることの例：

• 出力形式が正しいことを保証する（例：正しいスキーマを持つ JSON ドキュメントであること）
• LLM の幻覚を検出する
• LLM 応答に特定の情報が含まれていることを検証する

出力ガードレールの結果

出力ガードレールは次の結果を取り得ます。OutputGuardrail インターフェースには、これらの結果を提供するヘルパーメソッドがあります：

結果	OutputGuardrail 上のヘルパーメソッド	説明
success	success()	- 出力は有効です。 - チェーン内の次のガードレールが実行されます。最後のガードレールが通過すれば、出力が呼び出し側に返されます。 - チェーン内の前のガードレールが出力を書き換えた場合、success は 書き換えられた 出力が有効であることを意味します。書き換えと、それに付与された結果オブジェクトは維持されます。チェーン内の書き換えガードレールを参照してください。
success with rewrite	successWith(String) または successWith(String, Object)	- success と似ていますが、出力は元の形式では無効であり、有効になるよう書き換えられています。 - 書き換えられた出力に対して次のガードレールが実行されます。最後のガードレールが通過すれば、出力が呼び出し側に返されます。 - ガードレールによる書き換えは、チェーン内の前のガードレールによる書き換えを上書きします。 - successWith(String, Object) を使うと、結果オブジェクトは、それが導出された書き換え後のテキストとともに渡されます。そのため、後続のガードレールがテキストのみを書き換えた場合（successWith(String)）、結果オブジェクトはもはや現在のテキストに対応しないため、その結果オブジェクトは置き換えられて破棄されます。後続の単純な success() はそれを破棄しません。
success with result	successWithResult(Object)	- 出力は有効であり、書き換えられ ません。付与された結果オブジェクトは、チェーン内の残りのガードレールが通過した時点で呼び出し側に返されます。 - 結果オブジェクトが出力の書き換えから導出されたものでない場合（例：出力をデシリアライズした形式）は、successWith(String, Object) の代わりにこちらを使用してください。 - success with rewrite と異なり、出力は書き換えられたとみなされないため、後続のガードレールは引き続き fatal with retry や fatal with reprompt を使用できます。
failure	failure(String) または failure(String, Throwable)	- 出力は無効ですが、考えられるすべての検証問題を蓄積するため、チェーン内の後続ガードレールは引き続き実行されます。 - 検証失敗は OutputGuardrailException としてユーザーに返されます。
fatal	fatal(String) または fatal(String, Throwable)	出力は無効であり、呼び出し側に投げられる OutputGuardrailException で実行が中断されます。
fatal with retry	retry(String) または retry(String, Throwable)	- fatal と似ていますが、元の呼び出しと同じプロンプトとチャット履歴で LLM が再度呼び出されます。 - 設定可能な再試行回数 のあとも失敗が続く場合、呼び出し側に投げられる OutputGuardrailException で実行が中断されます。 - 再試行後にガードレールが通過した場合、ガードレールのチェーン全体が最初から再実行されます。
fatal with reprompt	reprompt(String, String) または reprompt(String, Throwable, String)	- fatal with retry と似ていますが、ガードレールが提供する新しいプロンプトで LLM が再度呼び出されます。 - この場合、ガードレールは前のユーザーメッセージに追加するメッセージを提供し、新しいユーザーメッセージと元のチャット履歴で LLM に新しいリクエストを送ります。 - 設定可能な再試行回数 のあとも失敗が続く場合、呼び出し側に投げられる OutputGuardrailException で実行が中断されます。 - 再プロンプト後にガードレールが通過した場合、ガードレールのチェーン全体が最初から再実行されます。

再試行または再プロンプトでは、AI Service にチャットメモリがあるかどうかにかかわらず、元の呼び出しの会話（システムメッセージ、ユーザーメッセージ、すべてのツール呼び出しと結果、および拒否された応答）が再送信されます。チャットメモリがない場合、会話はその呼び出しの間だけ保持されます。

出力ガードレールの宣言

出力ガードレールの宣言方法はいくつかあり、優先順位の高い順に次のとおりです：

1. AiServices ビルダーに直接設定された OutputGuardrail 実装のクラス名またはインスタンス。
2. 個々の AI Service メソッドに付けられた @OutputGuardrails アノテーション。
3. AI Service クラスに付けられた @OutputGuardrails アノテーション。

宣言方法に関係なく、出力ガードレールは常にリストに現れる順序で実行されます。リスト内のいずれかのガードレールによって書き換えられた出力は、それに続くガードレールから見え、後続のガードレールが再度書き換えない限り、呼び出し側にも返されます。

AiServices ビルダー

AiServices ビルダーに直接設定された OutputGuardrail 実装のクラス名またはインスタンスが最も高い優先順位を持ちます。つまり、他の方法で宣言されていても、ビルダーに宣言されたものが使用されます。

public interface Assistant {
    String chat(String question);
    String doSomethingElse(String question);
}

var assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .outputGuardrailClasses(FirstOutputGuardrail.class, SecondOutputGuardrail.class)
    .build();

または

public interface Assistant {
    String chat(String question);
    String doSomethingElse(String question);
}

var assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .outputGuardrails(new FirstOutputGuardrail(), new SecondOutputGuardrail())
    .build();

最初のシナリオでは、OutputGuardrail を実装するクラスが渡されます。これらのクラスの新しいインスタンスはリフレクションを使って動的に作成されます。

信息

クラスをインスタンスに変換する方法はカスタマイズできます。例えば、依存性注入を使うフレームワーク（Quarkus や Spring など）は、拡張ポイント を使って、毎回リフレクションで新しいインスタンスを作成するのではなく、クラスインスタンスの管理方法に基づいてインスタンスを提供できます。

個々の AI Service メソッドへのアノテーション

個々の AI Service メソッドに付けられた @OutputGuardrails アノテーション が次に高い優先順位を持ちます。

public interface Assistant {
    @OutputGuardrails({ FirstOutputGuardrail.class, SecondOutputGuardrail.class })
    String chat(String question);
    
    String doSomethingElse(String question);
}

var assistant = AiServices.create(Assistant.class, chatModel);

この例では、chat メソッドだけがガードレールを持ちます。

• chat メソッドでは、まず FirstOutputGuardrail が呼び出されます。
• それが成功した場合にのみ結果が呼び出し側に返されます。FirstOutputGuardrail が fatal、fatal with retry、または fatal with reprompt 結果にならなかった場合にのみ、SecondOutputGuardrail が呼び出されます。
• SecondOutputGuardrail は FirstOutputGuardrail の出力を受け取ります。
• SecondOutputGuardrail が再試行または再プロンプトのあとに成功した場合、FirstOutputGuardrail と SecondOutputGuardrail の両方が再実行されます。

doSomethingElse メソッドにはガードレールがありません。

AI Service クラスへのアノテーション

AI Service クラスに付けられた @OutputGuardrails アノテーション が最も低い優先順位を持ちます。

@OutputGuardrails({ FirstOutputGuardrail.class, SecondOutputGuardrail.class })
public interface Assistant {
    String chat(String question);
    String doSomethingElse(String question);
}

var assistant = AiServices.create(Assistant.class, chatModel);

この例では、chat と doSomethingElse の両メソッドがガードレールを持ちます。

• 前の例と同様に、まず FirstOutputGuardrail が呼び出されます。
• それが成功した場合にのみ結果が呼び出し側に返されます。FirstOutputGuardrail が fatal、fatal with retry、または fatal with reprompt 結果にならなかった場合にのみ、SecondOutputGuardrail が呼び出されます。
• SecondOutputGuardrail は FirstOutputGuardrail の出力を受け取ります。
• SecondOutputGuardrail が再試行または再プロンプトのあとに成功した場合、FirstOutputGuardrail と SecondOutputGuardrail の両方が再実行されます。

設定

出力ガードレールには、次の追加設定を指定できます：

設定	説明
maxRetries	- 再試行または再プロンプトを行う際の、出力ガードレールの最大再試行回数。 - デフォルトは 2。 - 再試行を無効にするには 0 に設定します。

個々の AI Service メソッドへのアノテーション

public interface MethodLevelAssistant {
    @OutputGuardrails(
            value = { FirstOutputGuardrail.class, SecondOutputGuardrail.class },
            maxRetries = 10
    )
    String chat(String question);
}

var assistant = AiServices.create(MethodLevelAssistant.class, chatModel);

AI Service クラスへのアノテーション

@OutputGuardrails(
        value = { FirstOutputGuardrail.class, SecondOutputGuardrail.class },
        maxRetries = 10
)
public interface ClassLevelAssistant {
    String chat(String question);
}

var assistant = AiServices.create(ClassLevelAssistant.class, chatModel);

AiServices ビルダー

public interface Assistant {
    String chat(String message);
}

var outputGuardrailsConfig = OutputGuardrailsConfig.builder()
        .maxRetries(10)
        .build();

var assistant = AiServices.builder(Assistant.class)
        .chatModel(chatModel)
        .outputGuardrailsConfig(outputGuardrailsConfig)
        .outputGuardrailClasss(FirstOutputGuardrail.class, SecondOutputGuardrail.class)
        .build();

ストリーミング応答での出力ガードレール

出力ガードレールは、ストリーミング応答を伴う操作でも機能します：

public interface StreamingAssistant {
    @OutputGuardrails({ FirstOutputGuardrail.class, SecondOutputGuardrail.class })
    TokenStream streamingChat(String message);
}

このシナリオでは、ストリーム全体が完了したとき、より具体的には TokenStream.onCompleteResponse が呼び出されたときに、出力ガードレールが実行されます。onPartialResponse はバッファリングされ、ガードレールが成功したあとに再生されます。

チェーン内の retry または reprompt が最終的に成功した場合、チェーン全体が 同期的に 再実行されます。各ガードレールは元の順序で 1 つずつ再実行されます。チェーンが完了すると、結果が TokenStream.onCompleteResponse に渡されます。

標準提供の出力ガードレール

一般的なユースケース向けに、LangChain4j が出力ガードレールの実装をいくつか提供しています：

ガードレールクラス	説明
JsonExtractorOutputGuardrail	応答が JSON から特定の型のオブジェクトへ正常にデシリアライズできるかどうかを確認する出力ガードレールです。 - Jackson ObjectMapper を使ってオブジェクトのデシリアライズを試みます。 - 応答を期待されるオブジェクト型にデシリアライズできない場合、LLM に再プロンプトします。 - 応答がすでにクリーンな JSON の場合は、デシリアライズされたオブジェクトを付与した単純な success として渡されるため、チェーン後続のガードレールは引き続き再プロンプトできます。JSON を周囲のテキストから抽出する必要があった場合、出力は抽出された JSON に書き換えられます。 - そのまま使用することも、拡張してカスタマイズすることもできます（動作をカスタマイズするためにオーバーライド可能な protected メソッドがいくつかあります）。
DecisionModelOutputGuardrail	決定モデルでモデルの応答をチェックする出力ガードレールです。 - 各チェックは「はい/いいえ」の質問で、「はい」はその応答を拒否しなければならないことを意味します。例：「この応答は個人データを開示していますか？」決定モデルは、応答を生成するためにモデルに送信されたメッセージ（システムメッセージ、ツール呼び出しとツール結果、およびそのために取得されたコンテンツを含むユーザーメッセージ）も受け取ります。決定モデルを参照してください。 - 拒否された応答は fatal 結果で失敗するか、設定されている場合はモデルが再プロンプトされます。

出力ガードレールのユニットテスト

langchain4j-test モジュールには、AssertJ に基づくユニットテスト用ユーティリティがあります。

Maven

<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-test</artifactId>
  <scope>test</scope>
</dependency>

Gradle (Groovy)

testImplementation 'dev.langchain4j:langchain4j-test'

Gradle (Kotlin)

testImplementation("dev.langchain4j:langchain4j-test")

依存関係を追加したら、次のような検証を行えます：

import static dev.langchain4j.test.guardrail.GuardrailAssertions.assertThat;

import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.guardrail.GuardrailResult.Result;

class Tests { 
    MyOutputGuardrail outputGuardrail = new MyOutputGuardrail();
    
    @Test 
    void test() {
        var aiMessage = AiMessage.from("Some output");
        var result = outputGuardrail.validate(aiMessage);
        
        // These are just some examples of what you can do
        assertThat(result)
                .isSuccessful()
                .hasResult(Result.FATAL)
                .hasFailures()
                .hasSingleFailureWithMessage("Hallucination detected!")
                .hasSingleFailureWithMessageAndReprompt("Hallucination detected!", "Please LLM don't hallucinate!")
                .assertSingleFailureSatisfied(failure -> assertThat(failure)...)
                .withFailures().....
    }
}

信息

詳細は GuardrailAssertions および OutputGuardrailResultAssert クラスを参照してください。

备注

I/O を行うガードレールは validateAsync(...) を実装できます。これにより、AI Service をノンブロッキングモードで使用する際にスレッドをブロックしません。ツールを考慮した再プロンプトを含む入力ガードレールと出力ガードレールは、非同期モードおよびリアクティブモードでサポートされています。 ノンブロッキングとリアクティブを参照してください。

組み合わせ

入力ガードレールと出力ガードレールは、好きなように組み合わせて使えます！

public class MyObjectJsonOutputGuardrail extends JsonExtractorOutputGuardrail<MyObject> {
    public MyObjectJsonOutputGuardrail() {
        super(MyObject.class);
    }
}

@InputGuardrails({ FirstInputGuardrail.class, SecondInputGuardrail.class })
@OutputGuardrails(value = SomeOutputGuardrail.class, maxRetries = 5)
public interface Assistant {
    String chat(String message);
    
    @InputGuardrails(PatternBasedPromptInjectionGuardrail.class)
    @OutputGuardrails(MyObjectJsonOutputGuardrail.class)
    MyObject chatAndReturnJson(String message);
}

var outputGuardrailsConfig = OutputGuardrailsConfig.builder()
        .maxRetries(10)
        .build();

var assistant = AiServices.builder(Assistant.class)
        .chatModel(chatModel)
        .inputGuardrails(new AnotherInputGuardrail())
        .outputGuardrailsConfig(outputGuardrailsConfig)
        .build();

この例では、AiServices ビルダー上で設定されているため、Assistant のすべてのメソッドが単一の入力ガードレール AnotherInputGuardrail を持ちます。さらに、設定も AiServices ビルダー上で設定されているため、すべての出力ガードレールの maxRetries 値は 10 になります。

chat メソッドは単一の出力ガードレール SomeOutputGuardrail を持ち、maxRetries 値は 10 です。

chatAndReturnJson メソッドは単一の出力ガードレール MyObjectJsonOutputGuardrail を持ち、maxRetries 値は 10 です。

拡張ポイント

ガードレールシステムは、他の下流フレームワーク（Quarkus や Spring Boot など）で拡張・再利用できるよう、組み合わせ可能な形で構築されています。このセクションでは、提供されている拡張ポイントまたは「フック」の一部を説明します。

これらの拡張ポイントはすべて Java Service Provider Interface（Java SPI） を利用します。

拡張ポイントインターフェース	目的
ClassInstanceFactory	クラスのインスタンスを提供します。 - インスタンスの作成/取得を他の手段に委譲することを意図しています。 - 提供されない場合、デフォルトコンストラクタを使ってリフレクションでインスタンスを作成します。 - 他のフレームワーク（Quarkus や Spring など）は、独自の bean コンテナを使ってクラスのインスタンスを提供する場合があります。それらのフレームワークが実装を提供します。 - Quarkus の実装は CDIClassInstanceFactory のようなものになる可能性があります - Spring の実装は ApplicationContextClassInstanceFactory のようなものになる可能性があります
ClassMetadataProviderFactory	クラスメタデータへのアクセスを提供します。 - AiService インターフェース上のメソッドをスキャンし、@InputGuardrails/@OutputGuardrails アノテーションを見つけて処理するために使用されます。 - 他の実装が見つからない場合のデフォルト実装は ReflectionBasedClassMetadataProviderFactory で、リフレクションを使ってクラスメタデータを提供します。
GuardrailServiceBuilderFactory	GuardrailService インスタンスを構築するためのビルダーインスタンスを提供します。GuardrailService インスタンスの構築方法をカスタマイズする必要がある場合、アプリケーションまたはフレームワークがこれを実装します。
InputGuardrailsConfigBuilderFactory	- デフォルトの InputGuardrailsConfigBuilder をオーバーライドおよび/または拡張するための SPI - 他のフレームワークが、入力ガードレール用の追加設定を持つ独自の実装を提供する場合があります。 - 他のフレームワークが別の仕組み（例：プロパティファイル）経由で入力ガードレール設定を駆動することも可能にします。
OutputGuardrailsConfigBuilderFactory	- デフォルトの OutputGuardrailsConfigBuilder をオーバーライドおよび/または拡張するための SPI - 他のフレームワークが、出力ガードレール用の追加設定を持つ独自の実装を提供する場合があります。 - 他のフレームワークが別の仕組み（例：プロパティファイル）経由で出力ガードレール設定を駆動することも可能にします。
InputGuardrailExecutorBuilderFactory	- デフォルトの InputGuardrailExecutorBuilder（InputGuardrailExecutor インスタンスの構築を担当）をオーバーライドおよび/または拡張するための SPI。
OutputGuardrailExecutorBuilderFactory	- デフォルトの OutputGuardrailExecutorBuilder（OutputGuardrailExecutor インスタンスの構築を担当）をオーバーライドおよび/または拡張するための SPI。