文档 / 分数(Scores)
分数(Scores)
分数(Scores)是 Langfuse 用于存储评估结果的通用数据对象。每当你想为一个 LLM 输出赋予质量判定时——无论是人工标注、LLM 评审、程序化检查,还是终端用户反馈——结果都以分数存储。
每个分数都有一个名称(name)(如 "correctness" 或 "helpfulness")、一个值(value)和一个数据类型(data type)。分数还支持可选的**评论(comment)**,用于补充上下文。
分数可以附加到 traces、observations、sessions 或 dataset runs 上。最常见的做法是把分数附加到 trace,以评估单次端到端交互。
有了分数之后,它们会出现在分数分析中,可以在自定义仪表盘中可视化,并可以通过 API 查询。
何时使用分数
当你不满足于观察应用在做什么,而想开始衡量它做得有多好时,分数就派上用场了。常见用例:
- 收集用户反馈:捕获用户的点赞/点踩或星级评分,并附加到 traces 上。参见用户反馈指南。
- 监控生产质量:配置自动评估器(如 LLM-as-a-Judge),持续为实时 traces 打分,检查幻觉、相关性或语气等问题。
- 运行护栏:为输出是否通过安全检查打分,如 PII 检测、格式校验或内容政策合规。
- 用实验对比变更:当你更改提示词、模型或流水线时,运行实验,针对数据集为新版本打分。
分数类型
Langfuse 支持四种分数数据类型:
| 类型 | 值 | 适用场景 |
|---|---|---|
NUMERIC |
浮点数(如 0.9) |
连续性判定,如准确性、相关性或相似度分数 |
CATEGORICAL |
来自预定义类别的字符串(如 "correct"、"partially correct") |
取值集合预先已知的离散分类 |
BOOLEAN |
0 或 1 |
通过/失败检查,如幻觉检测或格式校验 |
TEXT |
自由格式字符串(1-500 字符) | 开放式标注,如审阅者备注或定性反馈。常用于在通过轴心编码形式化为可量化分数之前的开放编码。 |
文本分数专为定性、开放式打分而设计。由于自由文本无法有意义地聚合或比较,文本分数不支持用于实验、LLM-as-a-Judge 或分数分析。
如何创建分数
有五种添加分数的方式:
- LLM-as-a-Judge:配置自动评估器,基于自定义标准(如幻觉、语气、相关性)为 traces 打分。它们可以返回数值或分类分数以及推理过程,并可以在生产实时 traces 或实验结果上运行。
- 代码评估器:在 Langfuse 中运行自定义 Python 或 TypeScript 评估器,进行精确匹配、JSON 校验或自定义业务规则等确定性检查。
- 通过 UI 打分:团队成员直接在 Langfuse UI 中手动为 traces、observations 或 sessions 打分。需要先配置分数配置(score config)。
- 标注队列:配置结构化审阅工作流,审阅者按批次处理 traces。
- 通过 API/SDK 打分:从应用代码中以编程方式添加分数。这是用户反馈(点赞/点踩、星级评分)、护栏结果或自定义评估流水线的首选方式。
该用分数还是标签?
| 分数 | 标签 | |
|---|---|---|
| 用途 | 衡量某事物_有多好_ | 描述某事物_是什么_ |
| 数据 | 数值、分类、布尔或文本值 | 简单的字符串标签 |
| 添加时机 | 可随时添加,甚至在 trace 创建很久之后 | 在追踪时设置,之后不可更改 |
| 用于 | 质量度量、分析、实验 | 过滤、分组、组织 |
经验法则:如果你在追踪时就已经知道类别(例如哪个功能或 API 端点触发了该 trace),使用标签。如果你需要事后对 traces 进行分类或评估,使用分数。
分数评论
每个分数都支持可选的 comment(评论) 字段。用它来记录推理过程(例如 LLM 评审为什么给出某个分数)、审阅者备注,或帮助他人理解分数值的上下文。评论会与分数一起显示在 Langfuse UI 中。
如果要捕获独立的定性反馈,请使用 TEXT 分数而非评论——评论最适合为已有分数补充推理说明。