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 のスパンタイプが割り当てられます。span属性を使用するには、Pythonアプリケーションに以下のimportを追加します。

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 という属性に割り当てられて、コンテキストの関連性が計算されます。

構成¶

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 の基になるすべての実行のリストを返します。