文档 / 分数数据模型

分数数据模型

本页描述 Langfuse 中与分数相关对象的数据模型。关于分数是什么以及何时使用它们的概览,参见分数概览。关于数据集、实验运行和函数定义,参见实验数据模型。

详细参考请参阅

分数(Scores)

分数是存储评估结果的数据对象。它们用于为 traces、observations、sessions 或 dataset runs 分配评估分数。分数可以通过标注手动添加、通过 SDK/API 以编程方式添加,或通过 LLM-as-a-Judge 评估器自动添加。

mermaid

classDiagram
direction LR
    class Score {
        id
        name
        value
        stringValue
        dataType
        source
        comment
        configId
    }

    Score --> Trace: traceId
    Score --> Observation: observationId
    Score --> Session: sessionId
    Score --> DatasetRun: datasetRunId

分数具有以下属性:

每个分数引用 Trace、Observation、Session 或 DatasetRun 中的恰好一个
分数要么是数值型、分类型、布尔型,要么是文本型(参见分数类型)
分数可以可选地链接到 ScoreConfig,以确保它们符合特定 schema

Score 对象

属性	类型	必需	描述
`id`	string	是	分数的唯一标识符。由 SDK 自动生成。可选地也可用作更新分数的幂等键。
`name`	string	是	分数的名称,例如 user_feedback、hallucination_eval
`value`	number	否	分数的数值。对数值和布尔分数始终定义。对分类分数可选。不用于文本分数。
`stringValue`	string	否	分数的字符串值。用于分类、布尔(字符串等价)和文本数据类型。如果提供了 `configId`,则根据 config 自动为分类分数设置。
`dataType`	string	否	当提供 `configId` 时根据 config 数据类型自动设置。否则可手动定义为 `NUMERIC`、`CATEGORICAL`、`BOOLEAN` 或 `TEXT`
`source`	string	是	根据分数来源自动设置。可以是 `API`、`EVAL` 或 `ANNOTATION`
`comment`	string	否	评估评论,常用于用户反馈、评估推理输出或内部备注
`traceId`	string	否	分数所关联的 trace 的 id
`observationId`	string	否	分数所关联的 observation(例如 LLM 调用)的 id
`sessionId`	string	否	分数所关联的 session 的 id
`datasetRunId`	string	否	分数所关联的 dataset run 的 id
`configId`	string	否	分数 config id,以确保分数遵循特定 schema。可在 Langfuse UI 中或通过 API 定义。

常见用例

级别	描述
Trace	用于评估单次交互。(最常见)
Observation	用于评估 trace 级别之下的单个 observation。
Session	用于跨多次交互对输出进行全面评估。
Dataset Run	用于 Dataset Run 的性能分数。

分数配置(Score Config)

分数配置用于确保你的分数遵循特定 schema。使用分数配置让你能够在团队中标准化打分 schema,并确保分数一致且可用于未来分析。

你可以在 Langfuse UI 中或通过我们的 API 定义 ScoreConfig。配置是不可变的,但可以归档(并随时恢复)。

mermaid

classDiagram
  Score --> ScoreConfig: configId

分数配置包括:

分数名称
数据类型: NUMERIC、CATEGORICAL、BOOLEAN、TEXT
分数值范围的约束(数值型的 Min/Max,分类数据类型的自定义类别,文本的 1-500 字符)

ScoreConfig 对象

属性	类型	必需	描述
`id`	string	是	分数配置的唯一标识符。
`name`	string	是	分数配置的名称,例如 user_feedback、hallucination_eval
`dataType`	string	是	可以是 `NUMERIC`、`CATEGORICAL`、`BOOLEAN` 或 `TEXT`
`isArchived`	boolean	否	分数配置是否已归档。默认为 false
`minValue`	number	否	设置数值分数的最小值。如果未设置,最小值默认为 -∞
`maxValue`	number	否	设置数值分数的最大值。如果未设置,最大值默认为 +∞
`categories`	list	否	定义分类分数的类别。带 label-value 对的对象列表
`description`	string	否	提供分数配置的进一步描述