AIアプリケーションの評価¶

シナリオ1: 関数のトレース¶

トレースが必要な関数の前に @instrument() を追加できます。これは自動的に関数への入力、出力（戻り値）、実行の待ち時間をキャプチャします。例えば、次のコードは、入力クエリと最終レスポンスを自動的にキャプチャする answer_query 関数のトレースを示しています。

@instrument()
def answer_query(self, query: str) -> str:
    context_str = self.retrieve_context(query)
    return self.generate_completion(query, context_str)

シナリオ 2: 特定のスパンタイプで関数をトレースします。¶

スパンタイプは、関数の性質を指定し、トレースの読みやすさと理解を改善します。たとえば、RAGアプリケーションでは、検索サービス（またはリトリーバー）のスパンタイプを``RETRIEVAL``として指定し、LLM推論呼び出しのスパンタイプを``GENERATION``として指定できます。以下のスパンタイプがサポートされています。

• RETRIEVAL:検索または検索関数のスパンタイプ

• GENERATION:LLMからのモデル推論呼び出しのスパンタイプ

• RECORD_ROOT:アプリケーション内のメイン関数のスパンタイプ

``@instrument()``でスパンタイプを指定しない場合、``UNKNOWN``スパンタイプがデフォルトで割り当てられます。スパン属性を使用するには、Pythonアプリケーションに以下のインポートを追加します。

from trulens.otel.semconv.trace import SpanAttributes

次のコード・スニペットは、 RAG アプリケーションのトレースを示しています。スパンタイプのプレフィックスは必ず SpanAttributes.SpanType とします。

@instrument(span_type=SpanAttributes.SpanType.RETRIEVAL)
def retrieve_context(self, query: str) -> list:
    """
    Retrieve relevant text from vector store.
    """
    return self.retrieve(query)

@instrument(span_type=SpanAttributes.SpanType.GENERATION)
def generate_completion(self, query: str, context_str: list) -> str:
    """
    Generate answer from context by calling an LLM.
    """
    return response

@instrument(span_type=SpanAttributes.SpanType.RECORD_ROOT)
def answer_query(self, query: str) -> str:
    context_str = self.retrieve_context(query)
    return self.generate_completion(query, context_str)

シナリオ 3: 関数のトレースと評価の計算¶

スパン・タイプをプロバイダーとして提供するだけでなく、アプリケーションの関連パラメーターをスパン属性に割り当てて、メトリックスを計算する必要があります。例えば、 RAG アプリケーションでコンテキストの関連性を計算するには、関連するクエリと検索結果のパラメーターをそれぞれ適切な属性 RETRIEVAL.QUERY_TEXT と RETRIEVAL.RETRIEVED_CONTEXTS に割り当てる必要があります。各メトリクスの計算に必要な属性は、Metricsページで確認できます。

各スパンのタイプでは、以下のスパン属性がサポートされています。

• RECORD_ROOT:INPUT、OUTPUT、GROUND_TRUTH_OUTPUT

• RETRIEVAL:QUERY_TEXT、RETRIEVED_CONTEXTS

• GENERATION:なし

span属性を使用するには、Pythonアプリケーションに以下のimportを追加する必要があります。

from trulens.otel.semconv.trace import SpanAttributes

次のコードスニペットは、検索サービスのコンテキスト関連性を計算する例です。属性は常に形式 SpanAttributes.<span type>.<attribute name> (例えば、 SpanAttributes.RETRIEVAL.QUERY_TEXT) に従わなければなりません。

@instrument(
    span_type=SpanAttributes.SpanType.RETRIEVAL,
    attributes={
        SpanAttributes.RETRIEVAL.QUERY_TEXT: "query",
        SpanAttributes.RETRIEVAL.RETRIEVED_CONTEXTS: "return",
    }
)
def retrieve_context(self, query: str) -> list:
    """
    Retrieve relevant text from vector store.
    """
    return self.retrieve(query)

先の例では、 query が retrieve_context() への入力パラメーターを表し、 return が返される値を表しています。これらは、 RETRIEVAL.QUERY_TEXT と RETRIEVAL.RETRIEVED_CONTEXTS という属性に割り当てられて、コンテキストの関連性が計算されます。

フレームワークアプリケーションの自動インスツルメント¶

``@instrument()``デコレーターを使用した手動のインスツルメンテーションに加えて、TruLensは一般的なLLMフレームワークで構築されたアプリケーションを自動的にインスツルメントする専用ラッパーを提供します。これらのラッパーは、関数ごとの手動デコレーションを必要としない統合と自動トレースを提供します。

from trulens.apps.langchain import TruChain

# Wrap your LangChain application
tru_recorder = TruChain(
    rag_chain,
    app_name="my_langchain_app",
    app_version="v1.0"
)

# Use the recorder as a context manager
with tru_recorder as recording:
    response = rag_chain.invoke(input_query)

from trulens.apps.langgraph import TruGraph

# Wrap your LangGraph application
tru_recorder = TruGraph(
    graph,
    app_name="my_langgraph_app",
    app_version="v1.0"
)

# Use the recorder as a context manager
with tru_recorder as recording:
    response = graph.invoke({"messages": [("user", input_query)]})

from trulens.apps.llamaindex import TruLlama

# Wrap your LlamaIndex query engine
tru_recorder = TruLlama(
    query_engine,
    app_name="my_llamaindex_app",
    app_version="v1.0"
)

# Use the recorder as a context manager
with tru_recorder as recording:
    response = query_engine.query(input_query)

構成¶

RunConfig から1つの実行が作成されます。

run_config = RunConfig(
    run_name=run_name,
    description="desc",
    label="custom tag useful for grouping comparable runs",
    source_type="DATAFRAME",
    dataset_name="My test dataframe name",
    dataset_spec={
        "RETRIEVAL.QUERY_TEXT": "user_query_field",
        "RECORD_ROOT.INPUT": "user_query_field",
        "RECORD_ROOT.GROUND_TRUTH_OUTPUT": "golden_answer_field",
    },
    llm_judge_name: "mistral-large2"
)

• run_name: str: 実行の名前で、同じ TruApp の下の一意のものであるべきです。

• description: str (オプション): 実行の文字列説明

• label: str (オプション): グループにまとめるためのラベル。

• source_type: str: データセットのソースを指定します。Python dataframeの DATAFRAME 、またはSnowflakeアカウントのユーザーテーブルの TABLE 。

• dataset_name: str: source_type が DATAFRAME の場合、ユーザーが指定した任意の名前。または、現在のコンテキスト (データベースとスキーマ) でのユーザーアカウントの有効な Snowflake テーブル名、または "database.schema.table_name" 形式の Snowflake 完全修飾名。

• dataset_spec: Dict[str, str]: サポートされているスパンの属性を、データフレームまたはテーブルのユーザーの列名にマッピングする辞書。許可されるキーは、データセット・ページで指定されたスパン属性で、許可される値は、ユーザーが指定したデータフレームまたはテーブルの列名です。例えば、上記の実行設定例の "golden_answer_field "は有効な列名でなければなりません。

• llm_judge_name: str (オプション): LLM-based メトリック計算中に LLM ジャッジとして使用する名前。対応ジャッジはモデルページをご覧ください。指定がない場合、デフォルト値は llama3.1-70b

run = tru_app.add_run(run_config=run_config)

リクエストパラメーター:

• run_config: RunConfig: 実行の構成が含まれます。

実行の検索¶

実行を取得します。

run = tru_app.get_run(run_name=run_name)

リクエストパラメーター:

• run_name: str: 実行の名前

実行のメタデータ表示¶

実行の詳細を説明します。

run.describe()

実行の起動¶

run.start() 関数を使用して実行を呼び出すことができます。実行構成で指定されたデータセットから入力を読み取り、各入力に対してアプリケーションを起動し、トレースを生成し、Snowflakeアカウントにストレージするために情報をインジェストします。run.start() は、データセット内のすべての入力に対してアプリケーションが起動され、インジェストが完了するかタイムアウトするまで、ブロック呼び出しとなります。

run.start()  # if source_type is "TABLE"

run.start(input_df=user_input_df)  # if source_type is "DATAFRAME"

リクエストパラメーター:

• input_df: DataFrame (オプション): SDK からpandasデータフレーム実行構成の source_type が DATAFRAME に指定されている場合、このフィールドは必須です。source_type が TABLE の場合、このフィールドは必須ではありません。

メトリクスの計算¶

アプリケーションが起動され、すべてのトレースが取り込まれた後、 run.compute_metrics() を使用してメトリック計算を開始できます。実行のステータスが INVOCATION_IN_PROGRESS である限り、計算を開始することはできません。ステータスが INVOCATION_COMPLETED または INVOCATION_PARTIALLY_COMPLETED になると、 run.compute_metrics() を開始することができます。run.compute_metrics() は非同期のノンブロッキング関数です。同じ実行で、異なるメトリクスのセットで compute_metrics を複数回呼び出すことができ、呼び出すたびに新しい計算ジョブがトリガーされます。一度計算されたメトリクスは、同じ実行で再度計算することはできません。

run.compute_metrics(metrics=[
    "coherence",
    "answer_relevance",
    "groundedness",
    "context_relevance",
    "correctness",
])

リクエストパラメーター:

• metrics: List[str]:Metrics にリストされているメトリクスの文字列名のリスト。メトリクスの名前は、大文字と小文字で指定します。例えば、Context Relevance は context_relevance と指定します。

実行のステータスの確認¶

実行中のステータスは、実行後に確認することができます。ステータスのリストはRun Statusセクションにあります。

run.get_status()

実行のキャンセル¶

run.cancel() を使用して、既存の実行をキャンセルできます。この演算子により、実行のステータスやメタデータフィールドを含め、今後実行が更新されることはありません。

run.cancel()

実行の削除¶

run.delete() を使用して、既存の実行を削除できます。この演算子により、実行に関連するメタデータが削除され、評価結果にアクセスできなくなります。しかし、実行の一部として生成されたトレースや評価は削除されず、保存されたままです。評価とトレースのストレージと削除に関する詳細情報については、Observabilityデータのセクションを参照してください。

run.delete()

アプリケーションの実行リスト¶

list_runs() 関数を使用すると、特定の TruApp アプリケーションオブジェクトに対応するすべての可 用性実行のリストを見ることができます。

tru_app.list_runs()

応答:

tru_app の基になるすべての実行のリストを返します。