Skip to main content
W&B Weave の スレッド を使用すると、LLM アプリケーションにおけるマルチターンの会話をトラッキングおよび分析できます。スレッドは関連する Call を共通の thread_id でグループ化します。これにより、セッション全体を可視化し、ターンをまたいで会話レベルのメトリクスをトラッキングできます。スレッドはプログラムから作成でき、Weights & Biases UI で可視化できます。 スレッドを使い始めるには、次の手順に従います。
  1. スレッドの基本を理解します。
  2. 一般的な使用パターンや実際のユースケースを示すコードサンプルを試します。

ユースケース

スレッドは、次のようなものを整理・分析したい場合に役立ちます。
  • マルチターンの会話
  • セッションベースのワークフロー
  • 相互に関連する一連の操作
スレッドを使用すると、Call をコンテキストごとにグループ化できるため、複数のステップにわたってシステムがどのように応答するかを把握しやすくなります。たとえば、1 つのユーザーセッション、エージェントによる一連の意思決定、あるいはインフラストラクチャー層とビジネスロジック層にまたがる複雑なリクエストをトラッキングできます。 スレッドとターンを使用してアプリケーションを構成すると、メトリクスが整理され、Weights & Biases UI での可視性も向上します。低レベルの Op をすべて確認する代わりに、重要な高レベルのステップに集中できます。

定義

スレッド

スレッド は、共通の会話コンテキストを共有する、関連する Call を論理的にまとめたグループです。スレッドには次の特徴があります。
  • 一意の thread_id を持つ
  • 1 つ以上の ターン を含む
  • Call をまたいでコンテキストを保持する
  • ユーザーセッション全体、または一連のインタラクションフローを表す

ターン

ターン は、スレッド内の上位レベルの操作で、UI ではスレッドビューの各行として表示されます。各ターンには次の特徴があります。
  • 会話またはワークフローにおける 1 つの論理的なステップを表します
  • スレッドコンテキストの直接の子であり、ネストされた下位レベルの Call を含む場合があります (これらはスレッドレベルの統計には表示されません)

Call

Call とは、アプリケーション内で @weave.op でデコレートされた関数の実行を指します。
  • ターン Call は、新しいターンを開始する最上位の操作です。
  • Nested Call は、ターン内で実行される下位の操作です。

トレース

トレース は、単一の操作の Call スタック全体を取得します。スレッドは、同じ論理的な会話またはセッションに属するトレースをグループ化します。つまり、スレッドは複数のターンで構成され、各ターンが会話の一部を表します。トレースの詳細については、トレースの概要を参照してください。

UI の概要

Weave プロジェクトのサイドバーで Threads を選択すると、Threads list view が開きます。
Weave サイドバーの Threads アイコン

Threads list view

  • project 内の最近のスレッドを一覧表示します。
  • 列には、ターン数、開始時刻、最終更新日時が表示されます。
  • 行をクリックすると、その詳細ドロワーが開きます。
Threads list view

スレッドの詳細ドロワー

  • 任意の行をクリックすると、その行の詳細ドロワーが開きます。
  • スレッド内のすべてのターンが表示されます。
  • ターンは開始順に一覧表示されます (所要時間や終了時刻ではなく、開始時刻に基づきます) 。
  • Call レベルのメタデータ (レイテンシー、入力、出力) が含まれます。
  • ログされている場合は、メッセージの内容や構造化データも表示されます。
  • ターンの実行内容全体を確認するには、スレッドの詳細ドロワーからターンを開きます。そのターン中に発生したすべてのネストされた操作を掘り下げて確認できます。
  • ターンに LLM Call から抽出されたメッセージが含まれている場合、それらはチャットペインに表示されます。これらのメッセージは通常、サポートされるインテグレーション (例: openai.ChatCompletion.create) による Call から取得されたもので、表示するには特定の条件を満たす必要があります。詳細については、チャットビューの動作を参照してください。

チャットビューの動作

チャットペインには、各ターンで実行された LLM Call から抽出された構造化メッセージデータが表示されます。このビューでは、やり取りを会話形式でレンダリングして確認できます。
構造化された LLM メッセージを表示している Threads のチャットペイン

メッセージとして扱われるもの

Weave は、ターン内の Call のうち、LLM プロバイダとの直接的なやり取り (プロンプトを送信して応答を受け取るなど) を表す Call からメッセージを抽出します。メッセージとして表示されるのは、他の Call の内部にネストされていない Call のみです。これにより、中間ステップや集計された内部ロジックが重複して表示されるのを防ぎます。 通常、メッセージを出力するのは、自動的にパッチが適用されたサードパーティ SDK です。次に例を示します。
  • openai.ChatCompletion.create
  • anthropic.Anthropic.completion

メッセージがない場合の動作

ターンがメッセージを出力しない場合、チャットペインにはそのターンのメッセージセクションが空の状態で表示されます。この場合でも、チャットペインには同じスレッド内の他のターンのメッセージが表示されることがあります。

ターンとチャットの連動

  • ターンをクリックすると、チャットペインがそのターンのメッセージ位置までスクロールします (ピン留め動作) 。
  • チャットペインをスクロールすると、ターンリスト内の対応するターンがハイライト表示されます。
ターンをクリックすると、そのターンのトレース全体を開けます。 左上に戻るボタンが表示され、クリックするとスレッドの詳細ビューに戻れます。この遷移では、Weave は UI の状態 (スクロール位置など) を保持しません。
スレッドビューに戻るための戻るボタンが表示された Threads の詳細ドロワー

SDK の使用方法

以下のセクションでは、Weave SDK を使用してスレッドをプログラムから作成、管理する方法について説明します。各サンプルでは、アプリケーション内でターンとスレッドを整理するための異なる手法を紹介します。ほとんどのサンプルでは、スタブ関数内に独自の LLM Call またはシステムの動作を実装してください。
  • セッションや会話をトラッキングするには、weave.thread() コンテキストマネージャーを使用します。
  • 論理的な操作を @weave.op でデコレートすると、ターンまたはネストされた Call としてトラッキングできます。
  • thread_id を渡すと、Weave はその ID を使用して、ブロック内のすべての操作を同じスレッドにグループ化します。thread_id を省略した場合は、Weave が一意の ID を自動生成します。
weave.thread() の戻り値は、thread_id プロパティを持つ ThreadContext オブジェクトです。この ID は、ログしたり、再利用したり、他のシステムに渡したりできます。 ネストされた weave.thread() コンテキストは、同じ thread_id を再利用しない限り、常に新しいスレッドを開始します。子コンテキストを終了しても、親コンテキストが中断されたり上書きされたりすることはありません。そのため、アプリケーションのロジックに応じて、フォークしたスレッド構造や階層的なスレッドのオーケストレーションを実現できます。

基本的なスレッドの作成

次のコードサンプルでは、weave.thread() を使用して 1 つ以上の操作を共通の thread_id でグループ化する方法を示します。アプリケーションでスレッドを使い始める最も簡単な方法です。

エージェントループの手動実装

この例では、@weave.op デコレーターと weave.thread() によるコンテキスト管理を使用して、会話型エージェントを手動で定義する方法を示します。process_user_message を呼び出すたびに、スレッド内に新しいターンが作成されます。独自のエージェントループを構築していて、コンテキストやネストの扱いを完全に制御したい場合に、このパターンを使用できます。 短時間のやり取りには自動生成されたスレッド ID を使用します。セッションをまたいでスレッドコンテキストを保持するには、カスタムのセッション ID (user_session_123 など) を渡します。

Call の深さが不均一な手動エージェント

この例では、スレッドコンテキストの適用方法によって、Call スタック内の異なる深さでターンを定義できることを示します。このサンプルでは 2 つのプロバイダー (OpenAI と Anthropic) を使用しており、ターン境界に到達するまでの Call の深さはプロバイダーごとに異なります。 すべてのターンは同じ thread_id を共有しますが、ターン境界がスタックのどの階層に現れるかは、プロバイダーのロジックによって異なります。これは、同じスレッドにグループ化したまま、バックエンドごとに Call のトレース方法を変えたい場合に便利です。

以前のセッションを再開する

以前に開始したセッションを再開し、同じスレッドに引き続き Call を追加する必要が生じることがあります。一方で、既存のセッションを再開できず、新しいスレッドを開始しなければならない場合もあります。 スレッドの再開を任意で行えるように実装する場合は、thread_id パラメーターを None のままにしないでください。None のままにすると、スレッドのグループ化が無効になります。常に有効なスレッド ID を指定してください。新しいスレッドを作成する場合は、generate_id() などの関数を使用して一意の ID を生成します。 thread_id が指定されていない場合、Weave の内部実装ではランダムな UUID v7 が自動生成されます。独自の generate_id() 関数でこの動作を再現することも、任意の一意な string 値を使用することもできます。

ネストされたスレッド

この例では、連携する複数のスレッドを使用して複雑なアプリケーションを構成する方法を示します。 各レイヤーはそれぞれ独自のスレッドコンテキストで実行されるため、関心事を明確に分離できます。親となるアプリケーションスレッドは、共有の ThreadContext を使用してスレッド ID を設定し、これらのレイヤーを連携させます。システムの各部分を個別に分析または監視しながら、それらを共通のセッションに関連付けたい場合は、このパターンを使用してください。

API 仕様

以下のセクションでは、スレッドのクエリエンドポイント、そのリクエストと応答のスキーマ、およびスレッドデータをプログラムから取得する際に使用できる一般的なクエリパターンについて説明します。

エンドポイント

エンドポイント: POST /threads/query

リクエストスキーマ

応答スキーマ

最近アクティブなスレッドをクエリする

この例では、更新日時が新しい順に 50 件のスレッドを取得します。my-project は実際の project ID に置き換えてください。

アクティビティレベル別にスレッドをクエリする

この例では、最もアクティブなスレッド上位 20 件をターン数順に並べて取得します。

最近のスレッドのみをクエリする

この例では、過去 24 時間以内に開始されたスレッドを返します。時間ウィンドウを変更するには、timedelta の days の値を調整してください。
最終更新日 2026年9月30日