评估 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：使用特定 span 类型跟踪函数¶

span 类型指定了函数的性质，提高了跟踪的可读性和可理解性。例如，在 RAG 应用程序中，您可以为搜索服务（或检索器）指定 span 类型为“RETRIEVAL”，并为 LLM 推理调用指定 span 类型为“GENERATION”。支持以下 span 类型：

• RETRIEVAL：用于检索或搜索函数的 span 类型

• GENERATION：通过 LLM 进行模型推理调用的 span 类型

• RECORD_ROOT：应用程序中主要函数的 span 类型

如果不使用 @instrument() 指定 span 类型，则默认分配 UNKNOWN span 类型。要使用 span 属性，请在 Python 应用程序中添加以下导入。

from trulens.otel.semconv.trace import SpanAttributes

以下代码片段演示了如何跟踪 RAG 应用程序。span 类型必须始终将 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：跟踪函数并计算求值¶

除了提供 span 类型外，您还必须将应用程序中的相关参数分配给 span 属性，以便计算指标。例如，要在 RAG 应用程序中计算上下文相关性，必须将相关查询和检索结果参数分别分配给相应的属性 RETRIEVAL.QUERY_TEXT 和``RETRIEVAL.RETRIEVED_CONTEXTS``。计算每个指标所需的属性可在“Metrics”页面找到。

每种 span 类型都支持以下 span 属性：

• RECORD_ROOT：INPUT、OUTPUT、GROUND_TRUTH_OUTPUT

• RETRIEVAL：QUERY_TEXT、RETRIEVED_CONTEXTS

• GENERATION：无

要使用 span 属性，您需要在 Python 应用程序中添加以下导入。

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 创建运行

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：指定数据集的来源。可以是 ``DATAFRAME``（适用于 python 数据框），也可以是 ``TABLE``（适用于 Snowflake 账户中的用户表）。

• dataset_name: str：如果 source_type 为 DATAFRAME，用户指定的任意名称。或者，当前上下文（数据库和架构）的用户账户下的有效 Snowflake 表名，或者“database.schema.table_name”形式的 Snowflake 完全限定名称。

• dataset_spec: Dict[str, str]：字典，可将支持的 span 属性映射到数据框或表中的用户列名。允许的键是“Dataset”页面中指定的 span 属性，允许的值是用户指定的数据框或表中的列名。例如，上述运行配置示例中的“golden_answer_field”必须是有效的列名

• llm_judge_name: str``（可选）：在基于 LLM 的指标计算过程中用作 LLM 裁判的名称。有关支持的裁判，请参阅“Models”页面。如果未指定，则默认值为 ``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]：“指标”中列出的指标的字符串名称列表。指标名称应使用蛇形命名法来指定。例如，Context Relevance 应指定为 context_relevance。

检查运行状态¶

您可以在运行开始后检查其状态。状态列表位于“运行状态”部分。

run.get_status()

取消运行¶

您可以使用 run.cancel() 取消现有运行。此操作将阻止今后对运行的任何更新，包括运行状态和元数据字段。

run.cancel()

删除运行¶

您可以使用 run.delete() 删除现有运行。此操作会删除与运行相关的元数据，且无法访问评估结果。不过，运行过程中生成的跟踪和评估结果不会删除，仍会保存。请参阅“可观察性数据”部分，了解有关存储和删除评估与跟踪的更多信息。

run.delete()

应用程序的运行列表¶

您可以使用 list_runs() 函数查看与特定 TruApp 应用程序对象对应的所有可用运行列表。

tru_app.list_runs()

响应：

返回 tru_app 下创建的所有运行的列表。