Langfuse 文档 中文 英文原文 ↗
文档 / 实验数据模型

实验数据模型

本页描述 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 对象:

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 数据集那样。

非官方中文翻译 · 图片/视频/代码均链接官方资源 · 版权归 Langfuse GmbH 所有 查看英文原文 ↗