跳到主要内容

可観測性

AI サービスの可観測性​

备注

AI サービスの可観測性は実験的な機能です。その API と動作は将来のバージョンで変更される可能性があります。

AI サービスの可観測性メカニズムにより、ユーザーは AiService の呼び出し中に何が起こっているかを追跡できます。 1 つの呼び出しに複数の LLM 呼び出しが含まれる場合があり、そのいずれかが成功または失敗する可能性があります。 AI サービスの可観測性により、ユーザーは呼び出しの完全なシーケンスとその結果を追跡できます。

备注

AI サービスの可観測性機能は、AI サービス を使用する場合にのみ利用可能です。これらは、ChatModel や StreamingChatModel には適用できない上位レベルの構成要素です。

この実装は元々 Quarkus LangChain4j extension に実装されており、ここにバックポートされました。

イベントの種類​

イベントの各タイプには一意の識別子があり、これを使用して複数の呼び出し間でイベントを関連付けることができます。 各タイプのイベントには、イベント内にカプセル化された情報が含まれています。 InvocationContext。

現在、次のタイプのイベントが利用可能です。

イベント名説明
AiServiceStartedEventLLM 呼び出しが開始されたときに呼び出されます。
AiServiceRequestIssuedEventLLM へのリクエストが送信される直前に呼び出されます。行われたリクエストの詳細が含まれます。ツールが存在する場合や、出力ガードレールが LLM に再プロンプトする場合、これは 1 回の AiService 呼び出し中に複数回呼び出されることがあるので注意が必要です。

システムメッセージやユーザーメッセージなどの情報が含まれます。
AiServiceResponseReceivedEventLLM からの応答を受信したときに呼び出されます。LLM 応答と対応するリクエストが含まれます。ツールが存在する場合や、出力ガードレールが LLM に再プロンプトする場合、これは 1 回の AiService 呼び出し中に複数回呼び出されることがあるので注意が必要です。

システムメッセージやユーザーメッセージなどの情報が含まれます。

すべての呼び出しがこのイベントを受け取るわけではありません。呼び出しが失敗した場合は、代わりに AiServiceErrorEvent を受け取り、キャンセルされた場合は AiServiceCancelledEvent を受け取ります。
AiServiceErrorEventLLM による呼び出しが失敗したときに発生します。障害の原因としては、ネットワーク障害、AiService の利用不可、入出力ガードレールによるリクエストのブロック、またはその他のさまざまな理由が考えられます。

発生した障害に関する情報が含まれています。
AiServiceInvocationSummaryEventAiService 呼び出しごとに 1 回、その AiServiceCompletedEvent、AiServiceErrorEvent、または AiServiceCancelledEvent の後に呼び出されます。

その呼び出し中に発火したすべてのイベントが、発火した順序で含まれるため、呼び出し全体を 1 か所で確認できます。これには、その呼び出しから(たとえばツールから)呼び出された AI Service の AiServiceInvocationSummaryEvent も含まれます。詳細は呼び出し全体のリッスンを参照してください。
AiServiceCompletedEventLLM 呼び出しが正常に完了すると呼び出されます。

すべての呼び出しがこのイベントを受け取るわけではありません。呼び出しが失敗した場合は、代わりに AiServiceErrorEvent を受け取り、キャンセルされた場合は AiServiceCancelledEvent を受け取ります。

呼び出しの結果に関する情報が含まれます。
AiServiceCancelledEvent呼び出しが完了する前にキャンセルされたときに呼び出されます。返された CompletableFuture または Flow.Publisher のサブスクリプションがキャンセルされた場合、またはコンテキストを受け取る TokenStream コールバック(onPartialResponseWithContext など)から StreamingHandle.cancel() が呼び出された場合です(ストリーミングのキャンセルを参照)。これはキャンセルが要求されたことを意味します。モデルプロバイダーやツールは、すでに実行中だった処理を完了する可能性があります。キャンセルされた呼び出しは、AiServiceCompletedEvent も AiServiceErrorEvent も受け取りません。キャンセルされたリクエストについてトークン使用量は報告されませんが、プロバイダーが課金する場合があります。実験的機能。
ToolExecutedEventツールの呼び出しが完了すると呼び出されます。これは、1 回の LLM 呼び出し内で複数回呼び出されることがあるので注意が必要です。

ツールのリクエストと結果、およびツールの実行が失敗したかどうか(isError()。イベントを作成した統合がこれを報告しない場合は UnsupportedOperationException をスローします。AiServices で作成された AI Service は常に報告しますが、JSON シリアライザーのようにイベントをリフレクションで読み取るコードは、報告しない統合からのイベントで失敗します)に関する情報が含まれます。

ツールエラーによって AI Service の呼び出しが失敗した場合(たとえば ToolExecutionErrorHandler.failInvocation() を使用した場合)にも、isError() が true を返す状態で発火します。この場合、結果はエラーテキストであり、LLM には送信されず、その後に AiServiceErrorEvent が続きます。
ToolCompensatedEventすでに完了したツールが、その後のやり取りのキャンセルまたは失敗によって補償されたときに呼び出されます。実験的機能。ノンブロッキング AI Service モードによって発行されます。

ツールのリクエスト、その結果、および補償の理由が含まれます。
RetrievalAugmentedEventRAG(contentRetriever(...) または retrievalAugmentor(...) で設定)を使用する AI Service の呼び出しごとに 1 回、ユーザーメッセージに追加するコンテンツが取得された後に呼び出されます。何も取得されなかった場合も呼び出されます。実験的機能。

取得に使用されたユーザーメッセージと、取得されたコンテンツ(Result<...> を返すメソッドがソースとして返すものと同じコンテンツ)が含まれます。各コンテンツリトリーバーの呼び出しを、受け取ったクエリとともに観測するには、ContentRetrieverListener を使用してください。
InputGuardrailExecutedEventinput guardrail 検証が実行されたときに呼び出されます。これらのイベントの 1 つは、ガードレールの呼び出しごとに発生します。

個々の入力ガードレールへの入力、その出力 (つまり、成功か失敗か)、および実行期間に関する情報が含まれます。
OutputGuardrailExecutedEventoutput guardrail 検証が実行されたときに呼び出されます。これらのイベントの 1 つは、ガードレールの呼び出しごとに発生します。

個々の出力ガードレールへの入力、その出力 (つまり、成功か、失敗か、再試行か、再プロンプトか)、および実行期間に関する情報が含まれます。

実行された AI Service の呼び出しは、必ず AiServiceCompletedEvent、AiServiceErrorEvent、AiServiceCancelledEvent のいずれか 1 つで終了します。すでに完了した呼び出しをキャンセルしても、イベントは発火しません。(TokenStream の呼び出しは、start() が呼び出されたときにのみ実行され、終了します。)呼び出しがキャンセルされた時点ですでに実行中だった処理のイベント(たとえば ToolExecutedEvent)は、AiServiceCancelledEvent の後に到着することがあります。

イベントをリッスンする​

それぞれの イベントの種類 には、イベントを受信するために実装できる独自のリスナーがあります。聞きたいイベントを選択できます。

イベントをリッスンするには、リッスンしたいリスナー インターフェイスを実装する独自のクラスを作成します。使用可能なリスナー インターフェイスは次のとおりです。

リスナー名イベント
AiServiceStartedListenerAiServiceStartedEvent
AiServiceRequestIssuedListenerAiServiceRequestIssuedEvent
AiServiceResponseReceivedListenerAiServiceResponseReceivedEvent
AiServiceErrorListenerAiServiceErrorEvent
AiServiceInvocationSummaryListenerAiServiceInvocationSummaryEvent
AiServiceCompletedListenerAiServiceCompletedEvent
AiServiceCancelledListenerAiServiceCancelledEvent
ToolExecutedEventListenerToolExecutedEvent
ToolCompensatedEventListenerToolCompensatedEvent
RetrievalAugmentedListenerRetrievalAugmentedEvent
InputGuardrailExecutedListenerInputGuardrailExecutedEvent
OutputGuardrailExecutedListenerOutputGuardrailExecutedEvent

リスナーを定義したら、AI サービス を作成するときにリスナーを登録します。 AiServices クラス には、さまざまな registerListener メソッドのバリアントがあります。

たとえば、次のようにして AiServiceCompletedEvent のリスナーを作成して登録できます。

import java.time.Instant;
import java.util.List;
import java.util.Optional;
import java.util.UUID;

import dev.langchain4j.observability.api.AiServiceListenerRegistrar;
import dev.langchain4j.observability.api.event.AiServiceCompletedEvent;
import dev.langchain4j.observability.api.listener.AiServiceCompletedListener;
import dev.langchain4j.invocation.InvocationContext;

public class MyAiServiceCompletedListener implements AiServiceCompletedListener {
@Override
public void onEvent(AiServiceCompletedEvent event) {
InvocationContext invocationContext = event.invocationContext();
Optional<Object> result = event.result();

// The invocationId will be the same for all events related to the same AI Service invocation
UUID invocationId = invocationContext.invocationId();
// If this AI Service was called from inside another AI Service invocation (for example from one of its tools or guardrails):
// the invocationId of that outer invocation; otherwise null (see "Linking nested invocations" below)
UUID parentInvocationId = invocationContext.parentInvocationId();
String aiServiceInterfaceName = invocationContext.interfaceName();
String aiServiceMethodName = invocationContext.methodName();
List<Object> aiServiceMethodArgs = invocationContext.methodArguments();
Object chatMemoryId = invocationContext.chatMemoryId();
Instant eventTimestamp = invocationContext.timestamp();

// Do something with the data
}
}

// When creating your AI Service
MyAiServiceCompletedListener myListener = new MyAiServiceCompletedListener();

var myService = AiServices.builder(MyAiService.class)
.chatModel(chatModel) // Could also be .streamingChatModel(...)
.registerListener(myListener)
.build();

呼び出し全体のリッスン​

個々のイベントをそれぞれリッスンする代わりに、AiServiceInvocationSummaryListener を登録して、呼び出しが終了した時点で 1 つの AiServiceInvocationSummaryEvent を受け取ることができます。その events() メソッドは、呼び出しで発火したすべてのイベント(つまり同じ invocationId を持つすべてのイベント)を、発火した順序で返します。最初は AiServiceStartedEvent で、最後は AiServiceCompletedEvent、AiServiceErrorEvent、または AiServiceCancelledEvent です。RetrievalAugmentedEvent や ToolExecutedEvent など、その呼び出しの他のイベントも含まれます。呼び出しが他の AI Service を(たとえばツールから)呼び出す場合は、それらの AiServiceInvocationSummaryEvent も含まれ、それらは独自の invocationId を持ちます(後述)。

var myService = AiServices.builder(MyAiService.class)
.chatModel(chatModel)
.registerListener((AiServiceInvocationSummaryListener) summary -> {
UUID invocationId = summary.invocationContext().invocationId();
List<AiServiceEvent> events = summary.events();

// Do something with the data
})
.build();

留意すべき点がいくつかあります:

  • 呼び出しの開始時に AiServiceInvocationSummaryListener が登録されている場合、またはイベントが収集されている呼び出しにネストされている場合(後述)、その呼び出しのイベントが収集されます。それ以外の場合はイベントは保持されないため、サマリーリスナーを使用しなければオーバーヘッドはありません。
  • 非同期またはストリーミングの呼び出しがキャンセルされた場合、AiServiceCancelledEvent で終了し、AiServiceInvocationSummaryEvent にはキャンセルまでに発火したイベントが含まれ、AiServiceCancelledEvent で終わります。
  • 呼び出しが終了した後にその呼び出しに対して発火したイベント(たとえば、キャンセルされた呼び出しがロールバックされた後に発火する ToolCompensatedEvent)は含まれません。
  • 別の AI Service 呼び出しの実行中に(たとえばツール内から)呼び出された AI Service は、独自の invocationId を持つ別個の呼び出しです。InvocationContext.parentInvocationId() によって外側の呼び出しにリンクされている場合(ネストされた呼び出しのリンクを参照)、外側のサマリーにネストされます:
    • 内側の呼び出しが終了すると、その AiServiceInvocationSummaryEvent が外側の呼び出しの events() に追加されます。内側の呼び出しのイベントはそのネストされたサマリーにのみ含まれ、そのサマリー自体がさらに深い呼び出しのサマリーを含むことがあります。
    • 外側の AI Service だけがサマリーリスナーを持っている場合でも、収集されます。その場合、イベントは外側の呼び出しが終了するまでメモリに保持されます。
    • そのサマリーは、内側の AI Service 自身のリスナーにも引き続き配信されます。そのため、両方の AI Service に登録されたリスナーは、内側のサマリーを 2 回(単独で 1 回、外側のサマリーの中で 1 回)受け取ります。トークン、コスト、ツール呼び出しを合算する際は、各呼び出しを 1 回だけ数えてください。たとえば、events() に含まれる AiServiceInvocationSummaryEvent をスキップします。
    • 外側の AI Service のサマリーリスナーは、内側の呼び出しのプロンプト、応答、ツール結果も受け取ります。ログ出力やエクスポートする内容をフィルタリングまたはマスキングしている場合は、ネストされたサマリーにも同じ処理を行ってください。
    • チャットモデル、チャットメモリ、またはその ChatMemoryStore から呼び出された内側の呼び出しはネストされます。外側の呼び出しが AiServiceStartedEvent を発火する前に終了する内側の呼び出し(ChatMemoryProvider、システムメッセージまたはユーザーメッセージのプロバイダー、システムメッセージトランスフォーマーから呼び出されたもの)、または外側の呼び出しが終了した後に終了するものは、リンクされますがネストされません。
  • TokenStream を返す AI Service メソッドでは、呼び出しはメソッドが呼び出された時点で開始されますが、start() でストリームが開始されて初めて終了します。開始されない TokenStream に対して収集されたイベントは解放されないため、作成したストリームは必ず開始してください。start() が設定エラー(たとえばエラーハンドラーの欠落)で失敗した場合、呼び出しは AiServiceErrorEvent で終了します。設定を修正してから再度 start() を呼び出すと、新しい呼び出しが開始されます。
  • AI Service メソッドが返すリアクティブストリームへの各サブスクリプションと、TokenStream.start() の各呼び出しは、独自の invocationId を持つ別個の呼び出しであり、複数のサブスクリプションが同時に実行される場合も含めて、それぞれ独自の AiServiceInvocationSummaryEvent が生成されます。同じ TokenStream の 2 回目の start() は、AI Service メソッドが呼び出されたときに取得されたコンテンツ、入力ガードレール、準備されたメッセージを再利用するため、そのサマリーには RetrievalAugmentedEvent も入力ガードレールのイベントも含まれません。再実行されるのはモデル呼び出し、ツール、出力ガードレールのみです。
  • AiServiceInvocationSummaryEvent はレジストラ自身によって発火されます。AiServiceListenerRegistrar.fireEvent 経由で発火しようとすると、IllegalArgumentException が発生します。

ネストされた呼び出しのリンク​

AI Service は、別の AI Service の内部(たとえばそのツールの 1 つ)から呼び出されることがよくあります。 2 つの呼び出しはそれぞれ別個の呼び出しであり、独自の invocationId と独自のイベントを持ちます。 それらをリンクするために、内側の呼び出しの InvocationContext には parentInvocationId()(実験的機能)があります。 これは外側の呼び出しの invocationId で、存在しない場合は null です。

interface Assistant {
String chat(String message);
}

interface Translator {
String translate(String text);
}

class TranslationTools {

private final Translator translator;

TranslationTools(Translator translator) {
this.translator = translator;
}

@Tool("Translates a text to English")
String translateToEnglish(String text) {
return translator.translate(text); // the inner invocation
}
}

// Collects the summaries of inner invocations, grouped by the invocation that called them
Map<UUID, List<AiServiceInvocationSummaryEvent>> innerByOuter = new ConcurrentHashMap<>();
AiServiceInvocationSummaryListener listener = summary -> {
UUID parentInvocationId = summary.invocationContext().parentInvocationId();
if (parentInvocationId != null) {
innerByOuter.computeIfAbsent(parentInvocationId, id -> new CopyOnWriteArrayList<>()).add(summary);
}
};

Translator translator = AiServices.builder(Translator.class)
.chatModel(chatModel)
.registerListener(listener)
.build();

Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(chatModel)
.tools(new TranslationTools(translator))
.registerListener(listener)
.build();

内側の呼び出しは、外側の AI Service の次のいずれかの部分から呼び出された場合に、外側の呼び出しにリンクされます:

  • ツール(tools、toolProvider)、ツールエラーハンドラー(toolExecutionErrorHandler、toolArgumentsErrorHandler)、または幻覚ツール名の戦略(hallucinatedToolNameStrategy)
  • 入力または出力ガードレール(inputGuardrails、outputGuardrails)
  • 検索オーグメンターのコンポーネント(retrievalAugmentor、contentRetriever)。たとえば、クエリトランスフォーマー、クエリルーター、コンテンツリトリーバーなど
  • システムメッセージまたはユーザーメッセージのプロバイダー(systemMessageProvider、userMessageProvider)、またはシステムメッセージトランスフォーマー(systemMessageTransformer)
  • チャットメモリ(chatMemory、chatMemoryProvider)。その ChatMemoryStore も含みます。たとえば、AI Service で古いメッセージを要約するチャットメモリなど
  • モデレーションモデル(moderationModel)
  • chatRequestTransformer
  • チャットモデルまたはストリーミングチャットモデル自体(chatModel、streamingChatModel)。たとえば、独自の ChatModel 実装など

parentInvocationId() が null になるのは次の場合です:

  • 自分のコードから呼び出す AI Service の場合。たとえば、リスナー、TokenStream ハンドラー、返されたストリームのサブスクライバー、返された CompletableFuture のコールバックの内部から呼び出す場合です。外側の呼び出しがまだ実行中であっても同様です。
  • 上記のいずれかの部分で、自分のコードが別のスレッドで内側の AI Service を呼び出す場合。たとえば CompletableFuture.supplyAsync(..., executor) を使う場合です。LangChain4j 自身が別のスレッドに移す処理(たとえば並行実行されるツール)はリンクされたままです。そのため、このリンクはベストエフォートと考えてください。

サマリーだけが必要な場合は、外側の AI Service にサマリーリスナーを設定すれば十分です。リンクされた内側の呼び出しのサマリーは、その events() にネストされます(呼び出し全体のリッスンを参照)。

Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(chatModel)
.tools(new TranslationTools(translator))
.registerListener((AiServiceInvocationSummaryListener) summary -> {
List<AiServiceInvocationSummaryEvent> innerSummaries = summary.events().stream()
.filter(AiServiceInvocationSummaryEvent.class::isInstance)
.map(AiServiceInvocationSummaryEvent.class::cast)
.toList();
})
.build();

制限事項:

  • LangChain4j が提供する AI Service 実装によって設定されます。その実装を置き換えるフレームワーク(たとえば AiServicesFactory 経由)は、サポートを追加するまで null を返します。AiServices.builder(...) を通じて作成する AI Service でも同様です。
  • エージェンティックワークフロー(シーケンス、並列、ループ、条件)またはスーパーバイザーによって実行されるエージェントは、まだリンクされません。別のエージェントのツールから呼び出されるエージェントはリンクされます。

呼び出しごとのモデル呼び出しのグループ化​

モデルやその他のコンポーネントのリスナーは、呼び出しを行った AI Service 呼び出しの invocationId を受け取ります。 そのため、どのモデル呼び出しがどの呼び出しに属するかを確認できます。 これらのリスナーのコンテキストには invocationId()(実験的機能)があります:

  • ChatModelListener(ChatModelRequestContext、ChatModelResponseContext、ChatModelErrorContext)
  • EmbeddingModelListener、ModerationModelListener、DecisionModelListener、ScoringModelListener
  • EmbeddingStoreListener と ContentRetrieverListener

invocationId() は、呼び出しが行われた AI Service 呼び出しの id です。チャットモデルの場合は、 ChatRequestOptions.invocationId(...) で渡された id があればそれ、なければ呼び出しを行う呼び出し(AI Service 自身の チャットモデルへの呼び出し(ツール実行後の呼び出しを含む)、およびそのツール、ガードレール、検索、チャットメモリ、 モデレーションなどが行う呼び出し)、それ以外の場合は null です。たとえば、自分のコードやリスナーからモデルを直接呼び出す場合です。 これは AI Service 呼び出しの invocationId であり、モデル呼び出しの id ではありません。 parentInvocationId()(前述)と組み合わせると、モデル呼び出しを含む呼び出しのツリーを構築できます。

// Counts the chat model calls of each AI Service invocation
Map<UUID, AtomicInteger> modelCallsByInvocation = new ConcurrentHashMap<>();

ChatModelListener listener = new ChatModelListener() {

@Override
public void onRequest(ChatModelRequestContext requestContext) {
UUID invocationId = requestContext.invocationId();
if (invocationId != null) { // null when the model is called outside of an AI Service invocation
modelCallsByInvocation.computeIfAbsent(invocationId, id -> new AtomicInteger()).incrementAndGet();
}
}
};

ChatModel chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName(GPT_4_O_MINI)
.listeners(List.of(listener))
.build();

Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(chatModel)
.build();

AI Service は把握しているがモデルは把握していないもの(たとえば会話のメモリ id)にモデル呼び出しをリンクするには、 モデルリスナーと AI Service リスナーを組み合わせます。AI Service イベントの InvocationContext には、 invocationId() と chatMemoryId() の両方があります。

interface PersonalAssistant {

String chat(@MemoryId String userId, @UserMessage String message);
}

// Adds up the token usage of each conversation
Map<UUID, Object> memoryIdByInvocation = new ConcurrentHashMap<>();
Map<Object, Integer> totalTokensByMemoryId = new ConcurrentHashMap<>();

ChatModelListener tokenCounter = new ChatModelListener() {

@Override
public void onResponse(ChatModelResponseContext responseContext) {
Object memoryId = responseContext.invocationId() == null
? null
: memoryIdByInvocation.get(responseContext.invocationId());
TokenUsage tokenUsage = responseContext.chatResponse().tokenUsage();
if (memoryId != null && tokenUsage != null && tokenUsage.totalTokenCount() != null) {
totalTokensByMemoryId.merge(memoryId, tokenUsage.totalTokenCount(), Integer::sum);
}
}
};

ChatModel chatModel = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName(GPT_4_O_MINI)
.listeners(List.of(tokenCounter))
.build();

PersonalAssistant assistant = AiServices.builder(PersonalAssistant.class)
.chatModel(chatModel)
.chatMemoryProvider(memoryId -> MessageWindowChatMemory.withMaxMessages(10))
.registerListeners(
(AiServiceStartedListener) event -> memoryIdByInvocation.put(
event.invocationContext().invocationId(), event.invocationContext().chatMemoryId()),
(AiServiceCompletedListener) event -> memoryIdByInvocation.remove(event.invocationContext().invocationId()),
(AiServiceErrorListener) event -> memoryIdByInvocation.remove(event.invocationContext().invocationId()),
(AiServiceCancelledListener) event -> memoryIdByInvocation.remove(event.invocationContext().invocationId()))
.build();

呼び出し id は、AI Service 自身のチャットモデルへの呼び出し(ツール実行後の呼び出しを含む)と、 上記の AI Service の各部分(ツール、ガードレール、検索、チャットメモリ、モデレーションなど)が行う呼び出しを、 parentInvocationId() と同じ方法でカバーします。

id を自分で渡す必要があるのは、コードがチャットモデルの呼び出しを別のスレッドに移す場合 (たとえばツール内で CompletableFuture.supplyAsync(..., executor) を使う場合)、または自分のチャットモデル呼び出しを ある呼び出しの下にグループ化したい場合のみです。これはチャットモデルでのみ、ChatRequestOptions で可能です。他のモデル、埋め込みストア、 コンテンツリトリーバーでは、コードが別のスレッドに移した呼び出しには invocationId がありません。ツールは、その呼び出しの InvocationContext をパラメーターとして受け取り、ガードレールはそのリクエストから取得します (request.requestParams().invocationContext()):

class ResearchTools {

private final ChatModel chatModel;
private final ExecutorService executor;

ResearchTools(ChatModel chatModel, ExecutorService executor) {
this.chatModel = chatModel;
this.executor = executor;
}

@Tool("Summarizes a text")
String summarize(String text, InvocationContext invocationContext) {
ChatRequest chatRequest = ChatRequest.builder()
.messages(UserMessage.from("Summarize: " + text))
.build();
ChatRequestOptions options = ChatRequestOptions.builder()
.invocationId(invocationContext.invocationId())
.build();
return CompletableFuture.supplyAsync(() -> chatModel.chat(chatRequest, options), executor)
.join()
.aiMessage()
.text();
}
}

独自の実装で AI Service を実行するフレームワーク(たとえば AiServicesFactory 経由)は、id を設定しない場合や、 モデルの呼び出し方によっては一部の呼び出しにのみ設定する場合があります。

独自のイベントとリスナーの作成​

AI サービスの可観測性機能は、拡張できるように設計されています。独自のイベントを作成したい場合は、AiServiceEvent インターフェースを実装して独自のイベントを定義することで作成できます。

次に、AiServiceListener インターフェースを実装して独自のイベント リスナーを作成します。

イベントとリスナーを取得したら、AiServiceListenerRegistrar のインスタンスを取得/管理し、fireEvent(event) メソッドを呼び出してイベントを起動する必要があります。

イベントが発生すると、組み込みイベントの場合と同様に、リスナーを作成してリスナーを登録できます。

拡張ポイント​

AiServiceListenerRegistrarFactory を実装し、Java Service Provider Interface (Java SPI) に登録することで、独自のカスタム AiServiceListenerRegistrar を作成することもできます。

これは、リスナーの登録/登録解除方法やイベントの発生方法を管理する場合に便利です。

チャットモデルの可観測性​

ChatModel および StreamingChatModel の一部の実装 (「可観測性」列を参照)では、ChatModelListener を構成して、次のようなイベントをリッスンできます。

  • LLM へのリクエスト
  • LLM からの応答
  • エラー

これらのイベントには、OpenTelemetry Generative AI Semantic Conventions で説明されているように、さまざまな属性が含まれます。たとえば:

  • リクエスト:
    • メッセージ
    • モデル
    • 温度
    • トップP
    • 最大トークン数
    • ツール
    • 応答フォーマット
    • など
  • 応答:
    • アシスタントメッセージ
    • ID
    • モデル
    • トークンの使用法
    • 終了理由
    • など

ChatModelListener の使用例を次に示します。

ChatModelListener listener = new ChatModelListener() {

@Override
public void onRequest(ChatModelRequestContext requestContext) {
ChatRequest chatRequest = requestContext.chatRequest();

List<ChatMessage> messages = chatRequest.messages();
System.out.println(messages);

ChatRequestParameters parameters = chatRequest.parameters();
System.out.println(parameters.modelName());
System.out.println(parameters.temperature());
System.out.println(parameters.topP());
System.out.println(parameters.topK());
System.out.println(parameters.frequencyPenalty());
System.out.println(parameters.presencePenalty());
System.out.println(parameters.maxOutputTokens());
System.out.println(parameters.stopSequences());
System.out.println(parameters.toolSpecifications());
System.out.println(parameters.toolChoice());
System.out.println(parameters.responseFormat());

if (parameters instanceof OpenAiChatRequestParameters openAiParameters) {
System.out.println(openAiParameters.maxCompletionTokens());
System.out.println(openAiParameters.logitBias());
System.out.println(openAiParameters.parallelToolCalls());
System.out.println(openAiParameters.seed());
System.out.println(openAiParameters.user());
System.out.println(openAiParameters.store());
System.out.println(openAiParameters.metadata());
System.out.println(openAiParameters.serviceTier());
System.out.println(openAiParameters.reasoningEffort());
}

System.out.println(requestContext.modelProvider());

Map<Object, Object> attributes = requestContext.attributes();
attributes.put("my-attribute", "my-value");
}

@Override
public void onResponse(ChatModelResponseContext responseContext) {
ChatResponse chatResponse = responseContext.chatResponse();

AiMessage aiMessage = chatResponse.aiMessage();
System.out.println(aiMessage);

ChatResponseMetadata metadata = chatResponse.metadata();
System.out.println(metadata.id());
System.out.println(metadata.modelName());
System.out.println(metadata.finishReason());

if (metadata instanceof OpenAiChatResponseMetadata openAiMetadata) {
System.out.println(openAiMetadata.created());
System.out.println(openAiMetadata.serviceTier());
System.out.println(openAiMetadata.systemFingerprint());
}

TokenUsage tokenUsage = metadata.tokenUsage();
System.out.println(tokenUsage.inputTokenCount());
System.out.println(tokenUsage.outputTokenCount());
System.out.println(tokenUsage.totalTokenCount());
if (tokenUsage instanceof OpenAiTokenUsage openAiTokenUsage) {
System.out.println(openAiTokenUsage.inputTokensDetails().cachedTokens());
System.out.println(openAiTokenUsage.outputTokensDetails().reasoningTokens());
}

ChatRequest chatRequest = responseContext.chatRequest();
System.out.println(chatRequest);

System.out.println(responseContext.modelProvider());

Map<Object, Object> attributes = responseContext.attributes();
System.out.println(attributes.get("my-attribute"));
}

@Override
public void onError(ChatModelErrorContext errorContext) {
Throwable error = errorContext.error();
error.printStackTrace();

ChatRequest chatRequest = errorContext.chatRequest();
System.out.println(chatRequest);

System.out.println(errorContext.modelProvider());

Map<Object, Object> attributes = errorContext.attributes();
System.out.println(attributes.get("my-attribute"));
}
};

ChatModel model = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName(GPT_4_O_MINI)
.listeners(List.of(listener))
.build();

model.chat("Tell me a joke about Java");

attributes マップにより、同じメソッドの onRequest、onResponse、および onError メソッド間で情報を受け渡すことができます。 ChatModelListener、および複数のChatModelListener間。 呼び出しごとのメタデータをリスナーに提供する必要がある場合は、ChatRequestOptions を使用します。 たとえば、テナントまたは相関識別子を ChatModelListener に渡すことができます。 listenerAttributes 経由。これらのオプションは、LangChain4j 呼び出しチェーン内でのみ使用されます。 これらは LLM プロバイダーには送信されません。

ChatRequest chatRequest = ChatRequest.builder()
.messages(UserMessage.from("Tell me a joke about Java"))
.build();

ChatRequestOptions options = ChatRequestOptions.builder()
.addListenerAttribute("tenantId", "tenant-123")
.addListenerAttribute("correlationId", "corr-456")
.build();

model.chat(chatRequest, options);

StreamingChatModel.chat(chatRequest, options, handler)も同様です。

リスナーの仕組み​

  • リスナーは List<ChatModelListener> として指定され、反復の順序で呼び出されます。
  • リスナーは同じスレッド内で同期的に呼び出されます。ストリーミングのケースの詳細については、以下をご覧ください。 2 番目のリスナーは、最初のリスナーが返されるまで呼び出されません。
  • ChatModelListener.onRequest() メソッドは、LLM プロバイダー API を呼び出す直前に呼び出されます。
  • ChatModelListener.onRequest() メソッドはリクエストごとに 1 回だけ呼び出されます。 LLM プロバイダー API の呼び出し中にエラーが発生し、再試行が行われた場合、 ChatModelListener.onRequest() は再試行のたびにnot 呼び出されます。
  • ChatModelListener.onResponse() メソッドは 1 回だけ呼び出されます。 LLM プロバイダーから正常な応答を受信した直後。
  • ChatModelListener.onError() メソッドは 1 回だけ呼び出されます。 LLM プロバイダー API の呼び出し中にエラーが発生し、再試行が行われた場合、 ChatModelListener.onError() は再試行のたびにnot 呼び出されます。
  • ChatModelListener メソッドのいずれかから例外がスローされた場合、 WARN レベルで記録されます。後続のリスナーの実行は通常どおり続行されます。
  • ChatRequest は ChatModelRequestContext、ChatModelResponseContext、ChatModelErrorContext 経由で提供されます は、ChatModel で設定されたデフォルトの ChatRequestParameters の両方を含む最後のリクエストです。 リクエスト固有の ChatRequestParameters が統合されました。
  • StreamingChatModel、ChatModelListener.onResponse()、ChatModelListener.onError()の場合 ChatModelListener.onRequest() とは別のスレッドで呼び出されます。 現在、スレッド コンテキストは自動的に伝播されないため、attributes マップを使用することをお勧めします。 必要なデータを ChatModelListener.onRequest() から ChatModelListener.onResponse() または ChatModelListener.onError() に伝播します。
  • StreamingChatModel の場合、ChatModelListener.onResponse() は、 StreamingChatResponseHandler.onCompleteResponse()と呼ばれます。 ChatModelListener.onError() と呼ばれます StreamingChatResponseHandler.onError() が呼び出される前に。

モデレーションモデルの可観測性​

リスナーをサポートする ModerationModel の実装 (OpenAiModerationModel、MistralAiModerationModel、 および WatsonxModerationModel) を使用すると、以下のようなイベントをリッスンするように ModerationModelListener を構成できます。

  • モデレーション API へのリクエスト
  • モデレーション API からの応答
  • エラー

ModerationModelListener の使用例を次に示します。

ModerationModelListener listener = new ModerationModelListener() {

@Override
public void onRequest(ModerationModelRequestContext requestContext) {
ModerationRequest moderationRequest = requestContext.moderationRequest();

// Access texts being moderated
System.out.println("Moderating texts: " + moderationRequest.texts());

System.out.println(requestContext.modelProvider());
System.out.println(moderationRequest.modelName());

Map<Object, Object> attributes = requestContext.attributes();
attributes.put("startTime", System.currentTimeMillis());
}

@Override
public void onResponse(ModerationModelResponseContext responseContext) {
ModerationResponse moderationResponse = responseContext.moderationResponse();

Moderation moderation = moderationResponse.moderation();
System.out.println("Flagged: " + moderation.flagged());
if (moderation.flagged()) {
System.out.println("Flagged text: " + moderation.flaggedText());
}

ModerationRequest moderationRequest = responseContext.moderationRequest();
System.out.println(moderationRequest);

System.out.println(responseContext.modelProvider());
System.out.println(moderationRequest.modelName());

Map<Object, Object> attributes = responseContext.attributes();
Long startTime = (Long) attributes.get("startTime");
if (startTime != null) {
System.out.println("Duration: " + (System.currentTimeMillis() - startTime) + "ms");
}
}

@Override
public void onError(ModerationModelErrorContext errorContext) {
Throwable error = errorContext.error();
error.printStackTrace();

ModerationRequest moderationRequest = errorContext.moderationRequest();
System.out.println(moderationRequest);

System.out.println(errorContext.modelProvider());
System.out.println(moderationRequest.modelName());

Map<Object, Object> attributes = errorContext.attributes();
System.out.println(attributes.get("startTime"));
}
};

ModerationModel model = OpenAiModerationModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.listeners(List.of(listener))
.build();

model.moderate("Text to check for policy violations");

attributes マップにより、同じメソッドの onRequest、onResponse、および onError メソッド間で情報を受け渡すことができます。 ModerationModelListener、および複数のModerationModelListener間。

リスナーの仕組み​

  • リスナーは List<ModerationModelListener> として指定され、反復の順序で呼び出されます。
  • リスナーは同じスレッド内で同期的に呼び出されます。
  • ModerationModelListener.onRequest() メソッドは、モデレーション API を呼び出す直前に呼び出されます。
  • ModerationModelListener.onRequest() メソッドはリクエストごとに 1 回だけ呼び出されます。 モデレーション API の呼び出し中にエラーが発生し、再試行が行われた場合、 ModerationModelListener.onRequest() は再試行のたびにnot 呼び出されます。
  • ModerationModelListener.onResponse() メソッドは 1 回だけ呼び出されます。 成功した応答を受け取った直後。
  • ModerationModelListener.onError() メソッドは 1 回だけ呼び出されます。 モデレーション API の呼び出し中にエラーが発生し、再試行が行われた場合、 ModerationModelListener.onError() は再試行のたびにnot 呼び出されます。
  • ModerationModelListener メソッドのいずれかから例外がスローされた場合、 WARN レベルで記録されます。後続のリスナーの実行は通常どおり続行されます。

RAG 可観測性 (EmbeddingModel、EmbeddingStore、ContentRetriever、ScoringModel)​

EmbeddingModel、EmbeddingStore、ContentRetriever、ScoringModel(取得したコンテンツの再ランキングに使用)にはリスナーを組み込んで、 以下を監視できます。

  • レイテンシー (attributes を使用して時間を測定)
  • ペイロード (例: EmbeddingSearchRequest.queryEmbedding() および取得された一致/コンテンツ)
  • エラー

EmbeddingModel リスナー​

EmbeddingModelListener を実装します:

import dev.langchain4j.model.embedding.listener.EmbeddingModelListener;
import dev.langchain4j.model.embedding.listener.EmbeddingModelRequestContext;
import dev.langchain4j.model.embedding.listener.EmbeddingModelResponseContext;
import dev.langchain4j.model.embedding.listener.EmbeddingModelErrorContext;

public class MyEmbeddingModelListener implements EmbeddingModelListener {

@Override
public void onRequest(EmbeddingModelRequestContext requestContext) {
requestContext.attributes().put("startNanos", System.nanoTime());
// requestContext.embeddingRequest() exposes the inputs, per-call parameters (input_type, dimensions, ...)
// and multimodal content. requestContext.modelProvider() identifies the provider.
}

@Override
public void onResponse(EmbeddingModelResponseContext responseContext) {
long startNanos = (long) responseContext.attributes().get("startNanos");
long durationNanos = System.nanoTime() - startNanos;
// Do something with duration and/or responseContext.embeddingResponse() (embeddings + metadata)
}

@Override
public void onError(EmbeddingModelErrorContext errorContext) {
// Do something with errorContext.error()
}
}

モデル ビルダーの listeners(...) メソッドを介してリスナーを接続します (推奨):

EmbeddingModel model = OpenAiEmbeddingModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("text-embedding-3-small")
.listeners(List.of(new MyEmbeddingModelListener()))
.build();

model.embed("hello");

リスナーには、embed(String) / embed(TextSegment) だけでなく、embed(EmbeddingRequest) 付近でも通知されます。 便利な方法。

备注

すでに構築されたモデルを EmbeddingModel#addListener(s) でラップすることで、リスナーをアタッチすることもできます。

EmbeddingModel observedModel = embeddingModel.addListener(new MyEmbeddingModelListener());

observedModel.embed("hello");

これは、既に構築されたモデル、またはビルダーが公開しないモデルにリスナーを追加する場合に便利です。 listeners(...)。ビルダーが listeners(...) を公開する場合は、必要がないため、そのアプローチを優先します。 ラッピング。

EmbeddingStore リスナー​

EmbeddingStoreListener を実装します:

import dev.langchain4j.store.embedding.listener.EmbeddingStoreListener;
import dev.langchain4j.store.embedding.listener.EmbeddingStoreRequestContext;
import dev.langchain4j.store.embedding.listener.EmbeddingStoreResponseContext;
import dev.langchain4j.store.embedding.listener.EmbeddingStoreErrorContext;

public class MyEmbeddingStoreListener implements EmbeddingStoreListener {

@Override
public void onRequest(EmbeddingStoreRequestContext<?> requestContext) {
requestContext.attributes().put("startNanos", System.nanoTime());
}

@Override
public void onResponse(EmbeddingStoreResponseContext<?> responseContext) {
long startNanos = (long) responseContext.attributes().get("startNanos");
long durationNanos = System.nanoTime() - startNanos;
// Do something with duration and/or the response payload (if any), e.g.:
if (responseContext instanceof EmbeddingStoreResponseContext.Search<?> search) {
// Do something with search.searchResult()
}
}

@Override
public void onError(EmbeddingStoreErrorContext<?> errorContext) {
// Do something with errorContext.error()
}
}

EmbeddingStore#addListener(s) を使用してリスナーを接続します。

EmbeddingStore<TextSegment> observedStore = embeddingStore.addListener(new MyEmbeddingStoreListener());

// Use observedStore as usual, e.g. in EmbeddingStoreIngestor / EmbeddingStoreContentRetriever

ContentRetriever リスナー​

ContentRetrieverListener を実装します:

import dev.langchain4j.rag.content.retriever.listener.ContentRetrieverListener;
import dev.langchain4j.rag.content.retriever.listener.ContentRetrieverRequestContext;
import dev.langchain4j.rag.content.retriever.listener.ContentRetrieverResponseContext;
import dev.langchain4j.rag.content.retriever.listener.ContentRetrieverErrorContext;

public class MyContentRetrieverListener implements ContentRetrieverListener {

@Override
public void onRequest(ContentRetrieverRequestContext requestContext) {
requestContext.attributes().put("startNanos", System.nanoTime());
}

@Override
public void onResponse(ContentRetrieverResponseContext responseContext) {
long startNanos = (long) responseContext.attributes().get("startNanos");
long durationNanos = System.nanoTime() - startNanos;
// Do something with duration and/or responseContext.contents()
}

@Override
public void onError(ContentRetrieverErrorContext errorContext) {
// Do something with errorContext.error()
}
}

ContentRetriever#addListener(s) を使用してリスナーを接続します。

ContentRetriever observedRetriever = contentRetriever.addListener(new MyContentRetrieverListener());

observedRetriever.retrieve(Query.from("my query"));

ContentRetrieverListener は、1 つのコンテンツリトリーバーの各呼び出しを観測します。AI Service がユーザーメッセージに追加する最終的なコンテンツを呼び出しごとに 1 回受け取るには、RetrievalAugmentedListener を使用してください(イベントをリッスンするを参照)。

ScoringModel リスナー​

ScoringModel は、クエリに対してテキストをスコアリングします。たとえば、ReRankingContentAggregator で取得したコンテンツを再ランキングする場合などです。 ScoringModelListener を実装します:

import dev.langchain4j.model.scoring.listener.ScoringModelListener;
import dev.langchain4j.model.scoring.listener.ScoringModelRequestContext;
import dev.langchain4j.model.scoring.listener.ScoringModelResponseContext;
import dev.langchain4j.model.scoring.listener.ScoringModelErrorContext;

public class MyScoringModelListener implements ScoringModelListener {

@Override
public void onRequest(ScoringModelRequestContext requestContext) {
requestContext.attributes().put("startNanos", System.nanoTime());
// requestContext.scoringRequest() exposes the texts being scored (documents()), the query() and the
// modelName() (null when the model sets none). requestContext.modelProvider() identifies the provider.
}

@Override
public void onResponse(ScoringModelResponseContext responseContext) {
long startNanos = (long) responseContext.attributes().get("startNanos");
long durationNanos = System.nanoTime() - startNanos;
// Do something with duration and/or responseContext.scoringResponse():
// scores() (one per document, in the same order), modelName() and tokenUsage().
// The unit of tokenUsage() depends on the provider: Cohere reports billed search units, not tokens.
}

@Override
public void onError(ScoringModelErrorContext errorContext) {
// Do something with errorContext.error()
}
}

モデルビルダーの listeners(...) メソッドでリスナーをアタッチします:

import dev.langchain4j.model.cohere.CohereScoringModel;
import dev.langchain4j.model.scoring.ScoringModel;
import dev.langchain4j.model.scoring.request.ScoringRequest;
import dev.langchain4j.model.scoring.response.ScoringResponse;
import java.util.List;

ScoringModel scoringModel = CohereScoringModel.builder()
.apiKey(System.getenv("COHERE_API_KEY"))
.modelName("rerank-v3.5")
.listeners(List.of(new MyScoringModelListener()))
.build();

ScoringResponse response = scoringModel.score(ScoringRequest.builder()
.documents(List.of("Paris is the capital of France", "Berlin is the capital of Germany"))
.query("What is the capital of France?")
.build());

リスナーには、score(ScoringRequest) とその非同期版である scoreAsync(ScoringRequest) の前後で通知されます。 CohereScoringModel、JinaScoringModel、VoyageAiScoringModel、WatsonxScoringModel、DecisionScoringModel は listeners(...) をサポートしています。これらのモデルでは、scoreAll(...) や score(text, query) を呼び出した場合にもリスナーに通知されるため、ReRankingContentAggregator が行うスコアリングも観測できます。例外が 1 つあります。 WatsonxScoringModel.scoreAll(segments, query, parameters)(RerankParameters 付き)はリスナーに通知しません。 リクエストごとのパラメーターを指定した呼び出しを観測するには、score(ScoringRequest) を使用してください。 その他のスコアリングモデル(たとえばインプロセス ONNX や Vertex AI のもの)は、まだリスナーをサポートしていません。

DecisionScoringModel は決定モデルに支えられています。その応答の tokenUsage() は決定呼び出しの合計であり、 決定モデルのリスナーがすでに 1 つずつ観測しています。トークン使用量を合算する際は、両方を数えないでください。

応答の modelName() は、プロバイダーが応答で報告するモデルです。JinaScoringModel、 VoyageAiScoringModel、WatsonxScoringModel は報告します。CohereScoringModel は報告しないため、その応答には リクエストされたモデル名が入ります。DecisionScoringModel には、その決定モデルが報告するモデル名が入ります。

リスナーの仕組み​

  • リスナーは List として指定され、反復の順序で呼び出されます。
  • リスナーは同じスレッド内で同期的に呼び出されます。
  • EmbeddingModel または ScoringModel の非同期呼び出し(embedAsync(...)、scoreAsync(...))では、 onResponse() と onError() は 呼び出しを完了させるスレッド上で呼び出されます。これは I/O スレッドの場合があるため、これらの中でブロックしないでください。たとえば、データベースへの書き込みなどの時間のかかる処理は 別のスレッドに引き渡してください。
  • onRequest() は、基礎となる操作を実行する直前に呼び出されます。
  • onResponse() は正常に完了した後に 1 回呼び出されます。
  • onError() は、基礎となる操作によって例外がスローされた場合に 1 回呼び出されます。
  • 非同期の EmbeddingModel または ScoringModel 呼び出しの future をキャンセルした場合、onResponse() も onError() も呼び出されません。
  • EmbeddingModel または ScoringModel に非同期実装がない場合、その非同期呼び出しは AsyncNotSupportedException で失敗し、この例外は onError() に渡されます。エラーをカウントするリスナーでは、これを除外したい場合があります。 offloadBlocking(true) で構築された RAG コンポーネントは、その場合に同期呼び出しを別のスレッドで実行し、 リスナーはそれを別個の呼び出しとして観測します。offloadBlocking(true) がない場合、RAG の呼び出しは UnsupportedFeatureException で失敗します。
  • リスナー メソッドの 1 つから例外がスローされた場合、その例外は WARN レベルでログに記録され、無視されます。
  • attributes マップにより、同じリスナーの onRequest、onResponse、onError メソッド間、 および複数のリスナー間で情報を受け渡すことができます。

Micrometer による可観測性メトリクス​

langchain4j-micrometer-metrics モジュールは、LangChain4j ライブラリにマイクロメーターベースのメトリクス実装を提供します。 現在、ChatModelListener 実装を使用した ChatModel と StreamingChatModel のインタラクションのメトリクスと、 Micrometer の MeterRegistry 経由でメトリクスを収集する EmbeddingModelListener 実装を使用した EmbeddingModel のインタラクションのメトリクスを提供しています。

メトリクスの名前は、OpenTelemetry Semantic Conventions for Generative AI Metrics に従います。 (v1.39.0)

⚠️実験的: このモジュールは@Experimentalとしてマークされており、将来のバージョンでは重大な変更が加えられる可能性があります。

⚠️ 警告: 生成 AI 用の OpenTelemetry セマンティック規則は現在 実験段階であり、安定していません。これは、将来のバージョンで重大な変更が行われる可能性があることを意味します。これらの規則に従う場合、規則が更新されたときに、ダッシュボード、アラート、自動化に重大な変更を導入する必要が生じる場合があります。

メトリクス​

現在、次のメトリクスが収集されています。

メトリクス名タイプ説明
gen_ai.client.token.usageヒストグラム (分布概要)チャット モデルリクエストごとに使用される入力トークンと出力トークンの数、および 埋め込み モデルリクエストごとの入力トークンの数
gen_ai.client.operation.durationタイマー成功・失敗を問わず、すべての チャット および 埋め込み モデルリクエストにかかった時間

gen_ai.client.token.usage のタグ​

タグ説明値の例
gen_ai.operation.name実行中の操作chat、embeddings
gen_ai.provider.nameAI プロバイダー名openai、azure.ai.inference、anthropic
gen_ai.request.modelリクエストのモデル名gpt-4、gpt-35-turbo、text-embedding-3-small
gen_ai.response.model応答からのモデル名gpt-4-0613
gen_ai.token.typeカウントされるトークンの種類input、output(埋め込みは input のみ記録)

gen_ai.client.operation.duration のタグ​

タグ説明値の例
gen_ai.operation.name実行中の操作chat、embeddings
gen_ai.provider.nameAI プロバイダー名openai、azure.ai.inference、anthropic
gen_ai.request.modelリクエストのモデル名gpt-4、gpt-35-turbo、text-embedding-3-small
gen_ai.response.model応答からのモデル名。失敗した呼び出しでは unknowngpt-4-0613、unknown
outcome呼び出しが成功したか失敗したかSUCCESS、ERROR
error.type例外のクラス名。成功した呼び出しでは nonenone、java.util.concurrent.TimeoutException

MicrometerMetricsChatModelListener の作成​

MicrometerMetricsChatModelListener は、ChatModel および StreamingChatModel インタラクションのメトリクスを収集します。 マイクロメーターの MeterRegistry をインスタンス化する必要があります。

import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.micrometer.metrics.listeners.MicrometerMetricsChatModelListener;
import dev.langchain4j.model.azure.AzureOpenAiChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.response.ChatResponse;
import io.micrometer.core.instrument.MeterRegistry;

import java.util.List;

// Get the MeterRegistry
MeterRegistry meterRegistry = new SimpleMeterRegistry();

// 1. Create the listener with the MeterRegistry and AI system name
MicrometerMetricsChatModelListener listener =
new MicrometerMetricsChatModelListener(meterRegistry);

// 2. Add the listener to your ChatModel
AzureOpenAiChatModel chatModel = AzureOpenAiChatModel.builder()
.endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"))
.apiKey(System.getenv("AZURE_OPENAI_KEY"))
.deploymentName(System.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"))
.listeners(List.of(listener))
.build();

// 3. Use the chat model as usual - metrics are collected automatically
ChatResponse response = chatModel.chat(ChatRequest.builder()
.messages(UserMessage.from("Hello!"))
.build());

埋め込みの gen_ai.client.operation.duration のタグ​

タグ説明値の例
gen_ai.operation.name実行中の操作embeddings
gen_ai.provider.nameAI プロバイダー名openai、ollama
gen_ai.request.modelリクエストのモデル名text-embedding-3-small
gen_ai.response.model応答からのモデル名。失敗した呼び出しでは unknowntext-embedding-3-small、unknown
outcome呼び出しが成功したか失敗したかSUCCESS、ERROR
error.type例外のクラス名。成功した呼び出しでは nonenone、java.net.SocketTimeoutException

MicrometerMetricsEmbeddingModelListener の作成​

MicrometerMetricsEmbeddingModelListener は、EmbeddingModel インタラクションのメトリクスを収集します。 埋め込み呼び出しには出力トークンがないため、gen_ai.token.type = input の gen_ai.client.token.usage のみを記録し、 成功・失敗を問わずすべての呼び出しについて gen_ai.client.operation.duration を記録します。 Micrometer の MeterRegistry をインスタンス化する必要があります。

import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.micrometer.metrics.listeners.MicrometerMetricsEmbeddingModelListener;
import dev.langchain4j.model.openai.OpenAiEmbeddingModel;
import dev.langchain4j.model.output.Response;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;

import java.util.List;

// Get the MeterRegistry
MeterRegistry meterRegistry = new SimpleMeterRegistry();

// 1. Create the listener with the MeterRegistry
MicrometerMetricsEmbeddingModelListener listener =
new MicrometerMetricsEmbeddingModelListener(meterRegistry);

// 2. Add the listener to your EmbeddingModel
OpenAiEmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("text-embedding-3-small")
.listeners(List.of(listener))
.build();

// 3. Use the embedding model as usual - metrics are collected automatically
Response<List<Embedding>> embeddings = embeddingModel.embedAll(List.of(TextSegment.from("Hello!")));

Micrometer Observation API​

これにより、Micrometer Observation API を使用して ChatModelListener が実装され、メトリクスとトレースの透過的な生成が可能になります。

これはlangchain4j-observationモジュールに実装されています。

生成されたテレメトリ​

トレース​

これにより、チャット インタラクションごとのスパンが提供されます。

例: observation trace

メトリクス​

次のヒストグラム:

  • gen_ai_client_token_usage
  • gen_ai_client_operation_duration

例:

# HELP gen_ai_client_operation_duration_active_seconds  
# TYPE gen_ai_client_operation_duration_active_seconds summary
gen_ai_client_operation_duration_active_seconds_count{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="unknown",outcome="SUCCESS"} 0
gen_ai_client_operation_duration_active_seconds_sum{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="unknown",outcome="SUCCESS"} 0.0
# HELP gen_ai_client_operation_duration_active_seconds_max
# TYPE gen_ai_client_operation_duration_active_seconds_max gauge
gen_ai_client_operation_duration_active_seconds_max{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="unknown",outcome="SUCCESS"} 0.0
# HELP gen_ai_client_operation_duration_seconds
# TYPE gen_ai_client_operation_duration_seconds summary
gen_ai_client_operation_duration_seconds_count{error="none",gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",outcome="SUCCESS"} 2
gen_ai_client_operation_duration_seconds_sum{error="none",gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",outcome="SUCCESS"} 3.384050045
# HELP gen_ai_client_operation_duration_seconds_max
# TYPE gen_ai_client_operation_duration_seconds_max gauge
gen_ai_client_operation_duration_seconds_max{error="none",gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",outcome="SUCCESS"} 2.115592691
# HELP gen_ai_client_token_usage_tokens Measures the quantity of used tokens
# TYPE gen_ai_client_token_usage_tokens summary
gen_ai_client_token_usage_tokens_count{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="input"} 2
gen_ai_client_token_usage_tokens_sum{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="input"} 508.0
gen_ai_client_token_usage_tokens_count{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="output"} 2
gen_ai_client_token_usage_tokens_sum{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="output"} 53.0
# HELP gen_ai_client_token_usage_tokens_max Measures the quantity of used tokens
# TYPE gen_ai_client_token_usage_tokens_max gauge
gen_ai_client_token_usage_tokens_max{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="input"} 273.0
gen_ai_client_token_usage_tokens_max{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="output"} 27.0
备注

リスナーのコールバックはブロックしてはいけません。 ChatModelListener と EmbeddingModelListener のコールバックは、 モデル自身のスレッド上で同期的に呼び出され、オフロードされることはありません。同期 API では、それは呼び出し側の スレッドです。非同期 API およびリアクティブ API では、onResponse/onError は応答を読み取るトランスポートの I/O ワーカー上で実行されます。 そこでブロッキング I/O(同期的なデータベース書き込み、可観測性バックエンドへの同期的な HTTP 呼び出しなど)を行うコールバックは、 そのワーカーを停止させ、同時実行下では進行中のすべての呼び出しのスループットを低下させます。 メトリクスの記録やスパンの開始/終了を行ってください(付属の Micrometer および Observation リスナーは、設計上ノンブロッキングです)。 コールバックがどうしてもブロックしなければならない場合は、コールバック内から独自のエグゼキューターにオフロードしてください。 ノンブロッキングとリアクティブを参照してください。

Spring Boot アプリケーションの可観測性​

詳細については、hereをご覧ください。

Spring Boot アプリケーション here でマイクロメーターメトリクスを収集する方法の詳細を参照してください。

Micrometer Observation API ライブラリを SpringBoot と統合する方法の詳細については、here を参照してください。

サードパーティの統合​

  • Arize Phoenix は、ローカルでのトレース確認と実験のための、Arize AI によるオープンソースのセルフホスト型オプションです。
  • Arize AX は、本番環境の LangChain4j アプリケーション向けに、マネージドクラウドおよびエンタープライズのセルフホスト型の可観測性をサポートします。
  • トレースを基にした評価ワークフローについては、Arize のエージェント評価ガイドと LLM 評価ガイドを参照してください。

OpenTelemetry GenAI インストルメンテーション​

コミュニティが管理する otel-genai-bridges プロジェクトには、OpenTelemetry Generative AI semantic conventions を使用して LangChain4j チャット アプリケーションを自動計測する Spring Boot スターターが同梱されています。

なぜ使うのか?​

  • 任意の ChatModel Bean をラップし、スパン、イベント、およびメトリクスを出力します。
  • プロンプト、完了、ツール呼び出し、待ち時間、トークン使用量、コスト、RAG 取得待ち時間をすぐにキャプチャします。
  • 事前構築された Grafana ダッシュボードを備えた Docker Compose サンプル (Collector → Tempo/Prometheus → Grafana) を提供します。

はじめる​

スターターを Spring Boot プロジェクトに追加します。

<!-- pom.xml -->
<dependency>
<groupId>com.dineshkumarkummara.otel</groupId>
<artifactId>langchain4j-otel</artifactId>
<version>0.1.0-SNAPSHOT</version>
</dependency>

application.yaml 経由でスターターを有効にします。

otel:
langchain4j:
enabled: true
system: openai
default-model: gpt-4o
capture-prompts: true
capture-completions: true
cost:
enabled: true
input-per-thousand: 0.0005
output-per-thousand: 0.0015

ネストされた cost スタンザはオプションです。トークンあたりのコストのメトリクスが必要な場合はこれを含めます。

クラスパスへの依存関係により、スターターは ChatModel Bean を自動的に見つけて、それらをテレメトリでラップします。

可観測性ビュー​

Grafana latency panel

完全な動作例 (可観測性スタックとセマンティック カーネル パリティを含む) については、dineshkumarkummara/otel-genai-bridges を参照してください。