文档 / 实验数据模型

实验数据模型

本页描述 Langfuse 中与实验相关对象的数据模型。关于这些对象如何协同工作的概览,参见概念页。关于分数和分数配置对象,参见分数数据模型。

详细参考请参阅

对象

数据集(Datasets)

数据集是输入和(可选)预期输出的集合,可在数据集运行期间使用。

Dataset 是 DatasetItem 的集合。

mermaid

classDiagram
direction LR
    class Dataset {
        name
        description
        metadata
    }

    class DatasetItem {
        datasetName
        input
        expectedOutput
        metadata
        sourceTraceId
        sourceObservationId
        id
        status
    }

    Dataset "1" --> "n" DatasetItem

Dataset 对象

属性	类型	必需	描述
`id`	string	是	数据集的唯一标识符
`name`	string	是	数据集的名称
`description`	string	否	数据集的描述
`metadata`	object	否	数据集的额外元数据
`remoteExperimentUrl`	string	否	用于触发实验的 webhook 端点
`remoteExperimentPayload`	object	否	用于触发实验的负载

DatasetItem 对象

属性	类型	必需	描述
`id`	string	是	数据集条目的唯一标识符。数据集条目按其 id 进行 upsert。Id 需要唯一(项目级),且不能跨数据集复用。
`datasetId`	string	是	此条目所属数据集的 ID
`input`	object	否	数据集条目的输入数据
`expectedOutput`	object	否	数据集条目的预期输出数据
`metadata`	object	否	数据集条目的额外元数据
`mediaReferences`	object[]	否	在 `input`、`expectedOutput` 和 `metadata` 中找到的已解析媒体引用。包含在包括已解析数据集媒体的 SDK 数据集获取和 API 响应中。
`sourceTraceId`	string	否	用于将此数据集条目链接到的源 trace 的 ID
`sourceObservationId`	string	否	用于将此数据集条目链接到的源 observation 的 ID
`status`	DatasetStatus	否	数据集条目的状态。新创建的条目默认为 ACTIVE。可能的值:`ACTIVE`、`ARCHIVED`

DatasetItemMediaReference 对象

数据集条目媒体引用从 input、expectedOutput 或 metadata 中存储的媒体 token 指向签名的媒体下载 URL。

属性	类型	必需	描述
`field`	string	是	包含引用的数据集条目属性的字段枚举。`input`、`expected_output`(对应 `expectedOutput`)或 `metadata` 之一。
`referenceString`	string	是	存储在数据集条目中的原始 Langfuse 媒体引用字符串。
`jsonPath`	string	是	字段内持有引用的字符串的 JSONPath,例如 `$['image']`。
`media`	object	是(可空)	已解析的媒体元数据。如果引用的媒体不存在或尚未成功上传,则为 `null`。

嵌套的 media 对象包含 mediaId、contentType、contentLength、url 和 urlExpiry。url 是签名的下载 URL,应在其过期日期之前使用。要刷新签名 URL,请重新获取数据集。

DatasetRun(实验运行)

数据集运行用于将数据集通过你的 LLM 应用运行,并可选地对结果应用评估方法。这通常被称为实验运行。

mermaid

classDiagram
direction LR
    class DatasetRun {
        id
        name
        description
        metadata
        datasetId
    }

    DatasetRun "1" --> "n" DatasetRunItem

    class DatasetRunItem {
        id
        datasetRunId
        datasetItemId
        traceId
        observationId
    }

DatasetRun 对象

属性	类型	必需	描述
`id`	string	是	数据集运行的唯一标识符
`name`	string	是	数据集运行的名称
`description`	string	否	数据集运行的描述
`metadata`	object	否	数据集运行的额外元数据
`datasetId`	string	是	此运行所属数据集的 ID

DatasetRunItem 对象

属性	类型	必需	描述
`id`	string	是	数据集运行条目的唯一标识符
`datasetRunId`	string	是	此条目所属数据集运行的 ID
`datasetItemId`	string	是	用于链接到此运行的数据集条目的 ID
`traceId`	string	是	用于链接到此运行的 trace 的 ID
`observationId`	string	否	用于链接到此运行的 observation 的 ID

大多数时候,我们建议 DatasetRunItems 直接引用 TraceID。对 ObservationID 的引用是为了与旧版 SDK 版本向后兼容而存在的。

端到端数据关系

一个实验可以组合若干 Langfuse 对象:

DatasetRuns(或实验运行)通过用你的 LLM 应用循环遍历 Dataset 的全部或选定的 DatasetItem 来创建。
对于作为输入传入 LLM 应用的每个 DatasetItem,会创建一个 DatasetRunItem 和一个 Trace。
可选地,可以将 Score 添加到 Trace,以在 DatasetRun 期间评估 LLM 应用的输出。

mermaid

classDiagram
direction LR
	namespace Datasets {
        class Dataset {
        }
        class DatasetItem {
        }
    }
    namespace DatasetRuns {
        class DatasetRun {
        }
        class DatasetRunItem {
        }
    }
    namespace Observability {
        class Trace {
        }
        class Observation {
        }
        }
    namespace Evals {
        class Score {
        }
    }


    class DatasetRun {
    }

    class DatasetRunItem {
    }

    class Dataset {
    }

    class DatasetItem {
    }

    class Trace {
	    input
	    output
    }

    class Observation {
        input
	    output
    }

    class Score {
	    name
	    value
	    comment
    }

    Dataset "1" --> "n" DatasetItem
    Dataset "1" --> "n" DatasetRun
    DatasetRun "1" --> "n" DatasetRunItem
    DatasetRunItem "1" --> "1" DatasetItem
    Trace "1" --> "n" Observation
    DatasetRunItem "1" --> "1" Trace
    DatasetRunItem "1" --> "0..1" Observation
    Observation "1" --> "n" Score
    Trace "1" --> "n" Score

关于这些对象在概念上如何协同工作的更多信息,参见概念页。关于 traces 和 observations 的更多细节,参见可观测性核心概念页。关于分数和分数配置对象的更多细节,参见分数数据模型。

函数定义

通过 SDK 运行实验时,你定义 task 和 evaluator 函数。这些是实验运行器为每个数据集条目调用的用户定义函数。关于实验在概念上如何工作的更多信息,参见概念页。

Task

task 是一个函数,在实验运行期间接收一个数据集条目并返回一个输出。

函数签名和参数参见 SDK 参考:

Evaluator

evaluator 是一个函数,为单个数据集条目对 task 的输出打分。评估器接收输入、输出、预期输出和元数据,并返回一个在 Langfuse 中成为 Score 的 Evaluation 对象。

函数签名和参数参见 SDK 参考:

Run Evaluator

run evaluator 是一个函数,评估完整的实验结果并计算聚合指标。在 Langfuse 数据集上运行时,产生的分数附加到数据集运行。

函数签名和参数参见 SDK 参考:

关于 task 和评估器的详细用法示例,参见通过 SDK 做实验。

本地数据集

目前,如果使用通过 SDK 做实验在本地数据集上运行实验,Langfuse 中只创建 traces——不生成数据集运行。每次任务执行都会创建一个单独的 trace,用于可观测性和调试。

我们的路线图中有改进,以支持类似的功能,例如对本地数据集的实验提供运行总览、对比视图等,就像对 Langfuse 数据集那样。