数据模型

本页描述 Litefuse 中与评估相关对象的数据模型。要了解这些对象如何协同工作，请参见核心概念页面。

详细参考请查阅

本页涉及以下对象：

对象/函数定义	说明
Dataset	用于运行实验的数据集条目集合。
Dataset Item	数据集中的单个条目。
Dataset Run	即实验运行。关联实验结果的对象。
Dataset Run Item	即实验运行条目。
Score	评估器的输出。
Score Config	定义分数如何计算和解读的配置。
Task Function	在某次实验中针对数据集条目运行的任务函数定义。
Evaluator Function	评估器的函数定义。

对象

Datasets

数据集是一组输入及（可选的）期望输出，可在数据集运行中使用。

Dataset 是 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	否	数据集条目的额外元信息
`sourceTraceId`	string	否	关联到此数据集条目的来源 trace 的 ID
`sourceObservationId`	string	否	关联到此数据集条目的来源 observation 的 ID
`status`	DatasetStatus	否	数据集条目的状态。新建条目默认为 ACTIVE。可选值：`ACTIVE`、`ARCHIVED`

DatasetRun（实验运行）

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

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

大多数情况下，我们建议 DatasetRunItem 直接引用 TraceID。引用 ObservationID 是为了向后兼容旧版 SDK。

Scores

分数是用于存储评估结果的数据对象。它们用于给 trace、observation、会话或数据集运行赋予评估分数。分数可以通过标注手动添加、通过 SDK/API 编程式添加，或通过 LLM-as-a-Judge 评估器自动添加。

分数具有以下特性：

每个 Score 恰好引用一个 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`
`source`	string	是	根据分数来源自动设置。可以是 `API`、`EVAL` 或 `ANNOTATION`
`comment`	string	否	评估评论，常用于用户反馈、评估推理输出或内部备注
`traceId`	string	否	分数关联的 trace 的 ID
`observationId`	string	否	分数关联的 observation（例如 LLM 调用）的 ID
`sessionId`	string	否	分数关联的会话的 ID
`datasetRunId`	string	否	分数关联的数据集运行的 ID
`configId`	string	否	分数配置 ID，用于确保分数遵循特定 schema。可在 Litefuse UI 或通过 API 定义。

常见用例

级别	说明
Trace	用于评估单次交互。（最常见）
Observation	用于评估 trace 之下的单个 observation。
Session	用于跨多次交互的综合评估。
Dataset Run	用于数据集运行的整体表现分数。

Score Config

分数配置用于确保你的分数遵循特定 schema。使用分数配置可以让团队的打分 schema 标准化，确保分数在后续分析中保持一致和可比。

你可以在 Litefuse UI 中或通过我们的 API 定义 ScoreConfig。配置不可变更，但可以归档（也可随时恢复）。

一个分数配置包含：

分数名称
数据类型： NUMERIC、CATEGORICAL、BOOLEAN
分数取值范围约束（数值型为最小/最大值，分类型为自定义类别）

ScoreConfig 对象

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

端到端的数据关系

一次实验可以组合 Litefuse 中多种对象：

DatasetRun（或实验运行）通过让你的 LLM 应用遍历 Dataset 中的全部或部分 DatasetItem 来创建。
对于每个被传入 LLM 应用作为输入的 DatasetItem，都会创建一个 DatasetRunItem 和一条 Trace。
在 DatasetRun 期间，可以可选地把 Score 添加到 Trace 上以评估 LLM 应用的输出。

关于这些对象在概念上如何协同工作，更多信息见核心概念页面。关于 trace 和 observation 的更多细节，见可观测性核心概念页面。

函数定义

通过 SDK 运行实验时，你需要定义 task 和 evaluator 函数。这是用户自定义的函数，实验运行器会针对每个数据集条目调用它们。关于实验在概念上的工作方式，见核心概念页面。

Task

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

函数签名和参数详见 SDK 参考：

Evaluator

evaluator 是一个函数，针对单个数据集条目对 task 的输出打分。它接收 input、output、expected output 和 metadata，并返回一个 Evaluation 对象，最终在 Litefuse 中变成一个 Score。

函数签名和参数详见 SDK 参考：

Run Evaluator

run evaluator 是一个函数，对完整实验结果进行评估并计算聚合指标。在 Litefuse 数据集上运行时，结果分数会附加到数据集运行上。

函数签名和参数详见 SDK 参考：

关于 task 和 evaluator 的详细使用示例，见 Experiments via SDK。

本地数据集

目前，如果通过 Experiments via SDK 在本地数据集上运行实验，Litefuse 中只会创建 trace —— 不会生成数据集运行。每次任务执行都会为可观测性和调试创建一条独立的 trace。

我们的路线图中包含一些改进，未来会让本地数据集上的实验也支持类似的运行概览、对比视图等功能，对齐 Litefuse 数据集体验。

分数分析数据集

这个页面对你有帮助吗？

支持